diff options
Diffstat (limited to 'doc')
760 files changed, 17312 insertions, 8502 deletions
diff --git a/doc/.vale/gitlab/Acronyms.yml b/doc/.vale/gitlab/Acronyms.yml index 2d4d0c6909f..122cac6f8a1 100644 --- a/doc/.vale/gitlab/Acronyms.yml +++ b/doc/.vale/gitlab/Acronyms.yml @@ -107,6 +107,7 @@ exceptions: - NTP - ONLY - OSS + - OTP - OWASP - PAT - PCI-DSS diff --git a/doc/.vale/gitlab/BadgeCapitalization.yml b/doc/.vale/gitlab/BadgeCapitalization.yml index 89d6f509d63..33425693d53 100644 --- a/doc/.vale/gitlab/BadgeCapitalization.yml +++ b/doc/.vale/gitlab/BadgeCapitalization.yml @@ -10,4 +10,5 @@ link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html level: error scope: raw raw: - - '\*\*\(([Ff]ree|[Pp]remium|[Uu]ltimate)( [Ss](elf|ass))?\)\*\*' + - '(?!\*\*\((FREE|PREMIUM|ULTIMATE)( (SELF|SAAS))?\)\*\*)' + - '(?i)\*\*\((free|premium|ultimate)( (self|saas))?\)\*\*' diff --git a/doc/.vale/gitlab/CurlStringsQuoted.yml b/doc/.vale/gitlab/CurlStringsQuoted.yml index c0bc8c18c93..a59fe64d990 100644 --- a/doc/.vale/gitlab/CurlStringsQuoted.yml +++ b/doc/.vale/gitlab/CurlStringsQuoted.yml @@ -10,4 +10,4 @@ link: https://docs.gitlab.com/ee/development/documentation/restful_api_styleguid level: error scope: code raw: - - 'curl.*[^"=]https?://.*' + - 'curl [^"]+://.*' diff --git a/doc/.vale/gitlab/ElementDescriptors.yml b/doc/.vale/gitlab/ElementDescriptors.yml new file mode 100644 index 00000000000..254da16d00c --- /dev/null +++ b/doc/.vale/gitlab/ElementDescriptors.yml @@ -0,0 +1,14 @@ +--- +# Suggestion: gitlab.ElementDescriptors +# +# Suggests the correct way to describe elements in a form. +# +# For a list of all options, see https://errata-ai.github.io/vale/styles/ +extends: substitution +message: 'When describing elements, %s "%s".' +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#language +level: suggestion +ignorecase: true +swap: + button: 'if possible, rewrite to not use' + area: 'use "section" instead of' diff --git a/doc/.vale/gitlab/HeaderGerunds.yml b/doc/.vale/gitlab/HeaderGerunds.yml deleted file mode 100644 index 9e5fa19f867..00000000000 --- a/doc/.vale/gitlab/HeaderGerunds.yml +++ /dev/null @@ -1,14 +0,0 @@ ---- -# Suggestion: gitlab.HeaderGerunds -# -# Checks for headers that start with gerunds (ing words). -# Related to: https://docs.gitlab.com/ee/development/documentation/structure.html -# -# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles -extends: substitution -message: 'Can this header start with an imperative verb, instead of a gerund (ing word)?' -link: https://docs.gitlab.com/ee/development/documentation/styleguide/#heading-titles -level: suggestion -scope: heading -swap: - - '^\w*ing.*': 'Troubleshooting' diff --git a/doc/.vale/gitlab/InternalLinkExtension.yml b/doc/.vale/gitlab/InternalLinkExtension.yml index 0b1baaf667c..5783c4347a9 100644 --- a/doc/.vale/gitlab/InternalLinkExtension.yml +++ b/doc/.vale/gitlab/InternalLinkExtension.yml @@ -10,4 +10,4 @@ link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html level: error scope: raw raw: - - '\[.+\]\((https?:){0}[\w\/\.-]+(\.html).*?\)' + - '\[.+\]\([\w\/\.-]+\.html[^)]*\)' diff --git a/doc/.vale/gitlab/InternalLinkFormat.yml b/doc/.vale/gitlab/InternalLinkFormat.yml index 51d5198a0ce..b9ee83b7f5c 100644 --- a/doc/.vale/gitlab/InternalLinkFormat.yml +++ b/doc/.vale/gitlab/InternalLinkFormat.yml @@ -10,4 +10,4 @@ link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html level: error scope: raw raw: - - '\[.+\]\(\.\/.+?\)' + - '\[.+\]\(\.\/.*?\)' diff --git a/doc/.vale/gitlab/OutdatedVersions.yml b/doc/.vale/gitlab/OutdatedVersions.yml index 05323726838..15ae0a5814a 100644 --- a/doc/.vale/gitlab/OutdatedVersions.yml +++ b/doc/.vale/gitlab/OutdatedVersions.yml @@ -19,3 +19,5 @@ tokens: - "GitLab (v)?7." - "GitLab (v)?8." - "GitLab (v)?9." + - "GitLab (v)?10." + - "GitLab (v)?11." diff --git a/doc/.vale/gitlab/ReadingLevel.yml b/doc/.vale/gitlab/ReadingLevel.yml index 0099e70ec8f..2e78c3ef36c 100644 --- a/doc/.vale/gitlab/ReadingLevel.yml +++ b/doc/.vale/gitlab/ReadingLevel.yml @@ -6,6 +6,7 @@ # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles extends: readability message: "Grade level (%s) is high. To lower the score, use shorter sentences and words." +link: https://docs.gitlab.com/ee/development/documentation/testing.html#vale-readability-score level: suggestion grade: 8 metrics: diff --git a/doc/.vale/gitlab/SubstitutionSuggestions.yml b/doc/.vale/gitlab/SubstitutionSuggestions.yml index bc9a6e3c70d..e7c0cc04244 100644 --- a/doc/.vale/gitlab/SubstitutionSuggestions.yml +++ b/doc/.vale/gitlab/SubstitutionSuggestions.yml @@ -14,7 +14,9 @@ swap: active user: '"billable user"' active users: '"billable users"' docs: '"documentation"' + e-mail: '"email"' GFM: '"GitLab Flavored Markdown"' + it is recommended: '"we recommend"' OAuth2: '"OAuth 2.0"' once that: '"after that"' once the: '"after the"' diff --git a/doc/.vale/gitlab/UnclearAntecedent.yml b/doc/.vale/gitlab/UnclearAntecedent.yml new file mode 100644 index 00000000000..863bbd4e109 --- /dev/null +++ b/doc/.vale/gitlab/UnclearAntecedent.yml @@ -0,0 +1,22 @@ +--- +# Suggestion: gitlab.UnclearAntecedent +# +# Checks for words that need a noun for clarity. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: existence +message: "'%s' is not precise. Try rewriting with a specific subject and verb." +link: https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html#this-these-that-those +level: suggestion +ignorecase: false +tokens: + - 'That is' + - 'That was' + - 'These are' + - 'These were' + - 'There are' + - 'There were' + - 'This is' + - 'This was' + - 'Those are' + - 'Those were' diff --git a/doc/.vale/gitlab/VersionText.yml b/doc/.vale/gitlab/VersionText.yml index e66a62497b1..fbdda17e2a0 100644 --- a/doc/.vale/gitlab/VersionText.yml +++ b/doc/.vale/gitlab/VersionText.yml @@ -9,9 +9,9 @@ # - `> Introduced` (version text without a link) # - `> [Introduced` (version text with a link) # -# Because it excludes `-`, it doesn't look for multi-line version text, for which content -# immediately on the next line is ok. However, this will often highlight where multi-line version -# text is attempted without `-` characters. +# Because it excludes the prefix `> - `, it doesn't look for multi-line version text, for which +# content immediately on the next line is ok. However, this will often highlight where multi-line +# version text is attempted without `-` characters. # # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles extends: existence @@ -20,4 +20,4 @@ link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html level: error scope: raw raw: - - '> (- ){0}\[?Introduced.+\n[^\n`]' + - '> \[?Introduced.+\n[^\n]' diff --git a/doc/.vale/gitlab/spelling-exceptions.txt b/doc/.vale/gitlab/spelling-exceptions.txt index 43ff584b550..d397a436ff9 100644 --- a/doc/.vale/gitlab/spelling-exceptions.txt +++ b/doc/.vale/gitlab/spelling-exceptions.txt @@ -90,6 +90,7 @@ callstack callstacks Camo canonicalized +captcha CentOS Certbot changeset @@ -160,7 +161,12 @@ deprovisions dequarantine dequarantined dequarantining +deserialization +deserialize +deserializers +deserializes DevOps +Dhall disambiguates discoverability dismissable @@ -209,6 +215,7 @@ fixup Flawfinder Flowdock Fluentd +Flycheck Forgerock formatters Fugit @@ -469,6 +476,7 @@ queryable Quicktime Rackspace Raspbian +rbenv rbtrace Rdoc reachability @@ -815,8 +823,10 @@ Worldline Xcode Xeon YouTrack +ytt Yubico Zeitwerk Zendesk +ZenTao zsh Zstandard diff --git a/doc/administration/audit_events.md b/doc/administration/audit_events.md index 48bd812c7f2..3ff5fb2635d 100644 --- a/doc/administration/audit_events.md +++ b/doc/administration/audit_events.md @@ -39,7 +39,7 @@ There are two kinds of events logged: ### Impersonation data -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/536) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/536) in GitLab 13.0. When a user is being [impersonated](../user/admin_area/index.md#user-impersonation), their actions are logged as audit events as usual, with two additional details: @@ -48,7 +48,7 @@ When a user is being [impersonated](../user/admin_area/index.md#user-impersonati  -### Group events **(PREMIUM)** +### Group events A user with: @@ -86,7 +86,7 @@ From there, you can see the following actions: Group events can also be accessed via the [Group Audit Events API](../api/audit_events.md#group-audit-events) -### Project events **(PREMIUM)** +### Project events A user with a Maintainer role (or above) can retrieve project audit events of all users. A user with a Developer role is limited to project audit events based on their individual actions. @@ -126,6 +126,10 @@ From there, you can see the following actions: - User password required for approvals was updated ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336211) in GitLab 14.2) - Permission to modify merge requests approval rules in merge requests was updated ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336211) in GitLab 14.2) - New approvals requirement when new commits are added to an MR was updated ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336211) in GitLab 14.2) +- When [strategies for feature flags](../operations/feature_flags.md#feature-flag-strategies) are changed ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68408) in GitLab 14.3) +- Allowing force push to protected branch changed ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/338873) in GitLab 14.3) +- Code owner approval requirement on merge requests targeting protected branch changed ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/338873) in GitLab 14.3) +- Users and groups allowed to merge and push to protected branch added or removed ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/338873) in GitLab 14.3) Project events can also be accessed via the [Project Audit Events API](../api/audit_events.md#project-audit-events). @@ -133,7 +137,7 @@ Project event queries are limited to a maximum of 30 days. ### Instance events **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2336) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2336) in GitLab 9.3. Server-wide audit events introduce the ability to observe user actions across the entire instance of your GitLab server, making it easy to understand who @@ -143,7 +147,7 @@ Instance events do not include group or project audit events. To view the server-wide audit events: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Monitoring > Audit Events**. The following user actions are recorded: @@ -203,6 +207,8 @@ to request it, or you can [add it yourself](../development/audit_event_guide/). #### Repository push +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/337993) in GitLab 14.3. + The current architecture of audit events is not prepared to receive a very high amount of records. It may make the user interface for your project or audit events very busy, and the disk space consumed by the `audit_events` PostgreSQL table may increase considerably. It's disabled by default @@ -240,8 +246,8 @@ The search filters you can see depends on which audit level you are at. ## Export to CSV **(PREMIUM SELF)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1449) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/285441) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1449) in GitLab 13.4. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/285441) in GitLab 13.7. Export to CSV allows customers to export the current filter view of your audit events as a CSV file, which stores tabular data in plain text. The data provides a comprehensive view with respect to @@ -249,7 +255,7 @@ audit events. To export the Audit Events to CSV: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Monitoring > Audit Events**. 1. Select the available search [filters](#search). 1. Select **Export as CSV**. diff --git a/doc/administration/auditor_users.md b/doc/administration/auditor_users.md index 5f31ed709f2..5498ea9d4be 100644 --- a/doc/administration/auditor_users.md +++ b/doc/administration/auditor_users.md @@ -57,7 +57,7 @@ helpful: To create an Auditor user: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Create a new user or edit an existing one, and in the **Access** section select Auditor. diff --git a/doc/administration/auth/atlassian.md b/doc/administration/auth/atlassian.md index 868482148e5..b58bbfa8eac 100644 --- a/doc/administration/auth/atlassian.md +++ b/doc/administration/auth/atlassian.md @@ -16,7 +16,7 @@ To enable the Atlassian OmniAuth provider for passwordless authentication you mu 1. Click **Create a new app**. 1. Choose an App Name, such as 'GitLab', and click **Create**. 1. Note the `Client ID` and `Secret` for the [GitLab configuration](#gitlab-configuration) steps. -1. In the left sidebar under **APIS AND FEATURES**, click **OAuth 2.0 (3LO)**. +1. On the left sidebar under **APIS AND FEATURES**, click **OAuth 2.0 (3LO)**. 1. Enter the GitLab callback URL using the format `https://gitlab.example.com/users/auth/atlassian_oauth2/callback` and click **Save changes**. 1. Click **+ Add** in the left sidebar under **APIS AND FEATURES**. 1. Click **Add** for **Jira platform REST API** and then **Configure**. diff --git a/doc/administration/auth/ldap/google_secure_ldap.md b/doc/administration/auth/ldap/google_secure_ldap.md index 55ccf6653a3..137f35986ac 100644 --- a/doc/administration/auth/ldap/google_secure_ldap.md +++ b/doc/administration/auth/ldap/google_secure_ldap.md @@ -87,6 +87,7 @@ values obtained during the LDAP client configuration earlier: password: 'd6V5H8nhMUW9AuDP25abXeLd' encryption: 'simple_tls' verify_certificates: true + retry_empty_result_with_codes: [80] tls_options: cert: | @@ -159,6 +160,7 @@ values obtained during the LDAP client configuration earlier: password: 'd6V5H8nhMUW9AuDP25abXeLd' encryption: 'simple_tls' verify_certificates: true + retry_empty_result_with_codes: [80] tls_options: cert: | @@ -213,7 +215,7 @@ values obtained during the LDAP client configuration earlier: ## Using encrypted credentials You can optionally store the `bind_dn` and `password` in a separate encrypted configuration file using the -[same steps as the regular LDAP integration](index.md#using-encrypted-credentials). +[same steps as the regular LDAP integration](index.md#use-encrypted-credentials). <!-- ## Troubleshooting diff --git a/doc/administration/auth/ldap/index.md b/doc/administration/auth/ldap/index.md index 63e3a0a3686..1992b450338 100644 --- a/doc/administration/auth/ldap/index.md +++ b/doc/administration/auth/ldap/index.md @@ -12,24 +12,22 @@ to support user authentication. This integration works with most LDAP-compliant directory servers, including: -- Microsoft Active Directory - - [Microsoft Active Directory Trusts](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc771568(v=ws.10)) are not supported. -- Apple Open Directory -- Open LDAP -- 389 Server +- Microsoft Active Directory. + [Microsoft Active Directory Trusts](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc771568(v=ws.10)) + are not supported. +- Apple Open Directory. +- Open LDAP. +- 389 Server. Users added through LDAP take a [licensed seat](../../../subscriptions/self_managed/index.md#billable-users). -GitLab Enterprise Editions (EE) include enhanced integration, -including group membership syncing and multiple LDAP server support. - ## Security GitLab assumes that LDAP users: - Are not able to change their LDAP `mail`, `email`, or `userPrincipalName` attributes. An LDAP user allowed to change their email on the LDAP server can potentially - [take over any account](#enabling-ldap-sign-in-for-existing-gitlab-users) + [take over any account](#enable-ldap-sign-in-for-existing-gitlab-users) on your GitLab server. - Have unique email addresses. If not, it's possible for LDAP users with the same email address to share the same GitLab account. @@ -42,7 +40,7 @@ the LDAP server, or share email addresses. Users deleted from the LDAP server are immediately blocked from signing in to GitLab. However, there's an LDAP check cache time of one hour (which is -[configurable](#adjusting-ldap-user-sync-schedule) for GitLab Premium users). +[configurable](#adjust-ldap-user-sync-schedule) for GitLab Premium users). This means users already signed-in or who are using Git over SSH can access GitLab for up to one hour. Manually block the user in the GitLab Admin Area to immediately block all access. @@ -53,7 +51,7 @@ LDAP-enabled users can authenticate with Git using their GitLab username or email and LDAP password, even if password authentication for Git is disabled in the application settings. -## Enabling LDAP sign-in for existing GitLab users +## Enable LDAP sign-in for existing GitLab users When a user signs in to GitLab with LDAP for the first time and their LDAP email address is the primary email address of an existing GitLab user, the @@ -74,7 +72,7 @@ See [Google Secure LDAP](google_secure_ldap.md) for detailed configuration instr ## Configuration -To enable LDAP integration you need to add your LDAP server settings in +To enable LDAP integration you must add your LDAP server settings in `/etc/gitlab/gitlab.rb` or `/home/git/gitlab/config/gitlab.yml` for Omnibus GitLab and installations from source respectively. @@ -155,7 +153,7 @@ production: ... ``` -### Basic Configuration Settings +### Basic configuration settings | Setting | Description | Required | Examples | |--------------------|-------------|----------|----------| @@ -169,12 +167,12 @@ production: | `verify_certificates` | Enables SSL certificate verification if encryption method is `start_tls` or `simple_tls`. Defaults to true. | **{dotted-circle}** No | boolean | | `timeout` | Set a timeout, in seconds, for LDAP queries. This helps avoid blocking a request if the LDAP server becomes unresponsive. A value of `0` means there is no timeout. (default: `10`) | **{dotted-circle}** No | `10` or `30` | | `active_directory` | This setting specifies if LDAP server is Active Directory LDAP server. For non-AD servers it skips the AD specific queries. If your LDAP server is not AD, set this to false. | **{dotted-circle}** No | boolean | -| `allow_username_or_email_login` | If enabled, GitLab ignores everything after the first `@` in the LDAP username submitted by the user on sign-in. If you are using `uid: 'userPrincipalName'` on ActiveDirectory you need to disable this setting, because the userPrincipalName contains an `@`. | **{dotted-circle}** No | boolean | +| `allow_username_or_email_login` | If enabled, GitLab ignores everything after the first `@` in the LDAP username submitted by the user on sign-in. If you are using `uid: 'userPrincipalName'` on ActiveDirectory you must disable this setting, because the userPrincipalName contains an `@`. | **{dotted-circle}** No | boolean | | `block_auto_created_users` | To maintain tight control over the number of billable users on your GitLab installation, enable this setting to keep new users blocked until they have been cleared by an administrator (default: false). | **{dotted-circle}** No | boolean | | `base` | Base where we can search for users. | **{check-circle}** Yes | `'ou=people,dc=gitlab,dc=example'` or `'DC=mydomain,DC=com'` | | `user_filter` | Filter LDAP users. Format: [RFC 4515](https://tools.ietf.org/search/rfc4515) Note: GitLab does not support `omniauth-ldap`'s custom filter syntax. | **{dotted-circle}** No | For examples, read [Examples of user filters](#examples-of-user-filters). | | `lowercase_usernames` | If enabled, GitLab converts the name to lower case. | **{dotted-circle}** No | boolean | -| `retry_empty_result_with_codes` | An array of LDAP query response code that will attempt to retrying the operation if the result/content is empty. | **{dotted-circle}** No | `[80]` | +| `retry_empty_result_with_codes` | An array of LDAP query response code that attempt to retry the operation if the result/content is empty. For Google Secure LDAP, set this value to `[80]`. | **{dotted-circle}** No | `[80]` | #### Examples of user filters @@ -183,17 +181,17 @@ Some examples of the `user_filter` field syntax: - `'(employeeType=developer)'` - `'(&(objectclass=user)(|(samaccountname=momo)(samaccountname=toto)))'` -### SSL Configuration Settings +### SSL configuration settings | Setting | Description | Required | Examples | |---------------|-------------|----------|----------| -| `ca_file` | Specifies the path to a file containing a PEM-format CA certificate, for example, if you need to use an internal CA. | **{dotted-circle}** No | `'/etc/ca.pem'` | +| `ca_file` | Specifies the path to a file containing a PEM-format CA certificate, for example, if you need an internal CA. | **{dotted-circle}** No | `'/etc/ca.pem'` | | `ssl_version` | Specifies the SSL version for OpenSSL to use, if the OpenSSL default is not appropriate. | **{dotted-circle}** No | `'TLSv1_1'` | | `ciphers` | Specific SSL ciphers to use in communication with LDAP servers. | **{dotted-circle}** No | `'ALL:!EXPORT:!LOW:!aNULL:!eNULL:!SSLv2'` | | `cert` | Client certificate. | **{dotted-circle}** No | `'-----BEGIN CERTIFICATE----- <REDACTED> -----END CERTIFICATE -----'` | | `key` | Client private key. | **{dotted-circle}** No | `'-----BEGIN PRIVATE KEY----- <REDACTED> -----END PRIVATE KEY -----'` | -### Attribute Configuration Settings +### Attribute configuration settings LDAP attributes that GitLab uses to create an account for the LDAP user. The specified attribute can either be the attribute name as a string (for example, `'mail'`), or an @@ -208,7 +206,7 @@ The user's LDAP sign-in is the attribute specified as `uid` above. | `first_name` | LDAP attribute for user first name. Used when the attribute configured for `name` does not exist. | **{dotted-circle}** No | `'givenName'` | | `last_name` | LDAP attribute for user last name. Used when the attribute configured for `name` does not exist. | **{dotted-circle}** No | `'sn'` | -### LDAP Sync Configuration Settings **(PREMIUM SELF)** +### LDAP Sync configuration settings **(PREMIUM SELF)** | Setting | Description | Required | Examples | |-------------------|-------------|----------|----------| @@ -261,7 +259,7 @@ Support for nested members in the user filter shouldn't be confused with GitLab does not support the custom filter syntax used by OmniAuth LDAP. -#### Escaping special characters +#### Escape special characters The `user_filter` DN can contain special characters. For example: @@ -292,7 +290,7 @@ The `user_filter` DN can contain special characters. For example: OU=Gitlab \28Inc\29,DC=gitlab,DC=com ``` -### Enabling LDAP username lowercase +### Enable LDAP username lowercase Some LDAP servers, depending on their configurations, can return uppercase usernames. This can lead to several confusing issues such as creating links or namespaces with uppercase names. @@ -362,10 +360,10 @@ This does not disable [using LDAP credentials for Git access](#git-password-auth 1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect. -### Using encrypted credentials +### Use encrypted credentials Instead of having the LDAP integration credentials stored in plaintext in the configuration files, you can optionally -use an encrypted file for the LDAP credentials. To use this feature, you first need to enable +use an encrypted file for the LDAP credentials. To use this feature, first you must enable [GitLab encrypted configuration](../../encrypted_configuration.md). The encrypted configuration for LDAP exists in an encrypted YAML file. By default the file is created at @@ -451,7 +449,7 @@ If initially your LDAP configuration looked like: ## Encryption -### TLS Server Authentication +### TLS server authentication There are two encryption methods, `simple_tls` and `start_tls`. @@ -461,7 +459,7 @@ exchanged but no validation of the LDAP server's SSL certificate is performed. ### Limitations -#### TLS Client Authentication +#### TLS client authentication Not implemented by `Net::LDAP`. @@ -555,7 +553,7 @@ The LDAP sync process: - Updates existing users. - Creates new users on first sign in. -### Adjusting LDAP user sync schedule **(PREMIUM SELF)** +### Adjust LDAP user sync schedule **(PREMIUM SELF)** By default, GitLab runs a worker once per day at 01:30 a.m. server time to check and update GitLab users against LDAP. @@ -592,7 +590,7 @@ sync to run once every 12 hours at the top of the hour. If your LDAP supports the `memberof` property, when the user signs in for the first time GitLab triggers a sync for groups the user should be a member of. -That way they don't need to wait for the hourly sync to be granted +That way they don't have to wait for the hourly sync to be granted access to their groups and projects. A group sync process runs every hour on the hour, and `group_base` must be set @@ -635,10 +633,10 @@ following. 1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect. -To take advantage of group sync, group owners or maintainers need to [create one -or more LDAP group links](#adding-group-links). +To take advantage of group sync, group owners or maintainers must [create one +or more LDAP group links](#add-group-links). -### Adding group links **(PREMIUM SELF)** +### Add group links **(PREMIUM SELF)** For information on adding group links by using CNs and filters, refer to the [GitLab groups documentation](../../../user/group/index.md#manage-group-memberships-via-ldap). @@ -702,15 +700,15 @@ When enabled, the following applies: - Users are not allowed to share project with other groups or invite members to a project created in a group. -To enable it you need to: +To enable it, you must: 1. [Enable LDAP](#configuration) -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Ensure the **Lock memberships to LDAP synchronization** checkbox is selected. -### Adjusting LDAP group sync schedule **(PREMIUM SELF)** +### Adjust LDAP group sync schedule **(PREMIUM SELF)** By default, GitLab runs a group sync process every hour, on the hour. The values shown are in cron format. If needed, you can use a diff --git a/doc/administration/auth/ldap/ldap-troubleshooting.md b/doc/administration/auth/ldap/ldap-troubleshooting.md index 15e8496e915..1952e8afa97 100644 --- a/doc/administration/auth/ldap/ldap-troubleshooting.md +++ b/doc/administration/auth/ldap/ldap-troubleshooting.md @@ -145,7 +145,7 @@ may see the following message: `Access denied for your LDAP account`. We have a workaround, based on toggling the access level of affected users: -1. As an administrator, on the top bar, select **Menu >** **{admin}** **Admin**. +1. As an administrator, on the top bar, select **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. @@ -203,7 +203,7 @@ field contains no data: To resolve this: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, go to **Settings > General**. 1. Expand both of the following: - **Account and limit**. @@ -336,7 +336,7 @@ Gitlab::Auth::Ldap::Person.find_by_uid('<uid>', adapter) ### Group memberships **(PREMIUM SELF)** -#### Membership(s) not granted **(PREMIUM SELF)** +#### Membership(s) not granted Sometimes you may think a particular user should be added to a GitLab group via LDAP group sync, but for some reason it's not happening. There are several @@ -345,10 +345,10 @@ things to check to debug the situation. - Ensure LDAP configuration has a `group_base` specified. [This configuration](index.md#group-sync) is required for group sync to work properly. - Ensure the correct [LDAP group link is added to the GitLab - group](index.md#adding-group-links). + group](index.md#add-group-links). - Check that the user has an LDAP identity: 1. Sign in to GitLab as an administrator user. - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Search for the user. 1. Open the user by clicking their name. Do not click **Edit**. @@ -356,7 +356,7 @@ things to check to debug the situation. an LDAP DN as the 'Identifier'. If not, this user hasn't signed in with LDAP yet and must do so first. - You've waited an hour or [the configured - interval](index.md#adjusting-ldap-group-sync-schedule) for the group to + interval](index.md#adjust-ldap-group-sync-schedule) for the group to sync. To speed up the process, either go to the GitLab group **Group information > Members** and press **Sync now** (sync one group) or [run the group sync Rake task](../../raketasks/ldap.md#run-a-group-sync) (sync all groups). @@ -395,7 +395,7 @@ group sync](#sync-all-groups) in the rails console and [look through the output](#example-console-output-after-a-group-sync) to see what happens when GitLab syncs the `admin_group`. -#### Sync all groups **(PREMIUM SELF)** +#### Sync all groups NOTE: To sync all groups manually when debugging is unnecessary, [use the Rake @@ -413,7 +413,7 @@ LdapAllGroupsSyncWorker.new.perform Next, [learn how to read the output](#example-console-output-after-a-group-sync). -##### Example console output after a group sync **(PREMIUM SELF)** +##### Example console output after a group sync Like the output from the user sync, the output from the [manual group sync](#sync-all-groups) is also very verbose. However, it contains lots @@ -503,7 +503,7 @@ stating as such: No `admin_group` configured for 'ldapmain' provider. Skipping ``` -#### Sync one group **(PREMIUM SELF)** +#### Sync one group [Syncing all groups](#sync-all-groups) can produce a lot of noise in the output, which can be distracting when you're only interested in troubleshooting the memberships of @@ -525,7 +525,7 @@ EE::Gitlab::Auth::Ldap::Sync::Group.execute_all_providers(group) The output is similar to [that you get from syncing all groups](#example-console-output-after-a-group-sync). -#### Query a group in LDAP **(PREMIUM SELF)** +#### Query a group in LDAP When you'd like to confirm that GitLab can read a LDAP group and see all its members, you can run the following: diff --git a/doc/administration/auth/smartcard.md b/doc/administration/auth/smartcard.md index 07c29984552..7e2699d5eb3 100644 --- a/doc/administration/auth/smartcard.md +++ b/doc/administration/auth/smartcard.md @@ -28,7 +28,7 @@ GitLab supports two authentication methods: ### Authentication against a local database with X.509 certificates -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/726) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.6 as an experimental feature. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/726) in GitLab 11.6 as an experimental feature. WARNING: Smartcard authentication against local databases may change or be removed completely in future @@ -55,7 +55,7 @@ Certificate: ### Authentication against a local database with X.509 certificates and SAN extension -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8605) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8605) in GitLab 12.3. Smartcards with X.509 certificates using SAN extensions can be used to authenticate with GitLab. @@ -98,7 +98,7 @@ Certificate: ### Authentication against an LDAP server -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7693) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8 as an experimental feature. Smartcard authentication against an LDAP server may change or be removed completely in future releases. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7693) in GitLab 11.8 as an experimental feature. Smartcard authentication against an LDAP server may change or be removed completely in the future. GitLab implements a standard way of certificate matching following [RFC4523](https://tools.ietf.org/html/rfc4523). It uses the diff --git a/doc/administration/cicd.md b/doc/administration/cicd.md new file mode 100644 index 00000000000..89fc31822ee --- /dev/null +++ b/doc/administration/cicd.md @@ -0,0 +1,75 @@ +--- +stage: Verify +group: Pipeline Execution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: howto +--- + +# GitLab CI/CD instance configuration **(FREE SELF)** + +GitLab CI/CD is enabled by default in all new projects on an instance. You can configure +the instance to have [GitLab CI/CD disabled by default](#disable-gitlab-cicd-in-new-projects) +in new projects. + +You can still choose to [enable GitLab CI/CD in individual projects](../ci/enable_or_disable_ci.md#enable-cicd-in-a-project) +at any time. + +## Disable GitLab CI/CD in new projects + +You can set GitLab CI/CD to be disabled by default in all new projects by modifying the settings in: + +- `gitlab.yml` for source installations. +- `gitlab.rb` for Omnibus GitLab installations. + +Existing projects that already had CI/CD enabled are unchanged. Also, this setting only changes +the project default, so project owners can still enable CI/CD in the project settings. + +For installations from source: + +1. Open `gitlab.yml` with your editor and set `builds` to `false`: + + ```yaml + ## Default project features settings + default_projects_features: + issues: true + merge_requests: true + wiki: true + snippets: false + builds: false + ``` + +1. Save the `gitlab.yml` file. + +1. Restart GitLab: + + ```shell + sudo service gitlab restart + ``` + +For Omnibus GitLab installations: + +1. Edit `/etc/gitlab/gitlab.rb` and add this line: + + ```ruby + gitlab_rails['gitlab_default_projects_features_builds'] = false + ``` + +1. Save the `/etc/gitlab/gitlab.rb` file. + +1. Reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +<!-- ## 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, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/administration/clusters/kas.md b/doc/administration/clusters/kas.md index 8e5c162001e..6afaff73396 100644 --- a/doc/administration/clusters/kas.md +++ b/doc/administration/clusters/kas.md @@ -129,3 +129,25 @@ or the path to `config.yaml` inside the project is not valid. To fix this, ensure that the paths to the configuration repository and to the `config.yaml` file are correct. + +### KAS logs - `dial tcp <GITLAB_INTERNAL_IP>:443: connect: connection refused` + +If you are running a self-managed GitLab instance and: + +- The instance isn't running behind an SSL-terminating proxy. +- The instance doesn't have HTTPS configured on the GitLab instance itself. +- The instance's hostname resolves locally to its internal IP address. + +You may see the following error when the KAS tries to connect to the GitLab API: + +```json +{"level":"error","time":"2021-08-16T14:56:47.289Z","msg":"GetAgentInfo()","correlation_id":"01FD7QE35RXXXX8R47WZFBAXTN","grpc_service":"gitlab.agent.reverse_tunnel.rpc.ReverseTunnel","grpc_method":"Connect","error":"Get \"https://gitlab.example.com/api/v4/internal/kubernetes/agent_info\": dial tcp 172.17.0.4:443: connect: connection refused"} +``` + +To fix this for [Omnibus](https://docs.gitlab.com/omnibus/) package installations, +set the following parameter in `/etc/gitlab/gitlab.rb` +(replacing `gitlab.example.com` with your GitLab instance's hostname): + +```ruby +gitlab_kas['gitlab_address'] = 'http://gitlab.example.com' +``` diff --git a/doc/administration/compliance.md b/doc/administration/compliance.md index e356ef0366b..1761af1ffa1 100644 --- a/doc/administration/compliance.md +++ b/doc/administration/compliance.md @@ -31,3 +31,4 @@ relevant compliance standards. |**[Compliance frameworks](../user/project/settings/index.md#compliance-frameworks)**<br>Create a custom compliance framework at the group level to describe the type of compliance requirements any child project needs to follow. | Premium+ | **{check-circle}** Yes | Group | |**[Compliance pipelines](../user/project/settings/index.md#compliance-pipeline-configuration)**<br>Define a pipeline configuration to run for any projects with a given compliance framework. | Ultimate | **{check-circle}** Yes | Group | |**[Compliance report](../user/compliance/compliance_report/index.md)**<br>Quickly get visibility into the compliance posture of your organization. | Ultimate | **{check-circle}** Yes | Group | +|**[External Status Checks](../user/project/merge_requests/status_checks.md)**<br>Interface with third party systems you already use during development to ensure you remain compliant. | Ultimate | **{check-circle}** Yes | Project | diff --git a/doc/administration/configure.md b/doc/administration/configure.md index 73fbf527fe1..d3e37b4a0ee 100644 --- a/doc/administration/configure.md +++ b/doc/administration/configure.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Configure your GitLab installation +# Configure your GitLab installation **(FREE SELF)** Customize and configure your self-managed GitLab installation. diff --git a/doc/administration/consul.md b/doc/administration/consul.md index c88047c4c61..72b3487a549 100644 --- a/doc/administration/consul.md +++ b/doc/administration/consul.md @@ -21,7 +21,7 @@ Before configuring Consul: 1. Review the [reference architecture](reference_architectures/index.md#available-reference-architectures) documentation to determine the number of Consul server nodes you should have. -1. If necessary, ensure the [appropriate ports are open](https://docs.gitlab.com/omnibus/package-information/defaults.html#ports) in your firewall. +1. If necessary, ensure the [appropriate ports are open](package_information/defaults.md#ports) in your firewall. ## Configure the Consul nodes diff --git a/doc/administration/database_load_balancing.md b/doc/administration/database_load_balancing.md index 7d17b22a4d7..45f27a8a8f2 100644 --- a/doc/administration/database_load_balancing.md +++ b/doc/administration/database_load_balancing.md @@ -117,9 +117,9 @@ For Sidekiq, we can define [data consistency](../development/sidekiq_style_guide.md#job-data-consistency-strategies) requirements for a specific job. -## Service Discovery +## Service Discovery **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5883) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5883) in GitLab 11.0. Service discovery allows GitLab to automatically retrieve a list of secondary databases to use, instead of having to manually specify these in the @@ -237,9 +237,9 @@ For example: {"severity":"INFO","time":"2019-09-02T12:12:01.728Z","correlation_id":"abcdefg","event":"host_online","message":"Host came back online","db_host":"111.222.333.444","db_port":null,"tag":"rails.database_load_balancing","environment":"production","hostname":"web-example-1","fqdn":"gitlab.example.com","path":null,"params":null} ``` -## Handling Stale Reads +## Handling Stale Reads **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3526) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3526) in GitLab 10.3. To prevent reading from an outdated secondary the load balancer checks if it is in sync with the primary. If the data is determined to be recent enough the diff --git a/doc/administration/encrypted_configuration.md b/doc/administration/encrypted_configuration.md index 8afe30d20ab..9224def4a5a 100644 --- a/doc/administration/encrypted_configuration.md +++ b/doc/administration/encrypted_configuration.md @@ -11,8 +11,8 @@ type: reference GitLab can read settings for certain features from encrypted settings files. The supported features are: -- [LDAP `user_bn` and `password`](auth/ldap/index.md#using-encrypted-credentials) -- [SMTP `user_name` and `password`](raketasks/smtp.md#secrets) +- [LDAP `user_bn` and `password`](auth/ldap/index.md#use-encrypted-credentials). +- [SMTP `user_name` and `password`](raketasks/smtp.md#secrets). In order to enable the encrypted configuration settings, a new base key needs to be generated for `encrypted_settings_key_base`. The secret can be generated in the following ways: @@ -35,4 +35,4 @@ The new secret can be generated by running: bundle exec rake gitlab:env:info RAILS_ENV=production GITLAB_GENERATE_ENCRYPTED_SETTINGS_KEY_BASE=true ``` -This prints general information on the GitLab instance, but also causes the key to be generated in `<path-to-gitlab-rails>/config/secrets.yml` +This prints general information on the GitLab instance, but also causes the key to be generated in `<path-to-gitlab-rails>/config/secrets.yml`. diff --git a/doc/administration/geo/disaster_recovery/background_verification.md b/doc/administration/geo/disaster_recovery/background_verification.md index 65e0ffd4366..caa806c92c8 100644 --- a/doc/administration/geo/disaster_recovery/background_verification.md +++ b/doc/administration/geo/disaster_recovery/background_verification.md @@ -60,7 +60,7 @@ Feature.enable('geo_repository_verification') On the **primary** node: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Nodes**. 1. Expand **Verification information** tab for that node to view automatic checksumming status for repositories and wikis. Successes are shown in green, pending work @@ -70,7 +70,7 @@ On the **primary** node: On the **secondary** node: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Nodes**. 1. Expand **Verification information** tab for that node to view automatic checksumming status for repositories and wikis. Successes are shown in green, pending work @@ -89,7 +89,7 @@ in sync. ## Repository re-verification -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8550) in GitLab Enterprise Edition 11.6. Available in [GitLab Premium](https://about.gitlab.com/pricing/). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8550) in GitLab 11.6. Due to bugs or transient infrastructure failures, it is possible for Git repositories to change unexpectedly without being marked for verification. @@ -100,7 +100,7 @@ increase load and vice versa. On the **primary** node: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Nodes**. 1. Select **Edit** for the **primary** node to customize the minimum re-verification interval: @@ -151,7 +151,7 @@ sudo gitlab-rake geo:verification:wiki:reset If the **primary** and **secondary** nodes have a checksum verification mismatch, the cause may not be apparent. To find the cause of a checksum mismatch: 1. On the **primary** node: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Projects**. 1. Find the project that you want to check the checksum differences and select its name. diff --git a/doc/administration/geo/disaster_recovery/planned_failover.md b/doc/administration/geo/disaster_recovery/planned_failover.md index 8b55bebb42b..a7a64701cbd 100644 --- a/doc/administration/geo/disaster_recovery/planned_failover.md +++ b/doc/administration/geo/disaster_recovery/planned_failover.md @@ -111,7 +111,7 @@ ensure these processes are close to 100% as possible during active use. On the **secondary** node: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Nodes**. Replicated objects (shown in green) should be close to 100%, and there should be no failures (shown in red). If a large proportion of @@ -139,7 +139,7 @@ This [content was moved to another location](background_verification.md). On the **primary** node: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Messages**. 1. Add a message notifying users on the maintenance window. You can check under **Geo > Nodes** to estimate how long it @@ -152,7 +152,7 @@ To ensure that all data is replicated to a secondary site, updates (write reques be disabled on the **primary** site: 1. Enable [maintenance mode](../../maintenance_mode/index.md) on the **primary** node. -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. On the Sidekiq dashboard, select **Cron**. 1. Select `Disable All` to disable non-Geo periodic background jobs. @@ -165,7 +165,7 @@ be disabled on the **primary** site: 1. If you are manually replicating any data not managed by Geo, trigger the final replication process now. 1. On the **primary** node: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. On the Sidekiq dashboard, select **Queues**, and wait for all queues except those with `geo` in the name to drop to 0. @@ -180,7 +180,7 @@ be disabled on the **primary** site: - The Geo log cursor is up to date (0 events behind). 1. On the **secondary** node: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. On the Sidekiq dashboard, select **Queues**, and wait for all the `geo` queues to drop to 0 queued and 0 running jobs. diff --git a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md index 27990748071..4255fba83f6 100644 --- a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md +++ b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md @@ -65,7 +65,7 @@ promote a Geo replica and perform a failover. On the **secondary** node: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Nodes** to see its status. Replicated objects (shown in green) should be close to 100%, and there should be no failures (shown in red). If a large proportion of @@ -130,7 +130,7 @@ follow these steps to avoid unnecessary data loss: connection. 1. On the **primary** node: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. On the Sidekiq dhasboard, select **Cron**. 1. Select `Disable All` to disable any non-Geo periodic background jobs. @@ -148,7 +148,7 @@ follow these steps to avoid unnecessary data loss: [data not managed by Geo](../../replication/datatypes.md#limitations-on-replicationverification), trigger the final replication process now. 1. On the **primary** node: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. On the Sidekiq dashboard, select **Queues**, and wait for all queues except those with `geo` in the name to drop to 0. @@ -163,7 +163,7 @@ follow these steps to avoid unnecessary data loss: - The Geo log cursor is up to date (0 events behind). 1. On the **secondary** node: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. On the Sidekiq dashboard, select **Queues**, and wait for all the `geo` queues to drop to 0 queued and 0 running jobs. diff --git a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md index 9d5e65cd194..18923da1056 100644 --- a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md +++ b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md @@ -115,7 +115,7 @@ follow these steps to avoid unnecessary data loss: connection. 1. On the **primary** node: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. On the Sidekiq dhasboard, select **Cron**. 1. Select `Disable All` to disable any non-Geo periodic background jobs. @@ -133,7 +133,7 @@ follow these steps to avoid unnecessary data loss: [data not managed by Geo](../../replication/datatypes.md#limitations-on-replicationverification), trigger the final replication process now. 1. On the **primary** node: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. On the Sidekiq dashboard, select **Queues**, and wait for all queues except those with `geo` in the name to drop to 0. @@ -148,7 +148,7 @@ follow these steps to avoid unnecessary data loss: - The Geo log cursor is up to date (0 events behind). 1. On the **secondary** node: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. On the Sidekiq dashboard, select **Queues**, and wait for all the `geo` queues to drop to 0 queued and 0 running jobs. diff --git a/doc/administration/geo/index.md b/doc/administration/geo/index.md index 7175d41abd8..48091967189 100644 --- a/doc/administration/geo/index.md +++ b/doc/administration/geo/index.md @@ -7,12 +7,6 @@ type: howto # Geo **(PREMIUM SELF)** -> - Introduced in GitLab Enterprise Edition 8.9. -> - Using Geo in combination with -> [multi-node architectures](../reference_architectures/index.md) -> is considered **Generally Available** (GA) in -> [GitLab Premium](https://about.gitlab.com/pricing/) 10.4. - Geo is the solution for widely distributed development teams and for providing a warm-standby as part of a disaster recovery strategy. ## Overview @@ -144,7 +138,7 @@ The following table lists basic ports that must be open between the **primary** | 22 | 22 | TCP | | 5432 | | PostgreSQL | -See the full list of ports used by GitLab in [Package defaults](https://docs.gitlab.com/omnibus/package-information/defaults.html) +See the full list of ports used by GitLab in [Package defaults](../package_information/defaults.md) NOTE: [Web terminal](../../ci/environments/index.md#web-terminals) support requires your load balancer to correctly handle WebSocket connections. @@ -214,11 +208,11 @@ For information on configuring Geo, see [Geo configuration](replication/configur ### Updating Geo -For information on how to update your Geo site(s) to the latest GitLab version, see [Updating the Geo sites](replication/updating_the_geo_nodes.md). +For information on how to update your Geo site(s) to the latest GitLab version, see [Updating the Geo sites](replication/updating_the_geo_sites.md). ### Pausing and resuming replication -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35913) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35913) in GitLab 13.2. WARNING: In GitLab 13.2 and 13.3, promoting a secondary site to a primary while the @@ -230,7 +224,7 @@ WARNING: Pausing and resuming of replication is currently only supported for Geo installations using an Omnibus GitLab-managed database. External databases are currently not supported. -In some circumstances, like during [upgrades](replication/updating_the_geo_nodes.md) or a [planned failover](disaster_recovery/planned_failover.md), it is desirable to pause replication between the primary and secondary. +In some circumstances, like during [upgrades](replication/updating_the_geo_sites.md) or a [planned failover](disaster_recovery/planned_failover.md), it is desirable to pause replication between the primary and secondary. Pausing and resuming replication is done via a command line tool from the a node in the secondary site where the `postgresql` service is enabled. diff --git a/doc/administration/geo/replication/configuration.md b/doc/administration/geo/replication/configuration.md index 5b22741f578..88f1ad5b490 100644 --- a/doc/administration/geo/replication/configuration.md +++ b/doc/administration/geo/replication/configuration.md @@ -199,7 +199,7 @@ keys must be manually replicated to the **secondary** site. gitlab-ctl reconfigure ``` -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Sites**. 1. Select **New site**.  @@ -257,7 +257,7 @@ method to be enabled. This is enabled by default, but if converting an existing On the **primary** site: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand **Visibility and access controls**. 1. Ensure "Enabled Git access protocols" is set to either "Both SSH and HTTP(S)" or "Only HTTP(S)". @@ -267,7 +267,7 @@ On the **primary** site: You can sign in to the **secondary** site with the same credentials you used with the **primary** site. After you sign in: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Sites**. 1. Verify that it's correctly identified as a **secondary** Geo site, and that Geo is enabled. @@ -338,7 +338,7 @@ when: ## Upgrading Geo -See the [updating the Geo sites document](updating_the_geo_nodes.md). +See the [updating the Geo sites document](updating_the_geo_sites.md). ## Troubleshooting diff --git a/doc/administration/geo/replication/datatypes.md b/doc/administration/geo/replication/datatypes.md index a696e5410e5..3f38436429a 100644 --- a/doc/administration/geo/replication/datatypes.md +++ b/doc/administration/geo/replication/datatypes.md @@ -47,12 +47,16 @@ verification methods: | Blobs | Container registry _(object storage)_ | Geo with API/Managed/Docker API (*2*) | _Not implemented_ | | Blobs | Package registry _(file system)_ | Geo with API | SHA256 checksum | | Blobs | Package registry _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | +| Blobs | Infrastructure registry _(file system)_ | Geo with API | SHA256 checksum | +| Blobs | Infrastructure registry _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | | Blobs | Versioned Terraform State _(file system)_ | Geo with API | SHA256 checksum | | Blobs | Versioned Terraform State _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | | Blobs | External Merge Request Diffs _(file system)_ | Geo with API | _Not implemented_ | | Blobs | External Merge Request Diffs _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | | Blobs | Pipeline artifacts _(file system)_ | Geo with API | SHA256 checksum | | Blobs | Pipeline artifacts _(object storage)_ | Geo with API/Managed (*2*) | SHA256 checksum | +| Blobs | Pages _(file system)_ | Geo with API | _Not implemented_ | +| Blobs | Pages _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | - (*1*): Redis replication can be used as part of HA with Redis sentinel. It's not used between Geo sites. - (*2*): Object storage replication can be performed by Geo or by your object storage provider/appliance @@ -189,21 +193,15 @@ successfully, you must replicate their data using some other means. |[Job logs](../../job_logs.md) | **Yes** (10.4) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/8923) | Via Object Storage provider if supported. Native Geo support (Beta). | Verified only on transfer or manually using [Integrity Check Rake Task](../../raketasks/check.md) on both sites and comparing the output between them. | |[Container Registry](../../packages/container_registry.md) | **Yes** (12.3) | No | No | Disabled by default. See [instructions](docker_registry.md) to enable. | |[Content in object storage (beta)](object_storage.md) | **Yes** (12.4) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/13845) | No | | -|[Infrastructure Registry for Terraform Module](../../../user/packages/terraform_module_registry/index.md) | **Yes** (14.0) | [**Yes**](#limitation-of-verification-for-files-in-object-storage) (14.0) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default. | +|[Infrastructure Registry](../../../user/packages/infrastructure_registry/index.md) | **Yes** (14.0) | [**Yes**](#limitation-of-verification-for-files-in-object-storage) (14.0) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default. | |[Project designs repository](../../../user/project/issues/design_management.md) | **Yes** (12.7) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/32467) | No | Designs also require replication of LFS objects and Uploads. | -|[Package Registry for npm](../../../user/packages/npm_registry/index.md) | **Yes** (13.2) | [**Yes**](#limitation-of-verification-for-files-in-object-storage) (13.10) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default. | -|[Package Registry for Maven](../../../user/packages/maven_repository/index.md) | **Yes** (13.2) | [**Yes**](#limitation-of-verification-for-files-in-object-storage) (13.10) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default. | -|[Package Registry for Conan](../../../user/packages/conan_repository/index.md) | **Yes** (13.2) | [**Yes**](#limitation-of-verification-for-files-in-object-storage) (13.10) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default. | -|[Package Registry for NuGet](../../../user/packages/nuget_repository/index.md) | **Yes** (13.2) | [**Yes**](#limitation-of-verification-for-files-in-object-storage) (13.10) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default. | -|[Package Registry for PyPI](../../../user/packages/pypi_repository/index.md) | **Yes** (13.2) | [**Yes**](#limitation-of-verification-for-files-in-object-storage) (13.10) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default. | -|[Package Registry for Composer](../../../user/packages/composer_repository/index.md) | **Yes** (13.2) | [**Yes**](#limitation-of-verification-for-files-in-object-storage) (13.10) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default. | -|[Package Registry for generic packages](../../../user/packages/generic_packages/index.md) | **Yes** (13.5) | [**Yes**](#limitation-of-verification-for-files-in-object-storage) (13.10) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default. | +|[Package Registry](../../../user/packages/package_registry/index.md) | **Yes** (13.2) | [**Yes**](#limitation-of-verification-for-files-in-object-storage) (13.10) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default. | |[Versioned Terraform State](../../terraform_state.md) | **Yes** (13.5) | [**Yes**](#limitation-of-verification-for-files-in-object-storage) (13.12) | Via Object Storage provider if supported. Native Geo support (Beta). | Replication is behind the feature flag `geo_terraform_state_version_replication`, enabled by default. Verification was behind the feature flag `geo_terraform_state_version_verification`, which was removed in 14.0| |[External merge request diffs](../../merge_request_diffs.md) | **Yes** (13.5) | No | Via Object Storage provider if supported. Native Geo support (Beta). | Replication is behind the feature flag `geo_merge_request_diff_replication`, enabled by default. Verification is under development, behind the feature flag `geo_merge_request_diff_verification`, introduced in 14.0.| |[Versioned snippets](../../../user/snippets.md#versioned-snippets) | [**Yes** (13.7)](https://gitlab.com/groups/gitlab-org/-/epics/2809) | [**Yes** (14.2)](https://gitlab.com/groups/gitlab-org/-/epics/2810) | No | Verification was implemented behind the feature flag `geo_snippet_repository_verification` in 13.11, and the feature flag was removed in 14.2. | |[Server-side Git hooks](../../server_hooks.md) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1867) | No | No | | |[Elasticsearch integration](../../../integration/elasticsearch.md) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/1186) | No | No | | -|[GitLab Pages](../../pages/index.md) | [No](https://gitlab.com/groups/gitlab-org/-/epics/589) | No | Via Object Storage provider if supported. **No** native Geo support (Beta). | | +|[GitLab Pages](../../pages/index.md) | [**Yes** (14.3)](https://gitlab.com/groups/gitlab-org/-/epics/589) | No | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_pages_deployment_replication`, enabled by default. | |[Dependency proxy images](../../../user/packages/dependency_proxy/index.md) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/259694) | No | No | Blocked on [Geo: Secondary Mimicry](https://gitlab.com/groups/gitlab-org/-/epics/1528). Replication of this cache is not needed for Disaster Recovery purposes because it can be recreated from external sources. | |[Vulnerability Export](../../../user/application_security/vulnerability_report/#export-vulnerability-details) | [Not planned](https://gitlab.com/groups/gitlab-org/-/epics/3111) | No | | Not planned because they are ephemeral and sensitive. They can be regenerated on demand. | diff --git a/doc/administration/geo/replication/disable_geo.md b/doc/administration/geo/replication/disable_geo.md index 485a5ee1950..ae2597ad649 100644 --- a/doc/administration/geo/replication/disable_geo.md +++ b/doc/administration/geo/replication/disable_geo.md @@ -36,7 +36,7 @@ to do that. To remove the **primary** site: 1. [Remove all secondary Geo sites](remove_geo_site.md) -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Nodes**. 1. Select **Remove** for the **primary** node. 1. Confirm by selecting **Remove** when the prompt appears. diff --git a/doc/administration/geo/replication/docker_registry.md b/doc/administration/geo/replication/docker_registry.md index 5cc4f66017b..4004ef3c17f 100644 --- a/doc/administration/geo/replication/docker_registry.md +++ b/doc/administration/geo/replication/docker_registry.md @@ -130,7 +130,7 @@ For each application and Sidekiq node on the **secondary** site: To verify Container Registry replication is working, on the **secondary** site: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Nodes**. The initial replication, or "backfill", is probably still in progress. diff --git a/doc/administration/geo/replication/faq.md b/doc/administration/geo/replication/faq.md index 28030dccb3b..70a6e506c28 100644 --- a/doc/administration/geo/replication/faq.md +++ b/doc/administration/geo/replication/faq.md @@ -52,7 +52,7 @@ query. ## Can I `git push` to a **secondary** site? -Yes! Pushing directly to a **secondary** site (for both HTTP and SSH, including Git LFS) was [introduced](https://about.gitlab.com/releases/2018/09/22/gitlab-11-3-released/) in [GitLab Premium](https://about.gitlab.com/pricing/#self-managed) 11.3. +Yes! Pushing directly to a **secondary** site (for both HTTP and SSH, including Git LFS) was [introduced](https://about.gitlab.com/releases/2018/09/22/gitlab-11-3-released/) in GitLab 11.3. ## How long does it take to have a commit replicated to a **secondary** site? diff --git a/doc/administration/geo/replication/object_storage.md b/doc/administration/geo/replication/object_storage.md index d3931c0ba80..1f799b30125 100644 --- a/doc/administration/geo/replication/object_storage.md +++ b/doc/administration/geo/replication/object_storage.md @@ -9,15 +9,19 @@ type: howto Geo can be used in combination with Object Storage (AWS S3, or other compatible object storage). -The storage method for files is recorded in the database, and the database is replicated -from the **primary** Geo site to the **secondary** Geo site, so the **secondary** Geo site -must match the storage method of the **primary** Geo site. -Therefore, if the **primary** Geo site uses object storage, the **secondary** Geo site must use it too. - Currently, **secondary** sites can use either: - The same storage bucket as the **primary** site. - A replicated storage bucket. +- Local storage, if the primary uses local storage. + +The storage method (local or object storage) for files is recorded in the database, and the database +is replicated from the **primary** Geo site to the **secondary** Geo site. + +When accessing an uploaded object, we get its storage method (local or object storage) from the +database, so the **secondary** Geo site must match the storage method of the **primary** Geo site. + +Therefore, if the **primary** Geo site uses object storage, the **secondary** Geo site must use it too. To have: @@ -38,7 +42,7 @@ whether they are stored on the local file system or in object storage. To enable GitLab replication: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Nodes**. 1. Select **Edit** on the **secondary** site. 1. In the **Synchronization Settings** section, find the **Allow this secondary node to replicate content on Object Storage** diff --git a/doc/administration/geo/replication/remove_geo_site.md b/doc/administration/geo/replication/remove_geo_site.md index 274eb28dbc9..b69dfe2e723 100644 --- a/doc/administration/geo/replication/remove_geo_site.md +++ b/doc/administration/geo/replication/remove_geo_site.md @@ -9,7 +9,7 @@ type: howto **Secondary** sites can be removed from the Geo cluster using the Geo administration page of the **primary** site. To remove a **secondary** site: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Nodes**. 1. Select the **Remove** button for the **secondary** site you want to remove. 1. Confirm by selecting **Remove** when the prompt appears. diff --git a/doc/administration/geo/replication/troubleshooting.md b/doc/administration/geo/replication/troubleshooting.md index e072696b37c..7b82d742bd5 100644 --- a/doc/administration/geo/replication/troubleshooting.md +++ b/doc/administration/geo/replication/troubleshooting.md @@ -27,7 +27,7 @@ Before attempting more advanced troubleshooting: On the **primary** node: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Nodes**. We perform the following health checks on each **secondary** node @@ -610,7 +610,7 @@ to start again from scratch, there are a few steps that can help you: ### Design repository failures on mirrored projects and project imports -On the top bar, under **Menu >** **{admin}** **Admin > Geo > Nodes**, +On the top bar, under **Menu > Admin > Geo > Nodes**, if the Design repositories progress bar shows `Synced` and `Failed` greater than 100%, and negative `Queued`, then the instance is likely affected by @@ -836,7 +836,7 @@ node's URL matches its external URL. On the **primary** node: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Nodes**. 1. Find the affected **secondary** site and select **Edit**. 1. Ensure the **URL** field matches the value found in `/etc/gitlab/gitlab.rb` diff --git a/doc/administration/geo/replication/tuning.md b/doc/administration/geo/replication/tuning.md index 9807f3e6444..bcff6181296 100644 --- a/doc/administration/geo/replication/tuning.md +++ b/doc/administration/geo/replication/tuning.md @@ -14,7 +14,7 @@ in the background. On the **primary** site: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Nodes**. 1. Select **Edit** of the secondary node you want to tune. 1. Under **Tuning settings**, there are several variables that can be tuned to diff --git a/doc/administration/geo/replication/updating_the_geo_nodes.md b/doc/administration/geo/replication/updating_the_geo_nodes.md index 03570048071..f07c8d547a4 100644 --- a/doc/administration/geo/replication/updating_the_geo_nodes.md +++ b/doc/administration/geo/replication/updating_the_geo_nodes.md @@ -1,52 +1,9 @@ --- -stage: Enablement -group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: howto +redirect_to: 'updating_the_geo_sites.md' +remove_date: '2021-11-23' --- -# Updating the Geo nodes **(PREMIUM SELF)** +This file was moved to [another location](updating_the_geo_sites.md). -WARNING: -Read these sections carefully before updating your Geo nodes. Not following -version-specific update steps may result in unexpected downtime. If you have -any specific questions, [contact Support](https://about.gitlab.com/support/#contact-support). - -Updating Geo nodes involves performing: - -1. [Version-specific update steps](version_specific_updates.md), depending on the - version being updated to or from. -1. [General update steps](#general-update-steps), for all updates. - -## General update steps - -NOTE: -These general update steps are not intended for [high-availability deployments](https://docs.gitlab.com/omnibus/update/README.html#multi-node--ha-deployment), and will cause downtime. If you want to avoid downtime, consider using [zero downtime updates](https://docs.gitlab.com/omnibus/update/README.html#zero-downtime-updates). - -To update the Geo nodes when a new GitLab version is released, update **primary** -and all **secondary** nodes: - -1. **Optional:** [Pause replication on each **secondary** node.](../index.md#pausing-and-resuming-replication) -1. Log into the **primary** node. -1. [Update GitLab on the **primary** node using Omnibus](https://docs.gitlab.com/omnibus/update/#update-using-the-official-repositories). -1. Log into each **secondary** node. -1. [Update GitLab on each **secondary** node using Omnibus](https://docs.gitlab.com/omnibus/update/#update-using-the-official-repositories). -1. If you paused replication in step 1, [resume replication on each **secondary**](../index.md#pausing-and-resuming-replication) -1. [Test](#check-status-after-updating) **primary** and **secondary** nodes, and check version in each. - -### Check status after updating - -Now that the update process is complete, you may want to check whether -everything is working correctly: - -1. Run the Geo Rake task on all nodes, everything should be green: - - ```shell - sudo gitlab-rake gitlab:geo:check - ``` - -1. Check the **primary** node's Geo dashboard for any errors. -1. Test the data replication by pushing code to the **primary** node and see if it - is received by **secondary** nodes. - -If you encounter any issues, see the [Geo troubleshooting guide](troubleshooting.md). +<!-- This redirect file can be deleted after <2021-11-23>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/geo/replication/updating_the_geo_sites.md b/doc/administration/geo/replication/updating_the_geo_sites.md new file mode 100644 index 00000000000..e82afe5f0d4 --- /dev/null +++ b/doc/administration/geo/replication/updating_the_geo_sites.md @@ -0,0 +1,54 @@ +--- +stage: Enablement +group: Geo +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: howto +--- + +# Updating the Geo sites **(PREMIUM SELF)** + +WARNING: +Read these sections carefully before updating your Geo sites. Not following +version-specific update steps may result in unexpected downtime. If you have +any specific questions, [contact Support](https://about.gitlab.com/support/#contact-support). + +Updating Geo sites involves performing: + +1. [Version-specific update steps](version_specific_updates.md), depending on the + version being updated to or from. +1. [General update steps](#general-update-steps), for all updates. + +## General update steps + +NOTE: +These general update steps are not intended for multi-site deployments, +and will cause downtime. If you want to avoid downtime, consider using +[zero downtime upgrades](../../../update/zero_downtime.md#multi-node--ha-deployment-with-geo). + +To update the Geo sites when a new GitLab version is released, update **primary** +and all **secondary** sites: + +1. **Optional:** [Pause replication on each **secondary** sites.](../index.md#pausing-and-resuming-replication) +1. SSH into each node of the **primary** site. +1. [Upgrade GitLab on the **primary** site](../../../update/package/index.md#upgrade-using-the-official-repositories). +1. SSH into each node of **secondary** sites. +1. [Upgrade GitLab on each **secondary** site](../../../update/package/index.md#upgrade-using-the-official-repositories). +1. If you paused replication in step 1, [resume replication on each **secondary**](../index.md#pausing-and-resuming-replication) +1. [Test](#check-status-after-updating) **primary** and **secondary** sites, and check version in each. + +### Check status after updating + +Now that the update process is complete, you may want to check whether +everything is working correctly: + +1. Run the Geo Rake task on an application node for the primary and secondary sites. Everything should be green: + + ```shell + sudo gitlab-rake gitlab:geo:check + ``` + +1. Check the **primary** site's Geo dashboard for any errors. +1. Test the data replication by pushing code to the **primary** site and see if it + is received by **secondary** sites. + +If you encounter any issues, see the [Geo troubleshooting guide](troubleshooting.md). diff --git a/doc/administration/geo/replication/usage.md b/doc/administration/geo/replication/usage.md index 7fe8eec467e..f3c8f6ac759 100644 --- a/doc/administration/geo/replication/usage.md +++ b/doc/administration/geo/replication/usage.md @@ -11,7 +11,7 @@ type: howto After you set up the [database replication and configure the Geo nodes](../index.md#setup-instructions), use your closest GitLab site as you would do with the primary one. -You can push directly to a **secondary** site (for both HTTP, SSH including Git LFS), and the request will be proxied to the primary site instead ([introduced](https://about.gitlab.com/releases/2018/09/22/gitlab-11-3-released/) in [GitLab Premium](https://about.gitlab.com/pricing/#self-managed) 11.3). +You can push directly to a **secondary** site (for both HTTP, SSH including Git LFS), and the request will be proxied to the primary site instead ([introduced](https://about.gitlab.com/releases/2018/09/22/gitlab-11-3-released/) in GitLab 11.3). Example of the output you will see when pushing to a **secondary** site: @@ -33,3 +33,13 @@ you can't store credentials in the URL like `user:password@URL`. Instead, you ca for Unix-like operating systems or `_netrc` for Windows. In that case, the credentials will be stored as a plain text. If you're looking for a more secure way to store credentials, you can use [Git Credential Storage](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage). + +## Fetch Go modules from Geo secondary sites + +Go modules can be pulled from secondary sites, with a number of limitations: + +- Git configuration (using `insteadOf`) is needed to fetch data from the Geo secondary site. +- For private projects, authentication details need to be specified in `~/.netrc`. + +Read more in the +[working with projects `go get` documentation](../../../user/project/working_with_projects.md#fetch-go-modules-from-geo-secondary-sites). diff --git a/doc/administration/geo/replication/version_specific_updates.md b/doc/administration/geo/replication/version_specific_updates.md index 155c06f90b8..84193e6baac 100644 --- a/doc/administration/geo/replication/version_specific_updates.md +++ b/doc/administration/geo/replication/version_specific_updates.md @@ -8,9 +8,44 @@ type: howto # Version-specific update instructions **(PREMIUM SELF)** Review this page for update instructions for your version. These steps -accompany the [general steps](updating_the_geo_nodes.md#general-update-steps) +accompany the [general steps](updating_the_geo_sites.md#general-update-steps) for updating Geo nodes. +## Updating to 14.1, 14.2, 14.3 + +We found an [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/336013) where the Container Registry replication wasn't fully working if you used multi-arch images. In case of a multi-arch image, only the primary architecture (for example `amd64`) would be replicated to the secondary node. This has been [fixed in GitLab 14.3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67624) and was backported to 14.2 and 14.1, but manual steps are required to force a re-sync. + +You can check if you are affected by running: + +```shell +docker manifest inspect <SECONDARY_IMAGE_LOCATION> | jq '.mediaType' +``` + +Where `<SECONDARY_IMAGE_LOCATION>` is a container image on your secondary node. +If the output matches `application/vnd.docker.distribution.manifest.list.v2+json` +(there can be a `mediaType` entry at several levels, we only care about the top level entry), +then you don't need to do anything. + +Otherwise, on all your **secondary** nodes, in a [Rails console](../../operations/rails_console.md), run the following: + + ```ruby + list_type = 'application/vnd.docker.distribution.manifest.list.v2+json' + + Geo::ContainerRepositoryRegistry.synced.each do |gcr| + cr = gcr.container_repository + primary = Geo::ContainerRepositorySync.new(cr) + cr.tags.each do |tag| + primary_manifest = JSON.parse(primary.send(:client).repository_raw_manifest(cr.path, tag.name)) + next unless primary_manifest['mediaType'].eql?(list_type) + + cr.delete_tag_by_name(tag.name) + end + primary.execute + end + ``` + +If you are running a version prior to 14.1 and are using Geo and multi-arch containers in your Container Registry, we recommend [upgrading](updating_the_geo_sites.md) to at least GitLab 14.1. + ## Updating to GitLab 14.0/14.1 We found an issue where [Primary sites can not be removed from the UI](https://gitlab.com/gitlab-org/gitlab/-/issues/338231). @@ -277,7 +312,7 @@ GitLab 12.2 includes the following minor PostgreSQL updates: This update occurs even if major PostgreSQL updates are disabled. -Before [refreshing Foreign Data Wrapper during a Geo upgrade](https://docs.gitlab.com/omnibus/update/README.html#run-post-deployment-migrations-and-checks), +Before [refreshing Foreign Data Wrapper during a Geo upgrade](../../../update/zero_downtime.md#step-4-run-post-deployment-migrations-and-checks), restart the Geo tracking database: ```shell diff --git a/doc/administration/geo/setup/database.md b/doc/administration/geo/setup/database.md index fa343f7eb40..d72bb0737ae 100644 --- a/doc/administration/geo/setup/database.md +++ b/doc/administration/geo/setup/database.md @@ -501,6 +501,79 @@ two other clusters of nodes supporting a Geo **secondary** site. One for the main database and the other for the tracking database. For more information, see [High Availability with Omnibus GitLab](../../postgresql/replication_and_failover.md). +### Changing the replication password + +To change the password for the [replication user](https://wiki.postgresql.org/wiki/Streaming_Replication) +when using Omnibus-managed PostgreSQL instances: + +On the GitLab Geo **primary** server: + +1. The default value for the replication user is `gitlab_replicator`, but if you've set a custom replication + user in your `/etc/gitlab/gitlab.rb` under the `postgresql['sql_replication_user']` setting, make sure to + adapt the following instructions for your own user. + + Generate an MD5 hash of the desired password: + + ```shell + sudo gitlab-ctl pg-password-md5 gitlab_replicator + # Enter password: <your_password_here> + # Confirm password: <your_password_here> + # 950233c0dfc2f39c64cf30457c3b7f1e + ``` + + Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + # Fill with the hash generated by `gitlab-ctl pg-password-md5 gitlab_replicator` + postgresql['sql_replication_password'] = '<md5_hash_of_your_password>' + ``` + +1. Save the file and reconfigure GitLab to change the replication user's password in PostgreSQL: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +1. Restart PostgreSQL for the replication password change to take effect: + + ```shell + sudo gitlab-ctl restart postgresql + ``` + +Until the password is updated on any **secondary** servers, the [PostgreSQL log](../../logs.md#postgresql-logs) on +the secondaries will report the following error message: + +```console +FATAL: could not connect to the primary server: FATAL: password authentication failed for user "gitlab_replicator" +``` + +On all GitLab Geo **secondary** servers: + +1. The first step isn't necessary from a configuration perspective, since the hashed `'sql_replication_password'` + is not used on the GitLab Geo **secondary**. However in the event that **secondary** needs to be promoted + to the GitLab Geo **primary**, make sure to match the `'sql_replication_password'` in the secondary + server configuration. + + Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + # Fill with the hash generated by `gitlab-ctl pg-password-md5 gitlab_replicator` on the Geo primary + postgresql['sql_replication_password'] = '<md5_hash_of_your_password>' + ``` + +1. During the initial replication setup, the `gitlab-ctl replicate-geo-database` command writes the plaintext + password for the replication user account to two locations: + + - `gitlab-geo.conf`: Used by the PostgreSQL replication process, written to the PostgreSQL data + directory, by default at `/var/opt/gitlab/postgresql/data/gitlab-geo.conf`. + - `.pgpass`: Used by the `gitlab-psql` user, located by default at `/var/opt/gitlab/postgresql/.pgpass`. + + Update the plaintext password in both of these files, and restart PostgreSQL: + + ```shell + sudo gitlab-ctl restart postgresql + ``` + ## Multi-node database replication In GitLab 14.0, Patroni replaced `repmgr` as the supported @@ -521,7 +594,7 @@ For instructions about how to set up Patroni on the primary site, see the #### Configuring Patroni cluster for a Geo secondary site -In a Geo secondary site, the main PostgreSQL database is a read-only replica of the primary site’s PostgreSQL database. +In a Geo secondary site, the main PostgreSQL database is a read-only replica of the primary site's PostgreSQL database. If you are currently using `repmgr` on your Geo primary site, see [these instructions](#migrating-from-repmgr-to-patroni) for migrating from `repmgr` to Patroni. @@ -651,7 +724,7 @@ Refer to your preferred Load Balancer's documentation for further guidance. ##### Step 3. Configure a PgBouncer node on the secondary site A production-ready and highly available configuration requires at least -three Consul nodes, a minimum of one PgBouncer node, but it’s recommended to have +three Consul nodes, a minimum of one PgBouncer node, but it's recommended to have one per database node. An internal load balancer (TCP) is required when there is more than one PgBouncer service nodes. The internal load balancer provides a single endpoint for connecting to the PgBouncer cluster. For more information, diff --git a/doc/administration/geo/setup/external_database.md b/doc/administration/geo/setup/external_database.md index 56d196b54ec..13dbf9d1434 100644 --- a/doc/administration/geo/setup/external_database.md +++ b/doc/administration/geo/setup/external_database.md @@ -249,7 +249,7 @@ the tracking database on port 5432. gitlab-rake geo:db:create ``` -1. The reconfigure should automatically migrate the database. You can migrate the database manually if needed, for example if `gitlab_rails['auto_migrate'] = false`: +1. The reconfigure should automatically migrate the database. You can migrate the database manually if needed, for example if `geo_secondary['auto_migrate'] = false`: ```shell gitlab-rake geo:db:migrate diff --git a/doc/administration/get_started.md b/doc/administration/get_started.md index 6fe66aa1642..c0d5a45d8d1 100644 --- a/doc/administration/get_started.md +++ b/doc/administration/get_started.md @@ -137,7 +137,7 @@ Keep your configuration files and backup archives in a separate location to ensu You can restore a backup only to **the exact same version and type** (Community Edition/Enterprise Edition) of GitLab on which it was created. - Review the [Omnibus backup and restore documentation](https://docs.gitlab.com/omnibus/settings/backups). -- Review the [Helm Chart backup and restore documentation](https://docs.gitlab.com/charts/backup-restore). +- Review the [Helm Chart backup and restore documentation](https://docs.gitlab.com/charts/backup-restore/). ### Back up GitLab SaaS @@ -177,7 +177,7 @@ The EC2 instance meets the requirements for an application data backup by taking In general, if you're running GitLab on a virtualized server, you can create VM snapshots of the entire GitLab server. It is common for a VM snapshot to require you to power down the server. -#### Option 2: GitLab Geo +#### Option 2: GitLab Geo **(PREMIUM SELF)** Geo provides local, read-only instances of your GitLab instances. @@ -191,7 +191,7 @@ Learn more about [replication limitations](../administration/geo/replication/dat GitLab provides support for self-managed GitLab through different channels. -- Priority support: Premium and Ultimate self-managed customers receive priority support with tiered response times. +- Priority support: [Premium and Ultimate](https://about.gitlab.com/pricing/) self-managed customers receive priority support with tiered response times. Learn more about [upgrading to priority support](https://about.gitlab.com/support/#upgrading-to-priority-support). - Live upgrade assistance: Get one-on-one expert guidance during a production upgrade. With your **priority support plan**, you're eligible for a live, scheduled screen-sharing session with a member of our support team. diff --git a/doc/administration/git_protocol.md b/doc/administration/git_protocol.md index e3e2db81fb0..c8c532e9a01 100644 --- a/doc/administration/git_protocol.md +++ b/doc/administration/git_protocol.md @@ -99,7 +99,7 @@ $ GIT_TRACE_PACKET=1 git -c protocol.version=2 ls-remote https://your-gitlab-ins Verify Git v2 is used by the client: ```shell -GIT_SSH_COMMAND="ssh -v" git -c protocol.version=2 ls-remote ssh://git@your-gitlab-instance.com/group/repo.git 2>&1 |grep GIT_PROTOCOL +GIT_SSH_COMMAND="ssh -v" git -c protocol.version=2 ls-remote ssh://git@your-gitlab-instance.com/group/repo.git 2>&1 | grep GIT_PROTOCOL ``` You should see that the `GIT_PROTOCOL` environment variable is sent: diff --git a/doc/administration/gitaly/configure_gitaly.md b/doc/administration/gitaly/configure_gitaly.md index 5e8cbac42c1..d0841f4e607 100644 --- a/doc/administration/gitaly/configure_gitaly.md +++ b/doc/administration/gitaly/configure_gitaly.md @@ -41,9 +41,8 @@ However, Gitaly can be deployed to its own server, which can benefit GitLab inst multiple machines. NOTE: -When configured to run on their own servers, Gitaly servers -[must be upgraded](https://docs.gitlab.com/omnibus/update/#upgrading-gitaly-servers) before Gitaly -clients in your cluster. +When configured to run on their own servers, Gitaly servers must be +[upgraded](../../update/package/index.md) before Gitaly clients in your cluster. The process for setting up Gitaly on its own server is: @@ -340,6 +339,12 @@ disable enforcement. For more information, see the documentation on configuring 1. Run `sudo -u git /home/git/gitaly/gitaly-hooks check /home/git/gitaly/config.toml` to confirm that Gitaly can perform callbacks to the GitLab internal API. +WARNING: +If directly copying repository data from a GitLab server to Gitaly, ensure that the metadata file, +default path `/var/opt/gitlab/git-data/repositories/.gitaly-metadata`, is not included in the transfer. +Copying this file causes GitLab to use the [Rugged patches](index.md#direct-access-to-git-in-gitlab) for repositories hosted on the Gitaly server, +leading to `Error creating pipeline` and `Commit not found` errors, or stale data. + ### Configure Gitaly clients As the final step, you must update Gitaly clients to switch from using local Gitaly service to use diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md index bca83e903ac..7a7aac884ed 100644 --- a/doc/administration/gitaly/index.md +++ b/doc/administration/gitaly/index.md @@ -87,11 +87,8 @@ Gitaly comes pre-configured with Omnibus GitLab, which is a configuration - Omnibus GitLab installations for up to 2000 users, see [specific Gitaly configuration instructions](../reference_architectures/2k_users.md#configure-gitaly). - Source installations or custom Gitaly installations, see [Configure Gitaly](configure_gitaly.md). -GitLab installations for more than 2000 users should use Gitaly Cluster. - -NOTE: -If not set in GitLab, feature flags are read as false from the console and Gitaly uses their -default value. The default value depends on the GitLab version. +GitLab installations for more than 2000 active users performing daily Git write operation may be +best suited by using Gitaly Cluster. ## Gitaly Cluster @@ -137,7 +134,7 @@ In this example: - The [replication factor](#replication-factor) is `3`. There are three copies maintained of each repository. -The availability objectives for Gitaly clusters are: +The availability objectives for Gitaly clusters assuming a single node failure are: - **Recovery Point Objective (RPO):** Less than 1 minute. @@ -155,6 +152,58 @@ The availability objectives for Gitaly clusters are: Faster outage detection, to improve this speed to less than 1 second, is tracked [in this issue](https://gitlab.com/gitlab-org/gitaly/-/issues/2608). +WARNING: +If complete cluster failure occurs, disaster recovery plans should be executed. These can affect the +RPO and RTO discussed above. + +### Architecture and configuration recommendations + +The following table provides recommendations based on your +requirements. Users means concurrent users actively performing +simultaneous Git Operations. + +Gitaly services are present in every GitLab installation and always coordinates Git repository storage and +retrieval. Gitaly can be as simple as a single background service when operating on a single instance Omnibus +GitLab (All of GitLab on one machine). Gitaly can be separated into it's own instance and it can be configured in +a full cluster configuration depending on scaling and availability requirements. + +The GitLab Reference Architectures provide guidance for what Gitaly configuration is advisable at each of the scales. +The Gitaly configuration is noted by the architecture diagrams and the table of required resources. + +| User Scaling | Reference Architecture To Use | GitLab Instance Configuration | Gitaly Configuration | Git Repository Storage | Instances Dedicated to Gitaly Services | +| ------------------------------------------------------------ | ------------------------------------------------------------ | -------------------------------------------- | ------------------------------- | ---------------------------------- | -------------------------------------- | +| Up to 1000 Users | [1K](../reference_architectures/1k_users.md) | Single Instance for all of GitLab | Already Integrated as a Service | Local Disk | 0 | +| Up to 2999 Users | [2K](../reference_architectures/2k_users.md) | Horizontally Scaled GitLab Instance (Non-HA) | Single Gitaly Server | Local Disk of Gitaly Instance | 1 | +| 3000 Users and Over | [3K](../reference_architectures/1k_users.md) | Horizontally Scaled GitLab Instance with HA | Gitaly Cluster | Local Disk of Each Gitaly Instance | 8 | +| RTO/RPO Requirements for AZ Failure Tolerance Regardless of User Scale | [3K (with downscaling)](../reference_architectures/3k_users.md) | Custom (1) | Gitaly Cluster | Local Disk of Each Gitaly Instance | 8 | + +1. If you feel that you need AZ Failure Tolerance for user scaling lower than 3K, please contact Customer Success + to discuss your RTO and RPO needs and what options exist to meet those objectives. + +WARNING: +At present, some [known database inconsistency issues](#known-issues-impacting-gitaly-cluster) +exist in Gitaly Cluster. It is our recommendation that for now, you remain on your current service. +We will adjust the date for NFS support removal if this applies to you. + +### Known issues impacting Gitaly Cluster + +The following table outlines current known issues impacting the use of Gitaly Cluster. For +the most up to date status of these issues, please refer to the referenced issues / epics. + +| Issue | Summary | +| Gitaly Cluster + Geo can cause database inconsistencies | There are some conditions during Geo replication that can cause database inconsistencies with Gitaly Cluster. These have been identified and are being resolved by updating Gitaly Cluster to [identify repositories with a unique and persistent identifier](https://gitlab.com/gitlab-org/gitaly/-/issues/3485). | +| Database inconsistencies due to repository access outside of Gitaly Cluster's control | Operations that write to the repository storage which do not go through normal Gitaly Cluster methods can cause database inconsistencies. These can include (but are not limited to) snapshot restoration for cluster node disks, node upgrades which modify files under Git control, or any other disk operation that may touch repository storage external to GitLab. The Gitaly team is actively working to provide manual commands to [reconcile the Praefect database with the repository storage](https://gitlab.com/groups/gitlab-org/-/epics/6723). | + +### Snapshot backup and recovery limitations + +Gitaly Cluster does not support snapshot backups because these can cause issues where the +Praefect database becomes out of sync with the disk storage. Because of how Praefect rebuilds +the replication metadata of Gitaly disk information during a restore, we recommend using the +[official backup and restore Rake tasks](../../raketasks/backup_restore.md). + +To track progress on work on a solution for manually re-synchronizing the Praefect database +with disk storage, see [this epic](https://gitlab.com/groups/gitlab-org/-/epics/6575). + ### Virtual storage Virtual storage makes it viable to have a single repository storage in GitLab to simplify repository @@ -306,7 +355,10 @@ For configuration information, see [Configure replication factor](praefect.md#co For more information on configuring Gitaly Cluster, see [Configure Gitaly Cluster](praefect.md). -### Migrate to Gitaly Cluster +## Migrate to Gitaly Cluster + +We recommend you migrate to Gitaly Cluster if your +[requirements recommend](#architecture-and-configuration-recommendations) Gitaly Cluster. Whether migrating to Gitaly Cluster because of [NFS support deprecation](index.md#nfs-deprecation-notice) or to move from single Gitaly nodes, the basic process involves: @@ -318,6 +370,11 @@ or to move from single Gitaly nodes, the basic process involves: Gitaly Cluster, existing repositories stored outside Gitaly Cluster must be moved. There is no automatic migration but the moves can be scheduled with the GitLab API. +WARNING: +At present, some [known database inconsistency issues](#known-issues-impacting-gitaly-cluster) +exist in Gitaly Cluster. It is our recommendation that for now, you remain on your current service. +We will adjust the date for NFS support removal if this applies to you. + ## Monitor Gitaly and Gitaly Cluster You can use the available logs and [Prometheus metrics](../monitoring/prometheus/index.md) to @@ -449,6 +506,8 @@ To monitor [strong consistency](#strong-consistency), you can use the following - `gitaly_hook_transaction_voting_delay_seconds`, the client-side delay introduced by waiting for the transaction to be committed. +You can also monitor the [Praefect logs](../logs.md#praefect-logs). + ## Do not bypass Gitaly GitLab doesn't advise directly accessing Gitaly repositories stored on disk with a Git client, @@ -539,12 +598,6 @@ To see if GitLab can access the repository file system directly, we use the foll Direct Git access is enable by default in Omnibus GitLab because it fills in the correct repository paths in the GitLab configuration file `config/gitlab.yml`. This satisfies the UUID check. -WARNING: -If directly copying repository data from a GitLab server to Gitaly, ensure that the metadata file, -default path `/var/opt/gitlab/git-data/repositories/.gitaly-metadata`, is not included in the transfer. -Copying this file causes GitLab to use the Rugged patches for repositories hosted on the Gitaly server, -leading to `Error creating pipeline` and `Commit not found` errors, or stale data. - ### Transition to Gitaly Cluster For the sake of removing complexity, we must remove direct Git access in GitLab. However, we can't diff --git a/doc/administration/gitaly/praefect.md b/doc/administration/gitaly/praefect.md index 4af7f1a58a5..eb666f1caf4 100644 --- a/doc/administration/gitaly/praefect.md +++ b/doc/administration/gitaly/praefect.md @@ -20,10 +20,6 @@ Configure Gitaly Cluster using either: Smaller GitLab installations may need only [Gitaly itself](index.md). -NOTE: -Upgrade instructions for Omnibus GitLab installations -[are available](https://docs.gitlab.com/omnibus/update/#gitaly-cluster). - ## Requirements The minimum recommended configuration for a Gitaly Cluster requires: @@ -279,7 +275,7 @@ you need to prepare PostgreSQL server with [setup instruction](#manual-database- ```ruby pgbouncer['databases'] = { - # Other database configuation including gitlabhq_production + # Other database configuration including gitlabhq_production ... praefect_production: { @@ -353,6 +349,7 @@ If there are multiple Praefect nodes: To complete this section you need a [configured PostgreSQL server](#postgresql), including: +WARNING: Praefect should be run on a dedicated node. Do not run Praefect on the application server, or a Gitaly node. @@ -994,7 +991,7 @@ Particular attention should be shown to: 1. Check that the Praefect storage is configured to store new repositories: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Repository**. 1. Expand the **Repository storage** section. @@ -1574,3 +1571,28 @@ sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.t - Replace the placeholder `<virtual-storage>` with the virtual storage containing the Gitaly node storage to be checked. - Replace the placeholder `<up-to-date-storage>` with the Gitaly storage name containing up to date repositories. - Replace the placeholder `<outdated-storage>` with the Gitaly storage name containing outdated repositories. + +### Manually remove repositories + +> [Introduced](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/3767) in GitLab 14.3. + +The `remove-repository` Praefect sub-command removes repositories from a Gitaly Cluster. It removes +all state associated with a given repository including: + +- On-disk repositories on all relevant Gitaly nodes. +- Any database state tracked by Praefect. + +```shell +sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml remove-repository -virtual-storage <virtual-storage> -repository <repository> +``` + +- `-virtual-storage` is the virtual storage the repository is located in. +- `-repository` is the repository's relative path in the storage. + +Sometimes parts of the repository continue to exist after running `remove-repository`. This can be caused +because of: + +- A deletion error. +- An in-flight RPC call targeting the repository. + +If this occurs, run `remove-repository` again. diff --git a/doc/administration/gitaly/troubleshooting.md b/doc/administration/gitaly/troubleshooting.md index 3dd700968f9..1b53a0994f5 100644 --- a/doc/administration/gitaly/troubleshooting.md +++ b/doc/administration/gitaly/troubleshooting.md @@ -23,7 +23,7 @@ See also [Gitaly timeout](../../user/admin_area/settings/gitaly_timeouts.md) set When using standalone Gitaly servers, you must make sure they are the same version as GitLab to ensure full compatibility: -1. On the top bar, select **Menu >** **{admin}** **Admin** on your GitLab instance. +1. On the top bar, select **Menu > Admin** on your GitLab instance. 1. On the left sidebar, select **Overview > Gitaly Servers**. 1. Confirm all Gitaly servers indicate that they are up to date. @@ -226,8 +226,8 @@ update the secrets file on the Gitaly server to match the Gitaly client, then ### Repository pushes fail with a `deny updating a hidden ref` error Due to [a change](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/3426) -introduced in GitLab 13.12, Gitaly has read-only, internal GitLab references that users are not -permitted to update. If you attempt to update internal references with `git push --mirror`, Git +introduced in GitLab 13.12, Gitaly has read-only, internal GitLab references that users are not +permitted to update. If you attempt to update internal references with `git push --mirror`, Git returns the rejection error, `deny updating a hidden ref`. The following references are read-only: @@ -243,7 +243,7 @@ To mirror-push branches and tags only, and avoid attempting to mirror-push prote git push origin +refs/heads/*:refs/heads/* +refs/tags/*:refs/tags/* ``` -Any other namespaces that the admin wants to push can be included there as well via additional patterns. +Any other namespaces that the admin wants to push can be included there as well via additional patterns. ### Command line tools cannot connect to Gitaly diff --git a/doc/administration/housekeeping.md b/doc/administration/housekeeping.md index 8f5bf2ee013..4de48aa3f14 100644 --- a/doc/administration/housekeeping.md +++ b/doc/administration/housekeeping.md @@ -27,7 +27,7 @@ GitLab automatically runs `git gc` and `git repack` on repositories after Git pu You can change how often this happens or turn it off: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Repository maintenance**. 1. In the **Housekeeping** section, configure the [housekeeping options](#housekeeping-options). @@ -62,6 +62,12 @@ Housekeeping also [removes unreferenced LFS files](../raketasks/cleanup.md#remov from your project on the same schedule as the `git gc` operation, freeing up storage space for your project. +WARNING: +Running `git gc` or `git repack` commands manually in the +[repository folder](repository_storage_types.md#from-project-name-to-hashed-path) +is discouraged. If the created pack files get incorrect access rights (that is, owned by the wrong user) +browsing to the project page might result in `404` and `503` errors. + ## How housekeeping handles pool repositories Housekeeping for pool repositories is handled differently from standard repositories. It is @@ -76,7 +82,7 @@ This is the current call stack by which it is invoked: 1. `ObjectPoolService#fetch` 1. `Gitaly::FetchIntoObjectPoolRequest` -To manually invoke it from a Rails console if needed, you can call +To manually invoke it from a [Rails console](operations/rails_console.md) if needed, you can call `project.pool_repository.object_pool.fetch`. This is a potentially long-running task, though Gitaly times out in about 8 hours. diff --git a/doc/administration/incoming_email.md b/doc/administration/incoming_email.md index c5cabc5794a..5b72583bc95 100644 --- a/doc/administration/incoming_email.md +++ b/doc/administration/incoming_email.md @@ -76,7 +76,7 @@ and use [an application password](https://support.google.com/mail/answer/185833) If you want to use Office 365, and two-factor authentication is enabled, make sure you're using an -[app password](https://docs.microsoft.com/en-us/azure/active-directory/user-help/multi-factor-authentication-end-user-app-passwords) +[app password](https://support.microsoft.com/en-us/account-billing/manage-app-passwords-for-two-step-verification-d6dc8c6d-4bf7-4851-ad95-6d07799387e9) instead of the regular password for the mailbox. To set up a basic Postfix mail server with IMAP access on Ubuntu, follow the @@ -464,7 +464,7 @@ Example configurations for Microsoft Office 365 with IMAP enabled. NOTE: As of September 2020 sub-addressing support -[has been added to Office 365](https://office365.uservoice.com/forums/273493-office-365-admin/suggestions/18612754-support-for-dynamic-email-aliases-in-office-36). This feature is not +[has been added to Office 365](https://support.microsoft.com/en-us/office/uservoice-pages-430e1a78-e016-472a-a10f-dc2a3df3450a). This feature is not enabled by default, and must be enabled through PowerShell. This series of PowerShell commands enables [sub-addressing](#email-sub-addressing) @@ -638,7 +638,7 @@ incoming_email: #### Microsoft Graph -> Introduced in [GitLab 13.11](https://gitlab.com/gitlab-org/gitlab/-/issues/214900). +> [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 diff --git a/doc/administration/index.md b/doc/administration/index.md index 46624ab39a3..9412994edb7 100644 --- a/doc/administration/index.md +++ b/doc/administration/index.md @@ -111,7 +111,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. ### GitLab platform integrations -- [Mattermost](https://docs.gitlab.com/omnibus/gitlab-mattermost/): Integrate with [Mattermost](https://mattermost.com), an open source, private cloud workplace for web messaging. +- [Mattermost](../integration/mattermost/index.md): Integrate with [Mattermost](https://mattermost.com), an open source, private cloud workplace for web messaging. - [PlantUML](integration/plantuml.md): Create diagrams in AsciiDoc and Markdown documents created in snippets, wikis, and repositories. - [Web terminals](integration/terminal.md): Provide terminal access to your applications deployed to Kubernetes from GitLab CI/CD [environments](../ci/environments/index.md#web-terminals). @@ -164,16 +164,16 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [Limit repository size](../user/admin_area/settings/account_and_limit_settings.md): Set a hard limit for your repositories' size. - [Static objects external storage](static_objects_external_storage.md): Set external storage for static objects in a repository. -## Continuous Integration settings +## CI/CD settings -- [Enable/disable GitLab CI/CD](../ci/enable_or_disable_ci.md#make-gitlab-cicd-disabled-by-default-in-new-projects): Enable or disable GitLab CI/CD for your instance. +- [Enable or disable GitLab CI/CD](cicd.md#disable-gitlab-cicd-in-new-projects): Set new projects in your instance to have GitLab CI/CD enabled or disabled by default. - [GitLab CI/CD administration settings](../user/admin_area/settings/continuous_integration.md): Enable or disable Auto DevOps site-wide and define the artifacts' max size and expiration time. - [External Pipeline Validation](external_pipeline_validation.md): Enable, disable, and configure external pipeline validation. - [Job artifacts](job_artifacts.md): Enable, disable, and configure job artifacts (a set of files and directories which are outputted by a job when it completes successfully). - [Job logs](job_logs.md): Information about the job logs. - [Register runners](../ci/runners/runners_scope.md): Learn how to register and configure runners. - [Shared runners pipelines quota](../user/admin_area/settings/continuous_integration.md#shared-runners-pipeline-minutes-quota): Limit the usage of pipeline minutes for shared runners. -- [Enable/disable Auto DevOps](../topics/autodevops/index.md#enable-or-disable-auto-devops): Enable or disable Auto DevOps for your instance. +- [Enable or disable Auto DevOps](../topics/autodevops/index.md#enable-or-disable-auto-devops): Enable or disable Auto DevOps for your instance. ## Snippet settings diff --git a/doc/administration/instance_limits.md b/doc/administration/instance_limits.md index 1ea2ec4c904..24ffee088f3 100644 --- a/doc/administration/instance_limits.md +++ b/doc/administration/instance_limits.md @@ -78,6 +78,16 @@ This setting limits the request rate on the Packages API per user or IP. For mor - **Default rate limit**: Disabled by default. +### Git LFS + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68642) in GitLab 14.3. + +This setting limits the request rate on the [Git LFS](../topics/git/lfs/index.md) +requests per user. For more information, read +[GitLab Git Large File Storage (LFS) Administration](../administration/lfs/index.md). + +- **Default rate limit**: Disabled by default. + ### Import/Export > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35728) in GitLab 13.2. @@ -387,6 +397,31 @@ To set this limit for a self-managed installation, run the following in the Plan.default.actual_limits.update!(ci_pipeline_schedules: 100) ``` +### Limit the number of pipelines created by a pipeline schedule per day + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/323066) in GitLab 14.0. + +You can limit the number of pipelines that pipeline schedules can trigger per day. + +Schedules that try to run pipelines more frequently than the limit are slowed to a maximum frequency. +The frequency is calculated by dividing 1440 (the number minutes in a day) by the +limit value. For example, for a maximum frequency of: + +- Once per minute, the limit must be `1440`. +- Once per 10 minutes, the limit must be `144`. +- Once per 60 minutes, the limit must be `24` + +There is no limit for self-managed instances by default. + +To set this limit to `1440` on a self-managed installation, run the following in the +[GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session): + +```ruby +Plan.default.actual_limits.update!(ci_daily_pipeline_schedule_triggers: 1440) +``` + +This limit is [enabled on GitLab.com](../user/gitlab_com/index.md#gitlab-cicd). + ### Number of instance level variables > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216097) in GitLab 13.1. @@ -513,19 +548,61 @@ Update `ci_jobs_trace_size_limit` with the new value in megabytes: Plan.default.actual_limits.update!(ci_jobs_trace_size_limit: 125) ``` +### Maximum number of active DAST profile schedules per project + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68551) in GitLab 14.3. + +Limit the number of active DAST profile schedules per project. A DAST profile schedule can be active or inactive. + +You can change the limit in the [GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session). +Update `dast_profile_schedules` with the new value: + +```ruby +Plan.default.actual_limits.update!(dast_profile_schedules: 50) +``` + +### Maximum size and depth of CI/CD configuration YAML files + +The default maximum size of a CI/CD configuration YAML file is 1 megabyte and the default depth is 100. + +You can change these limits in the [GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session). +Update `max_yaml_size_bytes` with the new value in megabytes: + +```ruby +ApplicationSetting.update!(max_yaml_size_bytes: 2.megabytes) +``` + +Update `max_yaml_depth` with the new value in megabytes: + +```ruby +ApplicationSetting.update!(max_yaml_depth: 125) +``` + +To disable this limitation entirely, disable the feature flag in the console: + +```ruby +Feature.disable(:ci_yaml_limit_size) +``` + ## Instance monitoring and metrics -### Incident Management inbound alert limits +### Limit inbound incident management alerts > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17859) in GitLab 12.5. -Limiting inbound alerts for an incident reduces the number of alerts (issues) -that can be created within a period of time, which can help prevent overloading -your incident responders with duplicate issues. You can reduce the volume of -alerts in the following ways: +You can limit the number of inbound alerts for [incidents](../operations/incident_management/incidents.md) +that can be created in a period of time. The inbound [incident management](../operations/incident_management/index.md) +alert limit can help prevent overloading your incident responders by reducing the +number of alerts or duplicate issues. + +To set inbound incident management alert limits: -- Max requests per period per project, 3600 seconds by default. -- Rate limit period in seconds, 3600 seconds by default. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Network**. +1. Expand General **Incident Management Limits**. +1. Select the **Enable Incident Management inbound alert limit** checkbox. +1. Optional. Input a custom value for **Maximum requests per project per rate limit period**. Default is 3600. +1. Optional. Input a custom value for **Rate limit period**. Default is 3600 seconds. ### Prometheus Alert JSON payloads @@ -577,9 +654,9 @@ panel_groups: See [Environment Dashboard](../ci/environments/environments_dashboard.md#adding-a-project-to-the-dashboard) for the maximum number of displayed projects. -## Environment data on Deploy Boards +## Environment data on deploy boards -[Deploy Boards](../user/project/deploy_boards.md) load information from Kubernetes about +[Deploy boards](../user/project/deploy_boards.md) load information from Kubernetes about Pods and Deployments. However, data over 10 MB for a certain environment read from Kubernetes won't be shown. @@ -645,7 +722,7 @@ indexed, which have a separate limit. For more information, read - For self-managed installations, the field length is unlimited by default. You can configure this limit for self-managed installations when you -[enable Elasticsearch](../integration/elasticsearch.md#enabling-advanced-search). +[enable Elasticsearch](../integration/elasticsearch.md#enable-advanced-search). Set the limit to `0` to disable it. ## Wiki limits @@ -733,7 +810,7 @@ Set the limit to `0` to allow any file size. When asking for versions of a given NuGet package name, the GitLab Package Registry returns a maximum of 300 versions. -## Branch retargeting on merge **(FREE SELF)** +## Branch retargeting on merge > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/320902) in GitLab 13.9. diff --git a/doc/administration/instance_review.md b/doc/administration/instance_review.md index f2ba3a5a562..b166bb32aa1 100644 --- a/doc/administration/instance_review.md +++ b/doc/administration/instance_review.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Instance Review **(FREE SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/6995) in [GitLab Free](https://about.gitlab.com/pricing/) 11.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/6995) in GitLab 11.3. If you run a medium-sized self-managed instance (50+ users) of a free version of GitLab, [either Community Edition or unlicensed Enterprise Edition](https://about.gitlab.com/install/ce-or-ee/), diff --git a/doc/administration/integration/kroki.md b/doc/administration/integration/kroki.md index 729894052b2..008d33c6c94 100644 --- a/doc/administration/integration/kroki.md +++ b/doc/administration/integration/kroki.md @@ -56,7 +56,7 @@ read the [Kroki installation](https://docs.kroki.io/kroki/setup/install/#_images You need to enable Kroki integration from Settings under Admin Area. To do that, log in with an administrator account and follow these steps: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. Go to **Settings > General**. 1. Expand the **Kroki** section. 1. Select **Enable Kroki** checkbox. diff --git a/doc/administration/integration/mailgun.md b/doc/administration/integration/mailgun.md new file mode 100644 index 00000000000..5a56aed4427 --- /dev/null +++ b/doc/administration/integration/mailgun.md @@ -0,0 +1,41 @@ +--- +stage: Growth +group: Expansion +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: reference, howto +--- + +# Mailgun and GitLab **(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 +permanent invite email failures. To set up the integration, you must: + +1. [Configure your Mailgun domain](#configure-your-mailgun-domain). +1. [Enable Mailgun integration](#enable-mailgun-integration). + +After completing the integration, Mailgun `permanent_failure` webhooks are sent to your GitLab instance. + +## Configure your Mailgun domain + +Before you can enable Mailgun in GitLab, set up your own Mailgun permanent failure endpoint to receive the webhooks. + +Using the [Mailgun webhook guide](https://www.mailgun.com/blog/a-guide-to-using-mailguns-webhooks/): + +1. Add a webhook with the **Event type** set to **Permanent Failure**. +1. Fill in the URL of your instance and include the `/-/members/mailgun/permanent_failures` path. + - Example: `https://myinstance.gitlab.com/-/members/mailgun/permanent_failures` + +## Enable Mailgun integration + +After configuring your Mailgun domain for the permanent failures endpoint, +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 **Menu >** **{admin}** **Admin**. +1. On the left sidebar, go to **Settings > General** and expand the **Mailgun** section. +1. Select the **Enable Mailgun** check box. +1. Enter the Mailgun HTTP webhook signing key as described in + [the Mailgun documentation](https://documentation.mailgun.com/en/latest/user_manual.html#webhooks) and + shown in the [API security](https://app.mailgun.com/app/account/security/api_keys) section for your Mailgun account. +1. Select **Save changes**. diff --git a/doc/administration/integration/plantuml.md b/doc/administration/integration/plantuml.md index 9f83ba8e972..94fef89d966 100644 --- a/doc/administration/integration/plantuml.md +++ b/doc/administration/integration/plantuml.md @@ -206,8 +206,8 @@ stop; After configuring your local PlantUML server, you're ready to enable the PlantUML integration: 1. Sign in to GitLab as an [Administrator](../../user/permissions.md) user. -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, go to **Settings > General** and expand the **PlantUML** section. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, go to **Settings > General** and expand the **PlantUML** section. 1. Select the **Enable PlantUML** checkbox. 1. Set the PlantUML instance as `https://gitlab.example.com/-/plantuml/`, and click **Save changes**. diff --git a/doc/administration/integration/terminal.md b/doc/administration/integration/terminal.md index 1be234c2771..882580b35b6 100644 --- a/doc/administration/integration/terminal.md +++ b/doc/administration/integration/terminal.md @@ -100,7 +100,7 @@ they receive a `Connection failed` message. By default, terminal sessions do not expire. To limit the terminal session lifetime in your GitLab instance: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. Select [**Settings > Web terminal**](../../user/admin_area/settings/index.md#general). 1. Set a `max session time`. diff --git a/doc/administration/job_artifacts.md b/doc/administration/job_artifacts.md index 3b1d253b4b6..b4c16e007cc 100644 --- a/doc/administration/job_artifacts.md +++ b/doc/administration/job_artifacts.md @@ -435,6 +435,27 @@ Ci::JobArtifact.where(project: project).order(size: :desc).limit(50).map { |a| p You can change the number of job artifacts listed by modifying `.limit(50)` to the number you want. +#### List artifacts in a single project + +List the artifacts for a single project, sorted by artifact size. The output includes the: + +- ID of the job that created the artifact +- artifact size +- artifact file type +- artifact creation date +- on-disk location of the artifact + +```ruby +p = Project.find_by_id(:project ID) +arts = Ci::JobArtifact.where(project: p) + +list = arts.order('sort DESC').limit(50).each do |art| + puts "Job ID: #{art.job_id} - Size: #{art.size}b - Type: #{art.file_type} - Created: #{art.created_at} - File loc: #{art.file}" +end +``` + +To change the number of projects listed, change the number in `limit(50)`. + #### Delete job artifacts from jobs completed before a specific date WARNING: diff --git a/doc/administration/job_logs.md b/doc/administration/job_logs.md index a4fdf734c2e..64d9248cb16 100644 --- a/doc/administration/job_logs.md +++ b/doc/administration/job_logs.md @@ -138,7 +138,7 @@ For more information, see [delete references to missing artifacts](raketasks/che > - Enabled on GitLab.com. > - [Recommended for production use](https://gitlab.com/groups/gitlab-org/-/epics/4275) in GitLab 13.6. > - [Recommended for production use with AWS S3](https://gitlab.com/gitlab-org/gitlab/-/issues/273498) in GitLab 13.7. -> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-incremental-logging). **(FREE SELF)** +> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-incremental-logging). By default job logs are sent from the GitLab Runner in chunks and cached temporarily on disk in `/var/opt/gitlab/gitlab-ci/builds` by Omnibus GitLab. After the job completes, @@ -183,7 +183,7 @@ Here is the detailed data flow: to disk, and there is no protection against misconfiguration. - There is [an epic tracking other potential limitations and improvements](https://gitlab.com/groups/gitlab-org/-/epics/3791). -### Enable or disable incremental logging **(FREE SELF)** +### Enable or disable incremental logging Incremental logging is under development, but [ready for production use as of GitLab 13.6](https://gitlab.com/groups/gitlab-org/-/epics/4275). It is deployed behind a feature flag that is **disabled by default**. diff --git a/doc/administration/logs.md b/doc/administration/logs.md index 883f1db8e09..990287e3907 100644 --- a/doc/administration/logs.md +++ b/doc/administration/logs.md @@ -50,6 +50,7 @@ except those captured by `runit`. | [Mailroom](#mail_room_jsonlog-default) | **{check-circle}** Yes | **{check-circle}** Yes | | [NGINX](#nginx-logs) | **{check-circle}** Yes | **{check-circle}** Yes | | [PostgreSQL Logs](#postgresql-logs) | **{dotted-circle}** No | **{check-circle}** Yes | +| [Praefect Logs](#praefect-logs) | **{dotted-circle}** Yes| **{check-circle}** Yes | | [Prometheus Logs](#prometheus-logs) | **{dotted-circle}** No | **{check-circle}** Yes | | [Puma](#puma-logs) | **{check-circle}** Yes | **{check-circle}** Yes | | [Redis Logs](#redis-logs) | **{dotted-circle}** No | **{check-circle}** Yes | @@ -63,9 +64,6 @@ Depending on your installation method, this file is located at: - Omnibus GitLab: `/var/log/gitlab/gitlab-rails/production_json.log` - Installations from source: `/home/git/gitlab/log/production_json.log` -When GitLab is running in an environment other than production, -the corresponding log file is shown here. - It contains a structured log for Rails controller requests received from GitLab, thanks to [Lograge](https://github.com/roidrage/lograge/). Requests from the API are logged to a separate file in `api_json.log`. @@ -216,9 +214,6 @@ Depending on your installation method, this file is located at: - Omnibus GitLab: `/var/log/gitlab/gitlab-rails/production.log` - Installations from source: `/home/git/gitlab/log/production.log` -When GitLab is running in an environment other than production, -the corresponding log file is shown here. - It contains information about all performed requests. You can see the URL and type of request, IP address, and what parts of code were involved to service this particular request. Also, you can see all SQL @@ -556,10 +551,9 @@ access to Git repositories. ### For GitLab versions 12.10 and up -For GitLab version 12.10 and later, there are two `gitlab-shell.log` files. Information containing `git-{upload-pack,receive-pack}` requests is at `/var/log/gitlab/gitlab-shell/gitlab-shell.log`. Information about hooks to -GitLab Shell from Gitaly is at `/var/log/gitlab/gitaly/gitlab-shell.log`. +GitLab Shell from Gitaly is at `/var/log/gitlab/gitaly/current`. Example log entries for `/var/log/gitlab/gitlab-shell/gitlab-shell.log`: @@ -585,7 +579,7 @@ Example log entries for `/var/log/gitlab/gitlab-shell/gitlab-shell.log`: } ``` -Example log entries for `/var/log/gitlab/gitaly/gitlab-shell.log`: +Example log entries for `/var/log/gitlab/gitaly/current`: ```json { @@ -668,6 +662,12 @@ This file is at `/var/log/gitlab/gitaly/gitaly_ruby_json.log` and is produced by [`gitaly-ruby`](gitaly/reference.md#gitaly-ruby). It contains an access log of gRPC calls made by Gitaly to `gitaly-ruby`. +### `gitaly_hooks.log` + +This file is at `/var/log/gitlab/gitaly/gitaly_hooks.log` and is +produced by `gitaly-hooks` command. It also contains records about +failures received during processing of the responses from GitLab API. + ## Puma Logs ### `puma_stdout.log` @@ -1063,6 +1063,12 @@ For Omnibus GitLab installations, GitLab Exporter logs are in `/var/log/gitlab/g For Omnibus GitLab installations, GitLab Kubernetes Agent Server logs are in `/var/log/gitlab/gitlab-kas/`. +## Praefect Logs + +For Omnibus GitLab installations, Praefect logs are in `/var/log/gitlab/praefect/`. + +GitLab also tracks [Prometheus metrics for Praefect](gitaly/#monitor-gitaly-cluster). + ## Performance bar stats > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/48149) in GitLab 13.7. diff --git a/doc/administration/maintenance_mode/index.md b/doc/administration/maintenance_mode/index.md index 7664c7c1751..39ee357cc2f 100644 --- a/doc/administration/maintenance_mode/index.md +++ b/doc/administration/maintenance_mode/index.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Maintenance Mode **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2149) in GitLab Premium 13.9. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2149) in GitLab 13.9. Maintenance Mode allows administrators to reduce write operations to a minimum while maintenance tasks are performed. The main goal is to block all external actions that change the internal state, including the PostgreSQL database, but especially files, Git repositories, Container repositories, and so on. @@ -21,7 +21,7 @@ Maintenance Mode allows most external actions that do not change internal state. There are three ways to enable Maintenance Mode as an administrator: - **Web UI**: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand **Maintenance Mode**, and toggle **Enable Maintenance Mode**. You can optionally add a message for the banner as well. @@ -45,7 +45,7 @@ There are three ways to enable Maintenance Mode as an administrator: There are three ways to disable Maintenance Mode: - **Web UI**: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand **Maintenance Mode**, and toggle **Enable Maintenance Mode**. You can optionally add a message for the banner as well. @@ -171,7 +171,7 @@ it is recommended that you disable all cron jobs except for those related to Geo To monitor queues and disable jobs: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Monitoring > Background Jobs**. ### Incident management diff --git a/doc/administration/merge_request_diffs.md b/doc/administration/merge_request_diffs.md index 1133bff204c..d6b9fa2b8d3 100644 --- a/doc/administration/merge_request_diffs.md +++ b/doc/administration/merge_request_diffs.md @@ -265,3 +265,9 @@ by assigning different processes to different parts of the table. The `BATCH` and `UPDATE_DELAY` parameters allow the speed of the migration to be traded off against concurrent access to the table. The `ANSI` parameter should be set to false if your terminal does not support ANSI escape codes. + +By default, `sudo` does not preserve existing environment variables. You should append them, rather than prefix them. + +```shell +sudo gitlab-rake gitlab:external_diffs:force_object_storage START_ID=59946109 END_ID=59946109 UPDATE_DELAY=5 +``` diff --git a/doc/administration/monitoring/gitlab_self_monitoring_project/index.md b/doc/administration/monitoring/gitlab_self_monitoring_project/index.md index f8764468256..90d0b65dbe5 100644 --- a/doc/administration/monitoring/gitlab_self_monitoring_project/index.md +++ b/doc/administration/monitoring/gitlab_self_monitoring_project/index.md @@ -14,7 +14,7 @@ GitLab provides administrators insights into the health of their GitLab instance To provide a native experience (similar interacting with an application deployed using GitLab), a project called **Monitoring** is created: -- With [internal visibility](../../../public_access/public_access.md#internal-projects). +- With [internal visibility](../../../public_access/public_access.md#internal-projects-and-groups). - Under a group called **GitLab Instance**. The project is created specifically for visualizing and configuring the monitoring of your GitLab @@ -34,7 +34,7 @@ This project can be used to: ## Create the self monitoring project -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Metrics and profiling** and expand **Self monitoring**. 1. Toggle **Self monitoring** on. 1. After your GitLab instance creates the project, GitLab displays a link to the @@ -47,7 +47,7 @@ WARNING: Deleting the self monitoring project removes any changes made to the project. If you create the project again, it's created in its default state. -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, go to **Settings > Metrics and profiling** and expand **Self monitoring**. 1. Toggle **Self monitoring** off. 1. In the confirmation dialog that opens, click **Delete self monitoring project**. diff --git a/doc/administration/monitoring/performance/gitlab_configuration.md b/doc/administration/monitoring/performance/gitlab_configuration.md index e8abe2708c7..f316a75a868 100644 --- a/doc/administration/monitoring/performance/gitlab_configuration.md +++ b/doc/administration/monitoring/performance/gitlab_configuration.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w GitLab Performance Monitoring is disabled by default. To enable it and change any of its settings: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Metrics and profiling** (`/admin/application_settings/metrics_and_profiling`). 1. Add the necessary configuration changes. diff --git a/doc/administration/monitoring/performance/grafana_configuration.md b/doc/administration/monitoring/performance/grafana_configuration.md index 0f40fd3c0e7..c37a264938e 100644 --- a/doc/administration/monitoring/performance/grafana_configuration.md +++ b/doc/administration/monitoring/performance/grafana_configuration.md @@ -62,7 +62,7 @@ repository. After setting up Grafana, you can enable a link to access it easily from the GitLab sidebar: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Metrics and profiling** and expand **Metrics - Grafana**. 1. Select the **Add a link to Grafana** checkbox. @@ -79,7 +79,7 @@ GitLab displays your link in the **Menu > Admin > Monitoring > Metrics Dashboard > [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5822) in GitLab 13.10. When setting up Grafana through the process above, no scope shows in the screen at -**Menu >** **{admin}** **Admin > Applications > GitLab Grafana**. However, the `read_user` scope is +**Menu > Admin > Applications > GitLab Grafana**. However, the `read_user` scope is required and is provided to the application automatically. Setting any scope other than `read_user` without also including `read_user` leads to this error when you try to log in using GitLab as the OAuth provider: diff --git a/doc/administration/monitoring/performance/performance_bar.md b/doc/administration/monitoring/performance/performance_bar.md index 6d9418133d8..ef4db93d5fc 100644 --- a/doc/administration/monitoring/performance/performance_bar.md +++ b/doc/administration/monitoring/performance/performance_bar.md @@ -72,7 +72,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.2/thread-memory-allocations-2.7.patch) +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), this is typically not the case and the memory view cannot be used. @@ -104,7 +104,7 @@ The performance bar is disabled by default for non-administrators. To enable it for a given group: 1. Sign in as a user with Administrator [role](../../../user/permissions.md). -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Metrics and profiling** (`admin/application_settings/metrics_and_profiling`), and expand **Profiling - Performance bar**. diff --git a/doc/administration/monitoring/prometheus/gitlab_exporter.md b/doc/administration/monitoring/prometheus/gitlab_exporter.md index 4ba4cad9143..d9852524aec 100644 --- a/doc/administration/monitoring/prometheus/gitlab_exporter.md +++ b/doc/administration/monitoring/prometheus/gitlab_exporter.md @@ -6,8 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab exporter **(FREE SELF)** ->- Available since [Omnibus GitLab 8.17](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/1132). ->- Renamed from `GitLab monitor exporter` to `GitLab exporter` in [GitLab 12.3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16511). +> Renamed from `GitLab monitor exporter` to `GitLab exporter` in [GitLab 12.3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16511). The [GitLab exporter](https://gitlab.com/gitlab-org/gitlab-exporter) enables you to measure various GitLab metrics pulled from Redis and the database in Omnibus GitLab @@ -33,8 +32,8 @@ the GitLab exporter exposed at `localhost:9168`. ## Use a different Rack server ->- Introduced in [Omnibus GitLab 13.8](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/4896). ->- WEBrick is now the default Rack server instead of Puma. +> - Introduced in [Omnibus GitLab 13.8](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/4896). +> - WEBrick is now the default Rack server instead of Puma. By default, the GitLab exporter runs on [WEBrick](https://github.com/ruby/webrick), a single-threaded Ruby web server. You can choose a different Rack server that better matches your performance needs. diff --git a/doc/administration/monitoring/prometheus/gitlab_metrics.md b/doc/administration/monitoring/prometheus/gitlab_metrics.md index 459eb259498..c36d2b0f7a4 100644 --- a/doc/administration/monitoring/prometheus/gitlab_metrics.md +++ b/doc/administration/monitoring/prometheus/gitlab_metrics.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w To enable the GitLab Prometheus metrics: 1. Log in to GitLab as a user with Administrator [role](../../../user/permissions.md). -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Metrics and profiling**. 1. Find the **Metrics - Prometheus** section, and select **Add link to Prometheus**. 1. [Restart GitLab](../../restart_gitlab.md#omnibus-gitlab-restart) for the changes to take effect. @@ -252,12 +252,26 @@ configuration option in `gitlab.yml`. These metrics are served from the | `geo_group_wiki_repositories_synced` | Gauge | 13.10 | Number of syncable group wikis synced on secondary | `url` | | `geo_group_wiki_repositories_failed` | Gauge | 13.10 | Number of syncable group wikis failed on secondary | `url` | | `geo_group_wiki_repositories_registry` | Gauge | 13.10 | Number of syncable group wikis in the registry | `url` | +| `geo_pages_deployments` | Gauge | 14.3 | Number of pages deployments on primary | `url` | +| `geo_pages_deployments_checksum_total` | Gauge | 14.3 | Number of pages deployments tried to checksum on primary | `url` | +| `geo_pages_deployments_checksummed` | Gauge | 14.3 | Number of pages deployments successfully checksummed on primary | `url` | +| `geo_pages_deployments_checksum_failed` | Gauge | 14.3 | Number of pages deployments failed to calculate the checksum on primary | `url` | +| `geo_pages_deployments_synced` | Gauge | 14.3 | Number of syncable pages deployments synced on secondary | `url` | +| `geo_pages_deployments_failed` | Gauge | 14.3 | Number of syncable pages deployments failed to sync on secondary | `url` | +| `geo_pages_deployments_registry` | Gauge | 14.3 | Number of pages deployments in the registry | `url` | +| `geo_pages_deployments_verification_total` | Gauge | 14.3 | Number of pages deployments verifications tried on secondary | `url` | +| `geo_pages_deployments_verified` | Gauge | 14.3 | Number of pages deployments verified on secondary | `url` | +| `geo_pages_deployments_verification_failed` | Gauge | 14.3 | Number of pages deployments verifications failed on secondary | `url` | | `limited_capacity_worker_running_jobs` | Gauge | 13.5 | Number of running jobs | `worker` | | `limited_capacity_worker_max_running_jobs` | Gauge | 13.5 | Maximum number of running jobs | `worker` | | `limited_capacity_worker_remaining_work_count` | Gauge | 13.5 | Number of jobs waiting to be enqueued | `worker` | | `destroyed_job_artifacts_count_total` | Counter | 13.6 | Number of destroyed expired job artifacts | | | `destroyed_pipeline_artifacts_count_total` | Counter | 13.8 | Number of destroyed expired pipeline artifacts | | | `gitlab_optimistic_locking_retries` | Histogram | 13.10 | Number of retry attempts to execute optimistic retry lock | | +| `geo_uploads` | Gauge | 14.1 | Number of uploads on primary | `url` | +| `geo_uploads_synced` | Gauge | 14.1 | Number of uploads synced on secondary | `url` | +| `geo_uploads_failed` | Gauge | 14.1 | Number of syncable uploads failed to sync on secondary | `url` | +| `geo_uploads_registry` | Gauge | 14.1 | Number of uploads in the registry | `url` | ## Database load balancing metrics **(PREMIUM SELF)** diff --git a/doc/administration/monitoring/prometheus/index.md b/doc/administration/monitoring/prometheus/index.md index dd81f71d418..e04aad9c6b8 100644 --- a/doc/administration/monitoring/prometheus/index.md +++ b/doc/administration/monitoring/prometheus/index.md @@ -55,8 +55,7 @@ To disable Prometheus and all of its exporters, as well as any added in the futu ### Changing the port and address Prometheus listens on WARNING: -The following change was added in [Omnibus GitLab 8.17](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/1261). Although possible, -it's not recommended to change the port Prometheus listens +Although possible, it's not recommended to change the port Prometheus listens on, as this might affect or conflict with other services running on the GitLab server. Proceed at your own risk. @@ -330,8 +329,6 @@ To add a Prometheus dashboard for a single server GitLab setup: ## GitLab metrics -> Introduced in GitLab 9.3. - GitLab monitors its own internal service metrics, and makes them available at the `/-/metrics` endpoint. Unlike other exporters, this endpoint requires authentication as it's available on the same URL and port as user traffic. Read more about the [GitLab Metrics](gitlab_metrics.md). @@ -380,9 +377,6 @@ The GitLab exporter allows you to measure various GitLab metrics, pulled from Re ## Configuring Prometheus to monitor Kubernetes -> - Introduced in GitLab 9.0. -> - Pod monitoring introduced in GitLab 9.4. - If your GitLab server is running within Kubernetes, Prometheus collects metrics from the Nodes and [annotated Pods](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#kubernetes_sd_config) in the cluster, including performance data on each container. This is particularly helpful if your CI/CD environments run in the same cluster, as you can use the [Prometheus project integration](../../../user/project/integrations/prometheus.md) to monitor them. To disable the monitoring of Kubernetes: diff --git a/doc/administration/object_storage.md b/doc/administration/object_storage.md index b8a6f2acc56..6c77576cb27 100644 --- a/doc/administration/object_storage.md +++ b/doc/administration/object_storage.md @@ -14,7 +14,7 @@ typically much more performant, reliable, and scalable. ## Options -GitLab has been tested on a number of object storage providers: +GitLab has been tested by vendors and customers on a number of object storage providers: - [Amazon S3](https://aws.amazon.com/s3/) - [Google Cloud Storage](https://cloud.google.com/storage) @@ -22,7 +22,7 @@ GitLab has been tested on a number of object storage providers: - [Oracle Cloud Infrastructure](https://docs.cloud.oracle.com/en-us/iaas/Content/Object/Tasks/s3compatibleapi.htm) - [OpenStack Swift](https://docs.openstack.org/swift/latest/s3_compat.html) - [Azure Blob storage](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) -- On-premises hardware and appliances from various storage vendors. +- On-premises hardware and appliances from various storage vendors, whose list is not officially established. - MinIO. We have [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. ### Known compatibility issues @@ -33,6 +33,10 @@ GitLab has been tested on a number of object storage providers: - Ceph S3 prior to [Kraken 11.0.2](https://ceph.com/releases/kraken-11-0-2-released/) does not support the [Upload Copy Part API](https://gitlab.com/gitlab-org/gitlab/-/issues/300604). You may need to [disable multi-threaded copying](#multi-threaded-copying). +- Amazon S3 [Object Lock](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock.html) + is not supported. Follow [issue #335775](https://gitlab.com/gitlab-org/gitlab/-/issues/335775) + for progress on enabling this option. + ## Configuration guides There are two ways of specifying object storage configuration in GitLab: @@ -70,6 +74,7 @@ because it does not require a shared folder. Consolidated object storage configuration can't be used for backups or Mattermost. See the [full table for a complete list](#storage-specific-configuration). +However, backups can be configured with [server side encryption](../raketasks/backup_restore.md#s3-encrypted-buckets) separately. Enabling consolidated object storage enables object storage for all object types. If you want to use local storage for specific object types, you can @@ -683,8 +688,8 @@ configuration. #### Encrypted S3 buckets -> - Introduced in [GitLab 13.1](https://gitlab.com/gitlab-org/gitlab-workhorse/-/merge_requests/466) for instance profiles only and [S3 default encryption](https://docs.aws.amazon.com/AmazonS3/latest/dev/bucket-encryption.html). -> - Introduced in [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/34460) for static credentials when [consolidated object storage configuration](#consolidated-object-storage-configuration) and [S3 default encryption](https://docs.aws.amazon.com/AmazonS3/latest/dev/bucket-encryption.html) are used. +> - [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). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/34460) in GitLab 13.2 for static credentials when [consolidated object storage configuration](#consolidated-object-storage-configuration) and [S3 default encryption](https://docs.aws.amazon.com/AmazonS3/latest/dev/bucket-encryption.html) are used. When configured either with an instance profile or with the consolidated object configuration, GitLab Workhorse properly uploads files to S3 @@ -695,7 +700,7 @@ supported since this requires sending the encryption keys in every request](http ##### Server-side encryption headers -> Introduced in [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/38240). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/38240) in GitLab 13.3. 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 diff --git a/doc/administration/operations/cleaning_up_redis_sessions.md b/doc/administration/operations/cleaning_up_redis_sessions.md index 194dd8f39e2..ed5014b65e1 100644 --- a/doc/administration/operations/cleaning_up_redis_sessions.md +++ b/doc/administration/operations/cleaning_up_redis_sessions.md @@ -1,64 +1,9 @@ --- -stage: Enablement -group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: 'index.md' +remove_date: '2021-12-10' --- -# Cleaning up stale Redis sessions +This document was moved to [another location](index.md). -Since version 6.2, GitLab stores web user sessions as key-value pairs in Redis. -Prior to GitLab 7.3, user sessions did not automatically expire from Redis. If -you have been running a large GitLab server (thousands of users) since before -GitLab 7.3 we recommend cleaning up stale sessions to compact the Redis -database after you upgrade to GitLab 7.3. You can also perform a cleanup while -still running GitLab 7.2 or older, but in that case new stale sessions will -start building up again after you clean up. - -In GitLab versions prior to 7.3.0, the session keys in Redis are 16-byte -hexadecimal values such as '976aa289e2189b17d7ef525a6702ace9'. Starting with -GitLab 7.3.0, the keys are -prefixed with `session:gitlab:`, so they would look like -`session:gitlab:976aa289e2189b17d7ef525a6702ace9`. Below we describe how to -remove the keys in the old format. - -NOTE: -The instructions below must be modified in accordance with your -configuration settings if you have used the advanced Redis -settings outlined in -[Configuration Files Documentation](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/README.md). - -First we define a shell function with the proper Redis connection details. - -```shell -rcli() { - # This example works for Omnibus installations of GitLab 7.3 or newer. For an - # installation from source you will have to change the socket path and the - # path to redis-cli. - sudo /opt/gitlab/embedded/bin/redis-cli -s /var/opt/gitlab/redis/redis.socket "$@" -} - -# test the new shell function; the response should be PONG -rcli ping -``` - -Now we do a search to see if there are any session keys in the old format for -us to clean up. - -```shell -# returns the number of old-format session keys in Redis -rcli keys '*' | grep '^[a-f0-9]\{32\}$' | wc -l -``` - -If the number is larger than zero, you can proceed to expire the keys from -Redis. If the number is zero there is nothing to clean up. - -```shell -# Tell Redis to expire each matched key after 600 seconds. -rcli keys '*' | grep '^[a-f0-9]\{32\}$' | awk '{ print "expire", $0, 600 }' | rcli -# This will print '(integer) 1' for each key that gets expired. -``` - -Over the next 15 minutes (10 minutes expiry time plus 5 minutes Redis -background save interval) your Redis database will be compacted. If you are -still using GitLab 7.2, users who are not clicking around in GitLab during the -10 minute expiry window will be signed out of GitLab. +<!-- This redirect file can be deleted after 2021-12-10. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/operations/extra_sidekiq_processes.md b/doc/administration/operations/extra_sidekiq_processes.md index 2cc4e3a4551..31cbd6c457b 100644 --- a/doc/administration/operations/extra_sidekiq_processes.md +++ b/doc/administration/operations/extra_sidekiq_processes.md @@ -90,7 +90,7 @@ To start multiple processes: To view the Sidekiq processes in GitLab: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Monitoring > Background Jobs**. ## Negate settings diff --git a/doc/administration/operations/extra_sidekiq_routing.md b/doc/administration/operations/extra_sidekiq_routing.md index 6938f8a7012..bb8eb184302 100644 --- a/doc/administration/operations/extra_sidekiq_routing.md +++ b/doc/administration/operations/extra_sidekiq_routing.md @@ -40,6 +40,8 @@ In `/etc/gitlab/gitlab.rb`: ```ruby sidekiq['routing_rules'] = [ + # Do not re-route workers that require their own queue + ['tags=needs_own_queue', nil], # Route all non-CPU-bound workers that are high urgency to `high-urgency` queue ['resource_boundary!=cpu&urgency=high', 'high-urgency'], # Route all database, gitaly and global search workers that are throttled to `throttled` queue @@ -164,3 +166,32 @@ with the migration to avoid losing jobs entirely, especially in a system with long queues of jobs. The migration can be done by following the migration steps mentioned in [Sidekiq job migration](../../raketasks/sidekiq_job_migration.md) + +### Workers that cannot be migrated + +Some workers cannot share a queue with other workers - typically because +they check the size of their own queue - and so must be excluded from +this process. We recommend excluding these from any further worker +routing by adding a rule to keep them in their own queue, for example: + +```ruby +sidekiq['routing_rules'] = [ + ['tags=needs_own_queue', nil], + # ... +] +``` + +These queues will also need to be included in at least one [Sidekiq +queue group](extra_sidekiq_processes.md#start-multiple-processes). + +The following table shows the workers that should have their own queue: + +| Worker name | Queue name | GitLab issue | +| --- | --- | --- | +| `EmailReceiverWorker` | `email_receiver` | [`gitlab-com/gl-infra/scalability#1263`](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/1263) | +| `ServiceDeskEmailReceiverWorker` | `service_desk_email_receiver` | [`gitlab-com/gl-infra/scalability#1263`](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/1263) | +| `ProjectImportScheduleWorker` | `project_import_schedule` | [`gitlab-org/gitlab#340630`](https://gitlab.com/gitlab-org/gitlab/-/issues/340630) | +| `HashedStorage::MigratorWorker` | `hashed_storage:hashed_storage_migrator` | [`gitlab-org/gitlab#340629`](https://gitlab.com/gitlab-org/gitlab/-/issues/340629) | +| `HashedStorage::ProjectMigrateWorker` | `hashed_storage:hashed_storage_project_migrate` | [`gitlab-org/gitlab#340629`](https://gitlab.com/gitlab-org/gitlab/-/issues/340629) | +| `HashedStorage::ProjectRollbackWorker` | `hashed_storage:hashed_storage_project_rollback` | [`gitlab-org/gitlab#340629`](https://gitlab.com/gitlab-org/gitlab/-/issues/340629) | +| `HashedStorage::RollbackerWorker` | `hashed_storage:hashed_storage_rollbacker` | [`gitlab-org/gitlab#340629`](https://gitlab.com/gitlab-org/gitlab/-/issues/340629) | diff --git a/doc/administration/operations/fast_ssh_key_lookup.md b/doc/administration/operations/fast_ssh_key_lookup.md index 5c1271486c0..e30ad4d8248 100644 --- a/doc/administration/operations/fast_ssh_key_lookup.md +++ b/doc/administration/operations/fast_ssh_key_lookup.md @@ -106,7 +106,7 @@ users as long as a large file exists. To disable any more writes to the `authorized_keys` file: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Network**. 1. Expand **Performance optimization**. 1. Clear the **Write to "authorized_keys" file** checkbox. diff --git a/doc/administration/operations/index.md b/doc/administration/operations/index.md index 4b16c3b3a7e..7ccfa2739bb 100644 --- a/doc/administration/operations/index.md +++ b/doc/administration/operations/index.md @@ -8,11 +8,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w Keep your GitLab instance up and running smoothly. -- [Clean up Redis sessions](cleaning_up_redis_sessions.md): Prior to GitLab 7.3, - user sessions did not automatically expire from Redis. If - you have been running a large GitLab server (thousands of users) since before - GitLab 7.3 we recommend cleaning up stale sessions to compact the Redis - database after you upgrade to GitLab 7.3. - [Rake tasks](../../raketasks/index.md): Tasks for common administration and operational processes such as [cleaning up unneeded items from GitLab instance](../../raketasks/cleanup.md), integrity checks, and more. diff --git a/doc/administration/operations/moving_repositories.md b/doc/administration/operations/moving_repositories.md index 765cf64e735..61a9ec8e7d4 100644 --- a/doc/administration/operations/moving_repositories.md +++ b/doc/administration/operations/moving_repositories.md @@ -39,6 +39,11 @@ WARNING: To move repositories into a [Gitaly Cluster](../gitaly/index.md#gitaly-cluster) in GitLab versions 13.12 to 14.1, you must [enable the `gitaly_replicate_repository_direct_fetch` feature flag](../feature_flags.md). +WARNING: +Repositories can be **permanently deleted** by a call to `/projects/:project_id/repository_storage_moves` +that attempts to move a project already stored in a Gitaly Cluster back into that cluster. +See [this issue for more details](https://gitlab.com/gitlab-org/gitaly/-/issues/3752). + Each repository is made read-only for the duration of the move. The repository is not writable until the move has completed. diff --git a/doc/administration/operations/puma.md b/doc/administration/operations/puma.md index e8477eaf686..775761d655d 100644 --- a/doc/administration/operations/puma.md +++ b/doc/administration/operations/puma.md @@ -36,6 +36,14 @@ For more details about the Puma configuration, see the ## Puma Worker Killer +Puma forks worker processes as part of a strategy to reduce memory use. + +Each time a worker is created, it shares memory with the primary process and +only uses additional memory when it makes changes or additions to its memory pages. + +Memory use by workers therefore increases over time, and Puma Worker Killer is the +mechanism that recovers this memory. + By default: - The [Puma Worker Killer](https://github.com/schneems/puma_worker_killer) restarts a worker if it @@ -56,6 +64,47 @@ To change the memory limit setting: sudo gitlab-ctl reconfigure ``` +There are costs associated with killing and replacing workers including +reduced capacity to run GitLab, and CPU that is consumed +restarting the workers. `per_worker_max_memory_mb` should be set to a +higher value if the worker killer is replacing workers too often. + +Worker count is calculated based on CPU cores, so a small GitLab deployment +with 4-8 workers may experience performance issues if workers are being restarted +frequently, once or more per minute. This is too often. + +A higher value of `1200` or more would be beneficial if the server has free memory. + +The worker killer checks every 20 seconds, and can be monitored using +[the Puma log](../logs.md#puma_stdoutlog) `/var/log/gitlab/puma/puma_stdout.log`. +For example, for GitLab 13.5: + +```plaintext +PumaWorkerKiller: Out of memory. 4 workers consuming total: 4871.23828125 MB +out of max: 4798.08 MB. Sending TERM to pid 26668 consuming 1001.00390625 MB. +``` + +From this output: + +- The formula that calculates the maximum memory value results in workers + being killed before they reach the `per_worker_max_memory_mb` value. +- The default values for the formula before GitLab 13.5 were 550MB for the primary + and `per_worker_max_memory_mb` specified 850MB for each worker. +- As of GitLab 13.5 the values are primary: 800MB, worker: 1024MB. +- The threshold for workers to be killed is set at 98% of the limit: + + ```plaintext + 0.98 * ( 800 + ( worker_processes * 1024MB ) ) + ``` + +- In the log output above, `0.98 * ( 800 + ( 4 * 1024 ) )` returns the + `max: 4798.08 MB` value. + +Increasing the maximum to `1200`, for example, would set a `max: 5488 MB` value. + +Workers use additional memory on top of the shared memory, how much +depends on a site's use of GitLab. + ## Worker timeout A [timeout of 60 seconds](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/initializers/rack_timeout.rb) @@ -95,7 +144,6 @@ considered as a fair tradeoff in a memory-constraint environment. When running Puma in Single mode, some features are not supported: -- Phased restart do not work: [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/300665) - [Phased restart](https://gitlab.com/gitlab-org/gitlab/-/issues/300665) - [Puma Worker Killer](https://gitlab.com/gitlab-org/gitlab/-/issues/300664) diff --git a/doc/administration/operations/sidekiq_memory_killer.md b/doc/administration/operations/sidekiq_memory_killer.md index 598baa4fcc7..e48ac6e65eb 100644 --- a/doc/administration/operations/sidekiq_memory_killer.md +++ b/doc/administration/operations/sidekiq_memory_killer.md @@ -4,7 +4,7 @@ group: Memory info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Sidekiq MemoryKiller +# Sidekiq MemoryKiller **(FREE SELF)** The GitLab Rails application code suffers from memory leaks. For web requests this problem is made manageable using diff --git a/doc/administration/operations/ssh_certificates.md b/doc/administration/operations/ssh_certificates.md index 374eebeb773..814e742b026 100644 --- a/doc/administration/operations/ssh_certificates.md +++ b/doc/administration/operations/ssh_certificates.md @@ -6,8 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # User lookup via OpenSSH's AuthorizedPrincipalsCommand **(FREE SELF)** -> [Available in](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19911) GitLab -> Community Edition 11.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19911) in GitLab 11.2. The default SSH authentication for GitLab requires users to upload their SSH public keys before they can use the SSH transport. diff --git a/doc/administration/operations/unicorn.md b/doc/administration/operations/unicorn.md deleted file mode 100644 index 6cee19186f9..00000000000 --- a/doc/administration/operations/unicorn.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: 'puma.md' -remove_date: '2021-08-26' ---- - -This file was moved to [another location](puma.md). - -<!-- This redirect file can be deleted after <2021-08-26>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/package_information/defaults.md b/doc/administration/package_information/defaults.md new file mode 100644 index 00000000000..45bea065995 --- /dev/null +++ b/doc/administration/package_information/defaults.md @@ -0,0 +1,72 @@ +--- +stage: Enablement +group: Distribution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Package defaults + +Unless configuration is specified in the `/etc/gitlab/gitlab.rb` file, +the package will assume the defaults as noted below. + +## Ports + +See the table below for the list of ports that the Omnibus GitLab assigns +by default: + +| Component | On by default | Communicates via | Alternative | Connection port | +| :----------------------------------------------------: | :------------: | :--------------: | :---------: | :------------------------------------: | +| <a name="gitlab-rails"></a> GitLab Rails | Yes | Port | X | 80 or 443 | +| <a name="gitlab-shell"></a> GitLab Shell | Yes | Port | X | 22 | +| <a name="postgresql"></a> PostgreSQL | Yes | Socket | Port (5432) | X | +| <a name="redis"></a> Redis | Yes | Socket | Port (6379) | X | +| <a name="puma"></a> Puma | Yes | Socket | Port (8080) | X | +| <a name="gitlab-workhorse"></a> GitLab Workhorse | Yes | Socket | Port (8181) | X | +| <a name="nginx-status"></a> NGINX status | Yes | Port | X | 8060 | +| <a name="prometheus"></a> Prometheus | Yes | Port | X | 9090 | +| <a name="node-exporter"></a> Node exporter | Yes | Port | X | 9100 | +| <a name="redis-exporter"></a> Redis exporter | Yes | Port | X | 9121 | +| <a name="postgres-exporter"></a> PostgreSQL exporter | Yes | Port | X | 9187 | +| <a name="pgbouncer-exporter"></a> PgBouncer exporter | No | Port | X | 9188 | +| <a name="gitlab-exporter"></a> GitLab Exporter | Yes | Port | X | 9168 | +| <a name="sidekiq-exporter"></a> Sidekiq exporter | Yes | Port | X | 8082 | +| <a name="puma-exporter"></a> Puma exporter | No | Port | X | 8083 | +| <a name="geo-postgresql"></a> Geo PostgreSQL | No | Socket | Port (5431) | X | +| <a name="redis-sentinel"></a> Redis Sentinel | No | Port | X | 26379 | +| <a name="incoming-email"></a> Incoming email | No | Port | X | 143 | +| <a name="elasticsearch"></a> Elastic search | No | Port | X | 9200 | +| <a name="gitlab-pages"></a> GitLab Pages | No | Port | X | 80 or 443 | +| <a name="gitlab-registry-web"></a> GitLab Registry | No* | Port | X | 80, 443 or 5050 | +| <a name="gitlab-registry"></a> GitLab Registry | No | Port | X | 5000 | +| <a name="ldap"></a> LDAP | No | Port | X | Depends on the component configuration | +| <a name="kerberos"></a> Kerberos | No | Port | X | 8443 or 8088 | +| <a name="omniauth"></a> OmniAuth | Yes | Port | X | Depends on the component configuration | +| <a name="smtp"></a> SMTP | No | Port | X | 465 | +| <a name="remote-syslog"></a> Remote syslog | No | Port | X | 514 | +| <a name="mattermost"></a> Mattermost | No | Port | X | 8065 | +| <a name="mattermost-web"></a> Mattermost | No | Port | X | 80 or 443 | +| <a name="pgbouncer"></a> PgBouncer | No | Port | X | 6432 | +| <a name="consul"></a> Consul | No | Port | X | 8300, 8301(UDP), 8500, 8600[^Consul-notes] | +| <a name="patroni"></a> Patroni | No | Port | X | 8008 | +| <a name="gitlab-kas"></a> GitLab KAS | No | Port | X | 8150 | +| <a name="gitaly"></a> Gitaly | No | Port | X | 8075 | + +Legend: + +- `Component` - Name of the component. +- `On by default` - Is the component running by default. +- `Communicates via` - How the component talks with the other components. +- `Alternative` - If it is possible to configure the component to use different type of communication. The type is listed with default port used in that case. +- `Connection port` - Port on which the component communicates. + +GitLab also expects a filesystem 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 +`2049` to be open. + +NOTE: +In some cases, the GitLab Registry will be automatically enabled by default. Please 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://www.consul.io/docs/install/ports#ports-table) for the list. diff --git a/doc/administration/package_information/deprecated_os.md b/doc/administration/package_information/deprecated_os.md new file mode 100644 index 00000000000..251dbe1e20e --- /dev/null +++ b/doc/administration/package_information/deprecated_os.md @@ -0,0 +1,82 @@ +--- +stage: Enablement +group: Distribution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# OS Versions that are no longer supported + +GitLab provides omnibus packages for operating systems only until their +EOL (End-Of-Life). After the EOL date of the OS, GitLab will stop releasing +official packages. The list of deprecated operating systems and the final GitLab +release for them can be found below: + +| OS Version | End Of Life | Last supported GitLab version | +| --------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Raspbian Wheezy | [May 2015](https://downloads.raspberrypi.org/raspbian/images/raspbian-2015-05-07/) | [GitLab CE](https://packages.gitlab.com/app/gitlab/raspberry-pi2/search?q=gitlab-ce_8.17&dist=debian%2Fwheezy) 8.17 | +| OpenSUSE 13.2 | [January 2017](https://en.opensuse.org/Lifetime#Discontinued_distributions) | [GitLab CE](https://packages.gitlab.com/app/gitlab/gitlab-ce/search?q=gitlab-ce-9.1&dist=opensuse%2F13.2) / [GitLab EE](https://packages.gitlab.com/app/gitlab/gitlab-ee/search?q=gitlab-ee-9.1&dist=opensuse%2F13.2) 9.1 | +| Ubuntu 12.04 | [April 2017](https://ubuntu.com/info/release-end-of-life) | [GitLab CE](https://packages.gitlab.com/app/gitlab/gitlab-ce/search?q=gitlab-ce_9.1&dist=ubuntu%2Fprecise) / [GitLab EE](https://packages.gitlab.com/app/gitlab/gitlab-ee/search?q=gitlab-ee_9.1&dist=ubuntu%2Fprecise) 9.1 | +| OpenSUSE 42.1 | [May 2017](https://en.opensuse.org/Lifetime#Discontinued_distributions) | [GitLab CE](https://packages.gitlab.com/app/gitlab/gitlab-ce/search?q=gitlab-ce-9.3&dist=opensuse%2F42.1) / [GitLab EE](https://packages.gitlab.com/app/gitlab/gitlab-ee/search?q=gitlab-ee-9.3&dist=opensuse%2F42.1) 9.3 | +| OpenSUSE 42.2 | [January 2018](https://en.opensuse.org/Lifetime#Discontinued_distributions) | [GitLab CE](https://packages.gitlab.com/app/gitlab/gitlab-ce/search?q=gitlab-ce-10.4&dist=opensuse%2F42.2) / [GitLab EE](https://packages.gitlab.com/app/gitlab/gitlab-ee/search?q=gitlab-ee-10.4&dist=opensuse%2F42.2) 10.4 | +| Debian Wheezy | [May 2018](https://www.debian.org/News/2018/20180601) | [GitLab CE](https://packages.gitlab.com/app/gitlab/gitlab-ce/search?q=gitlab-ce_11.6&dist=debian%2Fwheezy) / [GitLab EE](https://packages.gitlab.com/app/gitlab/gitlab-ee/search?q=gitlab-ee_11.6&dist=debian%2Fwheezy) 11.6 | +| Raspbian Jessie | [May 2017](https://downloads.raspberrypi.org/raspbian/images/raspbian-2017-07-05/) | [GitLab CE](https://packages.gitlab.com/app/gitlab/raspberry-pi2/search?q=gitlab-ce_11.7&dist=debian%2Fjessie) 11.7 | +| Ubuntu 14.04 | [April 2019](https://ubuntu.com/info/release-end-of-life) | [GitLab CE](https://packages.gitlab.com/app/gitlab/gitlab-ce/search?q=gitlab-ce_11.10&dist=ubuntu%2Ftrusty) / [GitLab EE](https://packages.gitlab.com/app/gitlab/gitlab-ee/search?q=gitlab-ee_11.10&dist=ubuntu%2Ftrusty) 11.10 | +| OpenSUSE 42.3 | [July 2019](https://en.opensuse.org/Lifetime#Discontinued_distributions) | [GitLab CE](https://packages.gitlab.com/app/gitlab/gitlab-ce/search?q=gitlab-ce-12.1&dist=opensuse%2F42.3) / [GitLab EE](https://packages.gitlab.com/app/gitlab/gitlab-ee/search?q=gitlab-ee-12.1&dist=opensuse%2F42.3) 12.1 | +| OpenSUSE 15.0 | [December 2019](https://en.opensuse.org/Lifetime#Discontinued_distributions) | [GitLab CE](https://packages.gitlab.com/app/gitlab/gitlab-ce/search?q=gitlab-ce-12.5&dist=opensuse%2F15.0) / [GitLab EE](https://packages.gitlab.com/app/gitlab/gitlab-ee/search?q=gitlab-ee-12.5&dist=opensuse%2F15.0) 12.5 | +| Raspbian Stretch | [June 2020](https://downloads.raspberrypi.org/raspbian/images/raspbian-2019-04-09/) | [GitLab CE](https://packages.gitlab.com/app/gitlab/raspberry-pi2/search?q=gitlab-ce_13.2&dist=raspbian%2Fstretch) 13.3 | +| Debian Jessie | [June 2020](https://www.debian.org/News/2020/20200709) | [GitLab CE](https://packages.gitlab.com/app/gitlab/gitlab-ce/search?q=gitlab-ce_13.2&dist=debian%2Fjessie) / [GitLab EE](https://packages.gitlab.com/app/gitlab/gitlab-ee/search?q=gitlab-ee_13.2&dist=debian%2Fjessie) 13.3 | +| CentOS 6 | [November 2020](https://wiki.centos.org/About/Product) | [GitLab CE](https://packages.gitlab.com/app/gitlab/gitlab-ce/search?q=13.6&filter=all&filter=all&dist=el%2F6) / [GitLab EE](https://packages.gitlab.com/app/gitlab/gitlab-ee/search?q=13.6&filter=all&filter=all&dist=el%2F6) 13.6 | +| OpenSUSE 15.1 | [November 2020](https://en.opensuse.org/Lifetime#Discontinued_distributions) | [GitLab CE](https://packages.gitlab.com/app/gitlab/gitlab-ce/search?q=gitlab-ce-13.12&dist=opensuse%2F15.1) / [GitLab EE](https://packages.gitlab.com/app/gitlab/gitlab-ee/search?q=gitlab-ee-13.12&dist=opensuse%2F15.2) 13.12 | +| Ubuntu 16.04 | [April 2021](https://ubuntu.com/info/release-end-of-life) | [GitLab CE](https://packages.gitlab.com/app/gitlab/gitlab-ce/search?q=gitlab-ce_13.12&dist=ubuntu%2Fxenial) / [GitLab EE](https://packages.gitlab.com/app/gitlab/gitlab-ee/search?q=gitlab-ee_13.12&dist=ubuntu%2Fxenial) 13.12 | + +NOTE: +An exception to this deprecation policy is when we are unable to provide +packages for the next version of the operating system. The most common reason +for this our package repository provider, Packagecloud, not supporting newer +versions and hence we can't upload packages to it. + +## Update GitLab package sources after upgrading the OS + +After upgrading the Operating System (OS) as per its own documentation, +it may be necessary to also update the GitLab package source URL +in your package manager configuration. +If your package manager reports that no further updates are available, +although [new versions have been released](https://about.gitlab.com/releases/categories/releases/), repeat the +"Add the GitLab package repository" instructions +of the [Linux package install guide](https://about.gitlab.com/install/#content). +Future GitLab upgrades will now be fetched according to your upgraded OS. + +## Supported Operating Systems + +GitLab officially supports LTS versions of operating systems. While OSs like +Ubuntu have a clear distinction between LTS and non-LTS versions, there are +other OSs, openSUSE for example, that don't follow the LTS concept. Hence to +avoid confusion, the official policy is that at any point of time, all the +operating systems supported by GitLab are listed in the [installation +page](https://about.gitlab.com/install/). + +The following lists the currently supported OSs and their possible EOL dates. + +| OS Version | First supported GitLab version | Arch | OS EOL | Details | +| ---------------- | ------------------------------ | --------------- | ------------- | ------------------------------------------------------------ | +| CentOS 7 | GitLab CE / GitLab EE 7.10.0 | x86_64 | June 2024 | <https://wiki.centos.org/About/Product> | +| CentOS 8 | GitLab CE / GitLab EE 12.8.1 | x86_64, aarch64 | Dec 2021 | <https://wiki.centos.org/About/Product> | +| Debian 9 | GitLab CE / GitLab EE 9.3.0 | amd64 | 2022 | <https://wiki.debian.org/DebianReleases#Production_Releases> | +| Debian 10 | GitLab CE / GitLab EE 12.2.0 | amd64, arm64 | TBD | <https://wiki.debian.org/DebianReleases#Production_Releases> | +| OpenSUSE 15.2 | GitLab CE / GitLab EE 13.11.0 | x86_64, aarch64 | Dec 2021 | <https://en.opensuse.org/Lifetime> | +| SLES 12 | GitLab EE 9.0.0 | x86_64 | Oct 2027 | <https://www.suse.com/lifecycle/> | +| Ubuntu 18.04 | GitLab CE / GitLab EE 10.7.0 | amd64 | April 2023 | <https://wiki.ubuntu.com/Releases> | +| Ubuntu 20.04 | GitLab CE / GitLab EE 13.2.0 | amd64, arm64 | April 2025 | <https://wiki.ubuntu.com/Releases> | +| Raspbian Buster | GitLab CE 12.2.0 | armhf | 2022 | <https://wiki.debian.org/DebianReleases#Production_Releases> | + +### Packages for ARM64 + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-omnibus-builder/-/issues/27) in GitLab 13.4. + +GitLab provides arm64/aarch64 packages for some supported operating systems. +You can see if your operating system architecture is supported in the table +above. + +WARNING: +There are currently still some [known issues and limitation](https://gitlab.com/groups/gitlab-org/-/epics/4397) +running GitLab on ARM. diff --git a/doc/administration/package_information/deprecation_policy.md b/doc/administration/package_information/deprecation_policy.md new file mode 100644 index 00000000000..cc16661442a --- /dev/null +++ b/doc/administration/package_information/deprecation_policy.md @@ -0,0 +1,95 @@ +--- +stage: Enablement +group: Distribution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Deprecation policy + +The Omnibus GitLab packages come with number of different libraries and services which offers users plethora of configuration options. + +As libraries and services get updated, their configuration options change +and become obsolete. To increase maintainability and preserve a working +setup, various configuration requires removal. + +## Configuration deprecation + +### Policy + +The Omnibus GitLab package will retain configuration for at least **one major** +version. We cannot guarantee that deprecated configuration +will be available in the next major release. See [example](#example) for more details. + +### Notice + +If the configuration becomes obsolete, we will announce the deprecation: + +- via release blog post on `https://about.gitlab.com/blog/`. The blog post item + will contain the deprecation notice together with the target removal date. +- via installation/reconfigure output (if applicable). +- via official documentation on `https://docs.gitlab.com/`. The documentation update will contain the corrected syntax (if applicable) or a date of configuration removal. + +### Procedure + +This section lists steps necessary for deprecating and removing configuration. + +We can differentiate two different types of configuration: + +- Sensitive: Configuration that can cause major service outage ( Data integrity, + installation integrity, preventing users from reaching the installation, etc.) +- Regular: Configuration that can make a feature unavailable but still makes the installation useable ( Change in default project/group settings, miscommunication with other components and similar ) + +We also need to differentiate deprecation and removal procedure. + +#### Deprecating configuration + +Deprecation procedure is similar for both `sensitive` and `regular` configuration. The only difference is in the removal target date. + +Common steps: + +1. Create an issue at the [Omnibus GitLab issue tracker](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues) with details on deprecation type and other necessary information. Apply the label `deprecation`. +1. Decide on the removal target for the deprecated configuration +1. Formulate deprecation notice for each item as noted in [Notice section](#notice) + +Removal target: + +For regular configuration, removal target should always be the date of the **next major** release. If the date is not known, you can reference the next major version. + +For sensitive configuration things are a bit more complicated. +We should aim to not remove sensitive configuration in the *next major* release if the next major release is 2 minor releases away (This number is chosen to match our security backport release policy). + +See the table below for some examples: + +| Config. type | Deprecation announced | Final minor release | Remove | +| -------- | -------- | -------- | -------- | +| Sensitive | 10.1.0 | 10.9.0 | 11.0.0 | +| Sensitive | 10.7.0 | 10.9.0 | 12.0.0 | +| Regular | 10.1.0 | 10.9.0 | 11.0.0 | +| Regular | 10.8.0 | 10.9.0 | 11.0.0 | + +#### Removing configuration + +When deprecation is announced and removal target set, the milestone for the issue +should be changed to match the removal target version. + +The final comment in the issue **has to have**: + +1. Text snippet for the release blog post section +1. Documentation MR ( or snippet ) for introducing the change +1. Draft MR removing the configuration OR details on what needs to be done. See [Adding deprecation messages](https://docs.gitlab.com/omnibus/development/adding-deprecation-messages.html) for more on this + +## Example + +User configuration available in `/etc/gitlab/gitlab.rb` was introduced in GitLab version 10.0, `gitlab_rails['configuration'] = true`. In GitLab version 10.4.0, a new change was introduced that requires rename of this configuration option. New configuration option is `gitlab_rails['better_configuration'] = true`. Development team will translate the old configuration into new one +and trigger a deprecation procedure. + +This means that these two configuration +options will both be valid through GitLab version 10. In other words, +if you still have `gitlab_rails['configuration'] = true` set in GitLab 10.8.0 +the feature will continue working the same way as if you had `gitlab_rails['better_configuration'] = true` set. +However, setting the old version of configuration will print out a deprecation +notice at the end of installation/upgrade/reconfigure run. + +With GitLab 11, `gitlab_rails['configuration'] = true` will no longer work and you will have to manually change the configuration in `/etc/gitlab/gitlab.rb` to the new valid config. +**Note** If this configuration option is sensitive and can put integrity of the installation or +data in danger, installation/upgrade will be aborted. diff --git a/doc/administration/package_information/index.md b/doc/administration/package_information/index.md new file mode 100644 index 00000000000..e18fb621b89 --- /dev/null +++ b/doc/administration/package_information/index.md @@ -0,0 +1,101 @@ +--- +stage: Enablement +group: Distribution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Package information + +The Omnibus GitLab package is bundled with all dependencies required for GitLab +to function correctly. More details can be found +at [bundling dependencies document](omnibus_packages.md). + +## Package Version + +The released package versions are in the format `MAJOR.MINOR.PATCH-EDITION.OMNIBUS_RELEASE` + +| Component | Meaning | Example | +| --------- | ------- | ------- | +| MAJOR.MINOR.PATCH | The GitLab version this corresponds to | 13.3.0 | +| EDITION | The edition of GitLab this corresponds to | ee | +| OMNIBUS_RELEASE | The omnibus release. Usually, this will be 0. This will be incremented if we need to build a new package without changing the GitLab version. | 0 | + +## Licenses + +See [licensing](licensing.md) + +## Defaults + +The Omnibus GitLab package requires various configuration to get the +components in working order. +If the configuration is not provided, the package will use the default +values assumed in the package. + +These defaults are noted in the package [defaults document](defaults.md). + +## Checking the versions of bundled software + +Once the Omnibus GitLab package is installed, all versions of the bundled +libraries are located in `/opt/gitlab/version-manifest.txt`. + +If you don't have the package installed, you can always check the Omnibus GitLab +[source repository](https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master), specifically the +[config directory](https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master/config). + +For example, if you take a look at the `8-6-stable` branch, you can conclude that +8.6 packages were running [Ruby 2.1.8](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/8-6-stable/config/projects/gitlab.rb#L48). +Or, that 8.5 packages were bundled with [NGINX 1.9.0](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/8-5-stable/config/software/nginx.rb#L20). + +## Signatures of GitLab, Inc. provided packages + +Documentation on package signatures can be found at [Signed Packages](signed_packages.md) + +## Checking for newer configuration options on upgrade + +Configuration file in `/etc/gitlab/gitlab.rb` is created on initial installation +of the Omnibus GitLab package. On subsequent package upgrades, the configuration +file is not updated with new configuration. This is done in order to avoid +accidental overwrite of user configuration provided in `/etc/gitlab/gitlab.rb`. + +New configuration options are noted in the +[`gitlab.rb.template` file](https://gitlab.com/gitlab-org/omnibus-gitlab/raw/master/files/gitlab-config-template/gitlab.rb.template). + +The Omnibus GitLab package also provides convenience command which will +compare the existing user configuration with the latest version of the +template contained in the package. + +To view a diff between your configuration file and the latest version, run: + +```shell +sudo gitlab-ctl diff-config +``` + +_**Note:** This command is available from GitLab 8.17_ + +**Important:** If you are copy-pasting the output of this command into your +`/etc/gitlab/gitlab.rb` configuration file, make sure to omit leading `+` and `-` +on each line. + +## Init system detection + +Omnibus GitLab will attempt to query the underlaying system in order to +check which init system it uses. +This manifests itself as a `WARNING` during the `sudo gitlab-ctl reconfigure` +run. + +Depending on the init system, this `WARNING` can be one of: + +```plaintext +/sbin/init: unrecognized option '--version' +``` + +when the underlying init system *IS NOT* upstart. + +```plaintext + -.mount loaded active mounted / +``` + +when the underlying init system *IS* systemd. + +These warnings _can be safely ignored_. They are not suppressed because this +allows everyone to debug possible detection issues faster. diff --git a/doc/administration/package_information/licensing.md b/doc/administration/package_information/licensing.md new file mode 100644 index 00000000000..8557a94bf93 --- /dev/null +++ b/doc/administration/package_information/licensing.md @@ -0,0 +1,79 @@ +--- +stage: Enablement +group: Distribution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Package Licensing + +## License + +While GitLab itself is MIT, the Omnibus GitLab sources are licensed under the Apache-2.0. + +## License file location + +Starting with version 8.11, the Omnibus GitLab package contains license +information of all software that is bundled within the package. + +After installing the package, licenses for each individual bundled library +can be found in `/opt/gitlab/LICENSES` directory. + +There is also one `LICENSE` file which contains all licenses compiled together. +This compiled license can be found in `/opt/gitlab/LICENSE` file. + +Starting with version 9.2, the Omnibus GitLab package ships a +`dependency_licenses.json` file containing version and license information of +all bundled software, including software libraries, Ruby gems that the rails +application uses, and JavaScript libraries that is required for the frontend +components. This file, being in JSON format, is easily machine parseable and +can be used for automated checks or validations. The file may be found at +`/opt/gitlab/dependency_licenses.json`. + +Starting with version 11.3, we have also made the license information available +online, at: <https://gitlab-org.gitlab.io/omnibus-gitlab/licenses.html> + +## Checking licenses + +The Omnibus GitLab package is made up of many pieces of software, comprising code +that is covered by many different licenses. Those licenses are provided and +compiled as stated above. + +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`, +`Unknown` or `Check` for each piece of software that is a part of the +Omnibus GitLab package. + +- `Good`: denotes a license that is approved for all usage types, within GitLab and + Omnibus GitLab. +- `Unknown`: denotes a license that is not recognized in the list of 'good' or 'bad', + which should be immediately reviewed for implications of use. +- `Check`: denotes a license that has the potential be incompatible with GitLab itself, + and thus should be checked for how it is used as a part of the Omnibus GitLab package + to ensure compliance. + +This list is currently sourced from the [GitLab development documentation on licensing](https://gitlab.com/gitlab-org/gitlab-foss/blob/master/doc/development/licensing.md). +However, due to the nature of the Omnibus GitLab package the licenses may not apply +in the same way. Such as with `git` and `rsync`. See the [GNU License FAQ](https://www.gnu.org/licenses/gpl-faq.en.html#MereAggregation) + +## License acknowledgements + +### libjpeg-turbo - BSD 3-clause license + +This software is based in part on the work of the Independent JPEG Group. + +## Trademark Usage + +Within the GitLab documentation, reference to third party technology(ies) and/or trademarks of third party entities, may be made. The inclusion of reference to third party technology and/or entities is solely for the purposes of example(s) of how GitLab software may interact with, or be used in conjunction with, such third party technology. +All trademarks, materials, documentation, and other intellectual property remain the property of any/all such third party. + +### 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). +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. + +If a trademark owner requires a particular notice or trademark requirement, such notice or requirement should be stated above. diff --git a/doc/administration/package_information/omnibus_packages.md b/doc/administration/package_information/omnibus_packages.md new file mode 100644 index 00000000000..aa73534fc55 --- /dev/null +++ b/doc/administration/package_information/omnibus_packages.md @@ -0,0 +1,115 @@ +--- +stage: Enablement +group: Distribution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Omnibus based packages and images + +Below you can find some basic information on why GitLab provides packages and +a Docker image that come with bundled dependencies. + +These methods are great for physical and virtual machine installations, and simple Docker installations. + +## Goals + +We have a few core goals with these packages: + +1. Extremely easy to install, upgrade, maintain. +1. Support for a wide variety of operating systems +1. Wide support of cloud service providers + +## Omnibus GitLab Architecture + +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 +unpredictably. + +The [GitLab Architecture Overview](../../development/architecture.md#gitlab-architecture-overview) shows some of these components and how they +interact. Each of these components needs to be configured and kept up to date. + +Most of the components also have external dependencies. For example, the Rails +application depends on a number of [Ruby gems](https://gitlab.com/gitlab-org/gitlab-foss/blob/master/Gemfile.lock). Some of these dependencies also +have their own external dependencies which need to be present on the Operating +System in order for them to function correctly. + +Furthermore, GitLab has a monthly release cycle requiring frequent maintenance +to stay up to date. + +All the things listed above present a challenge for the user maintaining the GitLab +installation. + +## External Software Dependencies + +For applications such as GitLab, external dependencies usually bring the following +challenges: + +- Keeping versions in sync between direct and indirect dependencies +- Availability of a version on a specific Operating System +- Version changes can introduce or remove previously used configuration +- Security implications when library is marked as vulnerable but does not have + a new version released yet + +Keep in mind that if a dependency exists on your Operating System, it does not +necessarily exist on other supported OSs. + +## Benefits + +A few benefits of a package with bundled dependencies: + +1. Minimal effort required to install GitLab. +1. Minimum configuration required to get GitLab up and running. +1. Minimum effort required to upgrade between GitLab versions. +1. Multiple platforms supported. +1. Maintenance on older platforms is greatly simplified. +1. Less effort to support potential issues. + +## Drawbacks + +Some drawbacks of a package with bundled dependencies: + +1. Duplication with possibly existing software. +1. Less flexibility in configuration. + +## Why would I install an omnibus package when I can use a system package? + +The answer can be simplified to: less maintenance required. Instead of handling +multiple packages that *can* break existing functionality if the versions are +not compatible, only handle one. + +Multiple packages require correct configuration in multiple locations. +Keeping configuration in sync can be error prone. + +If you have the skill set to maintain all current dependencies and enough time +to handle any future dependencies that might get introduced, the above listed +reasons might not be good enough for you to not use the omnibus package. + +There are two things to keep in mind before going down this route: + +1. Getting support for any problems + you encounter might be more difficult due to the number of possibilities that exist + when using a library version that is not tested by majority of users. +1. Omnibus package also allows shutting off of any services that you do not need, + if you need to run a component independently. For example, you can use a + [non-bundled PostgreSQL database](https://docs.gitlab.com/omnibus/settings/database.html#using-a-non-packaged-postgresql-database-management-server) with the omnibus package. + +Keep in mind that a non-standard solution like the omnibus package +might be a better fit when the application has a number of moving parts. + +## Docker image with multiple services + +[GitLab Docker image](../../install/docker.md#gitlab-docker-images) is based on the omnibus package. + +Considering that container spawned from this image contains multiple processes, +these types of containers are also referred to as 'fat containers'. + +There are reasons for and against an image like this, but they are similar to +what was noted above: + +1. Very simple to get started. +1. Upgrading to the latest version is extremely simple. +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. diff --git a/doc/administration/package_information/postgresql_versions.md b/doc/administration/package_information/postgresql_versions.md new file mode 100644 index 00000000000..89da4864872 --- /dev/null +++ b/doc/administration/package_information/postgresql_versions.md @@ -0,0 +1,42 @@ +--- +stage: Enablement +group: Distribution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# PostgreSQL versions shipped with Omnibus GitLab + +NOTE: +This table lists only GitLab versions where a significant change happened in the +package regarding PostgreSQL versions, not all. + +Usually, PostgreSQL versions change with major or minor GitLab releases. However, patch versions +of Omnibus GitLab sometimes update the patch level of PostgreSQL. + +For example: + +- Omnibus 12.7.6 shipped with PostgreSQL 9.6.14 and 10.9. +- Omnibus 12.7.7 shipped with PostgreSQL 9.6.17 and 10.12. + +[Find out which versions of PostgreSQL (and other components) ship with +each Omnibus GitLab release](https://gitlab-org.gitlab.io/omnibus-gitlab/licenses.html). + +Read more about update policies and warnings in the PostgreSQL +[upgrade docs](https://docs.gitlab.com/omnibus/settings/database.html#upgrade-packaged-postgresql-server). + +| GitLab version | PostgreSQL versions | Default version for fresh installs | Default version for upgrades | Notes | +| -------------- | --------------------- | ---------------------------------- | ---------------------------- | ----- | +| 14.1 | 12.6, 13.3 | 12.6 | 12.6 | PostgreSQL 13 available for fresh installations if not using Geo or High Availability. | +| 14.0 | 12.6 | 12.6 | 12.6 | HA installations with repmgr are no longer supported and will be prevented from upgrading to Omnibus GitLab 14.0 | +| 13.8 | 11.9, 12.4 | 12.4 | 12.4 | Package upgrades automatically performed PostgreSQL upgrade for nodes that are not part of a Geo or HA cluster.). | +| 13.7 | 11.9, 12.4 | 12.4 | 11.9 | For upgrades users can manually upgrade to 12.4 following the [upgrade docs](https://docs.gitlab.com/omnibus/settings/database.html#gitlab-133-and-later). | +| 13.4 | 11.9, 12.4 | 11.9 | 11.9 | Package upgrades aborted if users not running PostgreSQL 11 already | +| 13.3 | 11.7, 12.3 | 11.7 | 11.7 | Package upgrades aborted if users not running PostgreSQL 11 already | +| 13.0 | 11.7 | 11.7 | 11.7 | Package upgrades aborted if users not running PostgreSQL 11 already | +| 12.10 | 9.6.17, 10.12, and 11.7 | 11.7 | 11.7 | Package upgrades automatically performed PostgreSQL upgrade for nodes that are not part of a Geo or repmgr cluster. | +| 12.8 | 9.6.17, 10.12, and 11.7 | 10.12 | 10.12 | Users can manually upgrade to 11.7 following the upgrade docs. | +| 12.0 | 9.6.11 and 10.7 | 10.7 | 10.7 | Package upgrades automatically performed PostgreSQL upgrade. | +| 11.11 | 9.6.11 and 10.7 | 9.6.11 | 9.6.11 | Users can manually upgrade to 10.7 following the upgrade docs. | +| 10.0 | 9.6.3 | 9.6.3 | 9.6.3 | Package upgrades aborted if users still on 9.2. | +| 9.0 | 9.2.18 and 9.6.1 | 9.6.1 | 9.6.1 | Package upgrades automatically performed PostgreSQL upgrade. | +| 8.14 | 9.2.18 and 9.6.1 | 9.2.18 | 9.2.18 | Users can manually upgrade to 9.6 following the upgrade docs. | diff --git a/doc/administration/package_information/signed_packages.md b/doc/administration/package_information/signed_packages.md new file mode 100644 index 00000000000..fb994809460 --- /dev/null +++ b/doc/administration/package_information/signed_packages.md @@ -0,0 +1,25 @@ +--- +stage: Enablement +group: Distribution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Package Signatures + +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 (e.g. `9.3.x` and `9.4.x` after August 22, 2017). Any package version prior to August 22, 2017, will not be signed. Please 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. + +## GnuPG Public Keys + +All packages are signed with [GnuPG](https://www.gnupg.org/), in a method appropriate for their format. The key used to sign these packages can be found on [pgp.mit.edu](https://pgp.mit.edu) at [0x3cfcf9baf27eab47](https://pgp.mit.edu/pks/lookup?op=vindex&search=0x3CFCF9BAF27EAB47) + +## Verifying Signatures + +Information on how to verify GitLab package signatures can be found in [Package Signatures](https://docs.gitlab.com/omnibus/update/package_signatures.html). + +## GPG Signature Management + +Information on how GitLab manages GPG keys for package signing can be found in [the runbooks](https://gitlab.com/gitlab-com/runbooks/-/blob/master/docs/packaging/manage-package-signing-keys.md). diff --git a/doc/administration/packages/container_registry.md b/doc/administration/packages/container_registry.md index eb118709f94..1067474c8b4 100644 --- a/doc/administration/packages/container_registry.md +++ b/doc/administration/packages/container_registry.md @@ -321,7 +321,7 @@ The different supported drivers are: | Driver | Description | |--------------|--------------------------------------| | `filesystem` | Uses a path on the local file system | -| `Azure` | Microsoft Azure Blob Storage | +| `azure` | Microsoft Azure Blob Storage | | `gcs` | Google Cloud Storage | | `s3` | Amazon Simple Storage Service. Be sure to configure your storage bucket with the correct [S3 Permission Scopes](https://docs.docker.com/registry/storage-drivers/s3/#s3-permission-scopes). | | `swift` | OpenStack Swift Object Storage | @@ -1054,6 +1054,80 @@ PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin You may want to add the `-m` flag to [remove untagged manifests and unreferenced layers](#removing-untagged-manifests-and-unreferenced-layers). +## Configuring GitLab and Registry to run on separate nodes (Omnibus GitLab) + +By default, package assumes that both services are running on the same node. +In order to get GitLab and Registry to run on a separate nodes, separate configuration +is necessary for Registry and GitLab. + +### Configuring Registry + +Below you will find configuration options you should set in `/etc/gitlab/gitlab.rb`, +for Registry to run separately from GitLab: + +- `registry['registry_http_addr']`, default [set programmatically](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/10-3-stable/files/gitlab-cookbooks/gitlab/libraries/registry.rb#L50). Needs to be reachable by web server (or LB). +- `registry['token_realm']`, default [set programmatically](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/10-3-stable/files/gitlab-cookbooks/gitlab/libraries/registry.rb#L53). Specifies the endpoint to use to perform authentication, usually the GitLab URL. + This endpoint needs to be reachable by user. +- `registry['http_secret']`, [random string](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/10-3-stable/files/gitlab-cookbooks/gitlab/libraries/registry.rb#L32). A random piece of data used to sign state that may be stored with the client to protect against tampering. +- `registry['internal_key']`, default [automatically generated](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/10-3-stable/files/gitlab-cookbooks/gitlab/recipes/gitlab-rails.rb#L113-119). Contents of the key that GitLab uses to sign the tokens. They key gets created on the Registry server, but it won't be used there. +- `gitlab_rails['registry_key_path']`, default [set programmatically](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/10-3-stable/files/gitlab-cookbooks/gitlab/recipes/gitlab-rails.rb#L35). This is the path where `internal_key` contents will be written to disk. +- `registry['internal_certificate']`, default [automatically generated](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/10-3-stable/files/gitlab-cookbooks/registry/recipes/enable.rb#L60-66). Contents of the certificate that GitLab uses to sign the tokens. +- `registry['rootcertbundle']`, default [set programmatically](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/10-3-stable/files/gitlab-cookbooks/registry/recipes/enable.rb#L60). Path to certificate. This is the path where `internal_certificate` + contents will be written to disk. +- `registry['health_storagedriver_enabled']`, default [set programmatically](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/10-7-stable/files/gitlab-cookbooks/gitlab/libraries/registry.rb#L88). Configure whether health checks on the configured storage driver are enabled. +- `gitlab_rails['registry_issuer']`, [default value](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/10-3-stable/files/gitlab-cookbooks/gitlab/attributes/default.rb#L153). This setting needs to be set the same between Registry and GitLab. + +### Configuring GitLab + +Below you will find configuration options you should set in `/etc/gitlab/gitlab.rb`, +for GitLab to run separately from Registry: + +- `gitlab_rails['registry_enabled']`, must be set to `true`. This setting will + signal to GitLab that it should allow Registry API requests. +- `gitlab_rails['registry_api_url']`, default [set programmatically](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/10-3-stable/files/gitlab-cookbooks/gitlab/libraries/registry.rb#L52). This is the Registry URL used internally that users do not need to interact with, `registry['registry_http_addr']` with scheme. +- `gitlab_rails['registry_host']`, eg. `registry.gitlab.example`. Registry endpoint without the scheme, the address that gets shown to the end user. +- `gitlab_rails['registry_port']`. Registry endpoint port, visible to the end user. +- `gitlab_rails['registry_issuer']` must match the issuer in the Registry configuration. +- `gitlab_rails['registry_key_path']`, path to the key that matches the certificate on the + Registry side. +- `gitlab_rails['internal_key']`, contents of the key that GitLab uses to sign the tokens. + +## Architecture of GitLab Container Registry + +The GitLab registry is what users use to store their own Docker images. +Because of that the Registry is client facing, meaning that we expose it directly +on the web server (or load balancers, LB for short). + + + +The flow described by the diagram above: + +1. A user runs `docker login registry.gitlab.example` on their client. This reaches the web server (or LB) on port 443. +1. Web server connects to the Registry backend pool (by default, using port 5000). Since the user + didn’t provide a valid token, the Registry returns a 401 HTTP code and the URL (`token_realm` from + Registry configuration) where to get one. This points to the GitLab API. +1. The Docker client then connects to the GitLab API and obtains a token. +1. The API signs the token with the registry key and hands it to the Docker client +1. The Docker client now logs in again with the token received from the API. It can now push and pull Docker images. + +Reference: <https://docs.docker.com/registry/spec/auth/token/> + +### Communication between GitLab and Registry + +Registry doesn’t have a way to authenticate users internally so it relies on +GitLab to validate credentials. The connection between Registry and GitLab is +TLS encrypted. The key is used by GitLab to sign the tokens while the certificate +is used by Registry to validate the signature. By default, a self-signed certificate key pair is generated +for all installations. This can be overridden as needed. + +GitLab interacts with the Registry using the Registry private key. When a Registry +request goes out, a new short-living (10 minutes) namespace limited token is generated +and signed with the private key. +The Registry then verifies that the signature matches the registry certificate +specified in its configuration and allows the operation. +GitLab background jobs processing (through Sidekiq) also interacts with Registry. +These jobs talk directly to Registry in order to handle image deletion. + ## Troubleshooting Before diving in to the following sections, here's some basic troubleshooting: @@ -1122,7 +1196,7 @@ CI/CD > Container Registry > Authorization token duration (minutes)**. ### Docker login attempt fails with: 'token signed by untrusted key' -[Registry relies on GitLab to validate credentials](https://docs.gitlab.com/omnibus/architecture/registry/). +[Registry relies on GitLab to validate credentials](#architecture-of-gitlab-container-registry) If the registry fails to authenticate valid login attempts, you get the following error message: ```shell diff --git a/doc/administration/packages/dependency_proxy.md b/doc/administration/packages/dependency_proxy.md index c4906ef6d8e..32e7e191011 100644 --- a/doc/administration/packages/dependency_proxy.md +++ b/doc/administration/packages/dependency_proxy.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Dependency Proxy administration **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.11. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) to [GitLab Free](https://about.gitlab.com/pricing/) in GitLab 13.6. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) from GitLab Premium to GitLab Free in 13.6. GitLab can be used as a dependency proxy for a variety of common package managers. diff --git a/doc/administration/packages/img/gitlab-registry-architecture.png b/doc/administration/packages/img/gitlab-registry-architecture.png Binary files differnew file mode 100644 index 00000000000..742678d5e11 --- /dev/null +++ b/doc/administration/packages/img/gitlab-registry-architecture.png diff --git a/doc/administration/packages/index.md b/doc/administration/packages/index.md index 2c2e3fc0442..37473d35573 100644 --- a/doc/administration/packages/index.md +++ b/doc/administration/packages/index.md @@ -14,22 +14,17 @@ The Packages feature allows GitLab to act as a repository for the following: The Package Registry supports the following formats: -<div class="row"> -<div class="col-md-9"> -<table align="left" style="width:50%"> -<tr style="background:#dfdfdf"><th>Package type</th><th>GitLab version</th></tr> -<tr><td><a href="https://docs.gitlab.com/ee/user/packages/composer_repository/index.html">Composer</a></td><td>13.2+</td></tr> -<tr><td><a href="https://docs.gitlab.com/ee/user/packages/conan_repository/index.html">Conan</a></td><td>12.6+</td></tr> -<tr><td><a href="https://docs.gitlab.com/ee/user/packages/go_proxy/index.html">Go</a></td><td>13.1+</td></tr> -<tr><td><a href="https://docs.gitlab.com/ee/user/packages/maven_repository/index.html">Maven</a></td><td>11.3+</td></tr> -<tr><td><a href="https://docs.gitlab.com/ee/user/packages/npm_registry/index.html">npm</a></td><td>11.7+</td></tr> -<tr><td><a href="https://docs.gitlab.com/ee/user/packages/nuget_repository/index.html">NuGet</a></td><td>12.8+</td></tr> -<tr><td><a href="https://docs.gitlab.com/ee/user/packages/pypi_repository/index.html">PyPI</a></td><td>12.10+</td></tr> -<tr><td><a href="https://docs.gitlab.com/ee/user/packages/generic_packages/index.html">Generic packages</a></td><td>13.5+</td></tr> -<tr><td><a href="https://docs.gitlab.com/ee/user/packages/helm_repository/index.html">Helm Charts</a></td><td>14.1+</td></tr> -</table> -</div> -</div> +| Package type | GitLab version | +|-------------------------------------------------------------------|----------------| +| [Composer](../../user/packages/composer_repository/index.md) | 13.2+ | +| [Conan](../../user/packages/conan_repository/index.md) | 12.6+ | +| [Go](../../user/packages/go_proxy/index.md) | 13.1+ | +| [Maven](../../user/packages/maven_repository/index.md) | 11.3+ | +| [npm](../../user/packages/npm_registry/index.md) | 11.7+ | +| [NuGet](../../user/packages/nuget_repository/index.md) | 12.8+ | +| [PyPI](../../user/packages/pypi_repository/index.md) | 12.10+ | +| [Generic packages](../../user/packages/generic_packages/index.md) | 13.5+ | +| [Helm Charts](../../user/packages/helm_repository/index.md) | 14.1+ | ## Accepting contributions diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 5aeb3eaef7f..8b7af5ee170 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -196,43 +196,6 @@ to use the HTTPS protocol. WARNING: Multiple wildcards for one instance is not supported. Only one wildcard per instance can be assigned. -### Additional configuration for Docker container - -The GitLab Pages daemon doesn't have permissions to bind mounts when it runs -in a Docker container. To overcome this issue, you must change the `chroot` -behavior: - -1. Edit `/etc/gitlab/gitlab.rb`. -1. Set the `inplace_chroot` to `true` for GitLab Pages: - - ```ruby - gitlab_pages['inplace_chroot'] = true - ``` - -1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). - -NOTE: -`inplace_chroot` option might not work with the other features, such as [Pages Access Control](#access-control). -The [GitLab Pages README](https://gitlab.com/gitlab-org/gitlab-pages#caveats) has more information about caveats and workarounds. - -### Jailing mechanism disabled by default for API-based configuration - -Starting from GitLab 14.1 the [jailing/chroot mechanism is disabled by default](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/589). -If you are using API-based configuration and the new [Zip storage architecture](#zip-storage) -there is nothing you need to do. - -If you run into any problems, [open a new issue](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/new) -and enable the jail again by setting the environment variable: - -1. Edit `/etc/gitlab/gitlab.rb`. -1. Set the `DAEMON_ENABLE_JAIL` environment variable to `true` for GitLab Pages: - - ```ruby - gitlab_pages['env']['DAEMON_ENABLE_JAIL'] = "true" - ``` - -1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). - ### Global settings Below is a table of all configuration settings known to Pages in Omnibus GitLab, @@ -270,7 +233,7 @@ control over how the Pages daemon runs and serves content in your environment. | `auth_scope` | The OAuth application scope to use for authentication. Must match GitLab Pages OAuth application settings. Leave blank to use `api` scope by default. | | `gitlab_server` | Server to use for authentication when access control is enabled; defaults to GitLab `external_url`. | | `headers` | Specify any additional http headers that should be sent to the client with each response. Multiple headers can be given as an array, header and value as one string, for example `['my-header: myvalue', 'my-other-header: my-other-value']` | -| `inplace_chroot` | On [systems that don't support bind-mounts](index.md#additional-configuration-for-docker-container), this instructs GitLab Pages to `chroot` into its `pages_path` directory. Some caveats exist when using in-place `chroot`; refer to the GitLab Pages [README](https://gitlab.com/gitlab-org/gitlab-pages/blob/master/README.md#caveats) for more information. | +| `inplace_chroot` | [REMOVED in GitLab 14.3.](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/561) On [systems that don't support bind-mounts](index.md#gitlab-pages-fails-to-start-in-docker-container), this instructs GitLab Pages to `chroot` into its `pages_path` directory. Some caveats exist when using in-place `chroot`; refer to the GitLab Pages [README](https://gitlab.com/gitlab-org/gitlab-pages/blob/master/README.md#caveats) for more information. | | `enable_disk` | Allows the GitLab Pages daemon to serve content from disk. Shall be disabled if shared disk storage isn't available. | | `insecure_ciphers` | Use default list of cipher suites, may contain insecure ones like 3DES and RC4. | | `internal_gitlab_server` | Internal GitLab server address used exclusively for API requests. Useful if you want to send that traffic over an internal load balancer. Defaults to GitLab `external_url`. | @@ -298,8 +261,9 @@ control over how the Pages daemon runs and serves content in your environment. | `pages_path` | The directory on disk where pages are stored, defaults to `GITLAB-RAILS/shared/pages`. | | **`pages_nginx[]`** | | | `enable` | Include a virtual host `server{}` block for Pages inside NGINX. Needed for NGINX to proxy traffic back to the Pages daemon. Set to `false` if the Pages daemon should directly receive all requests, for example, when using [custom domains](index.md#custom-domains). | -| `FF_ENABLE_REDIRECTS` | Feature flag to disable redirects (enabled by default). Read the [redirects documentation](../../user/project/pages/redirects.md#disable-redirects) for more information. | -| `use_legacy_storage` | Temporarily-introduced parameter allowing to use legacy domain configuration source and storage. [Will be removed in GitLab 14.3](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6166). | +| `FF_ENABLE_REDIRECTS` | Feature flag to enable/disable redirects (enabled by default). Read the [redirects documentation](../../user/project/pages/redirects.md#feature-flag-for-redirects) for more information. | +| `FF_ENABLE_PLACEHOLDERS` | Feature flag to enable/disable rewrites (disabled by default). Read the [redirects documentation](../../user/project/pages/redirects.md#feature-flag-for-rewrites) for more information. | +| `use_legacy_storage` | Temporarily-introduced parameter allowing to use legacy domain configuration source and storage. [Removed in 14.3](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6166). | --- @@ -393,7 +357,7 @@ adding a GitLab-controlled verification code to the DNS records for that domain. If your user base is private or otherwise trusted, you can disable the verification requirement: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences**. 1. Expand **Pages**. 1. Clear the **Require users to prove ownership of custom domains** checkbox. @@ -410,7 +374,7 @@ sites served under a custom domain. To enable it: 1. Choose an email address on which you want to receive notifications about expiring domains. -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences**. 1. Expand **Pages**. 1. Enter the email address for receiving notifications and accept Let's Encrypt's Terms of Service. @@ -465,7 +429,7 @@ pre-existing applications must modify the GitLab Pages OAuth application. Follow this: 1. Enable [access control](#access-control). -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Applications**. 1. Expand **GitLab Pages**. 1. Clear the `api` scope's checkbox and select the desired scope's checkbox (for example, @@ -484,7 +448,7 @@ This can be useful to preserve information published with Pages websites to the of your instance only. To do that: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences**. 1. Expand **Pages**. 1. Select the **Disable public access to Pages sites** checkbox. @@ -522,7 +486,7 @@ Authority (CA) in the system certificate store. For Omnibus, this is fixed by [installing a custom CA in Omnibus GitLab](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). -### Zip serving and cache configuration +### ZIP serving and cache configuration > [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/392) in GitLab 13.7. @@ -530,19 +494,19 @@ WARNING: These are advanced settings. The recommended default values are set inside GitLab Pages. You should change these settings only if absolutely necessary. Use extreme caution. -GitLab Pages can serve content from zip archives through object storage (an +GitLab Pages can serve content from ZIP archives through object storage (an [issue](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/485) exists for supporting disk storage -as well). It uses an in-memory cache to increase the performance when serving content from a zip +as well). It uses an in-memory cache to increase the performance when serving content from a ZIP archive. You can modify the cache behavior by changing the following configuration flags. | Setting | Description | | ------- | ----------- | -| `zip_cache_expiration` | The cache expiration interval of zip archives. Must be greater than zero to avoid serving stale content. Default is 60s. | +| `zip_cache_expiration` | The cache expiration interval of ZIP archives. Must be greater than zero to avoid serving stale content. Default is 60s. | | `zip_cache_cleanup` | The interval at which archives are cleaned from memory if they have already expired. Default is 30s. | | `zip_cache_refresh` | The time interval in which an archive is extended in memory if accessed before `zip_cache_expiration`. This works together with `zip_cache_expiration` to determine if an archive is extended in memory. See the [example below](#zip-cache-refresh-example) for important details. Default is 30s. | -| `zip_open_timeout` | The maximum time allowed to open a zip archive. Increase this time for big archives or slow network connections, as doing so may affect the latency of serving Pages. Default is 30s. | +| `zip_open_timeout` | The maximum time allowed to open a ZIP archive. Increase this time for big archives or slow network connections, as doing so may affect the latency of serving Pages. Default is 30s. | -#### Zip cache refresh example +#### ZIP cache refresh example Archives are refreshed in the cache (extending the time they are held in memory) if they're accessed before `zip_cache_expiration`, and the time left before expiring is less than or equal to @@ -556,7 +520,7 @@ opened) it's refreshed. This extends the time the archive remains in memory from After an archive reaches `zip_cache_expiration`, it's marked as expired and removed on the next `zip_cache_cleanup` interval. - + ## Activate verbose logging for daemon @@ -665,7 +629,7 @@ Follow the steps below to configure the proxy listener of GitLab Pages. To set the global maximum pages size for a project: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences**. 1. Expand **Pages**. 1. Edit the **Maximum size of pages**. @@ -742,6 +706,9 @@ database encryption. Proceed with caution. gitlab_pages['gitlab_server'] = 'http://<gitlab_server_IP_or_URL>' ``` +1. If you have custom UID/GID settings on the **GitLab server**, add them to the **Pages server** `/etc/gitlab/gitlab.rb` as well, + otherwise running a `gitlab-ctl reconfigure` on the **GitLab server** can change file ownership and cause Pages requests to fail. + 1. Create a backup of the secrets file on the **Pages server**: ```shell @@ -1047,7 +1014,7 @@ If you use [object storage](#using-object-storage), you can disable local storag Starting from GitLab 13.12, this setting also disables the [legacy storage](#migrate-legacy-storage-to-zip-storage), so if you were using NFS to serve Pages, you can completely disconnect from it. -## Migrate GitLab Pages to 14.0 +## Prepare GitLab Pages for 14.0 In GitLab 14.0 a number of breaking changes were introduced which may require some user intervention. The steps below describe the best way to migrate without causing any downtime for your GitLab instance. @@ -1104,6 +1071,9 @@ You can also find the log file in `/var/log/gitlab/gitlab-pages/current`. ### `open /etc/ssl/ca-bundle.pem: permission denied` +WARNING: +This issue is fixed in GitLab 14.3 and above, try upgrading GitLab first. + GitLab Pages runs inside a `chroot` jail, usually in a uniquely numbered directory like `/tmp/gitlab-pages-*`. @@ -1135,6 +1105,9 @@ sudo gitlab-ctl restart gitlab-pages ### `dial tcp: lookup gitlab.example.com` and `x509: certificate signed by unknown authority` +WARNING: +This issue is fixed in GitLab 14.3 and above, try upgrading GitLab first. + When setting both `inplace_chroot` and `access_control` to `true`, you might encounter errors like: ```plaintext @@ -1260,6 +1233,14 @@ For example, you can adapt the `rsync` strategy from the [moving repositories documentation](../operations/moving_repositories.md). Alternatively, run the CI pipelines of those projects that contain a `pages` job again. +## 404 or 500 error when accessing GitLab Pages in a Geo setup + +Pages sites are only available on the primary Geo site, while the codebase of the project is available on all sites. + +If you try to access a Pages page on a secondary site, you will get a 404 or 500 HTTP code depending on the access control. + +Read more which [features don't support Geo replication/verification](../geo/replication/datatypes.md#limitations-on-replicationverification). + ### Failed to connect to the internal GitLab API If you see the following error: @@ -1297,7 +1278,7 @@ in all of your GitLab Pages instances. ### 500 error with `securecookie: failed to generate random iv` and `Failed to save the session` -This problem most likely results from an [out-dated operating system](https://docs.gitlab.com/omnibus/package-information/deprecated_os.html). +This problem most likely results from an [out-dated operating system](../package_information/deprecated_os.md). The [Pages daemon uses the `securecookie` library](https://gitlab.com/search?group_id=9970&project_id=734943&repository_ref=master&scope=blobs&search=securecookie&snippets=false) to get random strings via [`crypto/rand` in Go](https://golang.org/pkg/crypto/rand/#pkg-variables). This requires the `getrandom` system call or `/dev/urandom` to be available on the host OS. Upgrading to an [officially supported operating system](https://about.gitlab.com/install/) is recommended. @@ -1306,7 +1287,7 @@ Upgrading to an [officially supported operating system](https://about.gitlab.com This problem comes from the permissions of the GitLab Pages OAuth application. To fix it: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Applications > GitLab Pages**. 1. Edit the application. 1. Under **Scopes**, ensure that the `api` scope is selected. @@ -1391,17 +1372,12 @@ both servers. GitLab 14.0 introduces a number of changes to GitLab Pages which may require manual intervention. -1. Firstly [follow the migration guide](#migrate-gitlab-pages-to-140). +1. Firstly [follow the migration guide](#prepare-gitlab-pages-for-140). +1. Try to upgrade to GitLab 14.3 or above. Some of the issues were fixed in GitLab 14.1, 14.2 and 14.3. 1. If it doesn't work, see [GitLab Pages logs](#how-to-see-gitlab-pages-logs), and if you see any errors there then search them on this page. -The most common problem is when using [`inplace_chroot`](#dial-tcp-lookup-gitlabexamplecom-and-x509-certificate-signed-by-unknown-authority). - -NOTE: -Starting from 14.1, the chroot/jailing mechanism is -[disabled by default for API-based configuration](#jailing-mechanism-disabled-by-default-for-api-based-configuration). - WARNING: -As the last resort you can temporarily enable legacy storage and configuration mechanisms. Support for them [will be removed in GitLab 14.3](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6166), so GitLab Pages will stop working if don't resolve the underlying issue. +In GitLab 14.0-14.2 you can temporarily enable legacy storage and configuration mechanisms. To do that: @@ -1414,3 +1390,25 @@ To do that: ``` 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). + +### GitLab Pages fails to start in Docker container + +WARNING: +This issue is fixed in GitLab 14.3 and above, try upgrading GitLab first. + +The GitLab Pages daemon doesn't have permissions to bind mounts when it runs +in a Docker container. To overcome this issue, you must change the `chroot` +behavior: + +1. Edit `/etc/gitlab/gitlab.rb`. +1. Set the `inplace_chroot` to `true` for GitLab Pages: + + ```ruby + gitlab_pages['inplace_chroot'] = true + ``` + +1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). + +NOTE: +`inplace_chroot` option might not work with the other features, such as [Pages Access Control](#access-control). +The [GitLab Pages README](https://gitlab.com/gitlab-org/gitlab-pages#caveats) has more information about caveats and workarounds. diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md index b5c3330b2ce..278d792052a 100644 --- a/doc/administration/pages/source.md +++ b/doc/administration/pages/source.md @@ -473,7 +473,7 @@ The default for the maximum size of unpacked archives per project is 100 MB. To change this value: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences**. 1. Expand **Pages**. 1. Update the value for **Maximum size of pages (MB)**. diff --git a/doc/administration/polling.md b/doc/administration/polling.md index 5c4ee837057..8bd28824f83 100644 --- a/doc/administration/polling.md +++ b/doc/administration/polling.md @@ -26,7 +26,7 @@ The default value (`1`) is recommended for the majority of GitLab installations. To adjust the polling interval multiplier: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences**. 1. Expand **Polling interval multiplier**. 1. Set a value for the polling interval multiplier. This multiplier is applied to all resources at diff --git a/doc/administration/postgresql/pgbouncer.md b/doc/administration/postgresql/pgbouncer.md index 7171e90949e..e215622bbc7 100644 --- a/doc/administration/postgresql/pgbouncer.md +++ b/doc/administration/postgresql/pgbouncer.md @@ -173,7 +173,7 @@ ote_pid | tls Some database changes have to be done directly, and not through PgBouncer. Read more about the affected tasks: [database restores](../../raketasks/backup_restore.md#backup-and-restore-for-installations-using-pgbouncer) -and [GitLab upgrades](https://docs.gitlab.com/omnibus/update/README.html#use-postgresql-ha). +and [GitLab upgrades](../../update/zero_downtime.md#use-postgresql-ha). 1. To find the primary node, run the following on a database node: diff --git a/doc/administration/postgresql/replication_and_failover.md b/doc/administration/postgresql/replication_and_failover.md index 1308697c16e..2e0820b69c9 100644 --- a/doc/administration/postgresql/replication_and_failover.md +++ b/doc/administration/postgresql/replication_and_failover.md @@ -72,13 +72,13 @@ the PgBouncer service. ### Connection flow -Each service in the package comes with a set of [default ports](https://docs.gitlab.com/omnibus/package-information/defaults.html#ports). You may need to make specific firewall rules for the connections listed below: +Each service in the package comes with a set of [default ports](../package_information/defaults.md#ports). You may need to make specific firewall rules for the connections listed below: -- Application servers connect to either PgBouncer directly via its [default port](https://docs.gitlab.com/omnibus/package-information/defaults.html#pgbouncer) or via a configured Internal Load Balancer (TCP) that serves multiple PgBouncers. -- PgBouncer connects to the primary database servers [PostgreSQL default port](https://docs.gitlab.com/omnibus/package-information/defaults.html#postgresql) +- Application servers connect to either PgBouncer directly via its [default port](../package_information/defaults.md) or via a configured Internal Load Balancer (TCP) that serves multiple PgBouncers. +- PgBouncer connects to the primary database servers [PostgreSQL default port](../package_information/defaults.md) - Patroni actively manages the running PostgreSQL processes and configuration. -- PostgreSQL secondaries connect to the primary database servers [PostgreSQL default port](https://docs.gitlab.com/omnibus/package-information/defaults.html#postgresql) -- Consul servers and agents connect to each others [Consul default ports](https://docs.gitlab.com/omnibus/package-information/defaults.html#consul) +- PostgreSQL secondaries connect to the primary database servers [PostgreSQL default port](../package_information/defaults.md) +- Consul servers and agents connect to each others [Consul default ports](../package_information/defaults.md) ## Setting it up @@ -183,7 +183,7 @@ Few things to remember about the service itself: - The service runs as the same system account as the database - In the package, this is by default `gitlab-psql` -- If you use a non-default user account for PgBouncer service (by default `pgbouncer`), you need to specify this username. +- If you use a non-default user account for PgBouncer service (by default `pgbouncer`), you need to specify this username. - Passwords are stored in the following locations: - `/etc/gitlab/gitlab.rb`: hashed, and in plain text - `/var/opt/gitlab/pgbouncer/pg_auth`: hashed @@ -306,7 +306,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. -You have the option to enable TLS and use HTTPS over the same [port](https://docs.gitlab.com/omnibus/package-information/defaults.html#patroni). +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']`): @@ -789,7 +789,7 @@ You do not need any special consideration for Patroni while provisioning your da Patroni monitors the cluster and handles any failover. When the primary node fails it works with Consul to notify PgBouncer. On failure, Patroni handles the transitioning of the old primary to a replica and rejoins it to the cluster automatically. -With Patroni, the connection flow is slightly different. Patroni on each node connects to Consul agent to join the cluster. Only after this point it decides if the node is the primary or a replica. Based on this decision, it configures and starts PostgreSQL which it communicates with directly over a Unix socket. This means that if the Consul cluster is not functional or does not have a leader, Patroni and by extension PostgreSQL does not start. Patroni also exposes a REST API which can be accessed via its [default port](https://docs.gitlab.com/omnibus/package-information/defaults.html#patroni) +With Patroni, the connection flow is slightly different. Patroni on each node connects to Consul agent to join the cluster. Only after this point it decides if the node is the primary or a replica. Based on this decision, it configures and starts PostgreSQL which it communicates with directly over a Unix socket. This means that if the Consul cluster is not functional or does not have a leader, Patroni and by extension PostgreSQL does not start. Patroni also exposes a REST API which can be accessed via its [default port](../package_information/defaults.md) on each node. ### Check replication status diff --git a/doc/administration/pseudonymizer.md b/doc/administration/pseudonymizer.md index 533ebe0ad2f..da3a2e4b34c 100644 --- a/doc/administration/pseudonymizer.md +++ b/doc/administration/pseudonymizer.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Pseudonymizer **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5532) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5532) in GitLab 11.1. As the GitLab database hosts sensitive information, using it unfiltered for analytics implies high security requirements. To help alleviate this constraint, the Pseudonymizer diff --git a/doc/administration/raketasks/check.md b/doc/administration/raketasks/check.md index 56bf711f187..7cd7ecc26f7 100644 --- a/doc/administration/raketasks/check.md +++ b/doc/administration/raketasks/check.md @@ -204,12 +204,20 @@ See [LDAP Rake Tasks - LDAP Check](ldap.md#check) for details. The following are solutions to problems you might discover using the Rake tasks documented above. -### Dangling commits +### Dangling objects -`gitlab:git:fsck` can find dangling commits. To fix them, try -[enabling housekeeping](../housekeeping.md). +The `gitlab:git:fsck` task can find dangling objects such as: -If the issue persists, try triggering `gc` via the +```plaintext +dangling blob a12... +dangling commit b34... +dangling tag c56... +dangling tree d78... +``` + +To delete them, try [running housekeeping](../housekeeping.md). + +If the issue persists, try triggering garbage collection via the [Rails Console](../operations/rails_console.md#starting-a-rails-console-session): ```ruby @@ -217,6 +225,13 @@ p = Project.find_by_path("project-name") Repositories::HousekeepingService.new(p, :gc).execute ``` +If the dangling objects are younger than the 2 weeks default grace period, +and you don't want to wait until they expire automatically, run: + +```ruby +Repositories::HousekeepingService.new(p, :prune).execute +``` + ### Delete references to missing remote uploads `gitlab-rake gitlab:uploads:check VERBOSE=1` detects remote objects that do not exist because they were @@ -271,7 +286,7 @@ To delete these references to missing local artifacts (`job.log` files): ```ruby artifacts_deleted = 0 - ::Ci::JobArtifact.all.each do |artifact| ### Iterate artifacts + ::Ci::JobArtifact.find_each do |artifact| ### Iterate artifacts # next if artifact.file.filename != "job.log" ### Uncomment if only `job.log` files' references are to be processed next if artifact.file.exists? ### Skip if the file reference is valid artifacts_deleted += 1 diff --git a/doc/administration/raketasks/github_import.md b/doc/administration/raketasks/github_import.md index 0338732e886..f29e2a6c7f6 100644 --- a/doc/administration/raketasks/github_import.md +++ b/doc/administration/raketasks/github_import.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitHub import **(FREE SELF)** -> [Introduced]( https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10308) in GitLab 9.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10308) in GitLab 9.1. 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, diff --git a/doc/administration/raketasks/ldap.md b/doc/administration/raketasks/ldap.md index d7a37d1df3a..585d254e41d 100644 --- a/doc/administration/raketasks/ldap.md +++ b/doc/administration/raketasks/ldap.md @@ -44,7 +44,7 @@ waiting for the next scheduled group sync to be run. NOTE: If you'd like to change the frequency at which a group sync is performed, -[adjust the cron schedule](../auth/ldap/index.md#adjusting-ldap-group-sync-schedule) +[adjust the cron schedule](../auth/ldap/index.md#adjust-ldap-group-sync-schedule) instead. **Omnibus Installation** @@ -151,7 +151,8 @@ sudo gitlab-rake gitlab:ldap:rename_provider[old_provider,new_provider] force=ye ## Secrets -GitLab can use [LDAP configuration secrets](../auth/ldap/index.md#using-encrypted-credentials) to read from an encrypted file. The following Rake tasks are provided for updating the contents of the encrypted file. +GitLab can use [LDAP configuration secrets](../auth/ldap/index.md#use-encrypted-credentials) to read from an encrypted file. +The following Rake tasks are provided for updating the contents of the encrypted file. ### Show secret diff --git a/doc/administration/raketasks/praefect.md b/doc/administration/raketasks/praefect.md index 5fe0546999b..d2fd4943c68 100644 --- a/doc/administration/raketasks/praefect.md +++ b/doc/administration/raketasks/praefect.md @@ -7,7 +7,7 @@ type: reference # Praefect Rake tasks **(FREE SELF)** -> [Introduced]( https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28369) in GitLab 12.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28369) in GitLab 12.10. Rake tasks are available for projects that have been created on Praefect storage. See the [Praefect documentation](../gitaly/praefect.md) for information on configuring Praefect. diff --git a/doc/administration/raketasks/project_import_export.md b/doc/administration/raketasks/project_import_export.md index 80321d75d66..e0ca7bfdeaf 100644 --- a/doc/administration/raketasks/project_import_export.md +++ b/doc/administration/raketasks/project_import_export.md @@ -52,7 +52,7 @@ Note the following: compatible as described in the [Version history](../../user/project/settings/import_export.md#version-history). - The project import option must be enabled: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand **Visibility and access controls**. 1. Under **Import sources**, check the "Project export enabled" option. diff --git a/doc/administration/raketasks/storage.md b/doc/administration/raketasks/storage.md index cee63a6cae5..017565e1b39 100644 --- a/doc/administration/raketasks/storage.md +++ b/doc/administration/raketasks/storage.md @@ -109,7 +109,7 @@ sudo gitlab-rake gitlab:storage:migrate_to_hashed ID_FROM=50 ID_TO=100 To monitor the progress in GitLab: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. Watch how long the `hashed_storage:hashed_storage_project_migrate` queue will take to finish. After it reaches zero, you can confirm every project diff --git a/doc/administration/redis/replication_and_failover_external.md b/doc/administration/redis/replication_and_failover_external.md index 234b1aa7fb9..c19e42a5f14 100644 --- a/doc/administration/redis/replication_and_failover_external.md +++ b/doc/administration/redis/replication_and_failover_external.md @@ -349,7 +349,7 @@ or a failover promotes a different **Primary** node. ```yaml production: - url: redis://:redi-password-goes-here@gitlab-redis/ + url: redis://:redis-password-goes-here@gitlab-redis/ sentinels: - host: 10.0.0.1 diff --git a/doc/administration/redis/troubleshooting.md b/doc/administration/redis/troubleshooting.md index 0c1046ca22d..6ab3d55e06a 100644 --- a/doc/administration/redis/troubleshooting.md +++ b/doc/administration/redis/troubleshooting.md @@ -73,7 +73,7 @@ there may be something wrong with your configuration files or it can be related to [this issue](https://github.com/redis/redis-rb/issues/531). You must make sure you are defining the same value in `redis['master_name']` -and `redis['master_pasword']` as you defined for your sentinel node. +and `redis['master_password']` as you defined for your sentinel node. The way the Redis connector `redis-rb` works with sentinel is a bit non-intuitive. We try to hide the complexity in omnibus, but it still requires diff --git a/doc/administration/reference_architectures/10k_users.md b/doc/administration/reference_architectures/10k_users.md index f9397e6dbca..0fd597e6a2d 100644 --- a/doc/administration/reference_architectures/10k_users.md +++ b/doc/administration/reference_architectures/10k_users.md @@ -1550,7 +1550,7 @@ To configure the Praefect nodes, on each one: # Configure the Consul agent consul['enable'] = true ## Enable service discovery for Prometheus - consul['monitoring_service_discovery'] = true + consul['monitoring_service_discovery'] = true # START user configuration # Please set the real values as explained in Required Information section @@ -2390,7 +2390,7 @@ The following tables and diagram detail the hybrid environment using the same fo as the normal environment above. First are the components that run in Kubernetes. The recommendation at this time is to -use Google Cloud’s Kubernetes Engine (GKE) and associated machine types, but the memory +use Google Cloud's Kubernetes Engine (GKE) and associated machine types, but the memory and CPU requirements should translate to most other providers. We hope to update this in the future with further specific cloud provider details. diff --git a/doc/administration/reference_architectures/1k_users.md b/doc/administration/reference_architectures/1k_users.md index 18e34711953..ea40e150e58 100644 --- a/doc/administration/reference_architectures/1k_users.md +++ b/doc/administration/reference_architectures/1k_users.md @@ -13,7 +13,7 @@ full list of reference architectures, see If you need to serve up to 1,000 users and you don't have strict availability requirements, a single-node solution with [frequent backups](index.md#automated-backups) is appropriate for -many organizations . +many organizations. > - **Supported users (approximate):** 1,000 > - **High Availability:** No. For a highly-available environment, you can diff --git a/doc/administration/reference_architectures/25k_users.md b/doc/administration/reference_architectures/25k_users.md index 65d59422da8..f500434d75b 100644 --- a/doc/administration/reference_architectures/25k_users.md +++ b/doc/administration/reference_architectures/25k_users.md @@ -2402,7 +2402,7 @@ The following tables and diagram detail the hybrid environment using the same fo as the normal environment above. First are the components that run in Kubernetes. The recommendation at this time is to -use Google Cloud’s Kubernetes Engine (GKE) and associated machine types, but the memory +use Google Cloud's Kubernetes Engine (GKE) and associated machine types, but the memory and CPU requirements should translate to most other providers. We hope to update this in the future with further specific cloud provider details. diff --git a/doc/administration/reference_architectures/2k_users.md b/doc/administration/reference_architectures/2k_users.md index 0af4dbc8a7f..99dd29c3a83 100644 --- a/doc/administration/reference_architectures/2k_users.md +++ b/doc/administration/reference_architectures/2k_users.md @@ -995,7 +995,7 @@ The following tables and diagram detail the hybrid environment using the same fo as the normal environment above. First are the components that run in Kubernetes. The recommendation at this time is to -use Google Cloud’s Kubernetes Engine (GKE) and associated machine types, but the memory +use Google Cloud's Kubernetes Engine (GKE) and associated machine types, but the memory and CPU requirements should translate to most other providers. We hope to update this in the future with further specific cloud provider details. diff --git a/doc/administration/reference_architectures/3k_users.md b/doc/administration/reference_architectures/3k_users.md index f4ae01c7442..da36968f053 100644 --- a/doc/administration/reference_architectures/3k_users.md +++ b/doc/administration/reference_architectures/3k_users.md @@ -2124,7 +2124,7 @@ The following tables and diagram detail the hybrid environment using the same fo as the normal environment above. First are the components that run in Kubernetes. The recommendation at this time is to -use Google Cloud’s Kubernetes Engine (GKE) and associated machine types, but the memory +use Google Cloud's Kubernetes Engine (GKE) and associated machine types, but the memory and CPU requirements should translate to most other providers. We hope to update this in the future with further specific cloud provider details. diff --git a/doc/administration/reference_architectures/50k_users.md b/doc/administration/reference_architectures/50k_users.md index b262545b27d..b071b48cbd9 100644 --- a/doc/administration/reference_architectures/50k_users.md +++ b/doc/administration/reference_architectures/50k_users.md @@ -2413,7 +2413,7 @@ The following tables and diagram detail the hybrid environment using the same fo as the normal environment above. First are the components that run in Kubernetes. The recommendation at this time is to -use Google Cloud’s Kubernetes Engine (GKE) and associated machine types, but the memory +use Google Cloud's Kubernetes Engine (GKE) and associated machine types, but the memory and CPU requirements should translate to most other providers. We hope to update this in the future with further specific cloud provider details. diff --git a/doc/administration/reference_architectures/5k_users.md b/doc/administration/reference_architectures/5k_users.md index 666d18a66fc..4dfe628039a 100644 --- a/doc/administration/reference_architectures/5k_users.md +++ b/doc/administration/reference_architectures/5k_users.md @@ -2094,7 +2094,7 @@ The following tables and diagram detail the hybrid environment using the same fo as the normal environment above. First are the components that run in Kubernetes. The recommendation at this time is to -use Google Cloud’s Kubernetes Engine (GKE) and associated machine types, but the memory +use Google Cloud's Kubernetes Engine (GKE) and associated machine types, but the memory and CPU requirements should translate to most other providers. We hope to update this in the future with further specific cloud provider details. diff --git a/doc/administration/reference_architectures/index.md b/doc/administration/reference_architectures/index.md index 74d8bf39d03..4d95a61176b 100644 --- a/doc/administration/reference_architectures/index.md +++ b/doc/administration/reference_architectures/index.md @@ -139,8 +139,8 @@ to any of the [available reference architectures](#available-reference-architect > - Level of complexity: **Medium** > - Required domain knowledge: PostgreSQL, HAProxy, shared storage, distributed systems -GitLab supports [zero-downtime updates](https://docs.gitlab.com/omnibus/update/#zero-downtime-updates). -Single GitLab nodes can be updated with only a [few minutes of downtime](https://docs.gitlab.com/omnibus/update/README.html#single-node-deployment). +GitLab supports [zero-downtime upgrades](../../update/zero_downtime.md). +Single GitLab nodes can be updated with only a [few minutes of downtime](../../update/zero_downtime.md#single-node-deployment). To avoid this, we recommend to separate GitLab into several application nodes. As long as at least one of each component is online and capable of handling the instance's usage load, your team's productivity will not be interrupted during the update. diff --git a/doc/administration/reference_architectures/troubleshooting.md b/doc/administration/reference_architectures/troubleshooting.md index 61d9dfea2a2..aabf4809b4a 100644 --- a/doc/administration/reference_architectures/troubleshooting.md +++ b/doc/administration/reference_architectures/troubleshooting.md @@ -158,7 +158,7 @@ there may be something wrong with your configuration files or it can be related to [this issue](https://github.com/redis/redis-rb/issues/531). You must make sure you are defining the same value in `redis['master_name']` -and `redis['master_pasword']` as you defined for your sentinel node. +and `redis['master_password']` as you defined for your sentinel node. The way the Redis connector `redis-rb` works with sentinel is a bit non-intuitive. We try to hide the complexity in omnibus, but it still requires diff --git a/doc/administration/repository_checks.md b/doc/administration/repository_checks.md index ab203bb7993..0591f5b3c40 100644 --- a/doc/administration/repository_checks.md +++ b/doc/administration/repository_checks.md @@ -11,7 +11,7 @@ You can use [`git fsck`](https://git-scm.com/docs/git-fsck) to verify the integr committed to a repository. GitLab administrators can trigger this check for a project using the GitLab UI: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Projects**. 1. Select the project to check. 1. In the **Repository check** section, select **Trigger repository check**. @@ -25,7 +25,7 @@ This setting is off by default, because it can cause many false alarms. Instead of checking repositories manually, GitLab can be configured to run the checks periodically: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Repository** (`/admin/application_settings/repository`). 1. Expand the **Repository maintenance** section. 1. Enable **Enable repository checks**. @@ -50,7 +50,7 @@ disk at: If periodic repository checks cause false alarms, you can clear all repository check states: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Repository** (`/admin/application_settings/repository`). 1. Expand the **Repository maintenance** section. 1. Select **Clear all repository checks**. diff --git a/doc/administration/repository_storage_paths.md b/doc/administration/repository_storage_paths.md index f4aed0f6a0f..e7edfb9f338 100644 --- a/doc/administration/repository_storage_paths.md +++ b/doc/administration/repository_storage_paths.md @@ -146,7 +146,7 @@ Omnibus stores the repositories in a `repositories` subdirectory of the `git-dat After you [configure](#configure-repository-storage-paths) multiple repository storage paths, you can choose where new repositories are stored: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Repository** and expand the **Repository storage** section. 1. Enter values in the **Storage nodes for new repositories** fields. diff --git a/doc/administration/repository_storage_types.md b/doc/administration/repository_storage_types.md index f55bff1bf34..d2bab9a1e04 100644 --- a/doc/administration/repository_storage_types.md +++ b/doc/administration/repository_storage_types.md @@ -80,7 +80,7 @@ Administrators can look up a project's hashed path from its name or ID using: To look up a project's hash path in the Admin Area: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Projects** and select the project. The **Gitaly relative path** is displayed there and looks similar to: diff --git a/doc/administration/static_objects_external_storage.md b/doc/administration/static_objects_external_storage.md index 2f19a2e5058..21949388f19 100644 --- a/doc/administration/static_objects_external_storage.md +++ b/doc/administration/static_objects_external_storage.md @@ -16,8 +16,8 @@ storage such as a content delivery network (CDN). To configure external storage for static objects: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Repository**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Repository**. 1. Expand the **External storage for repository static objects** section. 1. Enter the base URL and an arbitrary token. When you [set up external storage](#set-up-external-storage), use a script that sets these values as `ORIGIN_HOSTNAME` and `STORAGE_TOKEN`. diff --git a/doc/administration/troubleshooting/diagnostics_tools.md b/doc/administration/troubleshooting/diagnostics_tools.md index fe85b5d5803..53d4810b920 100644 --- a/doc/administration/troubleshooting/diagnostics_tools.md +++ b/doc/administration/troubleshooting/diagnostics_tools.md @@ -23,8 +23,3 @@ running on. [strace-parser](https://gitlab.com/wchandler/strace-parser) is a small tool to analyze and summarize raw `strace` data. - -## Pritaly - -[Pritaly](https://gitlab.com/wchandler/pritaly) takes Gitaly logs and colorizes output -or converts the logs to JSON. diff --git a/doc/administration/troubleshooting/elasticsearch.md b/doc/administration/troubleshooting/elasticsearch.md index 79295856da8..cfce3b94554 100644 --- a/doc/administration/troubleshooting/elasticsearch.md +++ b/doc/administration/troubleshooting/elasticsearch.md @@ -196,7 +196,7 @@ Troubleshooting search result issues is rather straight forward on Elasticsearch The first step is to confirm GitLab is using Elasticsearch for the search function. To do this: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**, and then confirm the integration is enabled. 1. Confirm searches use Elasticsearch by accessing the rails console diff --git a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md index c55efe78216..491db37d9da 100644 --- a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md +++ b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md @@ -243,7 +243,7 @@ project.update!(repository_read_only: true) ### Transfer project from one namespace to another ```ruby - p= Project.find_by_full_path('<project_path>') +p = Project.find_by_full_path('<project_path>') # To set the owner of the project current_user= p.creator @@ -416,9 +416,9 @@ p.create_wiki ### creates the wiki project on the filesystem ### In case of issue boards not loading properly and it's getting time out. We need to call the Issue Rebalancing service to fix this ```ruby -p=Project.find_by_full_path('PROJECT PATH') +p = Project.find_by_full_path('PROJECT PATH') -IssueRebalancingService.new(p.issues.take).execute +Issues::RelativePositionRebalancingService.new(p.root_namespace.all_projects).execute ``` ## Imports / Exports @@ -596,6 +596,17 @@ curl --silent --header "Private-Token: ********************" \ "https://gitlab.example.com/api/v4/users?per_page=100&active" | jq --compact-output '.[] | [.id,.name,.username]' ``` +### Update Daily Billable & Historical users + +```ruby +# Forces recount of historical (max) users +::HistoricalDataWorker.new.perform + +# Forces recount of daily billable users +identifier = Analytics::UsageTrends::Measurement.identifiers[:billable_users] +::Analytics::UsageTrends::CounterJobWorker.new.perform(identifier, User.minimum(:id), User.maximum(:id), Time.zone.now) +``` + ### Block or Delete Users that have no projects or groups ```ruby @@ -999,8 +1010,8 @@ This content has been moved to the [Troubleshooting Sidekiq docs](sidekiq.md). ### Get information about LFS objects and associated project ```ruby -o=LfsObject.find_by(oid: "<oid>") -p=Project.find(LfsObjectsProject.find_by_lfs_object_id(o.id).project_id) +o = LfsObject.find_by(oid: "<oid>") +p = Project.find(LfsObjectsProject.find_by_lfs_object_id(o.id).project_id) ``` You can then delete these records from the database with: diff --git a/doc/administration/troubleshooting/log_parsing.md b/doc/administration/troubleshooting/log_parsing.md index 0a73c61ae94..c5443c564f4 100644 --- a/doc/administration/troubleshooting/log_parsing.md +++ b/doc/administration/troubleshooting/log_parsing.md @@ -55,6 +55,12 @@ zcat @400000006026b71d1a7af804.s | (head -1; tail -1) | jq '.time' zcat some_json.log.25.gz | (head -1; tail -1) | jq '.time' ``` +#### Get activity for correlation ID across multiple JSON logs in chronological order + +```shell +grep -hR <correlationID> | jq -c -R 'fromjson?' | jq -C -s 'sort_by(.time)' | less -R +``` + ### Parsing `production_json.log` and `api_json.log` #### Find all requests with a 5XX status code diff --git a/doc/administration/troubleshooting/postgresql.md b/doc/administration/troubleshooting/postgresql.md index 994c194c6db..3df957bacf9 100644 --- a/doc/administration/troubleshooting/postgresql.md +++ b/doc/administration/troubleshooting/postgresql.md @@ -116,7 +116,7 @@ References: ERROR: deadlock detected ``` -Three applicable timeouts are identified in the issue [#1](https://gitlab.com/gitlab-org/gitlab/-/issues/30528); our recommended settings are as follows: +Three applicable timeouts are identified in the issue [#30528](https://gitlab.com/gitlab-org/gitlab/-/issues/30528); our recommended settings are as follows: ```ini deadlock_timeout = 5s @@ -124,7 +124,7 @@ statement_timeout = 15s idle_in_transaction_session_timeout = 60s ``` -Quoting from issue [#1](https://gitlab.com/gitlab-org/gitlab/-/issues/30528): +Quoting from issue [#30528](https://gitlab.com/gitlab-org/gitlab/-/issues/30528): > "If a deadlock is hit, and we resolve it through aborting the transaction after a short period, then the retry mechanisms we already have will make the deadlocked piece of work try again, and it's unlikely we'll deadlock multiple times in a row." @@ -146,7 +146,7 @@ PostgresSQL defaults: - `statement_timeout = 0` (never) - `idle_in_transaction_session_timeout = 0` (never) -Comments in issue [#1](https://gitlab.com/gitlab-org/gitlab/-/issues/30528) +Comments in issue [#30528](https://gitlab.com/gitlab-org/gitlab/-/issues/30528) indicate that these should both be set to at least a number of minutes for all Omnibus GitLab installations (so they don't hang indefinitely). However, 15s for statement_timeout is very short, and will only be effective if the diff --git a/doc/administration/troubleshooting/tracing_correlation_id.md b/doc/administration/troubleshooting/tracing_correlation_id.md index 1bb10e72290..3518f52e6f6 100644 --- a/doc/administration/troubleshooting/tracing_correlation_id.md +++ b/doc/administration/troubleshooting/tracing_correlation_id.md @@ -27,7 +27,7 @@ activity with the site that you're visiting. See the links below for network mon documentation for some popular browsers. - [Network Monitor - Firefox Developer Tools](https://developer.mozilla.org/en-US/docs/Tools/Network_Monitor) -- [Inspect Network Activity In Chrome DevTools](https://developer.chrome.com/docs/devtools/network) +- [Inspect Network Activity In Chrome DevTools](https://developer.chrome.com/docs/devtools/network/) - [Safari Web Development Tools](https://developer.apple.com/safari/tools/) - [Microsoft Edge Network panel](https://docs.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium/network/) @@ -127,3 +127,11 @@ some sort of log aggregation software like Loki, ELK, Splunk, or others. You can use a tool like Ansible or PSSH (parallel SSH) that can execute identical commands across your servers in parallel, or craft your own solution. + +### Viewing the request in the Performance Bar + +You can use the [performance bar](../monitoring/performance/performance_bar.md) to view interesting data including calls made to SQL and Gitaly. + +To view the data, the correlation ID of the request must match the same session as the user +viewing the performance bar. For API requests, this means that you must perform the request +using the session cookie of the signed-in user. diff --git a/doc/administration/uploads.md b/doc/administration/uploads.md index 949687cfa0a..15ef024647c 100644 --- a/doc/administration/uploads.md +++ b/doc/administration/uploads.md @@ -53,8 +53,8 @@ _The uploads are stored by default in > **Notes:** > -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3867) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.5. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17358) in [GitLab Free](https://about.gitlab.com/pricing/) 10.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3867) in GitLab 10.5. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17358) from GitLab Premium to GitLab Free in 10.7. > - Since version 11.1, we support direct_upload to S3. If you don't want to use the local disk where GitLab is installed to store the diff --git a/doc/administration/whats-new.md b/doc/administration/whats-new.md index d669d05e9f0..d3768907989 100644 --- a/doc/administration/whats-new.md +++ b/doc/administration/whats-new.md @@ -29,7 +29,7 @@ in the first patch release, such as `13.10.1`. You can configure the What's new variant: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences**, then expand **What's new**. 1. Choose one of the following options: diff --git a/doc/api/access_requests.md b/doc/api/access_requests.md index 8ef3e882209..1634184a374 100644 --- a/doc/api/access_requests.md +++ b/doc/api/access_requests.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Group and project access requests API +# Group and project access requests API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/18583) in GitLab 8.11. diff --git a/doc/api/admin_sidekiq_queues.md b/doc/api/admin_sidekiq_queues.md index d0e310ab548..569dfd4c413 100644 --- a/doc/api/admin_sidekiq_queues.md +++ b/doc/api/admin_sidekiq_queues.md @@ -27,15 +27,16 @@ This API endpoint is only available to administrators. DELETE /admin/sidekiq/queues/:queue_name ``` -| Attribute | Type | Required | Description | -| --------- | -------------- | -------- | ----------- | -| `queue_name` | string | yes | The name of the queue to delete jobs from | -| `user` | string | no | The username of the user who scheduled the jobs | -| `project` | string | no | The full path of the project where the jobs were scheduled from | -| `root_namespace` | string | no | The root namespace of the project | -| `subscription_plan` | string | no | The subscription plan of the root namespace (GitLab.com only) | -| `caller_id` | string | no | The endpoint or background job that schedule the job (for example: `ProjectsController#create`, `/api/:version/projects/:id`, `PostReceive`) | -| `feature_category` | string | no | The feature category of the background job (for example: `issue_tracking` or `code_review`) | +| Attribute | Type | Required | Description | +|---------------------|--------|----------|----------------------------------------------------------------------------------------------------------------------------------------------| +| `queue_name` | string | yes | The name of the queue to delete jobs from | +| `user` | string | no | The username of the user who scheduled the jobs | +| `project` | string | no | The full path of the project where the jobs were scheduled from | +| `root_namespace` | string | no | The root namespace of the project | +| `subscription_plan` | string | no | The subscription plan of the root namespace (GitLab.com only) | +| `caller_id` | string | no | The endpoint or background job that schedule the job (for example: `ProjectsController#create`, `/api/:version/projects/:id`, `PostReceive`) | +| `feature_category` | string | no | The feature category of the background job (for example: `issue_tracking` or `code_review`) | +| `worker_class` | string | no | The class of the background job worker (for example: `PostReceive` or `MergeWorker`) | At least one attribute, other than `queue_name`, is required. diff --git a/doc/api/api_resources.md b/doc/api/api_resources.md index aae76697841..8706b1e7e76 100644 --- a/doc/api/api_resources.md +++ b/doc/api/api_resources.md @@ -15,7 +15,7 @@ Available resources for the [GitLab REST API](index.md) can be grouped in the fo See also: - [V3 to V4](v3_to_v4.md). -- Adding [deploy keys for multiple projects](deploy_keys.md#adding-deploy-keys-to-multiple-projects). +- Adding [deploy keys for multiple projects](deploy_keys.md#add-deploy-keys-to-multiple-projects). - [API Resources for various templates](#templates-api-resources). ## Project resources @@ -129,7 +129,7 @@ The following API resources are available outside of project and group contexts | Resource | Available endpoints | |:---------------------------------------------------|:------------------------------------------------------------------------| -| [Instance-level CI/CD variables](instance_level_ci_variables.md) | `/admin/ci/variables` | +| [Instance-level CI/CD variables](instance_level_ci_variables.md) **(FREE SELF)** | `/admin/ci/variables` | | [Sidekiq queues administration](admin_sidekiq_queues.md) **(FREE SELF)** | `/admin/sidekiq/queues/:queue_name` | | [Appearance](appearance.md) **(FREE SELF)** | `/application/appearance` | | [Applications](applications.md) | `/applications` | @@ -145,7 +145,7 @@ The following API resources are available outside of project and group contexts | [Group Activity Analytics](group_activity_analytics.md) | `/analytics/group_activity/{issues_count | merge_requests_count | new_members_count }` | | [Group repository storage moves](group_repository_storage_moves.md) **(PREMIUM SELF)** | `/group_repository_storage_moves` | | [Import repository from GitHub](import.md) | `/import/github` | -| [Instance clusters](instance_clusters.md) | `/admin/clusters` | +| [Instance clusters](instance_clusters.md) **(FREE SELF)** | `/admin/clusters` | | [Issues](issues.md) | `/issues` (also available for groups and projects) | | [Issues Statistics](issues_statistics.md) | `/issues_statistics` (also available for groups and projects) | | [Jobs](jobs.md) | `/job` | diff --git a/doc/api/applications.md b/doc/api/applications.md index 7047dccea88..2b5eff68010 100644 --- a/doc/api/applications.md +++ b/doc/api/applications.md @@ -4,7 +4,7 @@ group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Applications API +# Applications API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8160) in GitLab 10.5. diff --git a/doc/api/avatar.md b/doc/api/avatar.md index baa670f3e93..200d7524b7f 100644 --- a/doc/api/avatar.md +++ b/doc/api/avatar.md @@ -4,7 +4,7 @@ group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Avatar API +# Avatar API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19121) in GitLab 11.0. diff --git a/doc/api/award_emoji.md b/doc/api/award_emoji.md index dc3dc9fcaca..61f84dfb812 100644 --- a/doc/api/award_emoji.md +++ b/doc/api/award_emoji.md @@ -10,7 +10,7 @@ An [awarded emoji](../user/award_emojis.md) tells a thousand words. We call GitLab objects on which you can award an emoji "awardables". You can award emojis on the following: -- [Epics](../user/group/epics/index.md) ([API](epics.md)). +- [Epics](../user/group/epics/index.md) ([API](epics.md)). **(PREMIUM)** - [Issues](../user/project/issues/index.md) ([API](issues.md)). - [Merge requests](../user/project/merge_requests/index.md) ([API](merge_requests.md)). - [Snippets](../user/snippets.md) ([API](snippets.md)). diff --git a/doc/api/boards.md b/doc/api/boards.md index 3288aefb1cf..ab9bd4ea3f1 100644 --- a/doc/api/boards.md +++ b/doc/api/boards.md @@ -427,7 +427,7 @@ POST /projects/:id/boards/:board_id/lists NOTE: Label, assignee and milestone arguments are mutually exclusive, that is, only one of them are accepted in a request. -Check the [Issue Board documentation](../user/project/issue_board.md) +Check the [issue board documentation](../user/project/issue_board.md) for more information regarding the required license for each list type. ```shell diff --git a/doc/api/branches.md b/doc/api/branches.md index 15d1b6c2a18..7b9354f3264 100644 --- a/doc/api/branches.md +++ b/doc/api/branches.md @@ -47,7 +47,7 @@ Example response: "developers_can_push": false, "developers_can_merge": false, "can_push": true, - "web_url": "http://gitlab.example.com/my-group/my-project/-/tree/master", + "web_url": "https://gitlab.example.com/my-group/my-project/-/tree/master", "commit": { "author_email": "john@example.com", "author_name": "John Smith", @@ -103,7 +103,7 @@ Example response: "developers_can_push": false, "developers_can_merge": false, "can_push": true, - "web_url": "http://gitlab.example.com/my-group/my-project/-/tree/master", + "web_url": "https://gitlab.example.com/my-group/my-project/-/tree/master", "commit": { "author_email": "john@example.com", "author_name": "John Smith", @@ -180,7 +180,7 @@ Example response: "developers_can_push": false, "developers_can_merge": false, "can_push": true, - "web_url": "http://gitlab.example.com/my-group/my-project/-/tree/newbranch" + "web_url": "https://gitlab.example.com/my-group/my-project/-/tree/newbranch" } ``` diff --git a/doc/api/broadcast_messages.md b/doc/api/broadcast_messages.md index b98373b5a58..5aca0667f31 100644 --- a/doc/api/broadcast_messages.md +++ b/doc/api/broadcast_messages.md @@ -13,7 +13,7 @@ As of GitLab 12.8, GET requests do not require authentication. All other broadca - Guests result in `401 Unauthorized`. - Regular users result in `403 Forbidden`. -## Get all broadcast messages +## Get all broadcast messages **(FREE)** List all broadcast messages. @@ -46,7 +46,7 @@ Example response: ] ``` -## Get a specific broadcast message +## Get a specific broadcast message **(FREE)** Get a specific broadcast message. diff --git a/doc/api/bulk_imports.md b/doc/api/bulk_imports.md index 2325f25e789..2b71c83b224 100644 --- a/doc/api/bulk_imports.md +++ b/doc/api/bulk_imports.md @@ -4,7 +4,7 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab Migrations (Bulk Imports) API +# GitLab Migrations (Bulk Imports) API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/64335) in GitLab 14.1. diff --git a/doc/api/commits.md b/doc/api/commits.md index e164532e0eb..e91da23596f 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -289,11 +289,11 @@ Example response: ``` -## Cherry pick a commit +## Cherry-pick a commit > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8047) in GitLab 8.15. -Cherry picks a commit to a given branch. +Cherry-picks a commit to a given branch. ```plaintext POST /projects/:id/repository/commits/:sha/cherry_pick @@ -381,7 +381,7 @@ Parameters: | `id` | integer/string | yes | The ID or [URL-encoded path of the project](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 in GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/231032) | +| `dry_run` | boolean | no | Does not commit any changes. Default is false. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/231032) in GitLab 13.3 | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "branch=master" \ diff --git a/doc/api/container_registry.md b/doc/api/container_registry.md index 12bdeebca1d..2885cc7d803 100644 --- a/doc/api/container_registry.md +++ b/doc/api/container_registry.md @@ -4,7 +4,7 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Container Registry API +# Container Registry API **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/55978) in GitLab 11.8. > - The use of `CI_JOB_TOKEN` scoped to the current project was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49750) in GitLab 13.12. @@ -32,6 +32,8 @@ Feature.disable(:ci_job_token_scope) ## Change the visibility of the Container Registry +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18792) in GitLab 14.2. + This controls who can view the Container Registry. ```plaintext diff --git a/doc/api/custom_attributes.md b/doc/api/custom_attributes.md index 9908c58de35..94f924c051d 100644 --- a/doc/api/custom_attributes.md +++ b/doc/api/custom_attributes.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/engineering/ux/technical-writing/#assignments --- -# Custom Attributes API +# Custom Attributes API **(FREE SELF)** Every API call to custom attributes must be authenticated as administrator. diff --git a/doc/api/dependency_proxy.md b/doc/api/dependency_proxy.md index e9ddc1e9df9..535c6607cad 100644 --- a/doc/api/dependency_proxy.md +++ b/doc/api/dependency_proxy.md @@ -4,19 +4,16 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Dependency Proxy API +# Dependency Proxy API **(FREE)** ## Purge the dependency proxy for a group > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11631) in GitLab 12.10. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) to [GitLab Free](https://about.gitlab.com/pricing/) in GitLab 13.6. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) from GitLab Premium to GitLab Free in 13.6. Deletes the cached manifests and blobs for a group. This endpoint requires the [Owner role](../user/permissions.md) for the group. -WARNING: -[A bug exists](https://gitlab.com/gitlab-org/gitlab/-/issues/277161) for this API. - ```plaintext DELETE /groups/:id/dependency_proxy/cache ``` diff --git a/doc/api/deploy_keys.md b/doc/api/deploy_keys.md index 3d6d680e3e4..bb719b5bc79 100644 --- a/doc/api/deploy_keys.md +++ b/doc/api/deploy_keys.md @@ -4,11 +4,12 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Deploy keys API +# Deploy keys API **(FREE)** -## List all deploy keys +## List all deploy keys **(FREE SELF)** -Get a list of all deploy keys across all projects of the GitLab instance. This endpoint requires administrator access and is not available on GitLab.com. +Get a list of all deploy keys across all projects of the GitLab instance. This +endpoint requires an administrator role and is not available on GitLab.com. ```plaintext GET /deploy_keys @@ -74,7 +75,7 @@ Example response: ] ``` -## Single deploy key +## Get a single deploy key Get a single key. @@ -213,10 +214,10 @@ Example response: } ``` -## Adding deploy keys to multiple projects +## Add deploy keys to multiple projects -If you want to easily add the same deploy key to multiple projects in the same -group, this can be achieved quite easily with the API. +If you want to add the same deploy key to multiple projects in the same +group, this can be achieved with the API. First, find the ID of the projects you're interested in, by either listing all projects: diff --git a/doc/api/deploy_tokens.md b/doc/api/deploy_tokens.md index 6ed8f76583f..3de7ff4ac44 100644 --- a/doc/api/deploy_tokens.md +++ b/doc/api/deploy_tokens.md @@ -4,9 +4,9 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Deploy Tokens API +# Deploy Tokens API **(FREE)** -## List all deploy tokens +## List all deploy tokens **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21811) in GitLab 12.9. diff --git a/doc/api/deployments.md b/doc/api/deployments.md index 3ed431cf63d..5f710271d60 100644 --- a/doc/api/deployments.md +++ b/doc/api/deployments.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts, howto --- -# Deployments API +# Deployments API **(FREE)** ## List project deployments diff --git a/doc/api/discussions.md b/doc/api/discussions.md index 1c22f261e57..18b74e1450f 100644 --- a/doc/api/discussions.md +++ b/doc/api/discussions.md @@ -15,7 +15,9 @@ Discussions are a set of related notes on: - Merge requests - Commits -This includes system notes, which are notes about changes to the object (for example, when a milestone changes, a corresponding system note is added). Label notes are not part of this API, but recorded as separate events in [resource label events](resource_label_events.md). +This includes system notes, which are notes about changes to the object (for example, +when a milestone changes, a corresponding system note is added). Label notes are +not part of this API, but recorded as separate events in [resource label events](resource_label_events.md). ## Discussions pagination @@ -118,7 +120,8 @@ GET /projects/:id/issues/:issue_iid/discussions ``` ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions" +curl --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions" ``` ### Get single issue discussion item @@ -138,7 +141,8 @@ Parameters: | `discussion_id` | integer | yes | The ID of a discussion item | ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7" +curl --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/<discussion_id>" ``` ### Create new issue thread @@ -159,7 +163,8 @@ Parameters: | `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions?body=comment" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions?body=comment" ``` ### Add note to existing issue thread @@ -185,7 +190,8 @@ Parameters: | `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/<discussion_id>/notes?body=comment" ``` ### Modify existing issue thread note @@ -207,7 +213,8 @@ Parameters: | `body` | string | yes | The content of the note/reply | ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?body=comment" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/<discussion_id>/notes/1108?body=comment" ``` ### Delete an issue thread note @@ -228,7 +235,8 @@ Parameters: | `note_id` | integer | yes | The ID of a discussion note | ```shell -curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/636" +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/636" ``` ## Snippets @@ -326,7 +334,8 @@ GET /projects/:id/snippets/:snippet_id/discussions ``` ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions" +curl --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions" ``` ### Get single snippet discussion item @@ -346,7 +355,8 @@ Parameters: | `discussion_id` | integer | yes | The ID of a discussion item | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/<discussion_id>" ``` ### Create new snippet thread @@ -368,7 +378,8 @@ Parameters: | `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions?body=comment" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions?body=comment" ``` ### Add note to existing snippet thread @@ -391,7 +402,8 @@ Parameters: | `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/<discussion_id>/notes?body=comment" ``` ### Modify existing snippet thread note @@ -413,7 +425,8 @@ Parameters: | `body` | string | yes | The content of the note/reply | ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?body=comment" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/<discussion_id>/notes/1108?body=comment" ``` ### Delete a snippet thread note @@ -434,7 +447,8 @@ Parameters: | `note_id` | integer | yes | The ID of a discussion note | ```shell -curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/636" +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/636" ``` ## Epics **(ULTIMATE)** @@ -533,7 +547,8 @@ GET /groups/:id/epics/:epic_id/discussions ``` ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions" +curl --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions" ``` ### Get single epic discussion item @@ -553,7 +568,8 @@ Parameters: | `discussion_id` | integer | yes | The ID of a discussion item | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/<discussion_id>" ``` ### Create new epic thread @@ -575,7 +591,8 @@ Parameters: | `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions?body=comment" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions?body=comment" ``` ### Add note to existing epic thread @@ -599,7 +616,8 @@ Parameters: | `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/<discussion_id>/notes?body=comment" ``` ### Modify existing epic thread note @@ -621,7 +639,8 @@ Parameters: | `body` | string | yes | The content of note/reply | ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?body=comment" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/<discussion_id>/notes/1108?body=comment" ``` ### Delete an epic thread note @@ -642,7 +661,8 @@ Parameters: | `note_id` | integer | yes | The ID of a thread note | ```shell -curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/636" +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/636" ``` ## Merge requests @@ -805,7 +825,8 @@ Diff comments also contain position: ``` ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions" +curl --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions" ``` ### Get single merge request discussion item @@ -825,7 +846,8 @@ Parameters: | `discussion_id` | integer | yes | The ID of a discussion item | ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7 +curl --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/<discussion_id>" ``` ### Create new merge request thread @@ -866,57 +888,67 @@ Parameters for all comments: #### Create a new thread on the overview page ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions?body=comment" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions?body=comment" ``` #### Create a new thread in the merge request diff -- Both `position[old_path]` and `position[new_path]` are required and must refer to the file path before and after the change. -- To create a thread on an added line (highlighted in green in the merge request diff), use `position[new_line]` and don't include `position[old_line]`. -- To create a thread on a removed line (highlighted in red in the merge request diff), use `position[old_line]` and don't include `position[new_line]`. -- To create a thread on an unchanged line, include both `position[new_line]` and `position[old_line]` for the line. These positions might not be the same if earlier changes in the file changed the line number. This is a bug that we plan to fix in [GraphQL `createDiffNote` forces clients to compute redundant information (#325161)](https://gitlab.com/gitlab-org/gitlab/-/issues/325161). -- If you specify incorrect `base`/`head`/`start` `SHA` parameters, you might run into the following bug: [Merge request comments receive "download" link instead of inline code (#296829)](https://gitlab.com/gitlab-org/gitlab/-/issues/296829). +- Both `position[old_path]` and `position[new_path]` are required and must refer + to the file path before and after the change. +- To create a thread on an added line (highlighted in green in the merge request diff), + use `position[new_line]` and don't include `position[old_line]`. +- To create a thread on a removed line (highlighted in red in the merge request diff), + use `position[old_line]` and don't include `position[new_line]`. +- To create a thread on an unchanged line, include both `position[new_line]` and + `position[old_line]` for the line. These positions might not be the same if earlier + changes in the file changed the line number. This is a bug that we plan to fix in + [GraphQL `createDiffNote` forces clients to compute redundant information (#325161)](https://gitlab.com/gitlab-org/gitlab/-/issues/325161). +- If you specify incorrect `base`/`head`/`start` `SHA` parameters, you might run + into the following bug: + [Merge request comments receive "download" link instead of inline code (#296829)](https://gitlab.com/gitlab-org/gitlab/-/issues/296829). To create a new thread: 1. [Get the latest merge request version](merge_requests.md#get-mr-diff-versions): - ```shell - curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/versions" - ```` + ```shell + curl --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/versions" + ``` 1. Note the details of the latest version, which is listed first in the response array. - ```json - [ - { - "id": 164560414, - "head_commit_sha": "f9ce7e16e56c162edbc9e480108041cf6b0291fe", - "base_commit_sha": "5e6dffa282c5129aa67cd227a0429be21bfdaf80", - "start_commit_sha": "5e6dffa282c5129aa67cd227a0429be21bfdaf80", - "created_at": "2021-03-30T09:18:27.351Z", - "merge_request_id": 93958054, - "state": "collected", - "real_size": "2" - }, - "previous versions are here" - ] - ``` + ```json + [ + { + "id": 164560414, + "head_commit_sha": "f9ce7e16e56c162edbc9e480108041cf6b0291fe", + "base_commit_sha": "5e6dffa282c5129aa67cd227a0429be21bfdaf80", + "start_commit_sha": "5e6dffa282c5129aa67cd227a0429be21bfdaf80", + "created_at": "2021-03-30T09:18:27.351Z", + "merge_request_id": 93958054, + "state": "collected", + "real_size": "2" + }, + "previous versions are here" + ] + ``` 1. Create a new diff thread. This example creates a thread on an added line: - ```shell - curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\ - --form 'position[position_type]=text'\ - --form 'position[base_sha]=<use base_commit_sha from the versions response>'\ - --form 'position[head_sha]=<use head_commit_sha from the versions response>'\ - --form 'position[start_sha]=<use start_commit_sha from the versions response>'\ - --form 'position[new_path]=file.js'\ - --form 'position[old_path]=file.js'\ - --form 'position[new_line]=18'\ - --form 'body=test comment body'\ - "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions" - ``` + ```shell + curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\ + --form 'position[position_type]=text'\ + --form 'position[base_sha]=<use base_commit_sha from the versions response>'\ + --form 'position[head_sha]=<use head_commit_sha from the versions response>'\ + --form 'position[start_sha]=<use start_commit_sha from the versions response>'\ + --form 'position[new_path]=file.js'\ + --form 'position[old_path]=file.js'\ + --form 'position[new_line]=18'\ + --form 'body=test comment body'\ + "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions" + ``` #### Parameters for multiline comments @@ -933,14 +965,31 @@ Parameters for multiline comments only: #### Line code -A line code is of the form `<SHA>_<old>_<new>`: +A line code is of the form `<SHA>_<old>_<new>`, like this: `adc83b19e793491b1c6ea0fd8b46cd9f32e292fc_5_5` - `<SHA>` is the SHA1 hash of the filename. - `<old>` is the line number before the change. - `<new>` is the line number after the change. -For example, when commenting on an added line number 5, the line code -looks like `adc83b19e793491b1c6ea0fd8b46cd9f32e292fc_5_5`. +For example, if a commit (`<COMMIT_ID>`) deletes line 463 in the README, you can comment +on the deletion by referencing line 463 in the *old* file: + +```shell +curl --request POST --header "PRIVATE-TOKEN: [ACCESS_TOKEN]"\ + --form "note=Very clever to remove this unnecessary line!"\ + --form "path=README" --form "line=463" --form "line_type=old"\ + "https://gitlab.com/api/v4/projects/47/repository/commits/<COMMIT_ID>/comments" +``` + +If a commit (`<COMMIT_ID>`) adds line 157 to `hello.rb`, you can comment on the +addition by referencing line 157 in the *new* file: + +```shell +curl --request POST --header "PRIVATE-TOKEN: [ACCESS_TOKEN]"\ + --form "note=This is brilliant!" --form "path=hello.rb"\ + --form "line=157" --form "line_type=old"\ + "https://gitlab.com/api/v4/projects/47/repository/commits/<COMMIT_ID>/comments" +``` ### Resolve a merge request thread @@ -960,7 +1009,8 @@ Parameters: | `resolved` | boolean | yes | Resolve/unresolve the discussion | ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7?resolved=true" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/<discussion_id>?resolved=true" ``` ### Add note to existing merge request thread @@ -984,7 +1034,8 @@ Parameters: | `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/<discussion_id>/notes?body=comment" ``` ### Modify an existing merge request thread note @@ -1007,13 +1058,15 @@ Parameters: | `resolved` | boolean | no | Resolve/unresolve the note (exactly one of `body` or `resolved` must be set | ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?body=comment" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/<discussion_id>/notes/1108?body=comment" ``` Resolving a note: ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?resolved=true" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/<discussion_id>/notes/1108?resolved=true" ``` ### Delete a merge request thread note @@ -1034,7 +1087,8 @@ Parameters: | `note_id` | integer | yes | The ID of a thread note | ```shell -curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/636" +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/636" ``` ## Commits @@ -1177,7 +1231,8 @@ Diff comments contain also position: ``` ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions" +curl --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions" ``` ### Get single commit discussion item @@ -1197,7 +1252,8 @@ Parameters: | `discussion_id` | integer | yes | The ID of a discussion item | ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7" +curl --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/<discussion_id>" ``` ### Create new commit thread @@ -1232,7 +1288,8 @@ Parameters: | `position[y]` | integer | no | Y coordinate (for `image` diff notes) | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions?body=comment" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions?body=comment" ``` The rules for creating the API request are the same as when @@ -1259,7 +1316,8 @@ Parameters: | `created_at` | string | no | Date time string, ISO 8601 formatted, such `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/<discussion_id>/notes?body=comment ``` ### Modify an existing commit thread note @@ -1281,13 +1339,15 @@ Parameters: | `body` | string | no | The content of a note | ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?body=comment" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/<discussion_id>/notes/1108?body=comment" ``` Resolving a note: ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?resolved=true" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/<discussion_id>/notes/1108?resolved=true" ``` ### Delete a commit thread note @@ -1308,5 +1368,6 @@ Parameters: | `note_id` | integer | yes | The ID of a thread note | ```shell -curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/636" +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>"\ + "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/636" ``` diff --git a/doc/api/dora/metrics.md b/doc/api/dora/metrics.md index 38f1f50839e..8c82446db2e 100644 --- a/doc/api/dora/metrics.md +++ b/doc/api/dora/metrics.md @@ -7,7 +7,7 @@ type: reference, api # DevOps Research and Assessment (DORA) key metrics API **(ULTIMATE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/279039) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.10. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/279039) in GitLab 13.10. > - The legacy key/value pair `{ "<date>" => "<value>" }` was removed from the payload in GitLab 14.0. All methods require [reporter permissions and above](../../user/permissions.md). @@ -52,7 +52,7 @@ Example response: ## Get group-level DORA metrics -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/279039) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/279039) in GitLab 13.10. Get group-level DORA metrics. diff --git a/doc/api/dora4_project_analytics.md b/doc/api/dora4_project_analytics.md index efea9723ac4..5a6e1576a3d 100644 --- a/doc/api/dora4_project_analytics.md +++ b/doc/api/dora4_project_analytics.md @@ -7,7 +7,7 @@ type: reference, api # DORA4 Analytics Project API **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/279039) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/279039) in GitLab 13.7. WARNING: These endpoints are deprecated and will be removed in GitLab 14.0. Use the [DORA metrics API](dora/metrics.md) instead. diff --git a/doc/api/environments.md b/doc/api/environments.md index aa3697c54ac..5187ac7c1b2 100644 --- a/doc/api/environments.md +++ b/doc/api/environments.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts, howto --- -# Environments API +# Environments API **(FREE)** ## List environments @@ -194,7 +194,7 @@ PUT /projects/:id/environments/:environments_id | --------------- | ------- | --------------------------------- | ------------------------------- | | `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 | The new name 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` | ```shell diff --git a/doc/api/epic_links.md b/doc/api/epic_links.md index 5d8a92d0263..d87b44f43a7 100644 --- a/doc/api/epic_links.md +++ b/doc/api/epic_links.md @@ -15,7 +15,7 @@ Every API call to `epic_links` must be authenticated. If a user is not a member of a private group, a `GET` request on that group results in a `404` status code. -Multi-level Epics are available only in GitLab [Ultimate](https://about.gitlab.com/pricing/). +Multi-level Epics are available only in [GitLab Ultimate](https://about.gitlab.com/pricing/). If the Multi-level Epics feature is not available, a `403` status code is returned. ## List epics related to a given epic diff --git a/doc/api/error_tracking.md b/doc/api/error_tracking.md index 0fbb30ef364..1abe5522840 100644 --- a/doc/api/error_tracking.md +++ b/doc/api/error_tracking.md @@ -51,7 +51,7 @@ PATCH /projects/:id/error_tracking/settings | ------------ | ------- | -------- | --------------------- | | `id` | integer | yes | The ID or [URL-encoded path of the project](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 [GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68260) and later. | +| `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. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/error_tracking/settings?active=true" @@ -68,3 +68,87 @@ Example response: "integrated": false } ``` + +## Error Tracking client keys + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68384) in GitLab 14.3. + +For [integrated error tracking](https://gitlab.com/gitlab-org/gitlab/-/issues/329596) feature that is behind a disabled feature flag. Only for project maintainers. + +### List project client keys + +```plaintext +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. | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/error_tracking/client_keys" +``` + +Example response: + +```json +[ + { + "id": 1, + "active": true, + "public_key": "glet_aa77551d849c083f76d0bc545ed053a3", + "sentry_dsn": "https://glet_aa77551d849c083f76d0bc545ed053a3@gitlab.example.com/api/v4/error_tracking/collector/5" + }, + { + "id": 3, + "active": true, + "public_key": "glet_0ff98b1d849c083f76d0bc545ed053a3", + "sentry_dsn": "https://glet_0ff98b1d849c083f76d0bc545ed053a3@gitlab.example.com/api/v4/error_tracking/collector/5" + } +] +``` + +### Create a client key + +Creates a new client key for a project. The public key attribute is generated automatically. + +```plaintext +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. | + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \ + "https://gitlab.example.com/api/v4/projects/5/error_tracking/client_keys" +``` + +Example response: + +```json +{ + "id": 3, + "active": true, + "public_key": "glet_0ff98b1d849c083f76d0bc545ed053a3", + "sentry_dsn": "https://glet_0ff98b1d849c083f76d0bc545ed053a3@gitlab.example.com/api/v4/error_tracking/collector/5" +} +``` + +### Delete a client key + +Removes a client key from the project. + +```plaintext +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. | +| `key_id` | integer | yes | The ID of the client key. | + +```shell +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/error_tracking/client_keys/13" +``` diff --git a/doc/api/events.md b/doc/api/events.md index 3fbbfa62e66..8800e7f7f9b 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -4,7 +4,7 @@ group: Compliance info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Events API +# Events API **(FREE)** ## Filter parameters @@ -15,7 +15,7 @@ Available types for the `action` parameter, and the resources that might be affe - `approved` - Merge request - `closed` - - Epic + - Epic **(PREMIUM)** - Issue - Merge request - Milestone @@ -28,7 +28,7 @@ Available types for the `action` parameter, and the resources that might be affe - Snippet - `created` - Design - - Epic + - Epic **(PREMIUM)** - Issue - Merge request - Milestone @@ -49,7 +49,7 @@ Available types for the `action` parameter, and the resources that might be affe - `pushed` commits to (or deleted commits from) a repository, individually or in bulk. - Project - `reopened` - - Epic + - Epic **(PREMIUM)** - Issue - Merge request - Milestone diff --git a/doc/api/feature_flag_specs.md b/doc/api/feature_flag_specs.md index 33e454d50c4..f2853efc5f2 100644 --- a/doc/api/feature_flag_specs.md +++ b/doc/api/feature_flag_specs.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Feature Flag Specs API **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9566) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9566) in GitLab 12.5. This API was removed in [GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/213369). Please use [the new API](feature_flags.md) instead. diff --git a/doc/api/features.md b/doc/api/features.md index 87bd565e2bd..30efacb1d00 100644 --- a/doc/api/features.md +++ b/doc/api/features.md @@ -4,7 +4,7 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Features flags API +# Feature flags API **(FREE SELF)** This API is for managing Flipper-based [feature flags used in development of GitLab](../development/feature_flags/index.md). diff --git a/doc/api/freeze_periods.md b/doc/api/freeze_periods.md index a562423b2af..6ca69d047da 100644 --- a/doc/api/freeze_periods.md +++ b/doc/api/freeze_periods.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts, howto --- -# Freeze Periods API +# Freeze Periods API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29382) in GitLab 13.0. diff --git a/doc/api/geo_nodes.md b/doc/api/geo_nodes.md index 42cf40d62b8..d9b23485fd5 100644 --- a/doc/api/geo_nodes.md +++ b/doc/api/geo_nodes.md @@ -393,6 +393,18 @@ Example response: "package_files_verification_failed_count": null, "package_files_synced_in_percentage": "0.00%", "package_files_verified_in_percentage": "0.00%", + "pages_deployments_count": 5, + "pages_deployments_checksum_total_count": 5, + "pages_deployments_checksummed_count": 5, + "pages_deployments_checksum_failed_count": 0, + "pages_deployments_synced_count": null, + "pages_deployments_failed_count": null, + "pages_deployments_registry_count": null, + "pages_deployments_verification_total_count": null, + "pages_deployments_verified_count": null, + "pages_deployments_verification_failed_count": null, + "pages_deployments_synced_in_percentage": "0.00%", + "pages_deployments_verified_in_percentage": "0.00%", "terraform_state_versions_count": 5, "terraform_state_versions_checksum_total_count": 5, "terraform_state_versions_checksummed_count": 5, @@ -441,6 +453,11 @@ Example response: "pipeline_artifacts_verification_failed_count": null, "pipeline_artifacts_synced_in_percentage": "0.00%", "pipeline_artifacts_verified_in_percentage": "0.00%", + "uploads_count": 5, + "uploads_synced_count": null, + "uploads_failed_count": 0, + "uploads_registry_count": null, + "uploads_synced_in_percentage": "0.00%", }, { "geo_node_id": 2, @@ -583,6 +600,11 @@ Example response: "pipeline_artifacts_verification_failed_count": 0, "pipeline_artifacts_synced_in_percentage": "100.00%", "pipeline_artifacts_verified_in_percentage": "100.00%", + "uploads_count": 5, + "uploads_synced_count": null, + "uploads_failed_count": 0, + "uploads_registry_count": null, + "uploads_synced_in_percentage": "0.00%", } ] ``` @@ -722,6 +744,11 @@ Example response: "pipeline_artifacts_verification_failed_count": 0, "pipeline_artifacts_synced_in_percentage": "100.00%", "pipeline_artifacts_verified_in_percentage": "100.00%", + "uploads_count": 5, + "uploads_synced_count": null, + "uploads_failed_count": 0, + "uploads_registry_count": null, + "uploads_synced_in_percentage": "0.00%", } ``` diff --git a/doc/api/graphql/audit_report.md b/doc/api/graphql/audit_report.md index ba9967f85f2..76f3da2d6ea 100644 --- a/doc/api/graphql/audit_report.md +++ b/doc/api/graphql/audit_report.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/engineering/ux/technical-writing/#assignments --- -# Set up an Audit Report with GraphQL +# Set up an Audit Report with GraphQL **(FREE)** This page describes how you can use the GraphiQL explorer to set up an audit report for a specific subset of users. diff --git a/doc/api/graphql/custom_emoji.md b/doc/api/graphql/custom_emoji.md index cb5c0275e08..7307abc0568 100644 --- a/doc/api/graphql/custom_emoji.md +++ b/doc/api/graphql/custom_emoji.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/engineering/ux/technical-writing/#assignments --- -# Use custom emojis with GraphQL **(FREE SELF)** +# Use custom emojis with GraphQL **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37911) in GitLab 13.6 > - [Deployed behind a feature flag](../../user/feature_flags.md), disabled by default. @@ -93,7 +93,7 @@ For more information on: ## Enable or disable custom emoji API **(FREE SELF)** -Custom emoji is under development and but ready for production use. It is +Custom emoji is under development but ready for production use. It is deployed behind a feature flag that is **disabled by default**. [GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) can enable it. diff --git a/doc/api/graphql/index.md b/doc/api/graphql/index.md index e77e6102594..3523276bdf5 100644 --- a/doc/api/graphql/index.md +++ b/doc/api/graphql/index.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/engineering/ux/technical-writing/#assignments --- -# GraphQL API +# GraphQL API **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19008) in GitLab 11.0 (enabled by feature flag `graphql`). > - [Always enabled](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30444) in GitLab 12.1. diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md index 54709f56eb8..c4e73f9c058 100644 --- a/doc/api/graphql/reference/index.md +++ b/doc/api/graphql/reference/index.md @@ -1,6 +1,6 @@ --- -stage: Plan -group: Project Management +stage: Ecosystem +group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- @@ -56,7 +56,7 @@ Returns [`CiConfig`](#ciconfig). ### `Query.ciMinutesUsage` -The monthly CI minutes usage data for the current user. +Monthly CI minutes usage data for the current user. Returns [`CiMinutesNamespaceMonthlyUsageConnection`](#ciminutesnamespacemonthlyusageconnection). @@ -74,7 +74,7 @@ Returns [`ContainerRepositoryDetails`](#containerrepositorydetails). | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="querycontainerrepositoryid"></a>`id` | [`ContainerRepositoryID!`](#containerrepositoryid) | The global ID of the container repository. | +| <a id="querycontainerrepositoryid"></a>`id` | [`ContainerRepositoryID!`](#containerrepositoryid) | Global ID of the container repository. | ### `Query.currentLicense` @@ -132,7 +132,7 @@ Returns [`GeoNode`](#geonode). | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="querygeonodename"></a>`name` | [`String`](#string) | The name of the Geo node. Defaults to the current Geo node name. | +| <a id="querygeonodename"></a>`name` | [`String`](#string) | Name of the Geo node. Defaults to the current Geo node name. | ### `Query.group` @@ -185,7 +185,7 @@ Returns [`Issue`](#issue). | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="queryissueid"></a>`id` | [`IssueID!`](#issueid) | The global ID of the issue. | +| <a id="queryissueid"></a>`id` | [`IssueID!`](#issueid) | Global ID of the issue. | ### `Query.iteration` @@ -219,7 +219,7 @@ Returns [`MergeRequest`](#mergerequest). | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="querymergerequestid"></a>`id` | [`MergeRequestID!`](#mergerequestid) | The global ID of the merge request. | +| <a id="querymergerequestid"></a>`id` | [`MergeRequestID!`](#mergerequestid) | Global ID of the merge request. | ### `Query.metadata` @@ -261,7 +261,7 @@ Returns [`PackageDetailsType`](#packagedetailstype). | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="querypackageid"></a>`id` | [`PackagesPackageID!`](#packagespackageid) | The global ID of the package. | +| <a id="querypackageid"></a>`id` | [`PackagesPackageID!`](#packagespackageid) | Global ID of the package. | ### `Query.project` @@ -304,7 +304,7 @@ Returns [`QueryComplexity`](#querycomplexity). ### `Query.runner` -Find a runner. Available only when feature flag `runner_graphql_query` is enabled. This flag is enabled by default. +Find a runner. Returns [`CiRunner`](#cirunner). @@ -341,7 +341,7 @@ Returns [`RunnerSetup`](#runnersetup). ### `Query.runners` -Find runners visible to the current user. Available only when feature flag `runner_graphql_query` is enabled. This flag is enabled by default. +Find runners visible to the current user. Returns [`CiRunnerConnection`](#cirunnerconnection). @@ -373,11 +373,11 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="querysnippetsauthorid"></a>`authorId` | [`UserID`](#userid) | The ID of an author. | +| <a id="querysnippetsauthorid"></a>`authorId` | [`UserID`](#userid) | ID of an author. | | <a id="querysnippetsexplore"></a>`explore` | [`Boolean`](#boolean) | Explore personal snippets. | | <a id="querysnippetsids"></a>`ids` | [`[SnippetID!]`](#snippetid) | Array of global snippet IDs. For example, `gid://gitlab/ProjectSnippet/1`. | -| <a id="querysnippetsprojectid"></a>`projectId` | [`ProjectID`](#projectid) | The ID of a project. | -| <a id="querysnippetstype"></a>`type` | [`TypeEnum`](#typeenum) | The type of snippet. | +| <a id="querysnippetsprojectid"></a>`projectId` | [`ProjectID`](#projectid) | ID of a project. | +| <a id="querysnippetstype"></a>`type` | [`TypeEnum`](#typeenum) | Type of snippet. | | <a id="querysnippetsvisibility"></a>`visibility` | [`VisibilityScopesEnum`](#visibilityscopesenum) | Visibility of the snippet. | ### `Query.timelogs` @@ -504,7 +504,7 @@ Returns [`Vulnerability`](#vulnerability). | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="queryvulnerabilityid"></a>`id` | [`VulnerabilityID!`](#vulnerabilityid) | The Global ID of the Vulnerability. | +| <a id="queryvulnerabilityid"></a>`id` | [`VulnerabilityID!`](#vulnerabilityid) | Global ID of the Vulnerability. | ## `Mutation` type @@ -563,6 +563,7 @@ Input type: `AdminSidekiqQueuesDeleteJobsInput` | <a id="mutationadminsidekiqqueuesdeletejobsrootnamespace"></a>`rootNamespace` | [`String`](#string) | Delete jobs matching root_namespace in the context metadata. | | <a id="mutationadminsidekiqqueuesdeletejobssubscriptionplan"></a>`subscriptionPlan` | [`String`](#string) | Delete jobs matching subscription_plan in the context metadata. | | <a id="mutationadminsidekiqqueuesdeletejobsuser"></a>`user` | [`String`](#string) | Delete jobs matching user in the context metadata. | +| <a id="mutationadminsidekiqqueuesdeletejobsworkerclass"></a>`workerClass` | [`String`](#string) | Delete jobs with the given worker class. | #### Fields @@ -631,7 +632,7 @@ Input type: `ApiFuzzingCiConfigurationCreateInput` | <a id="mutationapifuzzingciconfigurationcreateauthusername"></a>`authUsername` | [`String`](#string) | CI variable containing the username for authenticating with the target API. | | <a id="mutationapifuzzingciconfigurationcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationapifuzzingciconfigurationcreateprojectpath"></a>`projectPath` | [`ID!`](#id) | Full path of the project. | -| <a id="mutationapifuzzingciconfigurationcreatescanmode"></a>`scanMode` | [`ApiFuzzingScanMode!`](#apifuzzingscanmode) | The mode for API fuzzing scans. | +| <a id="mutationapifuzzingciconfigurationcreatescanmode"></a>`scanMode` | [`ApiFuzzingScanMode!`](#apifuzzingscanmode) | Mode for API fuzzing scans. | | <a id="mutationapifuzzingciconfigurationcreatescanprofile"></a>`scanProfile` | [`String`](#string) | Name of a default profile to use for scanning. Ex: Quick-10. | | <a id="mutationapifuzzingciconfigurationcreatetarget"></a>`target` | [`String!`](#string) | URL for the target of API fuzzing scans. | @@ -642,7 +643,7 @@ Input type: `ApiFuzzingCiConfigurationCreateInput` | <a id="mutationapifuzzingciconfigurationcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationapifuzzingciconfigurationcreateconfigurationyaml"></a>`configurationYaml` | [`String`](#string) | A YAML snippet that can be inserted into the project's `.gitlab-ci.yml` to set up API fuzzing scans. | | <a id="mutationapifuzzingciconfigurationcreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationapifuzzingciconfigurationcreategitlabciyamleditpath"></a>`gitlabCiYamlEditPath` | [`String`](#string) | The location at which the project's `.gitlab-ci.yml` file can be edited in the browser. | +| <a id="mutationapifuzzingciconfigurationcreategitlabciyamleditpath"></a>`gitlabCiYamlEditPath` | [`String`](#string) | Location at which the project's `.gitlab-ci.yml` file can be edited in the browser. | ### `Mutation.awardEmojiAdd` @@ -654,7 +655,7 @@ Input type: `AwardEmojiAddInput` | ---- | ---- | ----------- | | <a id="mutationawardemojiaddawardableid"></a>`awardableId` | [`AwardableID!`](#awardableid) | Global ID of the awardable resource. | | <a id="mutationawardemojiaddclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationawardemojiaddname"></a>`name` | [`String!`](#string) | The emoji name. | +| <a id="mutationawardemojiaddname"></a>`name` | [`String!`](#string) | Emoji name. | #### Fields @@ -674,7 +675,7 @@ Input type: `AwardEmojiRemoveInput` | ---- | ---- | ----------- | | <a id="mutationawardemojiremoveawardableid"></a>`awardableId` | [`AwardableID!`](#awardableid) | Global ID of the awardable resource. | | <a id="mutationawardemojiremoveclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationawardemojiremovename"></a>`name` | [`String!`](#string) | The emoji name. | +| <a id="mutationawardemojiremovename"></a>`name` | [`String!`](#string) | Emoji name. | #### Fields @@ -694,7 +695,7 @@ Input type: `AwardEmojiToggleInput` | ---- | ---- | ----------- | | <a id="mutationawardemojitoggleawardableid"></a>`awardableId` | [`AwardableID!`](#awardableid) | Global ID of the awardable resource. | | <a id="mutationawardemojitoggleclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationawardemojitogglename"></a>`name` | [`String!`](#string) | The emoji name. | +| <a id="mutationawardemojitogglename"></a>`name` | [`String!`](#string) | Emoji name. | #### Fields @@ -760,10 +761,10 @@ Input type: `BoardListUpdateLimitMetricsInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationboardlistupdatelimitmetricsclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationboardlistupdatelimitmetricslimitmetric"></a>`limitMetric` | [`ListLimitMetric`](#listlimitmetric) | The new limit metric type for the list. | -| <a id="mutationboardlistupdatelimitmetricslistid"></a>`listId` | [`ListID!`](#listid) | The global ID of the list. | -| <a id="mutationboardlistupdatelimitmetricsmaxissuecount"></a>`maxIssueCount` | [`Int`](#int) | The new maximum issue count limit. | -| <a id="mutationboardlistupdatelimitmetricsmaxissueweight"></a>`maxIssueWeight` | [`Int`](#int) | The new maximum issue weight limit. | +| <a id="mutationboardlistupdatelimitmetricslimitmetric"></a>`limitMetric` | [`ListLimitMetric`](#listlimitmetric) | New limit metric type for the list. | +| <a id="mutationboardlistupdatelimitmetricslistid"></a>`listId` | [`ListID!`](#listid) | Global ID of the list. | +| <a id="mutationboardlistupdatelimitmetricsmaxissuecount"></a>`maxIssueCount` | [`Int`](#int) | New maximum issue count limit. | +| <a id="mutationboardlistupdatelimitmetricsmaxissueweight"></a>`maxIssueWeight` | [`Int`](#int) | New maximum issue weight limit. | #### Fields @@ -771,7 +772,7 @@ Input type: `BoardListUpdateLimitMetricsInput` | ---- | ---- | ----------- | | <a id="mutationboardlistupdatelimitmetricsclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationboardlistupdatelimitmetricserrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationboardlistupdatelimitmetricslist"></a>`list` | [`BoardList`](#boardlist) | The updated list. | +| <a id="mutationboardlistupdatelimitmetricslist"></a>`list` | [`BoardList`](#boardlist) | Updated list. | ### `Mutation.bulkEnableDevopsAdoptionNamespaces` @@ -1074,6 +1075,7 @@ Input type: `CreateBoardInput` | <a id="mutationcreateboardgrouppath"></a>`groupPath` | [`ID`](#id) | Full path of the group with which the resource is associated. | | <a id="mutationcreateboardhidebackloglist"></a>`hideBacklogList` | [`Boolean`](#boolean) | Whether or not backlog list is hidden. | | <a id="mutationcreateboardhideclosedlist"></a>`hideClosedList` | [`Boolean`](#boolean) | Whether or not closed list is hidden. | +| <a id="mutationcreateboarditerationcadenceid"></a>`iterationCadenceId` | [`IterationsCadenceID`](#iterationscadenceid) | ID of iteration cadence to be assigned to the board. | | <a id="mutationcreateboarditerationid"></a>`iterationId` | [`IterationID`](#iterationid) | ID of iteration to be assigned to the board. | | <a id="mutationcreateboardlabelids"></a>`labelIds` | [`[LabelID!]`](#labelid) | IDs of labels to be added to the board. | | <a id="mutationcreateboardlabels"></a>`labels` | [`[String!]`](#string) | Labels of the issue. | @@ -1149,7 +1151,7 @@ Input type: `CreateComplianceFrameworkInput` | ---- | ---- | ----------- | | <a id="mutationcreatecomplianceframeworkclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationcreatecomplianceframeworkerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationcreatecomplianceframeworkframework"></a>`framework` | [`ComplianceFramework`](#complianceframework) | The created compliance framework. | +| <a id="mutationcreatecomplianceframeworkframework"></a>`framework` | [`ComplianceFramework`](#complianceframework) | Created compliance framework. | ### `Mutation.createCustomEmoji` @@ -1186,7 +1188,7 @@ Input type: `CreateDiffNoteInput` | <a id="mutationcreatediffnoteclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationcreatediffnoteconfidential"></a>`confidential` | [`Boolean`](#boolean) | Confidentiality flag of a note. Default is false. | | <a id="mutationcreatediffnotenoteableid"></a>`noteableId` | [`NoteableID!`](#noteableid) | Global ID of the resource to add a note to. | -| <a id="mutationcreatediffnoteposition"></a>`position` | [`DiffPositionInput!`](#diffpositioninput) | The position of this note on a diff. | +| <a id="mutationcreatediffnoteposition"></a>`position` | [`DiffPositionInput!`](#diffpositioninput) | Position of this note on a diff. | #### Fields @@ -1204,24 +1206,24 @@ Input type: `CreateEpicInput` | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="mutationcreateepicaddlabelids"></a>`addLabelIds` | [`[ID!]`](#id) | The IDs of labels to be added to the epic. | +| <a id="mutationcreateepicaddlabelids"></a>`addLabelIds` | [`[ID!]`](#id) | IDs of labels to be added to the epic. | | <a id="mutationcreateepicclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationcreateepicconfidential"></a>`confidential` | [`Boolean`](#boolean) | Indicates if the epic is confidential. | -| <a id="mutationcreateepicdescription"></a>`description` | [`String`](#string) | The description of the epic. | -| <a id="mutationcreateepicduedatefixed"></a>`dueDateFixed` | [`String`](#string) | The end date of the epic. | +| <a id="mutationcreateepicdescription"></a>`description` | [`String`](#string) | Description of the epic. | +| <a id="mutationcreateepicduedatefixed"></a>`dueDateFixed` | [`String`](#string) | End date of the epic. | | <a id="mutationcreateepicduedateisfixed"></a>`dueDateIsFixed` | [`Boolean`](#boolean) | Indicates end date should be sourced from due_date_fixed field not the issue milestones. | -| <a id="mutationcreateepicgrouppath"></a>`groupPath` | [`ID!`](#id) | The group the epic to mutate is in. | -| <a id="mutationcreateepicremovelabelids"></a>`removeLabelIds` | [`[ID!]`](#id) | The IDs of labels to be removed from the epic. | -| <a id="mutationcreateepicstartdatefixed"></a>`startDateFixed` | [`String`](#string) | The start date of the epic. | +| <a id="mutationcreateepicgrouppath"></a>`groupPath` | [`ID!`](#id) | Group the epic to mutate is in. | +| <a id="mutationcreateepicremovelabelids"></a>`removeLabelIds` | [`[ID!]`](#id) | IDs of labels to be removed from the epic. | +| <a id="mutationcreateepicstartdatefixed"></a>`startDateFixed` | [`String`](#string) | Start date of the epic. | | <a id="mutationcreateepicstartdateisfixed"></a>`startDateIsFixed` | [`Boolean`](#boolean) | Indicates start date should be sourced from start_date_fixed field not the issue milestones. | -| <a id="mutationcreateepictitle"></a>`title` | [`String`](#string) | The title of the epic. | +| <a id="mutationcreateepictitle"></a>`title` | [`String`](#string) | Title of the epic. | #### Fields | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationcreateepicclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationcreateepicepic"></a>`epic` | [`Epic`](#epic) | The created epic. | +| <a id="mutationcreateepicepic"></a>`epic` | [`Epic`](#epic) | Created epic. | | <a id="mutationcreateepicerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | ### `Mutation.createImageDiffNote` @@ -1236,7 +1238,7 @@ Input type: `CreateImageDiffNoteInput` | <a id="mutationcreateimagediffnoteclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationcreateimagediffnoteconfidential"></a>`confidential` | [`Boolean`](#boolean) | Confidentiality flag of a note. Default is false. | | <a id="mutationcreateimagediffnotenoteableid"></a>`noteableId` | [`NoteableID!`](#noteableid) | Global ID of the resource to add a note to. | -| <a id="mutationcreateimagediffnoteposition"></a>`position` | [`DiffImagePositionInput!`](#diffimagepositioninput) | The position of this note on a diff. | +| <a id="mutationcreateimagediffnoteposition"></a>`position` | [`DiffImagePositionInput!`](#diffimagepositioninput) | Position of this note on a diff. | #### Fields @@ -1261,8 +1263,8 @@ Input type: `CreateIssueInput` | <a id="mutationcreateissuedescription"></a>`description` | [`String`](#string) | Description of the issue. | | <a id="mutationcreateissuediscussiontoresolve"></a>`discussionToResolve` | [`String`](#string) | ID of a discussion to resolve. Also pass `merge_request_to_resolve_discussions_of`. | | <a id="mutationcreateissueduedate"></a>`dueDate` | [`ISO8601Date`](#iso8601date) | Due date of the issue. | -| <a id="mutationcreateissueepicid"></a>`epicId` | [`EpicID`](#epicid) | The ID of an epic to associate the issue with. | -| <a id="mutationcreateissuehealthstatus"></a>`healthStatus` | [`HealthStatus`](#healthstatus) | The desired health status. | +| <a id="mutationcreateissueepicid"></a>`epicId` | [`EpicID`](#epicid) | ID of an epic to associate the issue with. | +| <a id="mutationcreateissuehealthstatus"></a>`healthStatus` | [`HealthStatus`](#healthstatus) | Desired health status. | | <a id="mutationcreateissueiid"></a>`iid` | [`Int`](#int) | IID (internal ID) of a project issue. Only admins and project owners can modify. | | <a id="mutationcreateissuelabelids"></a>`labelIds` | [`[LabelID!]`](#labelid) | IDs of labels to be added to the issue. | | <a id="mutationcreateissuelabels"></a>`labels` | [`[String!]`](#string) | Labels of the issue. | @@ -1272,7 +1274,7 @@ Input type: `CreateIssueInput` | <a id="mutationcreateissueprojectpath"></a>`projectPath` | [`ID!`](#id) | Project full path the issue is associated with. | | <a id="mutationcreateissuetitle"></a>`title` | [`String!`](#string) | Title of the issue. | | <a id="mutationcreateissuetype"></a>`type` | [`IssueType`](#issuetype) | Type of the issue. | -| <a id="mutationcreateissueweight"></a>`weight` | [`Int`](#int) | The weight of the issue. | +| <a id="mutationcreateissueweight"></a>`weight` | [`Int`](#int) | Weight of the issue. | #### Fields @@ -1295,13 +1297,13 @@ Input type: `CreateIterationInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationcreateiterationclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationcreateiterationdescription"></a>`description` | [`String`](#string) | The description of the iteration. | -| <a id="mutationcreateiterationduedate"></a>`dueDate` | [`String`](#string) | The end date of the iteration. | +| <a id="mutationcreateiterationdescription"></a>`description` | [`String`](#string) | Description of the iteration. | +| <a id="mutationcreateiterationduedate"></a>`dueDate` | [`String`](#string) | End date of the iteration. | | <a id="mutationcreateiterationgrouppath"></a>`groupPath` | [`ID`](#id) | Full path of the group with which the resource is associated. | | <a id="mutationcreateiterationiterationscadenceid"></a>`iterationsCadenceId` | [`IterationsCadenceID`](#iterationscadenceid) | Global ID of the iterations cadence to be assigned to newly created iteration. | | <a id="mutationcreateiterationprojectpath"></a>`projectPath` | [`ID`](#id) | Full path of the project with which the resource is associated. | -| <a id="mutationcreateiterationstartdate"></a>`startDate` | [`String`](#string) | The start date of the iteration. | -| <a id="mutationcreateiterationtitle"></a>`title` | [`String`](#string) | The title of the iteration. | +| <a id="mutationcreateiterationstartdate"></a>`startDate` | [`String`](#string) | Start date of the iteration. | +| <a id="mutationcreateiterationtitle"></a>`title` | [`String`](#string) | Title of the iteration. | #### Fields @@ -1309,7 +1311,7 @@ Input type: `CreateIterationInput` | ---- | ---- | ----------- | | <a id="mutationcreateiterationclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationcreateiterationerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationcreateiterationiteration"></a>`iteration` | [`Iteration`](#iteration) | The created iteration. | +| <a id="mutationcreateiterationiteration"></a>`iteration` | [`Iteration`](#iteration) | Created iteration. | ### `Mutation.createNote` @@ -1393,10 +1395,10 @@ Input type: `CreateTestCaseInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationcreatetestcaseclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationcreatetestcasedescription"></a>`description` | [`String`](#string) | The test case description. | -| <a id="mutationcreatetestcaselabelids"></a>`labelIds` | [`[ID!]`](#id) | The IDs of labels to be added to the test case. | -| <a id="mutationcreatetestcaseprojectpath"></a>`projectPath` | [`ID!`](#id) | The project full path to create the test case. | -| <a id="mutationcreatetestcasetitle"></a>`title` | [`String!`](#string) | The test case title. | +| <a id="mutationcreatetestcasedescription"></a>`description` | [`String`](#string) | Test case description. | +| <a id="mutationcreatetestcaselabelids"></a>`labelIds` | [`[ID!]`](#id) | IDs of labels to be added to the test case. | +| <a id="mutationcreatetestcaseprojectpath"></a>`projectPath` | [`ID!`](#id) | Project full path to create the test case in. | +| <a id="mutationcreatetestcasetitle"></a>`title` | [`String!`](#string) | Test case title. | #### Fields @@ -1404,7 +1406,51 @@ Input type: `CreateTestCaseInput` | ---- | ---- | ----------- | | <a id="mutationcreatetestcaseclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationcreatetestcaseerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationcreatetestcasetestcase"></a>`testCase` | [`Issue`](#issue) | The test case created. | +| <a id="mutationcreatetestcasetestcase"></a>`testCase` | [`Issue`](#issue) | Test case created. | + +### `Mutation.customerRelationsOrganizationCreate` + +Input type: `CustomerRelationsOrganizationCreateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationcustomerrelationsorganizationcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationcustomerrelationsorganizationcreatedefaultrate"></a>`defaultRate` | [`Float`](#float) | Standard billing rate for the organization. | +| <a id="mutationcustomerrelationsorganizationcreatedescription"></a>`description` | [`String`](#string) | Description or notes for the organization. | +| <a id="mutationcustomerrelationsorganizationcreategroupid"></a>`groupId` | [`GroupID!`](#groupid) | Group for the organization. | +| <a id="mutationcustomerrelationsorganizationcreatename"></a>`name` | [`String!`](#string) | Name of the organization. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationcustomerrelationsorganizationcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationcustomerrelationsorganizationcreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationcustomerrelationsorganizationcreateorganization"></a>`organization` | [`CustomerRelationsOrganization`](#customerrelationsorganization) | Organization after the mutation. | + +### `Mutation.customerRelationsOrganizationUpdate` + +Input type: `CustomerRelationsOrganizationUpdateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationcustomerrelationsorganizationupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationcustomerrelationsorganizationupdatedefaultrate"></a>`defaultRate` | [`Float`](#float) | Standard billing rate for the organization. | +| <a id="mutationcustomerrelationsorganizationupdatedescription"></a>`description` | [`String`](#string) | Description or notes for the organization. | +| <a id="mutationcustomerrelationsorganizationupdateid"></a>`id` | [`CustomerRelationsOrganizationID!`](#customerrelationsorganizationid) | Global ID of the organization. | +| <a id="mutationcustomerrelationsorganizationupdatename"></a>`name` | [`String`](#string) | Name of the organization. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationcustomerrelationsorganizationupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationcustomerrelationsorganizationupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationcustomerrelationsorganizationupdateorganization"></a>`organization` | [`CustomerRelationsOrganization!`](#customerrelationsorganization) | Organization after the mutation. | ### `Mutation.dastOnDemandScanCreate` @@ -1417,7 +1463,7 @@ Input type: `DastOnDemandScanCreateInput` | <a id="mutationdastondemandscancreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationdastondemandscancreatedastscannerprofileid"></a>`dastScannerProfileId` | [`DastScannerProfileID`](#dastscannerprofileid) | ID of the scanner profile to be used for the scan. | | <a id="mutationdastondemandscancreatedastsiteprofileid"></a>`dastSiteProfileId` | [`DastSiteProfileID!`](#dastsiteprofileid) | ID of the site profile to be used for the scan. | -| <a id="mutationdastondemandscancreatefullpath"></a>`fullPath` | [`ID!`](#id) | The project the site profile belongs to. | +| <a id="mutationdastondemandscancreatefullpath"></a>`fullPath` | [`ID!`](#id) | Project the site profile belongs to. | #### Fields @@ -1435,13 +1481,14 @@ Input type: `DastProfileCreateInput` | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="mutationdastprofilecreatebranchname"></a>`branchName` | [`String`](#string) | The associated branch. | +| <a id="mutationdastprofilecreatebranchname"></a>`branchName` | [`String`](#string) | Associated branch. | | <a id="mutationdastprofilecreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationdastprofilecreatedastprofileschedule"></a>`dastProfileSchedule` | [`DastProfileScheduleInput`](#dastprofilescheduleinput) | Represents a DAST Profile Schedule. Results in an error if `dast_on_demand_scans_scheduler` feature flag is disabled. | | <a id="mutationdastprofilecreatedastscannerprofileid"></a>`dastScannerProfileId` | [`DastScannerProfileID!`](#dastscannerprofileid) | ID of the scanner profile to be associated. | | <a id="mutationdastprofilecreatedastsiteprofileid"></a>`dastSiteProfileId` | [`DastSiteProfileID!`](#dastsiteprofileid) | ID of the site profile to be associated. | -| <a id="mutationdastprofilecreatedescription"></a>`description` | [`String`](#string) | The description of the profile. Defaults to an empty string. | -| <a id="mutationdastprofilecreatefullpath"></a>`fullPath` | [`ID!`](#id) | The project the profile belongs to. | -| <a id="mutationdastprofilecreatename"></a>`name` | [`String!`](#string) | The name of the profile. | +| <a id="mutationdastprofilecreatedescription"></a>`description` | [`String`](#string) | Description of the profile. Defaults to an empty string. | +| <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. | #### Fields @@ -1449,9 +1496,9 @@ Input type: `DastProfileCreateInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationdastprofilecreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationdastprofilecreatedastprofile"></a>`dastProfile` | [`DastProfile`](#dastprofile) | The created profile. | +| <a id="mutationdastprofilecreatedastprofile"></a>`dastProfile` | [`DastProfile`](#dastprofile) | Created profile. | | <a id="mutationdastprofilecreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationdastprofilecreatepipelineurl"></a>`pipelineUrl` | [`String`](#string) | The URL of the pipeline that was created. Requires `runAfterCreate` to be set to `true`. | +| <a id="mutationdastprofilecreatepipelineurl"></a>`pipelineUrl` | [`String`](#string) | URL of the pipeline that was created. Requires `runAfterCreate` to be set to `true`. | ### `Mutation.dastProfileDelete` @@ -1499,14 +1546,15 @@ Input type: `DastProfileUpdateInput` | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="mutationdastprofileupdatebranchname"></a>`branchName` | [`String`](#string) | The associated branch. | +| <a id="mutationdastprofileupdatebranchname"></a>`branchName` | [`String`](#string) | Associated branch. | | <a id="mutationdastprofileupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationdastprofileupdatedastprofileschedule"></a>`dastProfileSchedule` | [`DastProfileScheduleInput`](#dastprofilescheduleinput) | Represents a DAST profile schedule. Results in an error if `dast_on_demand_scans_scheduler` feature flag is disabled. | | <a id="mutationdastprofileupdatedastscannerprofileid"></a>`dastScannerProfileId` | [`DastScannerProfileID`](#dastscannerprofileid) | ID of the scanner profile to be associated. | | <a id="mutationdastprofileupdatedastsiteprofileid"></a>`dastSiteProfileId` | [`DastSiteProfileID`](#dastsiteprofileid) | ID of the site profile to be associated. | -| <a id="mutationdastprofileupdatedescription"></a>`description` | [`String`](#string) | The description of the profile. Defaults to an empty string. | -| <a id="mutationdastprofileupdatefullpath"></a>`fullPath` | [`ID!`](#id) | The project the profile belongs to. | +| <a id="mutationdastprofileupdatedescription"></a>`description` | [`String`](#string) | Description of the profile. Defaults to an empty string. | +| <a id="mutationdastprofileupdatefullpath"></a>`fullPath` | [`ID!`](#id) | Project the profile belongs to. | | <a id="mutationdastprofileupdateid"></a>`id` | [`DastProfileID!`](#dastprofileid) | ID of the profile to be deleted. | -| <a id="mutationdastprofileupdatename"></a>`name` | [`String`](#string) | The name of the profile. | +| <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. | #### Fields @@ -1514,7 +1562,7 @@ Input type: `DastProfileUpdateInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationdastprofileupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationdastprofileupdatedastprofile"></a>`dastProfile` | [`DastProfile`](#dastprofile) | The updated profile. | +| <a id="mutationdastprofileupdatedastprofile"></a>`dastProfile` | [`DastProfile`](#dastprofile) | Updated profile. | | <a id="mutationdastprofileupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationdastprofileupdatepipelineurl"></a>`pipelineUrl` | [`String`](#string) | The URL of the pipeline that was created. Requires the input argument `runAfterUpdate` to be set to `true` when calling the mutation, otherwise no pipeline will be created. | @@ -1527,12 +1575,12 @@ Input type: `DastScannerProfileCreateInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationdastscannerprofilecreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationdastscannerprofilecreatefullpath"></a>`fullPath` | [`ID!`](#id) | The project the scanner profile belongs to. | -| <a id="mutationdastscannerprofilecreateprofilename"></a>`profileName` | [`String!`](#string) | The name of the scanner profile. | +| <a id="mutationdastscannerprofilecreatefullpath"></a>`fullPath` | [`ID!`](#id) | Project the scanner profile belongs to. | +| <a id="mutationdastscannerprofilecreateprofilename"></a>`profileName` | [`String!`](#string) | Name of the scanner profile. | | <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) | The maximum number of minutes allowed for the spider to traverse the site. | -| <a id="mutationdastscannerprofilecreatetargettimeout"></a>`targetTimeout` | [`Int`](#int) | The maximum number of seconds allowed for the site under test to respond to a request. | +| <a id="mutationdastscannerprofilecreatespidertimeout"></a>`spiderTimeout` | [`Int`](#int) | Maximum number of minutes allowed for the spider to traverse the site. | +| <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. | #### Fields @@ -1571,13 +1619,13 @@ Input type: `DastScannerProfileUpdateInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationdastscannerprofileupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationdastscannerprofileupdatefullpath"></a>`fullPath` | [`ID!`](#id) | The project the scanner profile belongs to. | +| <a id="mutationdastscannerprofileupdatefullpath"></a>`fullPath` | [`ID!`](#id) | Project the scanner profile belongs to. | | <a id="mutationdastscannerprofileupdateid"></a>`id` | [`DastScannerProfileID!`](#dastscannerprofileid) | ID of the scanner profile to be updated. | -| <a id="mutationdastscannerprofileupdateprofilename"></a>`profileName` | [`String!`](#string) | The name of the scanner profile. | +| <a id="mutationdastscannerprofileupdateprofilename"></a>`profileName` | [`String!`](#string) | Name of the scanner profile. | | <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) | The maximum number of minutes allowed for the spider to traverse the site. | -| <a id="mutationdastscannerprofileupdatetargettimeout"></a>`targetTimeout` | [`Int!`](#int) | The maximum number of seconds allowed for the site under test to respond to a request. | +| <a id="mutationdastscannerprofileupdatespidertimeout"></a>`spiderTimeout` | [`Int!`](#int) | Maximum number of minutes allowed for the spider to traverse the site. | +| <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. | #### Fields @@ -1598,12 +1646,12 @@ Input type: `DastSiteProfileCreateInput` | ---- | ---- | ----------- | | <a id="mutationdastsiteprofilecreateauth"></a>`auth` | [`DastSiteProfileAuthInput`](#dastsiteprofileauthinput) | Parameters for authentication. | | <a id="mutationdastsiteprofilecreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationdastsiteprofilecreateexcludedurls"></a>`excludedUrls` | [`[String!]`](#string) | The URLs to skip during an authenticated scan. Defaults to `[]`. | -| <a id="mutationdastsiteprofilecreatefullpath"></a>`fullPath` | [`ID!`](#id) | The project the site profile belongs to. | -| <a id="mutationdastsiteprofilecreateprofilename"></a>`profileName` | [`String!`](#string) | The name of the site profile. | +| <a id="mutationdastsiteprofilecreateexcludedurls"></a>`excludedUrls` | [`[String!]`](#string) | URLs to skip during an authenticated scan. Defaults to `[]`. | +| <a id="mutationdastsiteprofilecreatefullpath"></a>`fullPath` | [`ID!`](#id) | Project the site profile belongs to. | +| <a id="mutationdastsiteprofilecreateprofilename"></a>`profileName` | [`String!`](#string) | Name of the site profile. | | <a id="mutationdastsiteprofilecreaterequestheaders"></a>`requestHeaders` | [`String`](#string) | Comma-separated list of request header names and values to be added to every request made by DAST. | -| <a id="mutationdastsiteprofilecreatetargettype"></a>`targetType` | [`DastTargetTypeEnum`](#dasttargettypeenum) | The type of target to be scanned. | -| <a id="mutationdastsiteprofilecreatetargeturl"></a>`targetUrl` | [`String`](#string) | The URL of the target to be scanned. | +| <a id="mutationdastsiteprofilecreatetargettype"></a>`targetType` | [`DastTargetTypeEnum`](#dasttargettypeenum) | Type of target to be scanned. | +| <a id="mutationdastsiteprofilecreatetargeturl"></a>`targetUrl` | [`String`](#string) | URL of the target to be scanned. | #### Fields @@ -1622,7 +1670,7 @@ Input type: `DastSiteProfileDeleteInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationdastsiteprofiledeleteclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationdastsiteprofiledeletefullpath"></a>`fullPath` | [`ID!`](#id) | The project the site profile belongs to. | +| <a id="mutationdastsiteprofiledeletefullpath"></a>`fullPath` | [`ID!`](#id) | Project the site profile belongs to. | | <a id="mutationdastsiteprofiledeleteid"></a>`id` | [`DastSiteProfileID!`](#dastsiteprofileid) | ID of the site profile to be deleted. | #### Fields @@ -1642,13 +1690,13 @@ Input type: `DastSiteProfileUpdateInput` | ---- | ---- | ----------- | | <a id="mutationdastsiteprofileupdateauth"></a>`auth` | [`DastSiteProfileAuthInput`](#dastsiteprofileauthinput) | Parameters for authentication. | | <a id="mutationdastsiteprofileupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationdastsiteprofileupdateexcludedurls"></a>`excludedUrls` | [`[String!]`](#string) | The URLs to skip during an authenticated scan. | -| <a id="mutationdastsiteprofileupdatefullpath"></a>`fullPath` | [`ID!`](#id) | The project the site profile belongs to. | +| <a id="mutationdastsiteprofileupdateexcludedurls"></a>`excludedUrls` | [`[String!]`](#string) | URLs to skip during an authenticated scan. | +| <a id="mutationdastsiteprofileupdatefullpath"></a>`fullPath` | [`ID!`](#id) | Project the site profile belongs to. | | <a id="mutationdastsiteprofileupdateid"></a>`id` | [`DastSiteProfileID!`](#dastsiteprofileid) | ID of the site profile to be updated. | -| <a id="mutationdastsiteprofileupdateprofilename"></a>`profileName` | [`String!`](#string) | The name of the site profile. | +| <a id="mutationdastsiteprofileupdateprofilename"></a>`profileName` | [`String!`](#string) | Name of the site profile. | | <a id="mutationdastsiteprofileupdaterequestheaders"></a>`requestHeaders` | [`String`](#string) | Comma-separated list of request header names and values to be added to every request made by DAST. | -| <a id="mutationdastsiteprofileupdatetargettype"></a>`targetType` | [`DastTargetTypeEnum`](#dasttargettypeenum) | The type of target to be scanned. | -| <a id="mutationdastsiteprofileupdatetargeturl"></a>`targetUrl` | [`String`](#string) | The URL of the target to be scanned. | +| <a id="mutationdastsiteprofileupdatetargettype"></a>`targetType` | [`DastTargetTypeEnum`](#dasttargettypeenum) | Type of target to be scanned. | +| <a id="mutationdastsiteprofileupdatetargeturl"></a>`targetUrl` | [`String`](#string) | URL of the target to be scanned. | #### Fields @@ -1667,8 +1715,8 @@ Input type: `DastSiteTokenCreateInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationdastsitetokencreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationdastsitetokencreatefullpath"></a>`fullPath` | [`ID!`](#id) | The project the site token belongs to. | -| <a id="mutationdastsitetokencreatetargeturl"></a>`targetUrl` | [`String`](#string) | The URL of the target to be validated. | +| <a id="mutationdastsitetokencreatefullpath"></a>`fullPath` | [`ID!`](#id) | Project the site token belongs to. | +| <a id="mutationdastsitetokencreatetargeturl"></a>`targetUrl` | [`String`](#string) | URL of the target to be validated. | #### Fields @@ -1677,7 +1725,7 @@ Input type: `DastSiteTokenCreateInput` | <a id="mutationdastsitetokencreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationdastsitetokencreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationdastsitetokencreateid"></a>`id` | [`DastSiteTokenID`](#dastsitetokenid) | ID of the site token. | -| <a id="mutationdastsitetokencreatestatus"></a>`status` | [`DastSiteProfileValidationStatusEnum`](#dastsiteprofilevalidationstatusenum) | The current validation status of the target. | +| <a id="mutationdastsitetokencreatestatus"></a>`status` | [`DastSiteProfileValidationStatusEnum`](#dastsiteprofilevalidationstatusenum) | Current validation status of the target. | | <a id="mutationdastsitetokencreatetoken"></a>`token` | [`String`](#string) | Token string. | ### `Mutation.dastSiteValidationCreate` @@ -1690,9 +1738,9 @@ Input type: `DastSiteValidationCreateInput` | ---- | ---- | ----------- | | <a id="mutationdastsitevalidationcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationdastsitevalidationcreatedastsitetokenid"></a>`dastSiteTokenId` | [`DastSiteTokenID!`](#dastsitetokenid) | ID of the site token. | -| <a id="mutationdastsitevalidationcreatefullpath"></a>`fullPath` | [`ID!`](#id) | The project the site profile belongs to. | -| <a id="mutationdastsitevalidationcreatestrategy"></a>`strategy` | [`DastSiteValidationStrategyEnum`](#dastsitevalidationstrategyenum) | The validation strategy to be used. | -| <a id="mutationdastsitevalidationcreatevalidationpath"></a>`validationPath` | [`String!`](#string) | The path to be requested during validation. | +| <a id="mutationdastsitevalidationcreatefullpath"></a>`fullPath` | [`ID!`](#id) | Project the site profile belongs to. | +| <a id="mutationdastsitevalidationcreatestrategy"></a>`strategy` | [`DastSiteValidationStrategyEnum`](#dastsitevalidationstrategyenum) | Validation strategy to be used. | +| <a id="mutationdastsitevalidationcreatevalidationpath"></a>`validationPath` | [`String!`](#string) | Path to be requested during validation. | #### Fields @@ -1701,7 +1749,7 @@ Input type: `DastSiteValidationCreateInput` | <a id="mutationdastsitevalidationcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationdastsitevalidationcreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationdastsitevalidationcreateid"></a>`id` | [`DastSiteValidationID`](#dastsitevalidationid) | ID of the site validation. | -| <a id="mutationdastsitevalidationcreatestatus"></a>`status` | [`DastSiteProfileValidationStatusEnum`](#dastsiteprofilevalidationstatusenum) | The current validation status. | +| <a id="mutationdastsitevalidationcreatestatus"></a>`status` | [`DastSiteProfileValidationStatusEnum`](#dastsiteprofilevalidationstatusenum) | Current validation status. | ### `Mutation.dastSiteValidationRevoke` @@ -1712,7 +1760,7 @@ Input type: `DastSiteValidationRevokeInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationdastsitevalidationrevokeclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationdastsitevalidationrevokefullpath"></a>`fullPath` | [`ID!`](#id) | The project the site validation belongs to. | +| <a id="mutationdastsitevalidationrevokefullpath"></a>`fullPath` | [`ID!`](#id) | Project the site validation belongs to. | | <a id="mutationdastsitevalidationrevokenormalizedtargeturl"></a>`normalizedTargetUrl` | [`String!`](#string) | Normalized URL of the target to be revoked. | #### Fields @@ -1851,7 +1899,7 @@ Input type: `DestroyComplianceFrameworkInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationdestroycomplianceframeworkclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationdestroycomplianceframeworkid"></a>`id` | [`ComplianceManagementFrameworkID!`](#compliancemanagementframeworkid) | The global ID of the compliance framework to destroy. | +| <a id="mutationdestroycomplianceframeworkid"></a>`id` | [`ComplianceManagementFrameworkID!`](#compliancemanagementframeworkid) | Global ID of the compliance framework to destroy. | #### Fields @@ -1899,6 +1947,27 @@ Input type: `DestroyContainerRepositoryTagsInput` | <a id="mutationdestroycontainerrepositorytagsdeletedtagnames"></a>`deletedTagNames` | [`[String!]!`](#string) | Deleted container repository tags. | | <a id="mutationdestroycontainerrepositorytagserrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +### `Mutation.destroyCustomEmoji` + +Available only when feature flag `custom_emoji` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. + +Input type: `DestroyCustomEmojiInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationdestroycustomemojiclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationdestroycustomemojiid"></a>`id` | [`CustomEmojiID!`](#customemojiid) | Global ID of the custom emoji to destroy. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationdestroycustomemojiclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationdestroycustomemojicustomemoji"></a>`customEmoji` | [`CustomEmoji`](#customemoji) | Deleted custom emoji. | +| <a id="mutationdestroycustomemojierrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + ### `Mutation.destroyEpicBoard` Input type: `DestroyEpicBoardInput` @@ -2109,18 +2178,18 @@ Input type: `EpicAddIssueInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationepicaddissueclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationepicaddissuegrouppath"></a>`groupPath` | [`ID!`](#id) | The group the epic to mutate belongs to. | -| <a id="mutationepicaddissueiid"></a>`iid` | [`ID!`](#id) | The IID of the epic to mutate. | -| <a id="mutationepicaddissueissueiid"></a>`issueIid` | [`String!`](#string) | The IID of the issue to be added. | -| <a id="mutationepicaddissueprojectpath"></a>`projectPath` | [`ID!`](#id) | The full path of the project the issue belongs to. | +| <a id="mutationepicaddissuegrouppath"></a>`groupPath` | [`ID!`](#id) | Group the epic to mutate belongs to. | +| <a id="mutationepicaddissueiid"></a>`iid` | [`ID!`](#id) | IID of the epic to mutate. | +| <a id="mutationepicaddissueissueiid"></a>`issueIid` | [`String!`](#string) | IID of the issue to be added. | +| <a id="mutationepicaddissueprojectpath"></a>`projectPath` | [`ID!`](#id) | Full path of the project the issue belongs to. | #### Fields | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationepicaddissueclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationepicaddissueepic"></a>`epic` | [`Epic`](#epic) | The epic after mutation. | -| <a id="mutationepicaddissueepicissue"></a>`epicIssue` | [`EpicIssue`](#epicissue) | The epic-issue relation. | +| <a id="mutationepicaddissueepic"></a>`epic` | [`Epic`](#epic) | Epic after mutation. | +| <a id="mutationepicaddissueepicissue"></a>`epicIssue` | [`EpicIssue`](#epicissue) | Epic-issue relationship. | | <a id="mutationepicaddissueerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | ### `Mutation.epicBoardCreate` @@ -2144,7 +2213,7 @@ Input type: `EpicBoardCreateInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationepicboardcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationepicboardcreateepicboard"></a>`epicBoard` | [`EpicBoard`](#epicboard) | The created epic board. | +| <a id="mutationepicboardcreateepicboard"></a>`epicBoard` | [`EpicBoard`](#epicboard) | Created epic board. | | <a id="mutationepicboardcreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | ### `Mutation.epicBoardListCreate` @@ -2187,7 +2256,7 @@ Input type: `EpicBoardListDestroyInput` | ---- | ---- | ----------- | | <a id="mutationepicboardlistdestroyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationepicboardlistdestroyerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationepicboardlistdestroylist"></a>`list` | [`EpicList`](#epiclist) | The epic board list. `null` if the board was destroyed successfully. | +| <a id="mutationepicboardlistdestroylist"></a>`list` | [`EpicList`](#epiclist) | Epic board list. `null` if the board was destroyed successfully. | ### `Mutation.epicBoardUpdate` @@ -2200,7 +2269,7 @@ Input type: `EpicBoardUpdateInput` | <a id="mutationepicboardupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationepicboardupdatehidebackloglist"></a>`hideBacklogList` | [`Boolean`](#boolean) | Whether or not backlog list is hidden. | | <a id="mutationepicboardupdatehideclosedlist"></a>`hideClosedList` | [`Boolean`](#boolean) | Whether or not closed list is hidden. | -| <a id="mutationepicboardupdateid"></a>`id` | [`BoardsEpicBoardID!`](#boardsepicboardid) | The epic board global ID. | +| <a id="mutationepicboardupdateid"></a>`id` | [`BoardsEpicBoardID!`](#boardsepicboardid) | Epic board global ID. | | <a id="mutationepicboardupdatelabelids"></a>`labelIds` | [`[LabelID!]`](#labelid) | IDs of labels to be added to the board. | | <a id="mutationepicboardupdatelabels"></a>`labels` | [`[String!]`](#string) | Labels of the issue. | | <a id="mutationepicboardupdatename"></a>`name` | [`String`](#string) | Board name. | @@ -2210,7 +2279,7 @@ Input type: `EpicBoardUpdateInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationepicboardupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationepicboardupdateepicboard"></a>`epicBoard` | [`EpicBoard`](#epicboard) | The updated epic board. | +| <a id="mutationepicboardupdateepicboard"></a>`epicBoard` | [`EpicBoard`](#epicboard) | Updated epic board. | | <a id="mutationepicboardupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | ### `Mutation.epicMoveList` @@ -2234,7 +2303,7 @@ Input type: `EpicMoveListInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationepicmovelistclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationepicmovelistepic"></a>`epic` | [`Epic`](#epic) | The epic after mutation. | +| <a id="mutationepicmovelistepic"></a>`epic` | [`Epic`](#epic) | Epic after mutation. | | <a id="mutationepicmovelisterrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | ### `Mutation.epicSetSubscription` @@ -2246,16 +2315,16 @@ Input type: `EpicSetSubscriptionInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationepicsetsubscriptionclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationepicsetsubscriptiongrouppath"></a>`groupPath` | [`ID!`](#id) | The group the epic to mutate belongs to. | -| <a id="mutationepicsetsubscriptioniid"></a>`iid` | [`ID!`](#id) | The IID of the epic to mutate. | -| <a id="mutationepicsetsubscriptionsubscribedstate"></a>`subscribedState` | [`Boolean!`](#boolean) | The desired state of the subscription. | +| <a id="mutationepicsetsubscriptiongrouppath"></a>`groupPath` | [`ID!`](#id) | Group the epic to mutate belongs to. | +| <a id="mutationepicsetsubscriptioniid"></a>`iid` | [`ID!`](#id) | IID of the epic to mutate. | +| <a id="mutationepicsetsubscriptionsubscribedstate"></a>`subscribedState` | [`Boolean!`](#boolean) | Desired state of the subscription. | #### Fields | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationepicsetsubscriptionclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationepicsetsubscriptionepic"></a>`epic` | [`Epic`](#epic) | The epic after mutation. | +| <a id="mutationepicsetsubscriptionepic"></a>`epic` | [`Epic`](#epic) | Epic after mutation. | | <a id="mutationepicsetsubscriptionerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | ### `Mutation.epicTreeReorder` @@ -2266,7 +2335,7 @@ Input type: `EpicTreeReorderInput` | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="mutationepictreereorderbaseepicid"></a>`baseEpicId` | [`EpicID!`](#epicid) | The ID of the base epic of the tree. | +| <a id="mutationepictreereorderbaseepicid"></a>`baseEpicId` | [`EpicID!`](#epicid) | ID of the base epic of the tree. | | <a id="mutationepictreereorderclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationepictreereordermoved"></a>`moved` | [`EpicTreeNodeFieldsInputType!`](#epictreenodefieldsinputtype) | Parameters for updating the tree positions. | @@ -2286,10 +2355,10 @@ Input type: `EscalationPolicyCreateInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationescalationpolicycreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationescalationpolicycreatedescription"></a>`description` | [`String`](#string) | The description of the escalation policy. | -| <a id="mutationescalationpolicycreatename"></a>`name` | [`String!`](#string) | The name of the escalation policy. | -| <a id="mutationescalationpolicycreateprojectpath"></a>`projectPath` | [`ID!`](#id) | The project to create the escalation policy for. | -| <a id="mutationescalationpolicycreaterules"></a>`rules` | [`[EscalationRuleInput!]!`](#escalationruleinput) | The steps of the escalation policy. | +| <a id="mutationescalationpolicycreatedescription"></a>`description` | [`String`](#string) | Description of the escalation policy. | +| <a id="mutationescalationpolicycreatename"></a>`name` | [`String!`](#string) | Name of the escalation policy. | +| <a id="mutationescalationpolicycreateprojectpath"></a>`projectPath` | [`ID!`](#id) | Project to create the escalation policy for. | +| <a id="mutationescalationpolicycreaterules"></a>`rules` | [`[EscalationRuleInput!]!`](#escalationruleinput) | Steps of the escalation policy. | #### Fields @@ -2297,7 +2366,7 @@ Input type: `EscalationPolicyCreateInput` | ---- | ---- | ----------- | | <a id="mutationescalationpolicycreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationescalationpolicycreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationescalationpolicycreateescalationpolicy"></a>`escalationPolicy` | [`EscalationPolicyType`](#escalationpolicytype) | The escalation policy. | +| <a id="mutationescalationpolicycreateescalationpolicy"></a>`escalationPolicy` | [`EscalationPolicyType`](#escalationpolicytype) | Escalation policy. | ### `Mutation.escalationPolicyDestroy` @@ -2308,7 +2377,7 @@ Input type: `EscalationPolicyDestroyInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationescalationpolicydestroyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationescalationpolicydestroyid"></a>`id` | [`IncidentManagementEscalationPolicyID!`](#incidentmanagementescalationpolicyid) | The escalation policy internal ID to remove. | +| <a id="mutationescalationpolicydestroyid"></a>`id` | [`IncidentManagementEscalationPolicyID!`](#incidentmanagementescalationpolicyid) | Escalation policy internal ID to remove. | #### Fields @@ -2316,7 +2385,7 @@ Input type: `EscalationPolicyDestroyInput` | ---- | ---- | ----------- | | <a id="mutationescalationpolicydestroyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationescalationpolicydestroyerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationescalationpolicydestroyescalationpolicy"></a>`escalationPolicy` | [`EscalationPolicyType`](#escalationpolicytype) | The escalation policy. | +| <a id="mutationescalationpolicydestroyescalationpolicy"></a>`escalationPolicy` | [`EscalationPolicyType`](#escalationpolicytype) | Escalation policy. | ### `Mutation.escalationPolicyUpdate` @@ -2327,10 +2396,10 @@ Input type: `EscalationPolicyUpdateInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationescalationpolicyupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationescalationpolicyupdatedescription"></a>`description` | [`String`](#string) | The description of the escalation policy. | -| <a id="mutationescalationpolicyupdateid"></a>`id` | [`IncidentManagementEscalationPolicyID!`](#incidentmanagementescalationpolicyid) | The ID of the on-call schedule to create the on-call rotation in. | -| <a id="mutationescalationpolicyupdatename"></a>`name` | [`String`](#string) | The name of the escalation policy. | -| <a id="mutationescalationpolicyupdaterules"></a>`rules` | [`[EscalationRuleInput!]`](#escalationruleinput) | The steps of the escalation policy. | +| <a id="mutationescalationpolicyupdatedescription"></a>`description` | [`String`](#string) | Description of the escalation policy. | +| <a id="mutationescalationpolicyupdateid"></a>`id` | [`IncidentManagementEscalationPolicyID!`](#incidentmanagementescalationpolicyid) | ID of the on-call schedule to create the on-call rotation in. | +| <a id="mutationescalationpolicyupdatename"></a>`name` | [`String`](#string) | Name of the escalation policy. | +| <a id="mutationescalationpolicyupdaterules"></a>`rules` | [`[EscalationRuleInput!]`](#escalationruleinput) | Steps of the escalation policy. | #### Fields @@ -2338,7 +2407,7 @@ Input type: `EscalationPolicyUpdateInput` | ---- | ---- | ----------- | | <a id="mutationescalationpolicyupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationescalationpolicyupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationescalationpolicyupdateescalationpolicy"></a>`escalationPolicy` | [`EscalationPolicyType`](#escalationpolicytype) | The escalation policy. | +| <a id="mutationescalationpolicyupdateescalationpolicy"></a>`escalationPolicy` | [`EscalationPolicyType`](#escalationpolicytype) | Escalation policy. | ### `Mutation.exportRequirements` @@ -2380,7 +2449,7 @@ Input type: `GitlabSubscriptionActivateInput` | ---- | ---- | ----------- | | <a id="mutationgitlabsubscriptionactivateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationgitlabsubscriptionactivateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationgitlabsubscriptionactivatelicense"></a>`license` | [`CurrentLicense`](#currentlicense) | The current license. | +| <a id="mutationgitlabsubscriptionactivatelicense"></a>`license` | [`CurrentLicense`](#currentlicense) | Current license. | ### `Mutation.groupUpdate` @@ -2413,8 +2482,8 @@ Input type: `HttpIntegrationCreateInput` | <a id="mutationhttpintegrationcreateactive"></a>`active` | [`Boolean!`](#boolean) | Whether the integration is receiving alerts. | | <a id="mutationhttpintegrationcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationhttpintegrationcreatename"></a>`name` | [`String!`](#string) | Name of the integration. | -| <a id="mutationhttpintegrationcreatepayloadattributemappings"></a>`payloadAttributeMappings` | [`[AlertManagementPayloadAlertFieldInput!]`](#alertmanagementpayloadalertfieldinput) | The custom mapping of GitLab alert attributes to fields from the payload_example. | -| <a id="mutationhttpintegrationcreatepayloadexample"></a>`payloadExample` | [`JsonString`](#jsonstring) | The example of an alert payload. | +| <a id="mutationhttpintegrationcreatepayloadattributemappings"></a>`payloadAttributeMappings` | [`[AlertManagementPayloadAlertFieldInput!]`](#alertmanagementpayloadalertfieldinput) | Custom mapping of GitLab alert attributes to fields from the payload example. | +| <a id="mutationhttpintegrationcreatepayloadexample"></a>`payloadExample` | [`JsonString`](#jsonstring) | Example of an alert payload. | | <a id="mutationhttpintegrationcreateprojectpath"></a>`projectPath` | [`ID!`](#id) | Project to create the integration in. | #### Fields @@ -2475,8 +2544,8 @@ Input type: `HttpIntegrationUpdateInput` | <a id="mutationhttpintegrationupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationhttpintegrationupdateid"></a>`id` | [`AlertManagementHttpIntegrationID!`](#alertmanagementhttpintegrationid) | ID of the integration to mutate. | | <a id="mutationhttpintegrationupdatename"></a>`name` | [`String`](#string) | Name of the integration. | -| <a id="mutationhttpintegrationupdatepayloadattributemappings"></a>`payloadAttributeMappings` | [`[AlertManagementPayloadAlertFieldInput!]`](#alertmanagementpayloadalertfieldinput) | The custom mapping of GitLab alert attributes to fields from the payload_example. | -| <a id="mutationhttpintegrationupdatepayloadexample"></a>`payloadExample` | [`JsonString`](#jsonstring) | The example of an alert payload. | +| <a id="mutationhttpintegrationupdatepayloadattributemappings"></a>`payloadAttributeMappings` | [`[AlertManagementPayloadAlertFieldInput!]`](#alertmanagementpayloadalertfieldinput) | Custom mapping of GitLab alert attributes to fields from the payload example. | +| <a id="mutationhttpintegrationupdatepayloadexample"></a>`payloadExample` | [`JsonString`](#jsonstring) | Example of an alert payload. | #### Fields @@ -2628,7 +2697,7 @@ Input type: `IssueSetIterationInput` | ---- | ---- | ----------- | | <a id="mutationissuesetiterationclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationissuesetiterationiid"></a>`iid` | [`String!`](#string) | IID of the issue to mutate. | -| <a id="mutationissuesetiterationiterationid"></a>`iterationId` | [`IterationID`](#iterationid) | The iteration to assign to the issue. | +| <a id="mutationissuesetiterationiterationid"></a>`iterationId` | [`IterationID`](#iterationid) | Iteration to assign to the issue. | | <a id="mutationissuesetiterationprojectpath"></a>`projectPath` | [`ID!`](#id) | Project the issue to mutate is in. | #### Fields @@ -2736,7 +2805,7 @@ Input type: `IterationCadenceCreateInput` | <a id="mutationiterationcadencecreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationiterationcadencecreatedescription"></a>`description` | [`String`](#string) | Description of the iteration cadence. Maximum length is 5000 characters. | | <a id="mutationiterationcadencecreatedurationinweeks"></a>`durationInWeeks` | [`Int`](#int) | Duration in weeks of the iterations within this cadence. | -| <a id="mutationiterationcadencecreategrouppath"></a>`groupPath` | [`ID!`](#id) | The group where the iteration cadence is created. | +| <a id="mutationiterationcadencecreategrouppath"></a>`groupPath` | [`ID!`](#id) | Group where the iteration cadence is created. | | <a id="mutationiterationcadencecreateiterationsinadvance"></a>`iterationsInAdvance` | [`Int`](#int) | Future iterations to be created when iteration cadence is set to automatic. | | <a id="mutationiterationcadencecreaterollover"></a>`rollOver` | [`Boolean`](#boolean) | Whether the iteration cadence should roll over issues to the next iteration or not. | | <a id="mutationiterationcadencecreatestartdate"></a>`startDate` | [`Time`](#time) | Timestamp of the iteration cadence start date. | @@ -2748,7 +2817,7 @@ Input type: `IterationCadenceCreateInput` | ---- | ---- | ----------- | | <a id="mutationiterationcadencecreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationiterationcadencecreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationiterationcadencecreateiterationcadence"></a>`iterationCadence` | [`IterationCadence`](#iterationcadence) | The created iteration cadence. | +| <a id="mutationiterationcadencecreateiterationcadence"></a>`iterationCadence` | [`IterationCadence`](#iterationcadence) | Created iteration cadence. | ### `Mutation.iterationCadenceDestroy` @@ -2794,7 +2863,7 @@ Input type: `IterationCadenceUpdateInput` | ---- | ---- | ----------- | | <a id="mutationiterationcadenceupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationiterationcadenceupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationiterationcadenceupdateiterationcadence"></a>`iterationCadence` | [`IterationCadence`](#iterationcadence) | The updated iteration cadence. | +| <a id="mutationiterationcadenceupdateiterationcadence"></a>`iterationCadence` | [`IterationCadence`](#iterationcadence) | Updated iteration cadence. | ### `Mutation.iterationCreate` @@ -2805,13 +2874,13 @@ Input type: `iterationCreateInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationiterationcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationiterationcreatedescription"></a>`description` | [`String`](#string) | The description of the iteration. | -| <a id="mutationiterationcreateduedate"></a>`dueDate` | [`String`](#string) | The end date of the iteration. | +| <a id="mutationiterationcreatedescription"></a>`description` | [`String`](#string) | Description of the iteration. | +| <a id="mutationiterationcreateduedate"></a>`dueDate` | [`String`](#string) | End date of the iteration. | | <a id="mutationiterationcreategrouppath"></a>`groupPath` | [`ID`](#id) | Full path of the group with which the resource is associated. | | <a id="mutationiterationcreateiterationscadenceid"></a>`iterationsCadenceId` | [`IterationsCadenceID`](#iterationscadenceid) | Global ID of the iterations cadence to be assigned to newly created iteration. | | <a id="mutationiterationcreateprojectpath"></a>`projectPath` | [`ID`](#id) | Full path of the project with which the resource is associated. | -| <a id="mutationiterationcreatestartdate"></a>`startDate` | [`String`](#string) | The start date of the iteration. | -| <a id="mutationiterationcreatetitle"></a>`title` | [`String`](#string) | The title of the iteration. | +| <a id="mutationiterationcreatestartdate"></a>`startDate` | [`String`](#string) | Start date of the iteration. | +| <a id="mutationiterationcreatetitle"></a>`title` | [`String`](#string) | Title of the iteration. | #### Fields @@ -2819,7 +2888,7 @@ Input type: `iterationCreateInput` | ---- | ---- | ----------- | | <a id="mutationiterationcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationiterationcreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationiterationcreateiteration"></a>`iteration` | [`Iteration`](#iteration) | The created iteration. | +| <a id="mutationiterationcreateiteration"></a>`iteration` | [`Iteration`](#iteration) | Created iteration. | ### `Mutation.iterationDelete` @@ -3263,7 +3332,7 @@ Input type: `NamespaceIncreaseStorageTemporarilyInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationnamespaceincreasestoragetemporarilyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationnamespaceincreasestoragetemporarilyid"></a>`id` | [`NamespaceID!`](#namespaceid) | The global ID of the namespace to mutate. | +| <a id="mutationnamespaceincreasestoragetemporarilyid"></a>`id` | [`NamespaceID!`](#namespaceid) | Global ID of the namespace to mutate. | #### Fields @@ -3271,7 +3340,7 @@ Input type: `NamespaceIncreaseStorageTemporarilyInput` | ---- | ---- | ----------- | | <a id="mutationnamespaceincreasestoragetemporarilyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationnamespaceincreasestoragetemporarilyerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationnamespaceincreasestoragetemporarilynamespace"></a>`namespace` | [`Namespace`](#namespace) | The namespace after mutation. | +| <a id="mutationnamespaceincreasestoragetemporarilynamespace"></a>`namespace` | [`Namespace`](#namespace) | Namespace after mutation. | ### `Mutation.oncallRotationCreate` @@ -3281,15 +3350,15 @@ Input type: `OncallRotationCreateInput` | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="mutationoncallrotationcreateactiveperiod"></a>`activePeriod` | [`OncallRotationActivePeriodInputType`](#oncallrotationactiveperiodinputtype) | The active period of time that the on-call rotation should take place. | +| <a id="mutationoncallrotationcreateactiveperiod"></a>`activePeriod` | [`OncallRotationActivePeriodInputType`](#oncallrotationactiveperiodinputtype) | Active period of time that the on-call rotation should take place. | | <a id="mutationoncallrotationcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationoncallrotationcreateendsat"></a>`endsAt` | [`OncallRotationDateInputType`](#oncallrotationdateinputtype) | The end date and time of the on-call rotation, in the timezone of the on-call schedule. | -| <a id="mutationoncallrotationcreatename"></a>`name` | [`String!`](#string) | The name of the on-call rotation. | -| <a id="mutationoncallrotationcreateparticipants"></a>`participants` | [`[OncallUserInputType!]!`](#oncalluserinputtype) | The usernames of users participating in the on-call rotation. A maximum limit of 100 participants applies. | -| <a id="mutationoncallrotationcreateprojectpath"></a>`projectPath` | [`ID!`](#id) | The project to create the on-call schedule in. | -| <a id="mutationoncallrotationcreaterotationlength"></a>`rotationLength` | [`OncallRotationLengthInputType!`](#oncallrotationlengthinputtype) | The rotation length of the on-call rotation. | -| <a id="mutationoncallrotationcreatescheduleiid"></a>`scheduleIid` | [`String!`](#string) | The IID of the on-call schedule to create the on-call rotation in. | -| <a id="mutationoncallrotationcreatestartsat"></a>`startsAt` | [`OncallRotationDateInputType!`](#oncallrotationdateinputtype) | The start date and time of the on-call rotation, in the timezone of the on-call schedule. | +| <a id="mutationoncallrotationcreateendsat"></a>`endsAt` | [`OncallRotationDateInputType`](#oncallrotationdateinputtype) | End date and time of the on-call rotation, in the timezone of the on-call schedule. | +| <a id="mutationoncallrotationcreatename"></a>`name` | [`String!`](#string) | Name of the on-call rotation. | +| <a id="mutationoncallrotationcreateparticipants"></a>`participants` | [`[OncallUserInputType!]!`](#oncalluserinputtype) | Usernames of users participating in the on-call rotation. A maximum limit of 100 participants applies. | +| <a id="mutationoncallrotationcreateprojectpath"></a>`projectPath` | [`ID!`](#id) | Project to create the on-call schedule in. | +| <a id="mutationoncallrotationcreaterotationlength"></a>`rotationLength` | [`OncallRotationLengthInputType!`](#oncallrotationlengthinputtype) | Rotation length of the on-call rotation. | +| <a id="mutationoncallrotationcreatescheduleiid"></a>`scheduleIid` | [`String!`](#string) | IID of the on-call schedule to create the on-call rotation in. | +| <a id="mutationoncallrotationcreatestartsat"></a>`startsAt` | [`OncallRotationDateInputType!`](#oncallrotationdateinputtype) | Start date and time of the on-call rotation, in the timezone of the on-call schedule. | #### Fields @@ -3297,7 +3366,7 @@ Input type: `OncallRotationCreateInput` | ---- | ---- | ----------- | | <a id="mutationoncallrotationcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationoncallrotationcreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationoncallrotationcreateoncallrotation"></a>`oncallRotation` | [`IncidentManagementOncallRotation`](#incidentmanagementoncallrotation) | The on-call rotation. | +| <a id="mutationoncallrotationcreateoncallrotation"></a>`oncallRotation` | [`IncidentManagementOncallRotation`](#incidentmanagementoncallrotation) | On-call rotation. | ### `Mutation.oncallRotationDestroy` @@ -3308,9 +3377,9 @@ Input type: `OncallRotationDestroyInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationoncallrotationdestroyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationoncallrotationdestroyid"></a>`id` | [`IncidentManagementOncallRotationID!`](#incidentmanagementoncallrotationid) | The ID of the on-call rotation to remove. | -| <a id="mutationoncallrotationdestroyprojectpath"></a>`projectPath` | [`ID!`](#id) | The project to remove the on-call schedule from. | -| <a id="mutationoncallrotationdestroyscheduleiid"></a>`scheduleIid` | [`String!`](#string) | The IID of the on-call schedule to the on-call rotation belongs to. | +| <a id="mutationoncallrotationdestroyid"></a>`id` | [`IncidentManagementOncallRotationID!`](#incidentmanagementoncallrotationid) | ID of the on-call rotation to remove. | +| <a id="mutationoncallrotationdestroyprojectpath"></a>`projectPath` | [`ID!`](#id) | Project to remove the on-call schedule from. | +| <a id="mutationoncallrotationdestroyscheduleiid"></a>`scheduleIid` | [`String!`](#string) | IID of the on-call schedule to the on-call rotation belongs to. | #### Fields @@ -3318,7 +3387,7 @@ Input type: `OncallRotationDestroyInput` | ---- | ---- | ----------- | | <a id="mutationoncallrotationdestroyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationoncallrotationdestroyerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationoncallrotationdestroyoncallrotation"></a>`oncallRotation` | [`IncidentManagementOncallRotation`](#incidentmanagementoncallrotation) | The on-call rotation. | +| <a id="mutationoncallrotationdestroyoncallrotation"></a>`oncallRotation` | [`IncidentManagementOncallRotation`](#incidentmanagementoncallrotation) | On-call rotation. | ### `Mutation.oncallRotationUpdate` @@ -3328,14 +3397,14 @@ Input type: `OncallRotationUpdateInput` | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="mutationoncallrotationupdateactiveperiod"></a>`activePeriod` | [`OncallRotationActivePeriodInputType`](#oncallrotationactiveperiodinputtype) | The active period of time that the on-call rotation should take place. | +| <a id="mutationoncallrotationupdateactiveperiod"></a>`activePeriod` | [`OncallRotationActivePeriodInputType`](#oncallrotationactiveperiodinputtype) | Active period of time that the on-call rotation should take place. | | <a id="mutationoncallrotationupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationoncallrotationupdateendsat"></a>`endsAt` | [`OncallRotationDateInputType`](#oncallrotationdateinputtype) | The end date and time of the on-call rotation, in the timezone of the on-call schedule. | -| <a id="mutationoncallrotationupdateid"></a>`id` | [`IncidentManagementOncallRotationID!`](#incidentmanagementoncallrotationid) | The ID of the on-call schedule to create the on-call rotation in. | -| <a id="mutationoncallrotationupdatename"></a>`name` | [`String`](#string) | The name of the on-call rotation. | -| <a id="mutationoncallrotationupdateparticipants"></a>`participants` | [`[OncallUserInputType!]`](#oncalluserinputtype) | The usernames of users participating in the on-call rotation. A maximum limit of 100 participants applies. | -| <a id="mutationoncallrotationupdaterotationlength"></a>`rotationLength` | [`OncallRotationLengthInputType`](#oncallrotationlengthinputtype) | The rotation length of the on-call rotation. | -| <a id="mutationoncallrotationupdatestartsat"></a>`startsAt` | [`OncallRotationDateInputType`](#oncallrotationdateinputtype) | The start date and time of the on-call rotation, in the timezone of the on-call schedule. | +| <a id="mutationoncallrotationupdateendsat"></a>`endsAt` | [`OncallRotationDateInputType`](#oncallrotationdateinputtype) | End date and time of the on-call rotation, in the timezone of the on-call schedule. | +| <a id="mutationoncallrotationupdateid"></a>`id` | [`IncidentManagementOncallRotationID!`](#incidentmanagementoncallrotationid) | ID of the on-call schedule to create the on-call rotation in. | +| <a id="mutationoncallrotationupdatename"></a>`name` | [`String`](#string) | Name of the on-call rotation. | +| <a id="mutationoncallrotationupdateparticipants"></a>`participants` | [`[OncallUserInputType!]`](#oncalluserinputtype) | Usernames of users participating in the on-call rotation. A maximum limit of 100 participants applies. | +| <a id="mutationoncallrotationupdaterotationlength"></a>`rotationLength` | [`OncallRotationLengthInputType`](#oncallrotationlengthinputtype) | Rotation length of the on-call rotation. | +| <a id="mutationoncallrotationupdatestartsat"></a>`startsAt` | [`OncallRotationDateInputType`](#oncallrotationdateinputtype) | Start date and time of the on-call rotation, in the timezone of the on-call schedule. | #### Fields @@ -3343,7 +3412,7 @@ Input type: `OncallRotationUpdateInput` | ---- | ---- | ----------- | | <a id="mutationoncallrotationupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationoncallrotationupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationoncallrotationupdateoncallrotation"></a>`oncallRotation` | [`IncidentManagementOncallRotation`](#incidentmanagementoncallrotation) | The on-call rotation. | +| <a id="mutationoncallrotationupdateoncallrotation"></a>`oncallRotation` | [`IncidentManagementOncallRotation`](#incidentmanagementoncallrotation) | On-call rotation. | ### `Mutation.oncallScheduleCreate` @@ -3354,10 +3423,10 @@ Input type: `OncallScheduleCreateInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationoncallschedulecreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationoncallschedulecreatedescription"></a>`description` | [`String`](#string) | The description of the on-call schedule. | -| <a id="mutationoncallschedulecreatename"></a>`name` | [`String!`](#string) | The name of the on-call schedule. | -| <a id="mutationoncallschedulecreateprojectpath"></a>`projectPath` | [`ID!`](#id) | The project to create the on-call schedule in. | -| <a id="mutationoncallschedulecreatetimezone"></a>`timezone` | [`String!`](#string) | The timezone of the on-call schedule. | +| <a id="mutationoncallschedulecreatedescription"></a>`description` | [`String`](#string) | Description of the on-call schedule. | +| <a id="mutationoncallschedulecreatename"></a>`name` | [`String!`](#string) | Name of the on-call schedule. | +| <a id="mutationoncallschedulecreateprojectpath"></a>`projectPath` | [`ID!`](#id) | Project to create the on-call schedule in. | +| <a id="mutationoncallschedulecreatetimezone"></a>`timezone` | [`String!`](#string) | Timezone of the on-call schedule. | #### Fields @@ -3365,7 +3434,7 @@ Input type: `OncallScheduleCreateInput` | ---- | ---- | ----------- | | <a id="mutationoncallschedulecreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationoncallschedulecreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationoncallschedulecreateoncallschedule"></a>`oncallSchedule` | [`IncidentManagementOncallSchedule`](#incidentmanagementoncallschedule) | The on-call schedule. | +| <a id="mutationoncallschedulecreateoncallschedule"></a>`oncallSchedule` | [`IncidentManagementOncallSchedule`](#incidentmanagementoncallschedule) | On-call schedule. | ### `Mutation.oncallScheduleDestroy` @@ -3376,8 +3445,8 @@ Input type: `OncallScheduleDestroyInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationoncallscheduledestroyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationoncallscheduledestroyiid"></a>`iid` | [`String!`](#string) | The on-call schedule internal ID to remove. | -| <a id="mutationoncallscheduledestroyprojectpath"></a>`projectPath` | [`ID!`](#id) | The project to remove the on-call schedule from. | +| <a id="mutationoncallscheduledestroyiid"></a>`iid` | [`String!`](#string) | On-call schedule internal ID to remove. | +| <a id="mutationoncallscheduledestroyprojectpath"></a>`projectPath` | [`ID!`](#id) | Project to remove the on-call schedule from. | #### Fields @@ -3385,7 +3454,7 @@ Input type: `OncallScheduleDestroyInput` | ---- | ---- | ----------- | | <a id="mutationoncallscheduledestroyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationoncallscheduledestroyerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationoncallscheduledestroyoncallschedule"></a>`oncallSchedule` | [`IncidentManagementOncallSchedule`](#incidentmanagementoncallschedule) | The on-call schedule. | +| <a id="mutationoncallscheduledestroyoncallschedule"></a>`oncallSchedule` | [`IncidentManagementOncallSchedule`](#incidentmanagementoncallschedule) | On-call schedule. | ### `Mutation.oncallScheduleUpdate` @@ -3396,11 +3465,11 @@ Input type: `OncallScheduleUpdateInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationoncallscheduleupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationoncallscheduleupdatedescription"></a>`description` | [`String`](#string) | The description of the on-call schedule. | -| <a id="mutationoncallscheduleupdateiid"></a>`iid` | [`String!`](#string) | The on-call schedule internal ID to update. | -| <a id="mutationoncallscheduleupdatename"></a>`name` | [`String`](#string) | The name of the on-call schedule. | -| <a id="mutationoncallscheduleupdateprojectpath"></a>`projectPath` | [`ID!`](#id) | The project to update the on-call schedule in. | -| <a id="mutationoncallscheduleupdatetimezone"></a>`timezone` | [`String`](#string) | The timezone of the on-call schedule. | +| <a id="mutationoncallscheduleupdatedescription"></a>`description` | [`String`](#string) | Description of the on-call schedule. | +| <a id="mutationoncallscheduleupdateiid"></a>`iid` | [`String!`](#string) | On-call schedule internal ID to update. | +| <a id="mutationoncallscheduleupdatename"></a>`name` | [`String`](#string) | Name of the on-call schedule. | +| <a id="mutationoncallscheduleupdateprojectpath"></a>`projectPath` | [`ID!`](#id) | Project to update the on-call schedule in. | +| <a id="mutationoncallscheduleupdatetimezone"></a>`timezone` | [`String`](#string) | Timezone of the on-call schedule. | #### Fields @@ -3408,7 +3477,7 @@ Input type: `OncallScheduleUpdateInput` | ---- | ---- | ----------- | | <a id="mutationoncallscheduleupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationoncallscheduleupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationoncallscheduleupdateoncallschedule"></a>`oncallSchedule` | [`IncidentManagementOncallSchedule`](#incidentmanagementoncallschedule) | The on-call schedule. | +| <a id="mutationoncallscheduleupdateoncallschedule"></a>`oncallSchedule` | [`IncidentManagementOncallSchedule`](#incidentmanagementoncallschedule) | On-call schedule. | ### `Mutation.pipelineCancel` @@ -3578,7 +3647,7 @@ Input type: `PromoteToEpicInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationpromotetoepicclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationpromotetoepicgrouppath"></a>`groupPath` | [`ID`](#id) | The group the promoted epic will belong to. | +| <a id="mutationpromotetoepicgrouppath"></a>`groupPath` | [`ID`](#id) | Group the promoted epic will belong to. | | <a id="mutationpromotetoepiciid"></a>`iid` | [`String!`](#string) | IID of the issue to mutate. | | <a id="mutationpromotetoepicprojectpath"></a>`projectPath` | [`ID!`](#id) | Project the issue to mutate is in. | @@ -3587,7 +3656,7 @@ Input type: `PromoteToEpicInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationpromotetoepicclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationpromotetoepicepic"></a>`epic` | [`Epic`](#epic) | The epic after issue promotion. | +| <a id="mutationpromotetoepicepic"></a>`epic` | [`Epic`](#epic) | Epic after issue promotion. | | <a id="mutationpromotetoepicerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationpromotetoepicissue"></a>`issue` | [`Issue`](#issue) | Issue after mutation. | @@ -3601,7 +3670,7 @@ Input type: `ReleaseAssetLinkCreateInput` | ---- | ---- | ----------- | | <a id="mutationreleaseassetlinkcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationreleaseassetlinkcreatedirectassetpath"></a>`directAssetPath` | [`String`](#string) | Relative path for a direct asset link. | -| <a id="mutationreleaseassetlinkcreatelinktype"></a>`linkType` | [`ReleaseAssetLinkType`](#releaseassetlinktype) | The type of the asset link. | +| <a id="mutationreleaseassetlinkcreatelinktype"></a>`linkType` | [`ReleaseAssetLinkType`](#releaseassetlinktype) | Type of the asset link. | | <a id="mutationreleaseassetlinkcreatename"></a>`name` | [`String!`](#string) | Name of the asset link. | | <a id="mutationreleaseassetlinkcreateprojectpath"></a>`projectPath` | [`ID!`](#id) | Full path of the project the asset link is associated with. | | <a id="mutationreleaseassetlinkcreatetagname"></a>`tagName` | [`String!`](#string) | Name of the associated release's tag. | @@ -3757,7 +3826,7 @@ Input type: `RepositionImageDiffNoteInput` | ---- | ---- | ----------- | | <a id="mutationrepositionimagediffnoteclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationrepositionimagediffnoteid"></a>`id` | [`DiffNoteID!`](#diffnoteid) | Global ID of the DiffNote to update. | -| <a id="mutationrepositionimagediffnoteposition"></a>`position` | [`UpdateDiffImagePositionInput!`](#updatediffimagepositioninput) | The position of this note on a diff. | +| <a id="mutationrepositionimagediffnoteposition"></a>`position` | [`UpdateDiffImagePositionInput!`](#updatediffimagepositioninput) | Position of this note on a diff. | #### Fields @@ -3769,8 +3838,6 @@ Input type: `RepositionImageDiffNoteInput` ### `Mutation.runnerDelete` -Available only when feature flag `runner_graphql_query` is enabled. This flag is enabled by default. - Input type: `RunnerDeleteInput` #### Arguments @@ -3789,8 +3856,6 @@ Input type: `RunnerDeleteInput` ### `Mutation.runnerUpdate` -Available only when feature flag `runner_graphql_query` is enabled. This flag is enabled by default. - Input type: `RunnerUpdateInput` #### Arguments @@ -3819,8 +3884,6 @@ Input type: `RunnerUpdateInput` ### `Mutation.runnersRegistrationTokenReset` -Available only when feature flag `runner_graphql_query` is enabled. This flag is enabled by default. - Input type: `RunnersRegistrationTokenResetInput` #### Arguments @@ -4082,6 +4145,7 @@ Input type: `UpdateBoardInput` | <a id="mutationupdateboardhidebackloglist"></a>`hideBacklogList` | [`Boolean`](#boolean) | Whether or not backlog list is hidden. | | <a id="mutationupdateboardhideclosedlist"></a>`hideClosedList` | [`Boolean`](#boolean) | Whether or not closed list is hidden. | | <a id="mutationupdateboardid"></a>`id` | [`BoardID!`](#boardid) | Board global ID. | +| <a id="mutationupdateboarditerationcadenceid"></a>`iterationCadenceId` | [`IterationsCadenceID`](#iterationscadenceid) | ID of iteration cadence to be assigned to the board. | | <a id="mutationupdateboarditerationid"></a>`iterationId` | [`IterationID`](#iterationid) | ID of iteration to be assigned to the board. | | <a id="mutationupdateboardlabelids"></a>`labelIds` | [`[LabelID!]`](#labelid) | IDs of labels to be added to the board. | | <a id="mutationupdateboardlabels"></a>`labels` | [`[String!]`](#string) | Labels of the issue. | @@ -4105,7 +4169,7 @@ Input type: `UpdateBoardEpicUserPreferencesInput` | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="mutationupdateboardepicuserpreferencesboardid"></a>`boardId` | [`BoardID!`](#boardid) | The board global ID. | +| <a id="mutationupdateboardepicuserpreferencesboardid"></a>`boardId` | [`BoardID!`](#boardid) | Board global ID. | | <a id="mutationupdateboardepicuserpreferencesclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationupdateboardepicuserpreferencescollapsed"></a>`collapsed` | [`Boolean!`](#boolean) | Whether the epic should be collapsed in the board. | | <a id="mutationupdateboardepicuserpreferencesepicid"></a>`epicId` | [`EpicID!`](#epicid) | ID of an epic to set preferences for. | @@ -4148,7 +4212,7 @@ Input type: `UpdateComplianceFrameworkInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationupdatecomplianceframeworkclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationupdatecomplianceframeworkid"></a>`id` | [`ComplianceManagementFrameworkID!`](#compliancemanagementframeworkid) | The global ID of the compliance framework to update. | +| <a id="mutationupdatecomplianceframeworkid"></a>`id` | [`ComplianceManagementFrameworkID!`](#compliancemanagementframeworkid) | Global ID of the compliance framework to update. | | <a id="mutationupdatecomplianceframeworkparams"></a>`params` | [`ComplianceFrameworkInput!`](#complianceframeworkinput) | Parameters to update the compliance framework with. | #### Fields @@ -4156,7 +4220,7 @@ Input type: `UpdateComplianceFrameworkInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationupdatecomplianceframeworkclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationupdatecomplianceframeworkcomplianceframework"></a>`complianceFramework` | [`ComplianceFramework`](#complianceframework) | The compliance framework after mutation. | +| <a id="mutationupdatecomplianceframeworkcomplianceframework"></a>`complianceFramework` | [`ComplianceFramework`](#complianceframework) | Compliance framework after mutation. | | <a id="mutationupdatecomplianceframeworkerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | ### `Mutation.updateContainerExpirationPolicy` @@ -4184,6 +4248,27 @@ Input type: `UpdateContainerExpirationPolicyInput` | <a id="mutationupdatecontainerexpirationpolicycontainerexpirationpolicy"></a>`containerExpirationPolicy` | [`ContainerExpirationPolicy`](#containerexpirationpolicy) | Container expiration policy after mutation. | | <a id="mutationupdatecontainerexpirationpolicyerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +### `Mutation.updateDependencyProxyImageTtlGroupPolicy` + +Input type: `UpdateDependencyProxyImageTtlGroupPolicyInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationupdatedependencyproxyimagettlgrouppolicyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationupdatedependencyproxyimagettlgrouppolicyenabled"></a>`enabled` | [`Boolean`](#boolean) | Indicates whether the policy is enabled or disabled. | +| <a id="mutationupdatedependencyproxyimagettlgrouppolicygrouppath"></a>`groupPath` | [`ID!`](#id) | Group path for the group dependency proxy image TTL policy. | +| <a id="mutationupdatedependencyproxyimagettlgrouppolicyttl"></a>`ttl` | [`Int`](#int) | Number of days to retain a cached image file. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationupdatedependencyproxyimagettlgrouppolicyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationupdatedependencyproxyimagettlgrouppolicydependencyproxyimagettlpolicy"></a>`dependencyProxyImageTtlPolicy` | [`DependencyProxyImageTtlGroupPolicy`](#dependencyproxyimagettlgrouppolicy) | Group image TTL policy after mutation. | +| <a id="mutationupdatedependencyproxyimagettlgrouppolicyerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + ### `Mutation.updateEpic` Input type: `UpdateEpicInput` @@ -4192,26 +4277,26 @@ Input type: `UpdateEpicInput` | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="mutationupdateepicaddlabelids"></a>`addLabelIds` | [`[ID!]`](#id) | The IDs of labels to be added to the epic. | +| <a id="mutationupdateepicaddlabelids"></a>`addLabelIds` | [`[ID!]`](#id) | IDs of labels to be added to the epic. | | <a id="mutationupdateepicclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationupdateepicconfidential"></a>`confidential` | [`Boolean`](#boolean) | Indicates if the epic is confidential. | -| <a id="mutationupdateepicdescription"></a>`description` | [`String`](#string) | The description of the epic. | -| <a id="mutationupdateepicduedatefixed"></a>`dueDateFixed` | [`String`](#string) | The end date of the epic. | +| <a id="mutationupdateepicdescription"></a>`description` | [`String`](#string) | Description of the epic. | +| <a id="mutationupdateepicduedatefixed"></a>`dueDateFixed` | [`String`](#string) | End date of the epic. | | <a id="mutationupdateepicduedateisfixed"></a>`dueDateIsFixed` | [`Boolean`](#boolean) | Indicates end date should be sourced from due_date_fixed field not the issue milestones. | -| <a id="mutationupdateepicgrouppath"></a>`groupPath` | [`ID!`](#id) | The group the epic to mutate is in. | -| <a id="mutationupdateepiciid"></a>`iid` | [`ID!`](#id) | The IID of the epic to mutate. | -| <a id="mutationupdateepicremovelabelids"></a>`removeLabelIds` | [`[ID!]`](#id) | The IDs of labels to be removed from the epic. | -| <a id="mutationupdateepicstartdatefixed"></a>`startDateFixed` | [`String`](#string) | The start date of the epic. | +| <a id="mutationupdateepicgrouppath"></a>`groupPath` | [`ID!`](#id) | Group the epic to mutate is in. | +| <a id="mutationupdateepiciid"></a>`iid` | [`ID!`](#id) | IID of the epic to mutate. | +| <a id="mutationupdateepicremovelabelids"></a>`removeLabelIds` | [`[ID!]`](#id) | IDs of labels to be removed from the epic. | +| <a id="mutationupdateepicstartdatefixed"></a>`startDateFixed` | [`String`](#string) | Start date of the epic. | | <a id="mutationupdateepicstartdateisfixed"></a>`startDateIsFixed` | [`Boolean`](#boolean) | Indicates start date should be sourced from start_date_fixed field not the issue milestones. | | <a id="mutationupdateepicstateevent"></a>`stateEvent` | [`EpicStateEvent`](#epicstateevent) | State event for the epic. | -| <a id="mutationupdateepictitle"></a>`title` | [`String`](#string) | The title of the epic. | +| <a id="mutationupdateepictitle"></a>`title` | [`String`](#string) | Title of the epic. | #### Fields | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationupdateepicclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationupdateepicepic"></a>`epic` | [`Epic`](#epic) | The epic after mutation. | +| <a id="mutationupdateepicepic"></a>`epic` | [`Epic`](#epic) | Epic after mutation. | | <a id="mutationupdateepicerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | ### `Mutation.updateEpicBoardList` @@ -4251,7 +4336,7 @@ Input type: `UpdateImageDiffNoteInput` | <a id="mutationupdateimagediffnotebody"></a>`body` | [`String`](#string) | Content of the note. | | <a id="mutationupdateimagediffnoteclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationupdateimagediffnoteid"></a>`id` | [`NoteID!`](#noteid) | Global ID of the note to update. | -| <a id="mutationupdateimagediffnoteposition"></a>`position` | [`UpdateDiffImagePositionInput`](#updatediffimagepositioninput) | The position of this note on a diff. | +| <a id="mutationupdateimagediffnoteposition"></a>`position` | [`UpdateDiffImagePositionInput`](#updatediffimagepositioninput) | Position of this note on a diff. | #### Fields @@ -4274,8 +4359,8 @@ Input type: `UpdateIssueInput` | <a id="mutationupdateissueconfidential"></a>`confidential` | [`Boolean`](#boolean) | Indicates the issue is confidential. | | <a id="mutationupdateissuedescription"></a>`description` | [`String`](#string) | Description of the issue. | | <a id="mutationupdateissueduedate"></a>`dueDate` | [`ISO8601Date`](#iso8601date) | Due date of the issue. | -| <a id="mutationupdateissueepicid"></a>`epicId` | [`EpicID`](#epicid) | The ID of the parent epic. NULL when removing the association. | -| <a id="mutationupdateissuehealthstatus"></a>`healthStatus` | [`HealthStatus`](#healthstatus) | The desired health status. | +| <a id="mutationupdateissueepicid"></a>`epicId` | [`EpicID`](#epicid) | ID of the parent epic. NULL when removing the association. | +| <a id="mutationupdateissuehealthstatus"></a>`healthStatus` | [`HealthStatus`](#healthstatus) | Desired health status. | | <a id="mutationupdateissueiid"></a>`iid` | [`String!`](#string) | IID of the issue to mutate. | | <a id="mutationupdateissuelabelids"></a>`labelIds` | [`[ID!]`](#id) | IDs of labels to be set. Replaces existing issue labels. | | <a id="mutationupdateissuelocked"></a>`locked` | [`Boolean`](#boolean) | Indicates discussion is locked on the issue. | @@ -4285,7 +4370,7 @@ Input type: `UpdateIssueInput` | <a id="mutationupdateissuestateevent"></a>`stateEvent` | [`IssueStateEvent`](#issuestateevent) | Close or reopen an issue. | | <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) | The weight of the issue. | +| <a id="mutationupdateissueweight"></a>`weight` | [`Int`](#int) | Weight of the issue. | #### Fields @@ -4378,7 +4463,7 @@ Input type: `UpdateRequirementInput` | ---- | ---- | ----------- | | <a id="mutationupdaterequirementclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationupdaterequirementdescription"></a>`description` | [`String`](#string) | Description of the requirement. | -| <a id="mutationupdaterequirementiid"></a>`iid` | [`String!`](#string) | The IID of the requirement to update. | +| <a id="mutationupdaterequirementiid"></a>`iid` | [`String!`](#string) | IID of the requirement to update. | | <a id="mutationupdaterequirementlasttestreportstate"></a>`lastTestReportState` | [`TestReportState`](#testreportstate) | Creates a test report for the requirement with the given state. | | <a id="mutationupdaterequirementprojectpath"></a>`projectPath` | [`ID!`](#id) | Full project path the requirement is associated with. | | <a id="mutationupdaterequirementstate"></a>`state` | [`RequirementState`](#requirementstate) | State of the requirement. | @@ -4457,7 +4542,39 @@ Input type: `VulnerabilityConfirmInput` | ---- | ---- | ----------- | | <a id="mutationvulnerabilityconfirmclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationvulnerabilityconfirmerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationvulnerabilityconfirmvulnerability"></a>`vulnerability` | [`Vulnerability`](#vulnerability) | The vulnerability after state change. | +| <a id="mutationvulnerabilityconfirmvulnerability"></a>`vulnerability` | [`Vulnerability`](#vulnerability) | Vulnerability after state change. | + +### `Mutation.vulnerabilityCreate` + +Input type: `VulnerabilityCreateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationvulnerabilitycreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationvulnerabilitycreateconfidence"></a>`confidence` | [`VulnerabilityConfidence`](#vulnerabilityconfidence) | Confidence of the vulnerability (defaults to `unknown`). | +| <a id="mutationvulnerabilitycreateconfirmedat"></a>`confirmedAt` | [`Time`](#time) | Timestamp of when the vulnerability state changed to confirmed (defaults to creation time if status is `confirmed`). | +| <a id="mutationvulnerabilitycreatedescription"></a>`description` | [`String!`](#string) | Description of the vulnerability. | +| <a id="mutationvulnerabilitycreatedetectedat"></a>`detectedAt` | [`Time`](#time) | Timestamp of when the vulnerability was first detected (defaults to creation time). | +| <a id="mutationvulnerabilitycreatedismissedat"></a>`dismissedAt` | [`Time`](#time) | Timestamp of when the vulnerability state changed to dismissed (defaults to creation time if status is `dismissed`). | +| <a id="mutationvulnerabilitycreateidentifiers"></a>`identifiers` | [`[VulnerabilityIdentifierInput!]!`](#vulnerabilityidentifierinput) | Array of CVE or CWE identifiers for the vulnerability. | +| <a id="mutationvulnerabilitycreatemessage"></a>`message` | [`String`](#string) | Additional information about the vulnerability. | +| <a id="mutationvulnerabilitycreateproject"></a>`project` | [`ProjectID!`](#projectid) | ID of the project to attach the vulnerability to. | +| <a id="mutationvulnerabilitycreateresolvedat"></a>`resolvedAt` | [`Time`](#time) | Timestamp of when the vulnerability state changed to resolved (defaults to creation time if status is `resolved`). | +| <a id="mutationvulnerabilitycreatescannername"></a>`scannerName` | [`String!`](#string) | Name of the security scanner used to discover the vulnerability. | +| <a id="mutationvulnerabilitycreateseverity"></a>`severity` | [`VulnerabilitySeverity`](#vulnerabilityseverity) | Severity of the vulnerability (defaults to `unknown`). | +| <a id="mutationvulnerabilitycreatesolution"></a>`solution` | [`String`](#string) | How to fix this vulnerability. | +| <a id="mutationvulnerabilitycreatestate"></a>`state` | [`VulnerabilityState`](#vulnerabilitystate) | State of the vulnerability (defaults to `detected`). | +| <a id="mutationvulnerabilitycreatetitle"></a>`title` | [`String!`](#string) | Title of the vulnerability. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationvulnerabilitycreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationvulnerabilitycreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationvulnerabilitycreatevulnerability"></a>`vulnerability` | [`Vulnerability`](#vulnerability) | Vulnerability created. | ### `Mutation.vulnerabilityDismiss` @@ -4478,7 +4595,7 @@ Input type: `VulnerabilityDismissInput` | ---- | ---- | ----------- | | <a id="mutationvulnerabilitydismissclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationvulnerabilitydismisserrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationvulnerabilitydismissvulnerability"></a>`vulnerability` | [`Vulnerability`](#vulnerability) | The vulnerability after dismissal. | +| <a id="mutationvulnerabilitydismissvulnerability"></a>`vulnerability` | [`Vulnerability`](#vulnerability) | Vulnerability after dismissal. | ### `Mutation.vulnerabilityExternalIssueLinkCreate` @@ -4499,7 +4616,7 @@ Input type: `VulnerabilityExternalIssueLinkCreateInput` | ---- | ---- | ----------- | | <a id="mutationvulnerabilityexternalissuelinkcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationvulnerabilityexternalissuelinkcreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationvulnerabilityexternalissuelinkcreateexternalissuelink"></a>`externalIssueLink` | [`VulnerabilityExternalIssueLink`](#vulnerabilityexternalissuelink) | The created external issue link. | +| <a id="mutationvulnerabilityexternalissuelinkcreateexternalissuelink"></a>`externalIssueLink` | [`VulnerabilityExternalIssueLink`](#vulnerabilityexternalissuelink) | Created external issue link. | ### `Mutation.vulnerabilityExternalIssueLinkDestroy` @@ -4510,7 +4627,7 @@ Input type: `VulnerabilityExternalIssueLinkDestroyInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationvulnerabilityexternalissuelinkdestroyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationvulnerabilityexternalissuelinkdestroyid"></a>`id` | [`VulnerabilitiesExternalIssueLinkID!`](#vulnerabilitiesexternalissuelinkid) | The global ID of the vulnerability external issue link. | +| <a id="mutationvulnerabilityexternalissuelinkdestroyid"></a>`id` | [`VulnerabilitiesExternalIssueLinkID!`](#vulnerabilitiesexternalissuelinkid) | Global ID of the vulnerability external issue link. | #### Fields @@ -4536,7 +4653,7 @@ Input type: `VulnerabilityResolveInput` | ---- | ---- | ----------- | | <a id="mutationvulnerabilityresolveclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationvulnerabilityresolveerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationvulnerabilityresolvevulnerability"></a>`vulnerability` | [`Vulnerability`](#vulnerability) | The vulnerability after state change. | +| <a id="mutationvulnerabilityresolvevulnerability"></a>`vulnerability` | [`Vulnerability`](#vulnerability) | Vulnerability after state change. | ### `Mutation.vulnerabilityRevertToDetected` @@ -4555,7 +4672,7 @@ Input type: `VulnerabilityRevertToDetectedInput` | ---- | ---- | ----------- | | <a id="mutationvulnerabilityreverttodetectedclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationvulnerabilityreverttodetectederrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationvulnerabilityreverttodetectedvulnerability"></a>`vulnerability` | [`Vulnerability`](#vulnerability) | The vulnerability after revert. | +| <a id="mutationvulnerabilityreverttodetectedvulnerability"></a>`vulnerability` | [`Vulnerability`](#vulnerability) | Vulnerability after revert. | ## Connections @@ -5221,6 +5338,29 @@ The edge type for [`ComplianceFramework`](#complianceframework). | <a id="complianceframeworkedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="complianceframeworkedgenode"></a>`node` | [`ComplianceFramework`](#complianceframework) | The item at the end of the edge. | +#### `ConnectedAgentConnection` + +The connection type for [`ConnectedAgent`](#connectedagent). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="connectedagentconnectionedges"></a>`edges` | [`[ConnectedAgentEdge]`](#connectedagentedge) | A list of edges. | +| <a id="connectedagentconnectionnodes"></a>`nodes` | [`[ConnectedAgent]`](#connectedagent) | A list of nodes. | +| <a id="connectedagentconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `ConnectedAgentEdge` + +The edge type for [`ConnectedAgent`](#connectedagent). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="connectedagentedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="connectedagentedgenode"></a>`node` | [`ConnectedAgent`](#connectedagent) | The item at the end of the edge. | + #### `ContainerRepositoryConnection` The connection type for [`ContainerRepository`](#containerrepository). @@ -5290,6 +5430,52 @@ The edge type for [`CustomEmoji`](#customemoji). | <a id="customemojiedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="customemojiedgenode"></a>`node` | [`CustomEmoji`](#customemoji) | The item at the end of the edge. | +#### `CustomerRelationsContactConnection` + +The connection type for [`CustomerRelationsContact`](#customerrelationscontact). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="customerrelationscontactconnectionedges"></a>`edges` | [`[CustomerRelationsContactEdge]`](#customerrelationscontactedge) | A list of edges. | +| <a id="customerrelationscontactconnectionnodes"></a>`nodes` | [`[CustomerRelationsContact]`](#customerrelationscontact) | A list of nodes. | +| <a id="customerrelationscontactconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `CustomerRelationsContactEdge` + +The edge type for [`CustomerRelationsContact`](#customerrelationscontact). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="customerrelationscontactedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="customerrelationscontactedgenode"></a>`node` | [`CustomerRelationsContact`](#customerrelationscontact) | The item at the end of the edge. | + +#### `CustomerRelationsOrganizationConnection` + +The connection type for [`CustomerRelationsOrganization`](#customerrelationsorganization). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="customerrelationsorganizationconnectionedges"></a>`edges` | [`[CustomerRelationsOrganizationEdge]`](#customerrelationsorganizationedge) | A list of edges. | +| <a id="customerrelationsorganizationconnectionnodes"></a>`nodes` | [`[CustomerRelationsOrganization]`](#customerrelationsorganization) | A list of nodes. | +| <a id="customerrelationsorganizationconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `CustomerRelationsOrganizationEdge` + +The edge type for [`CustomerRelationsOrganization`](#customerrelationsorganization). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="customerrelationsorganizationedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="customerrelationsorganizationedgenode"></a>`node` | [`CustomerRelationsOrganization`](#customerrelationsorganization) | The item at the end of the edge. | + #### `DastProfileConnection` The connection type for [`DastProfile`](#dastprofile). @@ -5382,6 +5568,52 @@ The edge type for [`DastSiteValidation`](#dastsitevalidation). | <a id="dastsitevalidationedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="dastsitevalidationedgenode"></a>`node` | [`DastSiteValidation`](#dastsitevalidation) | The item at the end of the edge. | +#### `DependencyProxyBlobConnection` + +The connection type for [`DependencyProxyBlob`](#dependencyproxyblob). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="dependencyproxyblobconnectionedges"></a>`edges` | [`[DependencyProxyBlobEdge]`](#dependencyproxyblobedge) | A list of edges. | +| <a id="dependencyproxyblobconnectionnodes"></a>`nodes` | [`[DependencyProxyBlob]`](#dependencyproxyblob) | A list of nodes. | +| <a id="dependencyproxyblobconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `DependencyProxyBlobEdge` + +The edge type for [`DependencyProxyBlob`](#dependencyproxyblob). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="dependencyproxyblobedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="dependencyproxyblobedgenode"></a>`node` | [`DependencyProxyBlob`](#dependencyproxyblob) | The item at the end of the edge. | + +#### `DependencyProxyManifestConnection` + +The connection type for [`DependencyProxyManifest`](#dependencyproxymanifest). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="dependencyproxymanifestconnectionedges"></a>`edges` | [`[DependencyProxyManifestEdge]`](#dependencyproxymanifestedge) | A list of edges. | +| <a id="dependencyproxymanifestconnectionnodes"></a>`nodes` | [`[DependencyProxyManifest]`](#dependencyproxymanifest) | A list of nodes. | +| <a id="dependencyproxymanifestconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `DependencyProxyManifestEdge` + +The edge type for [`DependencyProxyManifest`](#dependencyproxymanifest). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="dependencyproxymanifestedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="dependencyproxymanifestedgenode"></a>`node` | [`DependencyProxyManifest`](#dependencyproxymanifest) | The item at the end of the edge. | + #### `DesignAtVersionConnection` The connection type for [`DesignAtVersion`](#designatversion). @@ -6378,6 +6610,29 @@ The edge type for [`PackageTag`](#packagetag). | <a id="packagetagedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="packagetagedgenode"></a>`node` | [`PackageTag`](#packagetag) | The item at the end of the edge. | +#### `PagesDeploymentRegistryConnection` + +The connection type for [`PagesDeploymentRegistry`](#pagesdeploymentregistry). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="pagesdeploymentregistryconnectionedges"></a>`edges` | [`[PagesDeploymentRegistryEdge]`](#pagesdeploymentregistryedge) | A list of edges. | +| <a id="pagesdeploymentregistryconnectionnodes"></a>`nodes` | [`[PagesDeploymentRegistry]`](#pagesdeploymentregistry) | A list of nodes. | +| <a id="pagesdeploymentregistryconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `PagesDeploymentRegistryEdge` + +The edge type for [`PagesDeploymentRegistry`](#pagesdeploymentregistry). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="pagesdeploymentregistryedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="pagesdeploymentregistryedgenode"></a>`node` | [`PagesDeploymentRegistry`](#pagesdeploymentregistry) | The item at the end of the edge. | + #### `PathLockConnection` The connection type for [`PathLock`](#pathlock). @@ -7188,6 +7443,29 @@ The edge type for [`TreeEntry`](#treeentry). | <a id="treeentryedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="treeentryedgenode"></a>`node` | [`TreeEntry`](#treeentry) | The item at the end of the edge. | +#### `UploadRegistryConnection` + +The connection type for [`UploadRegistry`](#uploadregistry). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="uploadregistryconnectionedges"></a>`edges` | [`[UploadRegistryEdge]`](#uploadregistryedge) | A list of edges. | +| <a id="uploadregistryconnectionnodes"></a>`nodes` | [`[UploadRegistry]`](#uploadregistry) | A list of nodes. | +| <a id="uploadregistryconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `UploadRegistryEdge` + +The edge type for [`UploadRegistry`](#uploadregistry). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="uploadregistryedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="uploadregistryedgenode"></a>`node` | [`UploadRegistry`](#uploadregistry) | The item at the end of the edge. | + #### `UsageTrendsMeasurementConnection` The connection type for [`UsageTrendsMeasurement`](#usagetrendsmeasurement). @@ -7406,6 +7684,19 @@ Configuration details for an Agent. | ---- | ---- | ----------- | | <a id="agentconfigurationagentname"></a>`agentName` | [`String`](#string) | Name of the agent. | +### `AgentMetadata` + +Information about a connected Agent. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="agentmetadatacommit"></a>`commit` | [`String`](#string) | Agent version commit. | +| <a id="agentmetadatapodname"></a>`podName` | [`String`](#string) | Name of the pod running the Agent. | +| <a id="agentmetadatapodnamespace"></a>`podNamespace` | [`String`](#string) | Namespace of the pod running the Agent. | +| <a id="agentmetadataversion"></a>`version` | [`String`](#string) | Agent version tag. | + ### `AlertManagementAlert` Describes an alert from the project's Alert Management. @@ -7418,7 +7709,7 @@ Describes an alert from the project's Alert Management. | <a id="alertmanagementalertcreatedat"></a>`createdAt` | [`Time`](#time) | Timestamp the alert was created. | | <a id="alertmanagementalertdescription"></a>`description` | [`String`](#string) | Description of the alert. | | <a id="alertmanagementalertdetails"></a>`details` | [`JSON`](#json) | Alert details. | -| <a id="alertmanagementalertdetailsurl"></a>`detailsUrl` | [`String!`](#string) | The URL of the alert detail page. | +| <a id="alertmanagementalertdetailsurl"></a>`detailsUrl` | [`String!`](#string) | URL of the alert detail page. | | <a id="alertmanagementalertdiscussions"></a>`discussions` | [`DiscussionConnection!`](#discussionconnection) | All discussions on this noteable. (see [Connections](#connections)) | | <a id="alertmanagementalertendedat"></a>`endedAt` | [`Time`](#time) | Timestamp the alert ended. | | <a id="alertmanagementalertenvironment"></a>`environment` | [`Environment`](#environment) | Environment for the alert. | @@ -7430,7 +7721,7 @@ Describes an alert from the project's Alert Management. | <a id="alertmanagementalertmetricsdashboardurl"></a>`metricsDashboardUrl` | [`String`](#string) | URL for metrics embed for the alert. | | <a id="alertmanagementalertmonitoringtool"></a>`monitoringTool` | [`String`](#string) | Monitoring tool the alert came from. | | <a id="alertmanagementalertnotes"></a>`notes` | [`NoteConnection!`](#noteconnection) | All notes on this noteable. (see [Connections](#connections)) | -| <a id="alertmanagementalertprometheusalert"></a>`prometheusAlert` | [`PrometheusAlert`](#prometheusalert) | The alert condition for Prometheus. | +| <a id="alertmanagementalertprometheusalert"></a>`prometheusAlert` | [`PrometheusAlert`](#prometheusalert) | Alert condition for Prometheus. | | <a id="alertmanagementalertrunbook"></a>`runbook` | [`String`](#string) | Runbook for the alert as defined in alert details. | | <a id="alertmanagementalertservice"></a>`service` | [`String`](#string) | Service the alert came from. | | <a id="alertmanagementalertseverity"></a>`severity` | [`AlertManagementSeverity`](#alertmanagementseverity) | Severity of the alert. | @@ -7455,12 +7746,12 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="alertmanagementalerttodosaction"></a>`action` | [`[TodoActionEnum!]`](#todoactionenum) | The action to be filtered. | -| <a id="alertmanagementalerttodosauthorid"></a>`authorId` | [`[ID!]`](#id) | The ID of an author. | -| <a id="alertmanagementalerttodosgroupid"></a>`groupId` | [`[ID!]`](#id) | The ID of a group. | -| <a id="alertmanagementalerttodosprojectid"></a>`projectId` | [`[ID!]`](#id) | The ID of a project. | -| <a id="alertmanagementalerttodosstate"></a>`state` | [`[TodoStateEnum!]`](#todostateenum) | The state of the todo. | -| <a id="alertmanagementalerttodostype"></a>`type` | [`[TodoTargetEnum!]`](#todotargetenum) | The type of the todo. | +| <a id="alertmanagementalerttodosaction"></a>`action` | [`[TodoActionEnum!]`](#todoactionenum) | Action to be filtered. | +| <a id="alertmanagementalerttodosauthorid"></a>`authorId` | [`[ID!]`](#id) | ID of an author. | +| <a id="alertmanagementalerttodosgroupid"></a>`groupId` | [`[ID!]`](#id) | ID of a group. | +| <a id="alertmanagementalerttodosprojectid"></a>`projectId` | [`[ID!]`](#id) | ID of a project. | +| <a id="alertmanagementalerttodosstate"></a>`state` | [`[TodoStateEnum!]`](#todostateenum) | State of the todo. | +| <a id="alertmanagementalerttodostype"></a>`type` | [`[TodoTargetEnum!]`](#todotargetenum) | Type of the todo. | ### `AlertManagementAlertStatusCountsType` @@ -7491,7 +7782,7 @@ An endpoint and credentials used to accept alerts for a project. | <a id="alertmanagementhttpintegrationname"></a>`name` | [`String`](#string) | Name of the integration. | | <a id="alertmanagementhttpintegrationpayloadalertfields"></a>`payloadAlertFields` | [`[AlertManagementPayloadAlertField!]`](#alertmanagementpayloadalertfield) | Extract alert fields from payload example for custom mapping. | | <a id="alertmanagementhttpintegrationpayloadattributemappings"></a>`payloadAttributeMappings` | [`[AlertManagementPayloadAlertMappingField!]`](#alertmanagementpayloadalertmappingfield) | The custom mapping of GitLab alert attributes to fields from the payload_example. | -| <a id="alertmanagementhttpintegrationpayloadexample"></a>`payloadExample` | [`JsonString`](#jsonstring) | The example of an alert payload. | +| <a id="alertmanagementhttpintegrationpayloadexample"></a>`payloadExample` | [`JsonString`](#jsonstring) | Example of an alert payload. | | <a id="alertmanagementhttpintegrationtoken"></a>`token` | [`String`](#string) | Token used to authenticate alert notification requests. | | <a id="alertmanagementhttpintegrationtype"></a>`type` | [`AlertManagementIntegrationType!`](#alertmanagementintegrationtype) | Type of integration. | | <a id="alertmanagementhttpintegrationurl"></a>`url` | [`String`](#string) | Endpoint which accepts alert notifications. | @@ -7516,7 +7807,7 @@ Parsed field (with its name) from an alert used for custom mappings. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="alertmanagementpayloadalertmappingfieldfieldname"></a>`fieldName` | [`AlertManagementPayloadAlertFieldName`](#alertmanagementpayloadalertfieldname) | A GitLab alert field name. | +| <a id="alertmanagementpayloadalertmappingfieldfieldname"></a>`fieldName` | [`AlertManagementPayloadAlertFieldName`](#alertmanagementpayloadalertfieldname) | GitLab alert field name. | | <a id="alertmanagementpayloadalertmappingfieldlabel"></a>`label` | [`String`](#string) | Human-readable label of the payload path. | | <a id="alertmanagementpayloadalertmappingfieldpath"></a>`path` | [`[PayloadAlertFieldPathSegment!]`](#payloadalertfieldpathsegment) | Path to value inside payload JSON. | | <a id="alertmanagementpayloadalertmappingfieldtype"></a>`type` | [`AlertManagementPayloadAlertFieldType`](#alertmanagementpayloadalertfieldtype) | Type of the parsed value. | @@ -7556,9 +7847,9 @@ An API Fuzzing scan profile. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="apifuzzingscanprofiledescription"></a>`description` | [`String`](#string) | A short description of the profile. | -| <a id="apifuzzingscanprofilename"></a>`name` | [`String`](#string) | The unique name of the profile. | -| <a id="apifuzzingscanprofileyaml"></a>`yaml` | [`String`](#string) | A syntax highlit HTML representation of the YAML. | +| <a id="apifuzzingscanprofiledescription"></a>`description` | [`String`](#string) | Short description of the profile. | +| <a id="apifuzzingscanprofilename"></a>`name` | [`String`](#string) | Unique name of the profile. | +| <a id="apifuzzingscanprofileyaml"></a>`yaml` | [`String`](#string) | Syntax highlighted HTML representation of the YAML. | ### `ApprovalRule` @@ -7568,9 +7859,19 @@ Describes a rule for who can approve merge requests. | Name | Type | Description | | ---- | ---- | ----------- | +| <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="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)) | | <a id="approvalruleid"></a>`id` | [`GlobalID!`](#globalid) | ID of the rule. | | <a id="approvalrulename"></a>`name` | [`String`](#string) | Name of the rule. | +| <a id="approvalruleoverridden"></a>`overridden` | [`Boolean`](#boolean) | Indicates if the rule was overridden for the merge request. | +| <a id="approvalrulesection"></a>`section` | [`String`](#string) | Named section of the Code Owners file that the rule applies to. | +| <a id="approvalrulesourcerule"></a>`sourceRule` | [`ApprovalRule`](#approvalrule) | Source rule used to create the rule. | | <a id="approvalruletype"></a>`type` | [`ApprovalRuleType`](#approvalruletype) | Type of the rule. | +| <a id="approvalruleusers"></a>`users` | [`UserCoreConnection`](#usercoreconnection) | List of users added as approvers for the rule. (see [Connections](#connections)) | ### `AwardEmoji` @@ -7580,12 +7881,12 @@ An emoji awarded by a user. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="awardemojidescription"></a>`description` | [`String!`](#string) | The emoji description. | -| <a id="awardemojiemoji"></a>`emoji` | [`String!`](#string) | The emoji as an icon. | -| <a id="awardemojiname"></a>`name` | [`String!`](#string) | The emoji name. | -| <a id="awardemojiunicode"></a>`unicode` | [`String!`](#string) | The emoji in Unicode. | -| <a id="awardemojiunicodeversion"></a>`unicodeVersion` | [`String!`](#string) | The Unicode version for this emoji. | -| <a id="awardemojiuser"></a>`user` | [`UserCore!`](#usercore) | The user who awarded the emoji. | +| <a id="awardemojidescription"></a>`description` | [`String!`](#string) | Emoji description. | +| <a id="awardemojiemoji"></a>`emoji` | [`String!`](#string) | Emoji as an icon. | +| <a id="awardemojiname"></a>`name` | [`String!`](#string) | Emoji name. | +| <a id="awardemojiunicode"></a>`unicode` | [`String!`](#string) | Emoji in Unicode. | +| <a id="awardemojiunicodeversion"></a>`unicodeVersion` | [`String!`](#string) | Unicode version for this emoji. | +| <a id="awardemojiuser"></a>`user` | [`UserCore!`](#usercore) | User who awarded the emoji. | ### `BaseService` @@ -7637,14 +7938,15 @@ Represents a project or group issue board. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="boardassignee"></a>`assignee` | [`UserCore`](#usercore) | The board assignee. | +| <a id="boardassignee"></a>`assignee` | [`UserCore`](#usercore) | Board assignee. | | <a id="boardcreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp of when the board was created. | | <a id="boardhidebackloglist"></a>`hideBacklogList` | [`Boolean`](#boolean) | Whether or not backlog list is hidden. | | <a id="boardhideclosedlist"></a>`hideClosedList` | [`Boolean`](#boolean) | Whether or not closed list is hidden. | | <a id="boardid"></a>`id` | [`ID!`](#id) | ID (global ID) of the board. | -| <a id="boarditeration"></a>`iteration` | [`Iteration`](#iteration) | The board iteration. | +| <a id="boarditeration"></a>`iteration` | [`Iteration`](#iteration) | Board iteration. | +| <a id="boarditerationcadence"></a>`iterationCadence` | [`IterationCadence`](#iterationcadence) | Board iteration cadence. | | <a id="boardlabels"></a>`labels` | [`LabelConnection`](#labelconnection) | Labels of the board. (see [Connections](#connections)) | -| <a id="boardmilestone"></a>`milestone` | [`Milestone`](#milestone) | The board milestone. | +| <a id="boardmilestone"></a>`milestone` | [`Milestone`](#milestone) | Board milestone. | | <a id="boardname"></a>`name` | [`String`](#string) | Name of the board. | | <a id="boardupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp of when the board was last updated. | | <a id="boardwebpath"></a>`webPath` | [`String!`](#string) | Web path of the board. | @@ -7695,7 +7997,7 @@ Represents an epic on an issue board. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="boardepicauthor"></a>`author` | [`UserCore!`](#usercore) | Author of the epic. | -| <a id="boardepicawardemoji"></a>`awardEmoji` | [`AwardEmojiConnection`](#awardemojiconnection) | A list of award emojis associated with the epic. (see [Connections](#connections)) | +| <a id="boardepicawardemoji"></a>`awardEmoji` | [`AwardEmojiConnection`](#awardemojiconnection) | List of award emojis associated with the epic. (see [Connections](#connections)) | | <a id="boardepicclosedat"></a>`closedAt` | [`Time`](#time) | Timestamp of when the epic was closed. | | <a id="boardepicconfidential"></a>`confidential` | [`Boolean`](#boolean) | Indicates if the epic is confidential. | | <a id="boardepiccreatedat"></a>`createdAt` | [`Time`](#time) | Timestamp of when the epic was created. | @@ -7709,7 +8011,7 @@ Represents an epic on an issue board. | <a id="boardepicduedatefixed"></a>`dueDateFixed` | [`Time`](#time) | Fixed due date of the epic. | | <a id="boardepicduedatefrommilestones"></a>`dueDateFromMilestones` | [`Time`](#time) | Inherited due date of the epic from milestones. | | <a id="boardepicduedateisfixed"></a>`dueDateIsFixed` | [`Boolean`](#boolean) | Indicates if the due date has been manually set. | -| <a id="boardepicevents"></a>`events` | [`EventConnection`](#eventconnection) | A list of events associated with the object. (see [Connections](#connections)) | +| <a id="boardepicevents"></a>`events` | [`EventConnection`](#eventconnection) | List of events associated with the object. (see [Connections](#connections)) | | <a id="boardepicgroup"></a>`group` | [`Group!`](#group) | Group to which the epic belongs. | | <a id="boardepichaschildren"></a>`hasChildren` | [`Boolean!`](#boolean) | Indicates if the epic has children. | | <a id="boardepichasissues"></a>`hasIssues` | [`Boolean!`](#boolean) | Indicates if the epic has direct issues. | @@ -7723,7 +8025,7 @@ Represents an epic on an issue board. | <a id="boardepicparent"></a>`parent` | [`Epic`](#epic) | Parent epic of the epic. | | <a id="boardepicparticipants"></a>`participants` | [`UserCoreConnection`](#usercoreconnection) | List of participants for the epic. (see [Connections](#connections)) | | <a id="boardepicrelationpath"></a>`relationPath` | [`String`](#string) | URI path of the epic-issue relationship. | -| <a id="boardepicrelativeposition"></a>`relativePosition` | [`Int`](#int) | The relative position of the epic in the epic tree. | +| <a id="boardepicrelativeposition"></a>`relativePosition` | [`Int`](#int) | Relative position of the epic in the epic tree. | | <a id="boardepicstartdate"></a>`startDate` | [`Time`](#time) | Start date of the epic. | | <a id="boardepicstartdatefixed"></a>`startDateFixed` | [`Time`](#time) | Fixed start date of the epic. | | <a id="boardepicstartdatefrommilestones"></a>`startDateFromMilestones` | [`Time`](#time) | Inherited start date of the epic from milestones. | @@ -7861,7 +8163,7 @@ Represents a list for an issue board. | <a id="boardlistissuescount"></a>`issuesCount` | [`Int`](#int) | Count of issues in the list. | | <a id="boardlistiteration"></a>`iteration` | [`Iteration`](#iteration) | Iteration of the list. | | <a id="boardlistlabel"></a>`label` | [`Label`](#label) | Label of the list. | -| <a id="boardlistlimitmetric"></a>`limitMetric` | [`ListLimitMetric`](#listlimitmetric) | The current limit metric for the list. | +| <a id="boardlistlimitmetric"></a>`limitMetric` | [`ListLimitMetric`](#listlimitmetric) | Current limit metric for the list. | | <a id="boardlistlisttype"></a>`listType` | [`String!`](#string) | Type of the list. | | <a id="boardlistmaxissuecount"></a>`maxIssueCount` | [`Int`](#int) | Maximum number of issues in the list. | | <a id="boardlistmaxissueweight"></a>`maxIssueWeight` | [`Int`](#int) | Maximum weight of issues in the list. | @@ -7975,7 +8277,7 @@ Represents the total number of issues and their weights for a particular day. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="ciconfigjobrestrictionrefs"></a>`refs` | [`[String!]`](#string) | The Git refs the job restriction applies to. | +| <a id="ciconfigjobrestrictionrefs"></a>`refs` | [`[String!]`](#string) | Git refs the job restriction applies to. | ### `CiConfigNeed` @@ -8068,8 +8370,8 @@ Represents the total number of issues and their weights for a particular day. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="ciminutesnamespacemonthlyusageminutes"></a>`minutes` | [`Int`](#int) | The total number of minutes used by all projects in the namespace. | -| <a id="ciminutesnamespacemonthlyusagemonth"></a>`month` | [`String`](#string) | The month related to the usage data. | +| <a id="ciminutesnamespacemonthlyusageminutes"></a>`minutes` | [`Int`](#int) | Total number of minutes used by all projects in the namespace. | +| <a id="ciminutesnamespacemonthlyusagemonth"></a>`month` | [`String`](#string) | Month related to the usage data. | | <a id="ciminutesnamespacemonthlyusageprojects"></a>`projects` | [`CiMinutesProjectMonthlyUsageConnection`](#ciminutesprojectmonthlyusageconnection) | CI minutes usage data for projects in the namespace. (see [Connections](#connections)) | ### `CiMinutesProjectMonthlyUsage` @@ -8078,8 +8380,8 @@ Represents the total number of issues and their weights for a particular day. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="ciminutesprojectmonthlyusageminutes"></a>`minutes` | [`Int`](#int) | The number of CI minutes used by the project in the month. | -| <a id="ciminutesprojectmonthlyusagename"></a>`name` | [`String`](#string) | The name of the project. | +| <a id="ciminutesprojectmonthlyusageminutes"></a>`minutes` | [`Int`](#int) | Number of CI minutes used by the project in the month. | +| <a id="ciminutesprojectmonthlyusagename"></a>`name` | [`String`](#string) | Name of the project. | ### `CiRunner` @@ -8137,11 +8439,12 @@ GitLab CI/CD configuration template. | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="clusteragentconnections"></a>`connections` | [`ConnectedAgentConnection`](#connectedagentconnection) | Active connections for the cluster agent. (see [Connections](#connections)) | | <a id="clusteragentcreatedat"></a>`createdAt` | [`Time`](#time) | Timestamp the cluster agent was created. | | <a id="clusteragentcreatedbyuser"></a>`createdByUser` | [`UserCore`](#usercore) | User object, containing information about the person who created the agent. | | <a id="clusteragentid"></a>`id` | [`ID!`](#id) | ID of the cluster agent. | | <a id="clusteragentname"></a>`name` | [`String`](#string) | Name of the cluster agent. | -| <a id="clusteragentproject"></a>`project` | [`Project`](#project) | The project this cluster agent is associated with. | +| <a id="clusteragentproject"></a>`project` | [`Project`](#project) | Project this cluster agent is associated with. | | <a id="clusteragenttokens"></a>`tokens` | [`ClusterAgentTokenConnection`](#clusteragenttokenconnection) | Tokens associated with the cluster agent. (see [Connections](#connections)) | | <a id="clusteragentupdatedat"></a>`updatedAt` | [`Time`](#time) | Timestamp the cluster agent was updated. | | <a id="clusteragentwebpath"></a>`webPath` | [`String`](#string) | Web path of the cluster agent. | @@ -8154,7 +8457,7 @@ GitLab CI/CD configuration template. | ---- | ---- | ----------- | | <a id="clusteragenttokenclusteragent"></a>`clusterAgent` | [`ClusterAgent`](#clusteragent) | Cluster agent this token is associated with. | | <a id="clusteragenttokencreatedat"></a>`createdAt` | [`Time`](#time) | Timestamp the token was created. | -| <a id="clusteragenttokencreatedbyuser"></a>`createdByUser` | [`UserCore`](#usercore) | The user who created the token. | +| <a id="clusteragenttokencreatedbyuser"></a>`createdByUser` | [`UserCore`](#usercore) | User who created the token. | | <a id="clusteragenttokendescription"></a>`description` | [`String`](#string) | Description of the token. | | <a id="clusteragenttokenid"></a>`id` | [`ClustersAgentTokenID!`](#clustersagenttokenid) | Global ID of the token. | | <a id="clusteragenttokenlastusedat"></a>`lastUsedAt` | [`Time`](#time) | Timestamp the token was last used. | @@ -8193,10 +8496,10 @@ Represents a code quality degradation on the pipeline. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="codequalitydegradationdescription"></a>`description` | [`String!`](#string) | A description of the code quality degradation. | -| <a id="codequalitydegradationfingerprint"></a>`fingerprint` | [`String!`](#string) | A unique fingerprint to identify the code quality degradation. For example, an MD5 hash. | -| <a id="codequalitydegradationline"></a>`line` | [`Int!`](#int) | The line on which the code quality degradation occurred. | -| <a id="codequalitydegradationpath"></a>`path` | [`String!`](#string) | The relative path to the file containing the code quality degradation. | +| <a id="codequalitydegradationdescription"></a>`description` | [`String!`](#string) | Description of the code quality degradation. | +| <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). | ### `Commit` @@ -8239,6 +8542,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | <a id="commitpipelinesref"></a>`ref` | [`String`](#string) | Filter pipelines by the ref they are run for. | | <a id="commitpipelinessha"></a>`sha` | [`String`](#string) | Filter pipelines by the sha of the commit they are run for. | +| <a id="commitpipelinessource"></a>`source` | [`String`](#string) | Filter pipelines by their source. Will be ignored if `dast_view_scans` feature flag is disabled. | | <a id="commitpipelinesstatus"></a>`status` | [`PipelineStatusEnum`](#pipelinestatusenum) | Filter pipelines by their status. | ### `ComplianceFramework` @@ -8298,6 +8602,18 @@ Conan metadata. | <a id="conanmetadatarecipepath"></a>`recipePath` | [`String!`](#string) | Recipe path of the Conan package. | | <a id="conanmetadataupdatedat"></a>`updatedAt` | [`Time!`](#time) | Date of most recent update. | +### `ConnectedAgent` + +Connection details for an Agent. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="connectedagentconnectedat"></a>`connectedAt` | [`Time`](#time) | When the connection was established. | +| <a id="connectedagentconnectionid"></a>`connectionId` | [`BigInt`](#bigint) | ID of the connection. | +| <a id="connectedagentmetadata"></a>`metadata` | [`AgentMetadata`](#agentmetadata) | Information about the Agent. | + ### `ContainerExpirationPolicy` A tag expiration policy designed to keep only the images that matter most. @@ -8326,7 +8642,7 @@ A container repository. | ---- | ---- | ----------- | | <a id="containerrepositorycandelete"></a>`canDelete` | [`Boolean!`](#boolean) | Can the current user delete the container repository. | | <a id="containerrepositorycreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp when the container repository was created. | -| <a id="containerrepositoryexpirationpolicycleanupstatus"></a>`expirationPolicyCleanupStatus` | [`ContainerRepositoryCleanupStatus`](#containerrepositorycleanupstatus) | The tags cleanup status for the container repository. | +| <a id="containerrepositoryexpirationpolicycleanupstatus"></a>`expirationPolicyCleanupStatus` | [`ContainerRepositoryCleanupStatus`](#containerrepositorycleanupstatus) | Tags cleanup status for the container repository. | | <a id="containerrepositoryexpirationpolicystartedat"></a>`expirationPolicyStartedAt` | [`Time`](#time) | Timestamp when the cleanup done by the expiration policy was started on the container repository. | | <a id="containerrepositoryid"></a>`id` | [`ID!`](#id) | ID of the container repository. | | <a id="containerrepositorylocation"></a>`location` | [`String!`](#string) | URL of the container repository. | @@ -8347,7 +8663,7 @@ Details of a container repository. | ---- | ---- | ----------- | | <a id="containerrepositorydetailscandelete"></a>`canDelete` | [`Boolean!`](#boolean) | Can the current user delete the container repository. | | <a id="containerrepositorydetailscreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp when the container repository was created. | -| <a id="containerrepositorydetailsexpirationpolicycleanupstatus"></a>`expirationPolicyCleanupStatus` | [`ContainerRepositoryCleanupStatus`](#containerrepositorycleanupstatus) | The tags cleanup status for the container repository. | +| <a id="containerrepositorydetailsexpirationpolicycleanupstatus"></a>`expirationPolicyCleanupStatus` | [`ContainerRepositoryCleanupStatus`](#containerrepositorycleanupstatus) | Tags cleanup status for the container repository. | | <a id="containerrepositorydetailsexpirationpolicystartedat"></a>`expirationPolicyStartedAt` | [`Time`](#time) | Timestamp when the cleanup done by the expiration policy was started on the container repository. | | <a id="containerrepositorydetailsid"></a>`id` | [`ID!`](#id) | ID of the container repository. | | <a id="containerrepositorydetailslocation"></a>`location` | [`String!`](#string) | URL of the container repository. | @@ -8375,7 +8691,7 @@ A tag from a container repository. | <a id="containerrepositorytagpath"></a>`path` | [`String!`](#string) | Path of the tag. | | <a id="containerrepositorytagrevision"></a>`revision` | [`String`](#string) | Revision of the tag. | | <a id="containerrepositorytagshortrevision"></a>`shortRevision` | [`String`](#string) | Short revision of the tag. | -| <a id="containerrepositorytagtotalsize"></a>`totalSize` | [`BigInt`](#bigint) | The size of the tag. | +| <a id="containerrepositorytagtotalsize"></a>`totalSize` | [`BigInt`](#bigint) | Size of the tag. | ### `CurrentLicense` @@ -8410,9 +8726,38 @@ A custom emoji uploaded by user. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="customemojiexternal"></a>`external` | [`Boolean!`](#boolean) | Whether the emoji is an external link. | -| <a id="customemojiid"></a>`id` | [`CustomEmojiID!`](#customemojiid) | The ID of the emoji. | -| <a id="customemojiname"></a>`name` | [`String!`](#string) | The name of the emoji. | -| <a id="customemojiurl"></a>`url` | [`String!`](#string) | The link to file of the emoji. | +| <a id="customemojiid"></a>`id` | [`CustomEmojiID!`](#customemojiid) | ID of the emoji. | +| <a id="customemojiname"></a>`name` | [`String!`](#string) | Name of the emoji. | +| <a id="customemojiurl"></a>`url` | [`String!`](#string) | Link to file of the emoji. | + +### `CustomerRelationsContact` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="customerrelationscontactcreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp the contact was created. | +| <a id="customerrelationscontactdescription"></a>`description` | [`String`](#string) | Description or notes for the contact. | +| <a id="customerrelationscontactemail"></a>`email` | [`String`](#string) | Email address of the contact. | +| <a id="customerrelationscontactfirstname"></a>`firstName` | [`String!`](#string) | First name of the contact. | +| <a id="customerrelationscontactid"></a>`id` | [`ID!`](#id) | Internal ID of the contact. | +| <a id="customerrelationscontactlastname"></a>`lastName` | [`String!`](#string) | Last name of the contact. | +| <a id="customerrelationscontactorganization"></a>`organization` | [`CustomerRelationsOrganization`](#customerrelationsorganization) | Organization of the contact. | +| <a id="customerrelationscontactphone"></a>`phone` | [`String`](#string) | Phone number of the contact. | +| <a id="customerrelationscontactupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp the contact was last updated. | + +### `CustomerRelationsOrganization` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="customerrelationsorganizationcreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp the organization was created. | +| <a id="customerrelationsorganizationdefaultrate"></a>`defaultRate` | [`Float`](#float) | Standard billing rate for the organization. | +| <a id="customerrelationsorganizationdescription"></a>`description` | [`String`](#string) | Description or notes for the organization. | +| <a id="customerrelationsorganizationid"></a>`id` | [`ID!`](#id) | Internal ID of the organization. | +| <a id="customerrelationsorganizationname"></a>`name` | [`String!`](#string) | Name of the organization. | +| <a id="customerrelationsorganizationupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp the organization was last updated. | ### `DastProfile` @@ -8422,13 +8767,14 @@ Represents a DAST Profile. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="dastprofilebranch"></a>`branch` | [`DastProfileBranch`](#dastprofilebranch) | The associated branch. | -| <a id="dastprofiledastscannerprofile"></a>`dastScannerProfile` | [`DastScannerProfile`](#dastscannerprofile) | The associated scanner profile. | -| <a id="dastprofiledastsiteprofile"></a>`dastSiteProfile` | [`DastSiteProfile`](#dastsiteprofile) | The associated site profile. | -| <a id="dastprofiledescription"></a>`description` | [`String`](#string) | The description of the scan. | +| <a id="dastprofilebranch"></a>`branch` | [`DastProfileBranch`](#dastprofilebranch) | Associated branch. | +| <a id="dastprofiledastprofileschedule"></a>`dastProfileSchedule` | [`DastProfileSchedule`](#dastprofileschedule) | Associated profile schedule. Will always return `null` if `dast_on_demand_scans_scheduler` feature flag is disabled. | +| <a id="dastprofiledastscannerprofile"></a>`dastScannerProfile` | [`DastScannerProfile`](#dastscannerprofile) | Associated scanner profile. | +| <a id="dastprofiledastsiteprofile"></a>`dastSiteProfile` | [`DastSiteProfile`](#dastsiteprofile) | Associated site profile. | +| <a id="dastprofiledescription"></a>`description` | [`String`](#string) | Description of the scan. | | <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) | The name of the profile. | +| <a id="dastprofilename"></a>`name` | [`String`](#string) | Name of the profile. | ### `DastProfileBranch` @@ -8439,7 +8785,33 @@ Represents a DAST Profile Branch. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="dastprofilebranchexists"></a>`exists` | [`Boolean`](#boolean) | Indicates whether or not the branch exists. | -| <a id="dastprofilebranchname"></a>`name` | [`String`](#string) | The name of the branch. | +| <a id="dastprofilebranchname"></a>`name` | [`String`](#string) | Name of the branch. | + +### `DastProfileCadence` + +Represents DAST Profile Cadence. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="dastprofilecadenceduration"></a>`duration` | [`Int`](#int) | Duration of the DAST profile cadence. | +| <a id="dastprofilecadenceunit"></a>`unit` | [`DastProfileCadenceUnit`](#dastprofilecadenceunit) | Unit for the duration of DAST profile cadence. | + +### `DastProfileSchedule` + +Represents a DAST profile schedule. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="dastprofilescheduleactive"></a>`active` | [`Boolean`](#boolean) | Status of the DAST profile schedule. | +| <a id="dastprofileschedulecadence"></a>`cadence` | [`DastProfileCadence`](#dastprofilecadence) | Cadence of the DAST profile schedule. | +| <a id="dastprofilescheduleid"></a>`id` | [`DastProfileScheduleID!`](#dastprofilescheduleid) | ID of the DAST profile schedule. | +| <a id="dastprofileschedulenextrunat"></a>`nextRunAt` | [`Time`](#time) | Next run time of the DAST profile schedule in the given timezone. | +| <a id="dastprofileschedulestartsat"></a>`startsAt` | [`Time`](#time) | Start time of the DAST profile schedule in the given timezone. | +| <a id="dastprofilescheduletimezone"></a>`timezone` | [`String`](#string) | Time zone of the start time of the DAST profile schedule. | ### `DastScannerProfile` @@ -8455,8 +8827,8 @@ Represents a DAST scanner profile. | <a id="dastscannerprofilereferencedinsecuritypolicies"></a>`referencedInSecurityPolicies` | [`[String!]`](#string) | List of security policy names that are referencing given project. | | <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) | The maximum number of minutes allowed for the spider to traverse the site. | -| <a id="dastscannerprofiletargettimeout"></a>`targetTimeout` | [`Int`](#int) | The maximum number of seconds allowed for the site under test to respond to a request. | +| <a id="dastscannerprofilespidertimeout"></a>`spiderTimeout` | [`Int`](#int) | Maximum number of minutes allowed for the spider to traverse the site. | +| <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. | ### `DastSiteProfile` @@ -8469,16 +8841,16 @@ Represents a DAST Site Profile. | ---- | ---- | ----------- | | <a id="dastsiteprofileauth"></a>`auth` | [`DastSiteProfileAuth`](#dastsiteprofileauth) | Target authentication details. | | <a id="dastsiteprofileeditpath"></a>`editPath` | [`String`](#string) | Relative web path to the edit page of a site profile. | -| <a id="dastsiteprofileexcludedurls"></a>`excludedUrls` | [`[String!]`](#string) | The URLs to skip during an authenticated scan. | +| <a id="dastsiteprofileexcludedurls"></a>`excludedUrls` | [`[String!]`](#string) | URLs to skip during an authenticated scan. | | <a id="dastsiteprofileid"></a>`id` | [`DastSiteProfileID!`](#dastsiteprofileid) | ID of the site profile. | | <a id="dastsiteprofilenormalizedtargeturl"></a>`normalizedTargetUrl` | [`String`](#string) | Normalized URL of the target to be scanned. | -| <a id="dastsiteprofileprofilename"></a>`profileName` | [`String`](#string) | The name of the site profile. | +| <a id="dastsiteprofileprofilename"></a>`profileName` | [`String`](#string) | Name of the site profile. | | <a id="dastsiteprofilereferencedinsecuritypolicies"></a>`referencedInSecurityPolicies` | [`[String!]`](#string) | List of security policy names that are referencing given project. | | <a id="dastsiteprofilerequestheaders"></a>`requestHeaders` | [`String`](#string) | Comma-separated list of request header names and values to be added to every request made by DAST. | -| <a id="dastsiteprofiletargettype"></a>`targetType` | [`DastTargetTypeEnum`](#dasttargettypeenum) | The type of target to be scanned. | -| <a id="dastsiteprofiletargeturl"></a>`targetUrl` | [`String`](#string) | The URL of the target to be scanned. | +| <a id="dastsiteprofiletargettype"></a>`targetType` | [`DastTargetTypeEnum`](#dasttargettypeenum) | Type of target to be scanned. | +| <a id="dastsiteprofiletargeturl"></a>`targetUrl` | [`String`](#string) | URL of the target to be scanned. | | <a id="dastsiteprofileuserpermissions"></a>`userPermissions` | [`DastSiteProfilePermissions!`](#dastsiteprofilepermissions) | Permissions for the current user on the resource. | -| <a id="dastsiteprofilevalidationstatus"></a>`validationStatus` | [`DastSiteProfileValidationStatusEnum`](#dastsiteprofilevalidationstatusenum) | The current validation status of the site profile. | +| <a id="dastsiteprofilevalidationstatus"></a>`validationStatus` | [`DastSiteProfileValidationStatusEnum`](#dastsiteprofilevalidationstatusenum) | Current validation status of the site profile. | ### `DastSiteProfileAuth` @@ -8490,10 +8862,10 @@ Input type for DastSiteProfile authentication. | ---- | ---- | ----------- | | <a id="dastsiteprofileauthenabled"></a>`enabled` | [`Boolean`](#boolean) | Indicates whether authentication is enabled. | | <a id="dastsiteprofileauthpassword"></a>`password` | [`String`](#string) | Redacted password to authenticate with on the target website. | -| <a id="dastsiteprofileauthpasswordfield"></a>`passwordField` | [`String`](#string) | The name of password field at the sign-in HTML form. | +| <a id="dastsiteprofileauthpasswordfield"></a>`passwordField` | [`String`](#string) | Name of password field at the sign-in HTML form. | | <a id="dastsiteprofileauthurl"></a>`url` | [`String`](#string) | The URL of the page containing the sign-in HTML form on the target website. | -| <a id="dastsiteprofileauthusername"></a>`username` | [`String`](#string) | The username to authenticate with on the target website. | -| <a id="dastsiteprofileauthusernamefield"></a>`usernameField` | [`String`](#string) | The name of username field at the sign-in HTML form. | +| <a id="dastsiteprofileauthusername"></a>`username` | [`String`](#string) | Username to authenticate with on the target website. | +| <a id="dastsiteprofileauthusernamefield"></a>`usernameField` | [`String`](#string) | Name of username field at the sign-in HTML form. | ### `DastSiteProfilePermissions` @@ -8526,8 +8898,59 @@ The response from the AdminSidekiqQueuesDeleteJobs mutation. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="deletejobsresponsecompleted"></a>`completed` | [`Boolean`](#boolean) | Whether or not the entire queue was processed in time; if not, retrying the same request is safe. | -| <a id="deletejobsresponsedeletedjobs"></a>`deletedJobs` | [`Int`](#int) | The number of matching jobs deleted. | -| <a id="deletejobsresponsequeuesize"></a>`queueSize` | [`Int`](#int) | The queue size after processing. | +| <a id="deletejobsresponsedeletedjobs"></a>`deletedJobs` | [`Int`](#int) | Number of matching jobs deleted. | +| <a id="deletejobsresponsequeuesize"></a>`queueSize` | [`Int`](#int) | Queue size after processing. | + +### `DependencyProxyBlob` + +Dependency proxy blob. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="dependencyproxyblobcreatedat"></a>`createdAt` | [`Time!`](#time) | Date of creation. | +| <a id="dependencyproxyblobfilename"></a>`fileName` | [`String!`](#string) | Name of the blob. | +| <a id="dependencyproxyblobsize"></a>`size` | [`String!`](#string) | Size of the blob file. | +| <a id="dependencyproxyblobupdatedat"></a>`updatedAt` | [`Time!`](#time) | Date of most recent update. | + +### `DependencyProxyImageTtlGroupPolicy` + +Group-level Dependency Proxy TTL policy settings. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="dependencyproxyimagettlgrouppolicycreatedat"></a>`createdAt` | [`Time`](#time) | Timestamp of creation. | +| <a id="dependencyproxyimagettlgrouppolicyenabled"></a>`enabled` | [`Boolean!`](#boolean) | Indicates whether the policy is enabled or disabled. | +| <a id="dependencyproxyimagettlgrouppolicyttl"></a>`ttl` | [`Int`](#int) | Number of days to retain a cached image file. | +| <a id="dependencyproxyimagettlgrouppolicyupdatedat"></a>`updatedAt` | [`Time`](#time) | Timestamp of the most recent update. | + +### `DependencyProxyManifest` + +Dependency proxy manifest. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="dependencyproxymanifestcreatedat"></a>`createdAt` | [`Time!`](#time) | Date of creation. | +| <a id="dependencyproxymanifestdigest"></a>`digest` | [`String!`](#string) | Digest of the manifest. | +| <a id="dependencyproxymanifestfilename"></a>`fileName` | [`String!`](#string) | Name of the manifest. | +| <a id="dependencyproxymanifestimagename"></a>`imageName` | [`String!`](#string) | Name of the image. | +| <a id="dependencyproxymanifestsize"></a>`size` | [`String!`](#string) | Size of the manifest file. | +| <a id="dependencyproxymanifestupdatedat"></a>`updatedAt` | [`Time!`](#time) | Date of most recent update. | + +### `DependencyProxySetting` + +Group-level Dependency Proxy settings. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="dependencyproxysettingenabled"></a>`enabled` | [`Boolean!`](#boolean) | Indicates whether the dependency proxy is enabled for the group. | ### `Design` @@ -8537,18 +8960,18 @@ A single design. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="designdiffrefs"></a>`diffRefs` | [`DiffRefs!`](#diffrefs) | The diff refs for this design. | +| <a id="designdiffrefs"></a>`diffRefs` | [`DiffRefs!`](#diffrefs) | Diff refs for this design. | | <a id="designdiscussions"></a>`discussions` | [`DiscussionConnection!`](#discussionconnection) | All discussions on this noteable. (see [Connections](#connections)) | | <a id="designevent"></a>`event` | [`DesignVersionEvent!`](#designversionevent) | How this design was changed in the current version. | -| <a id="designfilename"></a>`filename` | [`String!`](#string) | The filename of the design. | -| <a id="designfullpath"></a>`fullPath` | [`String!`](#string) | The full path to the design file. | -| <a id="designid"></a>`id` | [`ID!`](#id) | The ID of this design. | -| <a id="designimage"></a>`image` | [`String!`](#string) | The URL of the full-sized image. | +| <a id="designfilename"></a>`filename` | [`String!`](#string) | Filename of the design. | +| <a id="designfullpath"></a>`fullPath` | [`String!`](#string) | Full path to the design file. | +| <a id="designid"></a>`id` | [`ID!`](#id) | ID of this design. | +| <a id="designimage"></a>`image` | [`String!`](#string) | URL of the full-sized image. | | <a id="designimagev432x230"></a>`imageV432x230` | [`String`](#string) | The URL of the design resized to fit within the bounds of 432x230. This will be `null` if the image has not been generated. | -| <a id="designissue"></a>`issue` | [`Issue!`](#issue) | The issue the design belongs to. | +| <a id="designissue"></a>`issue` | [`Issue!`](#issue) | Issue the design belongs to. | | <a id="designnotes"></a>`notes` | [`NoteConnection!`](#noteconnection) | All notes on this noteable. (see [Connections](#connections)) | -| <a id="designnotescount"></a>`notesCount` | [`Int!`](#int) | The total count of user-created notes for this design. | -| <a id="designproject"></a>`project` | [`Project!`](#project) | The project the design belongs to. | +| <a id="designnotescount"></a>`notesCount` | [`Int!`](#int) | Total count of user-created notes for this design. | +| <a id="designproject"></a>`project` | [`Project!`](#project) | Project the design belongs to. | #### Fields with arguments @@ -8593,18 +9016,18 @@ A design pinned to a specific version. The image field reflects the design as of | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="designatversiondesign"></a>`design` | [`Design!`](#design) | The underlying design. | -| <a id="designatversiondiffrefs"></a>`diffRefs` | [`DiffRefs!`](#diffrefs) | The diff refs for this design. | +| <a id="designatversiondesign"></a>`design` | [`Design!`](#design) | Underlying design. | +| <a id="designatversiondiffrefs"></a>`diffRefs` | [`DiffRefs!`](#diffrefs) | Diff refs for this design. | | <a id="designatversionevent"></a>`event` | [`DesignVersionEvent!`](#designversionevent) | How this design was changed in the current version. | -| <a id="designatversionfilename"></a>`filename` | [`String!`](#string) | The filename of the design. | -| <a id="designatversionfullpath"></a>`fullPath` | [`String!`](#string) | The full path to the design file. | -| <a id="designatversionid"></a>`id` | [`ID!`](#id) | The ID of this design. | -| <a id="designatversionimage"></a>`image` | [`String!`](#string) | The URL of the full-sized image. | +| <a id="designatversionfilename"></a>`filename` | [`String!`](#string) | Filename of the design. | +| <a id="designatversionfullpath"></a>`fullPath` | [`String!`](#string) | Full path to the design file. | +| <a id="designatversionid"></a>`id` | [`ID!`](#id) | ID of this design. | +| <a id="designatversionimage"></a>`image` | [`String!`](#string) | URL of the full-sized image. | | <a id="designatversionimagev432x230"></a>`imageV432x230` | [`String`](#string) | The URL of the design resized to fit within the bounds of 432x230. This will be `null` if the image has not been generated. | -| <a id="designatversionissue"></a>`issue` | [`Issue!`](#issue) | The issue the design belongs to. | -| <a id="designatversionnotescount"></a>`notesCount` | [`Int!`](#int) | The total count of user-created notes for this design. | -| <a id="designatversionproject"></a>`project` | [`Project!`](#project) | The project the design belongs to. | -| <a id="designatversionversion"></a>`version` | [`DesignVersion!`](#designversion) | The version this design-at-versions is pinned to. | +| <a id="designatversionissue"></a>`issue` | [`Issue!`](#issue) | Issue the design belongs to. | +| <a id="designatversionnotescount"></a>`notesCount` | [`Int!`](#int) | Total count of user-created notes for this design. | +| <a id="designatversionproject"></a>`project` | [`Project!`](#project) | Project the design belongs to. | +| <a id="designatversionversion"></a>`version` | [`DesignVersion!`](#designversion) | Version this design-at-versions is pinned to. | ### `DesignCollection` @@ -8830,16 +9253,16 @@ Snapshot. | <a id="devopsadoptionsnapshotdastenabledcount"></a>`dastEnabledCount` | [`Int`](#int) | Total number of projects with enabled DAST. | | <a id="devopsadoptionsnapshotdependencyscanningenabledcount"></a>`dependencyScanningEnabledCount` | [`Int`](#int) | Total number of projects with enabled dependency scanning. | | <a id="devopsadoptionsnapshotdeploysucceeded"></a>`deploySucceeded` | [`Boolean!`](#boolean) | At least one deployment succeeded. | -| <a id="devopsadoptionsnapshotendtime"></a>`endTime` | [`Time!`](#time) | The end time for the snapshot where the data points were collected. | +| <a id="devopsadoptionsnapshotendtime"></a>`endTime` | [`Time!`](#time) | End time for the snapshot where the data points were collected. | | <a id="devopsadoptionsnapshotissueopened"></a>`issueOpened` | [`Boolean!`](#boolean) | At least one issue was opened. | | <a id="devopsadoptionsnapshotmergerequestapproved"></a>`mergeRequestApproved` | [`Boolean!`](#boolean) | At least one merge request was approved. | | <a id="devopsadoptionsnapshotmergerequestopened"></a>`mergeRequestOpened` | [`Boolean!`](#boolean) | At least one merge request was opened. | | <a id="devopsadoptionsnapshotpipelinesucceeded"></a>`pipelineSucceeded` | [`Boolean!`](#boolean) | At least one pipeline succeeded. | -| <a id="devopsadoptionsnapshotrecordedat"></a>`recordedAt` | [`Time!`](#time) | The time the snapshot was recorded. | +| <a id="devopsadoptionsnapshotrecordedat"></a>`recordedAt` | [`Time!`](#time) | Time the snapshot was recorded. | | <a id="devopsadoptionsnapshotrunnerconfigured"></a>`runnerConfigured` | [`Boolean!`](#boolean) | At least one runner was used. | | <a id="devopsadoptionsnapshotsastenabledcount"></a>`sastEnabledCount` | [`Int`](#int) | Total number of projects with enabled SAST. | | <a id="devopsadoptionsnapshotsecurityscansucceeded"></a>`securityScanSucceeded` **{warning-solid}** | [`Boolean!`](#boolean) | **Deprecated** in 14.1. Substituted with specific security metrics. Always false. | -| <a id="devopsadoptionsnapshotstarttime"></a>`startTime` | [`Time!`](#time) | The start time for the snapshot where the data points were collected. | +| <a id="devopsadoptionsnapshotstarttime"></a>`startTime` | [`Time!`](#time) | Start time for the snapshot where the data points were collected. | | <a id="devopsadoptionsnapshottotalprojectscount"></a>`totalProjectsCount` | [`Int`](#int) | Total number of projects. | | <a id="devopsadoptionsnapshotvulnerabilitymanagementusedcount"></a>`vulnerabilityManagementUsedCount` | [`Int`](#int) | Total number of projects with vulnerability management used at least once. | @@ -8929,9 +9352,9 @@ Returns [`[DoraMetric!]`](#dorametric). | Name | Type | Description | | ---- | ---- | ----------- | | <a id="dorametricsenddate"></a>`endDate` | [`Date`](#date) | Date range to end at. Default is the current date. | -| <a id="dorametricsenvironmenttier"></a>`environmentTier` | [`DeploymentTier`](#deploymenttier) | The deployment tier of the environments to return. Defaults to `PRODUCTION`. | +| <a id="dorametricsenvironmenttier"></a>`environmentTier` | [`DeploymentTier`](#deploymenttier) | Deployment tier of the environments to return. Defaults to `PRODUCTION`. | | <a id="dorametricsinterval"></a>`interval` | [`DoraMetricBucketingInterval`](#dorametricbucketinginterval) | How the metric should be aggregrated. Defaults to `DAILY`. In the case of `ALL`, the `date` field in the response will be `null`. | -| <a id="dorametricsmetric"></a>`metric` | [`DoraMetricType!`](#dorametrictype) | The type of metric to return. | +| <a id="dorametricsmetric"></a>`metric` | [`DoraMetricType!`](#dorametrictype) | Type of metric to return. | | <a id="dorametricsstartdate"></a>`startDate` | [`Date`](#date) | Date range to start from. Default is 3 months ago. | ### `DoraMetric` @@ -8952,9 +9375,9 @@ Describes where code is deployed for a project. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="environmentid"></a>`id` | [`ID!`](#id) | ID of the environment. | -| <a id="environmentlatestopenedmostseverealert"></a>`latestOpenedMostSevereAlert` | [`AlertManagementAlert`](#alertmanagementalert) | The most severe open alert for the environment. If multiple alerts have equal severity, the most recent is returned. | +| <a id="environmentlatestopenedmostseverealert"></a>`latestOpenedMostSevereAlert` | [`AlertManagementAlert`](#alertmanagementalert) | Most severe open alert for the environment. If multiple alerts have equal severity, the most recent is returned. | | <a id="environmentname"></a>`name` | [`String!`](#string) | Human-readable name of the environment. | -| <a id="environmentpath"></a>`path` | [`String!`](#string) | The path to the environment. | +| <a id="environmentpath"></a>`path` | [`String!`](#string) | Path to the environment. | | <a id="environmentstate"></a>`state` | [`String!`](#string) | State of the environment, for example: available/stopped. | #### Fields with arguments @@ -8980,7 +9403,7 @@ Represents an epic. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="epicauthor"></a>`author` | [`UserCore!`](#usercore) | Author of the epic. | -| <a id="epicawardemoji"></a>`awardEmoji` | [`AwardEmojiConnection`](#awardemojiconnection) | A list of award emojis associated with the epic. (see [Connections](#connections)) | +| <a id="epicawardemoji"></a>`awardEmoji` | [`AwardEmojiConnection`](#awardemojiconnection) | List of award emojis associated with the epic. (see [Connections](#connections)) | | <a id="epicclosedat"></a>`closedAt` | [`Time`](#time) | Timestamp of when the epic was closed. | | <a id="epicconfidential"></a>`confidential` | [`Boolean`](#boolean) | Indicates if the epic is confidential. | | <a id="epiccreatedat"></a>`createdAt` | [`Time`](#time) | Timestamp of when the epic was created. | @@ -8994,7 +9417,7 @@ Represents an epic. | <a id="epicduedatefixed"></a>`dueDateFixed` | [`Time`](#time) | Fixed due date of the epic. | | <a id="epicduedatefrommilestones"></a>`dueDateFromMilestones` | [`Time`](#time) | Inherited due date of the epic from milestones. | | <a id="epicduedateisfixed"></a>`dueDateIsFixed` | [`Boolean`](#boolean) | Indicates if the due date has been manually set. | -| <a id="epicevents"></a>`events` | [`EventConnection`](#eventconnection) | A list of events associated with the object. (see [Connections](#connections)) | +| <a id="epicevents"></a>`events` | [`EventConnection`](#eventconnection) | List of events associated with the object. (see [Connections](#connections)) | | <a id="epicgroup"></a>`group` | [`Group!`](#group) | Group to which the epic belongs. | | <a id="epichaschildren"></a>`hasChildren` | [`Boolean!`](#boolean) | Indicates if the epic has children. | | <a id="epichasissues"></a>`hasIssues` | [`Boolean!`](#boolean) | Indicates if the epic has direct issues. | @@ -9008,7 +9431,7 @@ Represents an epic. | <a id="epicparent"></a>`parent` | [`Epic`](#epic) | Parent epic of the epic. | | <a id="epicparticipants"></a>`participants` | [`UserCoreConnection`](#usercoreconnection) | List of participants for the epic. (see [Connections](#connections)) | | <a id="epicrelationpath"></a>`relationPath` | [`String`](#string) | URI path of the epic-issue relationship. | -| <a id="epicrelativeposition"></a>`relativePosition` | [`Int`](#int) | The relative position of the epic in the epic tree. | +| <a id="epicrelativeposition"></a>`relativePosition` | [`Int`](#int) | Relative position of the epic in the epic tree. | | <a id="epicstartdate"></a>`startDate` | [`Time`](#time) | Start date of the epic. | | <a id="epicstartdatefixed"></a>`startDateFixed` | [`Time`](#time) | Fixed start date of the epic. | | <a id="epicstartdatefrommilestones"></a>`startDateFromMilestones` | [`Time`](#time) | Inherited start date of the epic from milestones. | @@ -9222,6 +9645,7 @@ Relationship between an epic and an issue. | <a id="epicissueepic"></a>`epic` | [`Epic`](#epic) | Epic to which this issue belongs. | | <a id="epicissueepicissueid"></a>`epicIssueId` | [`ID!`](#id) | ID of the epic-issue relation. | | <a id="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="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. | @@ -9349,9 +9773,9 @@ Represents an escalation policy. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="escalationpolicytypedescription"></a>`description` | [`String`](#string) | The description of the escalation policy. | +| <a id="escalationpolicytypedescription"></a>`description` | [`String`](#string) | Description of the escalation policy. | | <a id="escalationpolicytypeid"></a>`id` | [`IncidentManagementEscalationPolicyID`](#incidentmanagementescalationpolicyid) | ID of the escalation policy. | -| <a id="escalationpolicytypename"></a>`name` | [`String`](#string) | The name of the escalation policy. | +| <a id="escalationpolicytypename"></a>`name` | [`String`](#string) | Name of the escalation policy. | | <a id="escalationpolicytyperules"></a>`rules` | [`[EscalationRuleType!]`](#escalationruletype) | Steps of the escalation policy. | ### `EscalationRuleType` @@ -9362,11 +9786,11 @@ Represents an escalation rule for an escalation policy. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="escalationruletypeelapsedtimeseconds"></a>`elapsedTimeSeconds` | [`Int`](#int) | The time in seconds before the rule is activated. | +| <a id="escalationruletypeelapsedtimeseconds"></a>`elapsedTimeSeconds` | [`Int`](#int) | Time in seconds before the rule is activated. | | <a id="escalationruletypeid"></a>`id` | [`IncidentManagementEscalationRuleID`](#incidentmanagementescalationruleid) | ID of the escalation policy. | -| <a id="escalationruletypeoncallschedule"></a>`oncallSchedule` | [`IncidentManagementOncallSchedule`](#incidentmanagementoncallschedule) | The on-call schedule to notify. | -| <a id="escalationruletypestatus"></a>`status` | [`EscalationRuleStatus`](#escalationrulestatus) | The status required to prevent the rule from activating. | -| <a id="escalationruletypeuser"></a>`user` | [`UserCore`](#usercore) | The user to notify. | +| <a id="escalationruletypeoncallschedule"></a>`oncallSchedule` | [`IncidentManagementOncallSchedule`](#incidentmanagementoncallschedule) | On-call schedule to notify. | +| <a id="escalationruletypestatus"></a>`status` | [`EscalationRuleStatus`](#escalationrulestatus) | Status required to prevent the rule from activating. | +| <a id="escalationruletypeuser"></a>`user` | [`UserCore`](#usercore) | User to notify. | ### `Event` @@ -9404,21 +9828,21 @@ Represents an external issue. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="geonodecontainerrepositoriesmaxcapacity"></a>`containerRepositoriesMaxCapacity` | [`Int`](#int) | The maximum concurrency of container repository sync for this secondary node. | +| <a id="geonodecontainerrepositoriesmaxcapacity"></a>`containerRepositoriesMaxCapacity` | [`Int`](#int) | Maximum concurrency of container repository sync for this secondary node. | | <a id="geonodeenabled"></a>`enabled` | [`Boolean`](#boolean) | Indicates whether this Geo node is enabled. | -| <a id="geonodefilesmaxcapacity"></a>`filesMaxCapacity` | [`Int`](#int) | The maximum concurrency of LFS/attachment backfill for this secondary node. | +| <a id="geonodefilesmaxcapacity"></a>`filesMaxCapacity` | [`Int`](#int) | Maximum concurrency of LFS/attachment backfill for this secondary node. | | <a id="geonodeid"></a>`id` | [`ID!`](#id) | ID of this GeoNode. | -| <a id="geonodeinternalurl"></a>`internalUrl` | [`String`](#string) | The URL defined on the primary node that secondary nodes should use to contact it. | -| <a id="geonodeminimumreverificationinterval"></a>`minimumReverificationInterval` | [`Int`](#int) | The interval (in days) in which the repository verification is valid. Once expired, it will be reverified. | -| <a id="geonodename"></a>`name` | [`String`](#string) | The unique identifier for this Geo node. | +| <a id="geonodeinternalurl"></a>`internalUrl` | [`String`](#string) | URL defined on the primary node secondary nodes should use to contact it. | +| <a id="geonodeminimumreverificationinterval"></a>`minimumReverificationInterval` | [`Int`](#int) | Interval (in days) in which the repository verification is valid. After expiry, it is reverted. | +| <a id="geonodename"></a>`name` | [`String`](#string) | Unique identifier for this Geo node. | | <a id="geonodeprimary"></a>`primary` | [`Boolean`](#boolean) | Indicates whether this Geo node is the primary. | -| <a id="geonodereposmaxcapacity"></a>`reposMaxCapacity` | [`Int`](#int) | The maximum concurrency of repository backfill for this secondary node. | -| <a id="geonodeselectivesyncnamespaces"></a>`selectiveSyncNamespaces` | [`NamespaceConnection`](#namespaceconnection) | The namespaces that should be synced, if `selective_sync_type` == `namespaces`. (see [Connections](#connections)) | -| <a id="geonodeselectivesyncshards"></a>`selectiveSyncShards` | [`[String!]`](#string) | The repository storages whose projects should be synced, if `selective_sync_type` == `shards`. | +| <a id="geonodereposmaxcapacity"></a>`reposMaxCapacity` | [`Int`](#int) | Maximum concurrency of repository backfill for this secondary node. | +| <a id="geonodeselectivesyncnamespaces"></a>`selectiveSyncNamespaces` | [`NamespaceConnection`](#namespaceconnection) | Namespaces that should be synced, if `selective_sync_type` == `namespaces`. (see [Connections](#connections)) | +| <a id="geonodeselectivesyncshards"></a>`selectiveSyncShards` | [`[String!]`](#string) | Repository storages whose projects should be synced, if `selective_sync_type` == `shards`. | | <a id="geonodeselectivesynctype"></a>`selectiveSyncType` | [`String`](#string) | Indicates if syncing is limited to only specific groups, or shards. | | <a id="geonodesyncobjectstorage"></a>`syncObjectStorage` | [`Boolean`](#boolean) | Indicates if this secondary node will replicate blobs in Object Storage. | -| <a id="geonodeurl"></a>`url` | [`String`](#string) | The user-facing URL for this Geo node. | -| <a id="geonodeverificationmaxcapacity"></a>`verificationMaxCapacity` | [`Int`](#int) | The maximum concurrency of repository verification for this secondary node. | +| <a id="geonodeurl"></a>`url` | [`String`](#string) | User-facing URL for this Geo node. | +| <a id="geonodeverificationmaxcapacity"></a>`verificationMaxCapacity` | [`Int`](#int) | Maximum concurrency of repository verification for this secondary node. | #### Fields with arguments @@ -9486,6 +9910,22 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | <a id="geonodepackagefileregistriesids"></a>`ids` | [`[ID!]`](#id) | Filters registries by their ID. | +##### `GeoNode.pagesDeploymentRegistries` + +Find Pages Deployment registries on this Geo node. + +Returns [`PagesDeploymentRegistryConnection`](#pagesdeploymentregistryconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="geonodepagesdeploymentregistriesids"></a>`ids` | [`[ID!]`](#id) | Filters registries by their ID. | + ##### `GeoNode.pipelineArtifactRegistries` Find pipeline artifact registries on this Geo node. @@ -9534,6 +9974,22 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | <a id="geonodeterraformstateversionregistriesids"></a>`ids` | [`[ID!]`](#id) | Filters registries by their ID. | +##### `GeoNode.uploadRegistries` + +Find Upload registries on this Geo node Available only when feature flag `geo_upload_replication` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. + +Returns [`UploadRegistryConnection`](#uploadregistryconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="geonodeuploadregistriesids"></a>`ids` | [`[ID!]`](#id) | Filters registries by their ID. | + ### `GrafanaIntegration` #### Fields @@ -9556,13 +10012,22 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="groupadditionalpurchasedstoragesize"></a>`additionalPurchasedStorageSize` | [`Float`](#float) | Additional storage purchased for the root namespace in bytes. | | <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="groupbillablememberscount"></a>`billableMembersCount` | [`Int`](#int) | The number of billable users in the group. | +| <a id="groupbillablememberscount"></a>`billableMembersCount` | [`Int`](#int) | Number of billable users in the group. | +| <a id="groupcontacts"></a>`contacts` | [`CustomerRelationsContactConnection`](#customerrelationscontactconnection) | Find contacts of this group. (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="groupcustomemoji"></a>`customEmoji` | [`CustomEmojiConnection`](#customemojiconnection) | Custom emoji within this namespace. Available only when feature flag `custom_emoji` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. (see [Connections](#connections)) | +| <a id="groupdependencyproxyblobcount"></a>`dependencyProxyBlobCount` | [`Int!`](#int) | Number of dependency proxy blobs cached in the group. | +| <a id="groupdependencyproxyblobs"></a>`dependencyProxyBlobs` | [`DependencyProxyBlobConnection`](#dependencyproxyblobconnection) | Dependency Proxy blobs. (see [Connections](#connections)) | +| <a id="groupdependencyproxyimagecount"></a>`dependencyProxyImageCount` | [`Int!`](#int) | Number of dependency proxy images cached in the group. | +| <a id="groupdependencyproxyimageprefix"></a>`dependencyProxyImagePrefix` | [`String!`](#string) | Prefix for pulling images when using the dependency proxy. | +| <a id="groupdependencyproxyimagettlpolicy"></a>`dependencyProxyImageTtlPolicy` | [`DependencyProxyImageTtlGroupPolicy`](#dependencyproxyimagettlgrouppolicy) | Dependency proxy TTL policy for the group. | +| <a id="groupdependencyproxymanifests"></a>`dependencyProxyManifests` | [`DependencyProxyManifestConnection`](#dependencyproxymanifestconnection) | Dependency Proxy manifests. (see [Connections](#connections)) | +| <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="groupdora"></a>`dora` | [`Dora`](#dora) | The group's DORA metrics. | +| <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="groupepicboards"></a>`epicBoards` | [`EpicBoardConnection`](#epicboardconnection) | Find epic boards. (see [Connections](#connections)) | | <a id="groupepicsenabled"></a>`epicsEnabled` | [`Boolean`](#boolean) | Indicates if Epics are enabled for namespace. | @@ -9573,10 +10038,11 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="grouplfsenabled"></a>`lfsEnabled` | [`Boolean`](#boolean) | Indicates if Large File Storage (LFS) is enabled for namespace. | | <a id="groupmentionsdisabled"></a>`mentionsDisabled` | [`Boolean`](#boolean) | Indicates if a group is disabled from getting mentioned. | | <a id="groupname"></a>`name` | [`String!`](#string) | Name of the namespace. | -| <a id="grouppackagesettings"></a>`packageSettings` | [`PackageSettings`](#packagesettings) | The package settings for the namespace. | +| <a id="grouporganizations"></a>`organizations` | [`CustomerRelationsOrganizationConnection`](#customerrelationsorganizationconnection) | Find organizations of this group. (see [Connections](#connections)) | +| <a id="grouppackagesettings"></a>`packageSettings` | [`PackageSettings`](#packagesettings) | Package settings for the namespace. | | <a id="groupparent"></a>`parent` | [`Group`](#group) | Parent group. | | <a id="grouppath"></a>`path` | [`String!`](#string) | Path of the namespace. | -| <a id="groupprojectcreationlevel"></a>`projectCreationLevel` | [`String`](#string) | The permission level required to create projects in the group. | +| <a id="groupprojectcreationlevel"></a>`projectCreationLevel` | [`String`](#string) | Permission level required to create projects in the group. | | <a id="grouprepositorysizeexcessprojectcount"></a>`repositorySizeExcessProjectCount` | [`Int!`](#int) | Number of projects in the root namespace where the repository size exceeds the limit. | | <a id="grouprequestaccessenabled"></a>`requestAccessEnabled` | [`Boolean`](#boolean) | Indicates if users can request access to namespace. | | <a id="grouprequiretwofactorauthentication"></a>`requireTwoFactorAuthentication` | [`Boolean`](#boolean) | Indicates if all users in this group are required to set up two-factor authentication. | @@ -9585,7 +10051,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="groupsharedrunnerssetting"></a>`sharedRunnersSetting` | [`SharedRunnersSetting`](#sharedrunnerssetting) | Shared runners availability for the namespace and its descendants. | | <a id="groupstats"></a>`stats` | [`GroupStats`](#groupstats) | Group statistics. | | <a id="groupstoragesizelimit"></a>`storageSizeLimit` | [`Float`](#float) | Total storage limit of the root namespace in bytes. | -| <a id="groupsubgroupcreationlevel"></a>`subgroupCreationLevel` | [`String`](#string) | The permission level required to create subgroups within the group. | +| <a id="groupsubgroupcreationlevel"></a>`subgroupCreationLevel` | [`String`](#string) | Permission level required to create subgroups within the group. | | <a id="grouptemporarystorageincreaseendson"></a>`temporaryStorageIncreaseEndsOn` | [`Time`](#time) | Date until the temporary storage increase is active. | | <a id="grouptotalrepositorysize"></a>`totalRepositorySize` | [`Float`](#float) | Total repository size of all projects in the root namespace in bytes. | | <a id="grouptotalrepositorysizeexcess"></a>`totalRepositorySizeExcess` | [`Float`](#float) | Total excess repository size of all projects in the root namespace in bytes. | @@ -9797,7 +10263,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="groupissuesassigneeid"></a>`assigneeId` | [`String`](#string) | ID of a user assigned to the issues, "none" and "any" values are supported. | +| <a id="groupissuesassigneeid"></a>`assigneeId` | [`String`](#string) | ID of a user assigned to the issues. Wildcard values "NONE" and "ANY" are supported. | | <a id="groupissuesassigneeusername"></a>`assigneeUsername` **{warning-solid}** | [`String`](#string) | **Deprecated** in 13.11. Use `assigneeUsernames`. | | <a id="groupissuesassigneeusernames"></a>`assigneeUsernames` | [`[String!]`](#string) | Usernames of users assigned to the issue. | | <a id="groupissuesauthorusername"></a>`authorUsername` | [`String`](#string) | Username of the author of the issue. | @@ -9814,6 +10280,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="groupissueslabelname"></a>`labelName` | [`[String]`](#string) | Labels applied to this issue. | | <a id="groupissuesmilestonetitle"></a>`milestoneTitle` | [`[String]`](#string) | Milestone applied to this issue. | | <a id="groupissuesmilestonewildcardid"></a>`milestoneWildcardId` | [`MilestoneWildcardId`](#milestonewildcardid) | Filter issues by milestone ID wildcard. | +| <a id="groupissuesmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. Wildcard values "NONE" and "ANY" are supported. | | <a id="groupissuesnot"></a>`not` | [`NegatedIssueFilterInput`](#negatedissuefilterinput) | Negated arguments. | | <a id="groupissuessearch"></a>`search` | [`String`](#string) | Search query for issue title or description. | | <a id="groupissuessort"></a>`sort` | [`IssueSort`](#issuesort) | Sort issues by this criteria. | @@ -9870,7 +10337,7 @@ four standard [pagination arguments](#connection-pagination-arguments): ##### `Group.label` -A label available on this group. +Label available on this group. Returns [`Label`](#label). @@ -9897,7 +10364,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="grouplabelsincludeancestorgroups"></a>`includeAncestorGroups` | [`Boolean`](#boolean) | Include labels from ancestor groups. | | <a id="grouplabelsincludedescendantgroups"></a>`includeDescendantGroups` | [`Boolean`](#boolean) | Include labels from descendant groups. | | <a id="grouplabelsonlygrouplabels"></a>`onlyGroupLabels` | [`Boolean`](#boolean) | Include only group level labels. | -| <a id="grouplabelssearchterm"></a>`searchTerm` | [`String`](#string) | A search term to find labels with. | +| <a id="grouplabelssearchterm"></a>`searchTerm` | [`String`](#string) | Search term to find labels with. | ##### `Group.mergeRequests` @@ -9924,7 +10391,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="groupmergerequestsnot"></a>`not` | [`MergeRequestsResolverNegatedParams`](#mergerequestsresolvernegatedparams) | List of negated arguments. Warning: this argument is experimental and a subject to change in future. | | <a id="groupmergerequestssort"></a>`sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | | <a id="groupmergerequestssourcebranches"></a>`sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | -| <a id="groupmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | A merge request state. If provided, all resolved merge requests will have this state. | +| <a id="groupmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | <a id="groupmergerequeststargetbranches"></a>`targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | ##### `Group.milestones` @@ -9941,17 +10408,17 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="groupmilestonescontainingdate"></a>`containingDate` | [`Time`](#time) | A date that the milestone contains. | +| <a id="groupmilestonescontainingdate"></a>`containingDate` | [`Time`](#time) | Date the milestone contains. | | <a id="groupmilestonesenddate"></a>`endDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.end. | | <a id="groupmilestonesids"></a>`ids` | [`[ID!]`](#id) | Array of global milestone IDs, e.g., `"gid://gitlab/Milestone/1"`. | | <a id="groupmilestonesincludeancestors"></a>`includeAncestors` | [`Boolean`](#boolean) | Include milestones from all parent groups. | | <a id="groupmilestonesincludedescendants"></a>`includeDescendants` | [`Boolean`](#boolean) | Include milestones from all subgroups and subprojects. | -| <a id="groupmilestonessearchtitle"></a>`searchTitle` | [`String`](#string) | A search string for the title. | +| <a id="groupmilestonessearchtitle"></a>`searchTitle` | [`String`](#string) | Search string for the title. | | <a id="groupmilestonessort"></a>`sort` | [`MilestoneSort`](#milestonesort) | Sort milestones by this criteria. | | <a id="groupmilestonesstartdate"></a>`startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | | <a id="groupmilestonesstate"></a>`state` | [`MilestoneStateEnum`](#milestonestateenum) | Filter milestones by state. | | <a id="groupmilestonestimeframe"></a>`timeframe` | [`Timeframe`](#timeframe) | List items overlapping the given timeframe. | -| <a id="groupmilestonestitle"></a>`title` | [`String`](#string) | The title of the milestone. | +| <a id="groupmilestonestitle"></a>`title` | [`String`](#string) | Title of the milestone. | ##### `Group.packages` @@ -9994,6 +10461,27 @@ four standard [pagination arguments](#connection-pagination-arguments): | <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. | +##### `Group.runners` + +Find runners visible to the current user. + +Returns [`CiRunnerConnection`](#cirunnerconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="grouprunnersmembership"></a>`membership` | [`RunnerMembershipFilter`](#runnermembershipfilter) | Control which runners to include in the results. | +| <a id="grouprunnerssearch"></a>`search` | [`String`](#string) | Filter by full token or partial text in description field. | +| <a id="grouprunnerssort"></a>`sort` | [`CiRunnerSort`](#cirunnersort) | Sort order of results. | +| <a id="grouprunnersstatus"></a>`status` | [`CiRunnerStatus`](#cirunnerstatus) | Filter runners by status. | +| <a id="grouprunnerstaglist"></a>`tagList` | [`[String!]`](#string) | Filter by tags associated with the runner (comma-separated or array). | +| <a id="grouprunnerstype"></a>`type` | [`CiRunnerType`](#cirunnertype) | Filter runners by type. | + ##### `Group.timelogs` Time logged on issues and merge requests in the group and its subgroups. @@ -10112,6 +10600,7 @@ Represents a Group Membership. | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="grouppermissionscreateprojects"></a>`createProjects` | [`Boolean!`](#boolean) | Indicates the user can perform `create_projects` on this resource. | | <a id="grouppermissionsreadgroup"></a>`readGroup` | [`Boolean!`](#boolean) | Indicates the user can perform `read_group` on this resource. | ### `GroupReleaseStats` @@ -10199,6 +10688,7 @@ Describes an incident management on-call schedule. | <a id="incidentmanagementoncallscheduledescription"></a>`description` | [`String`](#string) | Description of the on-call schedule. | | <a id="incidentmanagementoncallscheduleiid"></a>`iid` | [`ID!`](#id) | Internal ID of the on-call schedule. | | <a id="incidentmanagementoncallschedulename"></a>`name` | [`String!`](#string) | Name of the on-call schedule. | +| <a id="incidentmanagementoncallscheduleoncallusers"></a>`oncallUsers` | [`[UserCore!]`](#usercore) | | | <a id="incidentmanagementoncallschedulerotations"></a>`rotations` | [`IncidentManagementOncallRotationConnection!`](#incidentmanagementoncallrotationconnection) | On-call rotations for the on-call schedule. (see [Connections](#connections)) | | <a id="incidentmanagementoncallscheduletimezone"></a>`timezone` | [`String!`](#string) | Time zone of the on-call schedule. | @@ -10301,6 +10791,7 @@ Returns [`VulnerabilitySeveritiesCount`](#vulnerabilityseveritiescount). | <a id="issueemailsdisabled"></a>`emailsDisabled` | [`Boolean!`](#boolean) | Indicates if a project has email notifications disabled: `true` if email notifications are disabled. | | <a id="issueepic"></a>`epic` | [`Epic`](#epic) | Epic to which this issue belongs. | | <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="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. | @@ -10521,7 +11012,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | | <a id="kasenabled"></a>`enabled` | [`Boolean!`](#boolean) | Indicates whether the Kubernetes Agent Server is enabled. | -| <a id="kasexternalurl"></a>`externalUrl` | [`String`](#string) | The URL used by the Agents to communicate with KAS. | +| <a id="kasexternalurl"></a>`externalUrl` | [`String`](#string) | URL used by the Agents to communicate with KAS. | | <a id="kasversion"></a>`version` | [`String`](#string) | KAS version. | ### `Label` @@ -10599,6 +11090,7 @@ Maven metadata. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mergerequestallowcollaboration"></a>`allowCollaboration` | [`Boolean`](#boolean) | Indicates if members of the target project can push to the fork. | +| <a id="mergerequestapprovalstate"></a>`approvalState` | [`MergeRequestApprovalState!`](#mergerequestapprovalstate) | Information relating to rules that must be satisfied to merge this merge request. | | <a id="mergerequestapprovalsleft"></a>`approvalsLeft` | [`Int`](#int) | Number of approvals left. | | <a id="mergerequestapprovalsrequired"></a>`approvalsRequired` | [`Int`](#int) | Number of approvals required. | | <a id="mergerequestapproved"></a>`approved` | [`Boolean!`](#boolean) | Indicates if the merge request has all the required approvals. Returns true if no required approvals are configured. | @@ -10628,7 +11120,7 @@ Maven metadata. | <a id="mergerequestforceremovesourcebranch"></a>`forceRemoveSourceBranch` | [`Boolean`](#boolean) | Indicates if the project settings will lead to source branch deletion after merge. | | <a id="mergerequesthasci"></a>`hasCi` | [`Boolean!`](#boolean) | Indicates if the merge request has CI. | | <a id="mergerequesthassecurityreports"></a>`hasSecurityReports` | [`Boolean!`](#boolean) | Indicates if the source branch has any security reports. | -| <a id="mergerequestheadpipeline"></a>`headPipeline` | [`Pipeline`](#pipeline) | The pipeline running on the branch HEAD of the merge request. | +| <a id="mergerequestheadpipeline"></a>`headPipeline` | [`Pipeline`](#pipeline) | Pipeline running on the branch HEAD of the merge request. | | <a id="mergerequesthumantimeestimate"></a>`humanTimeEstimate` | [`String`](#string) | Human-readable time estimate of the merge request. | | <a id="mergerequesthumantotaltimespent"></a>`humanTotalTimeSpent` | [`String`](#string) | Human-readable total time reported as spent on the merge request. | | <a id="mergerequestid"></a>`id` | [`ID!`](#id) | ID of the merge request. | @@ -10646,7 +11138,7 @@ Maven metadata. | <a id="mergerequestmergeable"></a>`mergeable` | [`Boolean!`](#boolean) | Indicates if the merge request is mergeable. | | <a id="mergerequestmergeablediscussionsstate"></a>`mergeableDiscussionsState` | [`Boolean`](#boolean) | Indicates if all discussions in the merge request have been resolved, allowing the merge request to be merged. | | <a id="mergerequestmergedat"></a>`mergedAt` | [`Time`](#time) | Timestamp of when the merge request was merged, null if not merged. | -| <a id="mergerequestmilestone"></a>`milestone` | [`Milestone`](#milestone) | The milestone of the merge request. | +| <a id="mergerequestmilestone"></a>`milestone` | [`Milestone`](#milestone) | Milestone of the merge request. | | <a id="mergerequestnotes"></a>`notes` | [`NoteConnection!`](#noteconnection) | All notes on this noteable. (see [Connections](#connections)) | | <a id="mergerequestparticipants"></a>`participants` | [`UserCoreConnection`](#usercoreconnection) | Participants in the merge request. This includes the author, assignees, reviewers, and users mentioned in notes. (see [Connections](#connections)) | | <a id="mergerequestproject"></a>`project` | [`Project!`](#project) | Alias for target_project. | @@ -10713,7 +11205,7 @@ Returns [`[DiffStats!]`](#diffstats). | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="mergerequestdiffstatspath"></a>`path` | [`String`](#string) | A specific file-path. | +| <a id="mergerequestdiffstatspath"></a>`path` | [`String`](#string) | Specific file path. | ##### `MergeRequest.pipelines` @@ -10731,6 +11223,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | <a id="mergerequestpipelinesref"></a>`ref` | [`String`](#string) | Filter pipelines by the ref they are run for. | | <a id="mergerequestpipelinessha"></a>`sha` | [`String`](#string) | Filter pipelines by the sha of the commit they are run for. | +| <a id="mergerequestpipelinessource"></a>`source` | [`String`](#string) | Filter pipelines by their source. Will be ignored if `dast_view_scans` feature flag is disabled. | | <a id="mergerequestpipelinesstatus"></a>`status` | [`PipelineStatusEnum`](#pipelinestatusenum) | Filter pipelines by their status. | ##### `MergeRequest.reference` @@ -10745,6 +11238,17 @@ Returns [`String!`](#string). | ---- | ---- | ----------- | | <a id="mergerequestreferencefull"></a>`full` | [`Boolean`](#boolean) | Boolean option specifying whether the reference should be returned in full. | +### `MergeRequestApprovalState` + +Information relating to rules that must be satisfied to merge this merge request. + +#### Fields + +| 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="mergerequestapprovalstaterules"></a>`rules` | [`[ApprovalRule!]`](#approvalrule) | List of approval rules associated with the merge request. | + ### `MergeRequestAssignee` A user assigned to a merge request. @@ -10760,7 +11264,7 @@ A user assigned to a merge request. | <a id="mergerequestassigneegroupcount"></a>`groupCount` | [`Int`](#int) | Group count for the user. | | <a id="mergerequestassigneegroupmemberships"></a>`groupMemberships` | [`GroupMemberConnection`](#groupmemberconnection) | Group memberships of the user. (see [Connections](#connections)) | | <a id="mergerequestassigneeid"></a>`id` | [`ID!`](#id) | ID of the user. | -| <a id="mergerequestassigneelocation"></a>`location` | [`String`](#string) | The location of the user. | +| <a id="mergerequestassigneelocation"></a>`location` | [`String`](#string) | Location of the user. | | <a id="mergerequestassigneemergerequestinteraction"></a>`mergeRequestInteraction` | [`UserMergeRequestInteraction`](#usermergerequestinteraction) | Details of this user's interactions with the merge request. | | <a id="mergerequestassigneename"></a>`name` | [`String!`](#string) | Human-readable name of the user. | | <a id="mergerequestassigneenamespace"></a>`namespace` | [`Namespace`](#namespace) | Personal namespace of the user. | @@ -10801,7 +11305,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="mergerequestassigneeassignedmergerequestsreviewerusername"></a>`reviewerUsername` | [`String`](#string) | Username of the reviewer. | | <a id="mergerequestassigneeassignedmergerequestssort"></a>`sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | | <a id="mergerequestassigneeassignedmergerequestssourcebranches"></a>`sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | -| <a id="mergerequestassigneeassignedmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | A merge request state. If provided, all resolved merge requests will have this state. | +| <a id="mergerequestassigneeassignedmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | <a id="mergerequestassigneeassignedmergerequeststargetbranches"></a>`targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | ##### `MergeRequestAssignee.authoredMergeRequests` @@ -10830,9 +11334,26 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="mergerequestassigneeauthoredmergerequestsreviewerusername"></a>`reviewerUsername` | [`String`](#string) | Username of the reviewer. | | <a id="mergerequestassigneeauthoredmergerequestssort"></a>`sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | | <a id="mergerequestassigneeauthoredmergerequestssourcebranches"></a>`sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | -| <a id="mergerequestassigneeauthoredmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | A merge request state. If provided, all resolved merge requests will have this state. | +| <a id="mergerequestassigneeauthoredmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | <a id="mergerequestassigneeauthoredmergerequeststargetbranches"></a>`targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | +##### `MergeRequestAssignee.groups` + +Groups where the user has access. Will always return `null` if `paginatable_namespace_drop_down_for_project_creation` feature flag is disabled. + +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="mergerequestassigneegroupspermissionscope"></a>`permissionScope` | [`GroupPermission`](#grouppermission) | Filter by permissions the user has on groups. | +| <a id="mergerequestassigneegroupssearch"></a>`search` | [`String`](#string) | Search by group name or path. | + ##### `MergeRequestAssignee.reviewRequestedMergeRequests` Merge requests assigned to the user for review. @@ -10859,7 +11380,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="mergerequestassigneereviewrequestedmergerequestsprojectpath"></a>`projectPath` | [`String`](#string) | The full-path of the project the authored merge requests should be in. Incompatible with projectId. | | <a id="mergerequestassigneereviewrequestedmergerequestssort"></a>`sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | | <a id="mergerequestassigneereviewrequestedmergerequestssourcebranches"></a>`sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | -| <a id="mergerequestassigneereviewrequestedmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | A merge request state. If provided, all resolved merge requests will have this state. | +| <a id="mergerequestassigneereviewrequestedmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | <a id="mergerequestassigneereviewrequestedmergerequeststargetbranches"></a>`targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | ##### `MergeRequestAssignee.snippets` @@ -10877,7 +11398,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mergerequestassigneesnippetsids"></a>`ids` | [`[SnippetID!]`](#snippetid) | Array of global snippet IDs. For example, `gid://gitlab/ProjectSnippet/1`. | -| <a id="mergerequestassigneesnippetstype"></a>`type` | [`TypeEnum`](#typeenum) | The type of snippet. | +| <a id="mergerequestassigneesnippetstype"></a>`type` | [`TypeEnum`](#typeenum) | Type of snippet. | | <a id="mergerequestassigneesnippetsvisibility"></a>`visibility` | [`VisibilityScopesEnum`](#visibilityscopesenum) | Visibility of the snippet. | ##### `MergeRequestAssignee.starredProjects` @@ -10932,12 +11453,12 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="mergerequestassigneetodosaction"></a>`action` | [`[TodoActionEnum!]`](#todoactionenum) | The action to be filtered. | -| <a id="mergerequestassigneetodosauthorid"></a>`authorId` | [`[ID!]`](#id) | The ID of an author. | -| <a id="mergerequestassigneetodosgroupid"></a>`groupId` | [`[ID!]`](#id) | The ID of a group. | -| <a id="mergerequestassigneetodosprojectid"></a>`projectId` | [`[ID!]`](#id) | The ID of a project. | -| <a id="mergerequestassigneetodosstate"></a>`state` | [`[TodoStateEnum!]`](#todostateenum) | The state of the todo. | -| <a id="mergerequestassigneetodostype"></a>`type` | [`[TodoTargetEnum!]`](#todotargetenum) | The type of the todo. | +| <a id="mergerequestassigneetodosaction"></a>`action` | [`[TodoActionEnum!]`](#todoactionenum) | Action to be filtered. | +| <a id="mergerequestassigneetodosauthorid"></a>`authorId` | [`[ID!]`](#id) | ID of an author. | +| <a id="mergerequestassigneetodosgroupid"></a>`groupId` | [`[ID!]`](#id) | ID of a group. | +| <a id="mergerequestassigneetodosprojectid"></a>`projectId` | [`[ID!]`](#id) | ID of a project. | +| <a id="mergerequestassigneetodosstate"></a>`state` | [`[TodoStateEnum!]`](#todostateenum) | State of the todo. | +| <a id="mergerequestassigneetodostype"></a>`type` | [`[TodoTargetEnum!]`](#todotargetenum) | Type of the todo. | ### `MergeRequestDiffRegistry` @@ -10989,7 +11510,7 @@ A user assigned to a merge request as a reviewer. | <a id="mergerequestreviewergroupcount"></a>`groupCount` | [`Int`](#int) | Group count for the user. | | <a id="mergerequestreviewergroupmemberships"></a>`groupMemberships` | [`GroupMemberConnection`](#groupmemberconnection) | Group memberships of the user. (see [Connections](#connections)) | | <a id="mergerequestreviewerid"></a>`id` | [`ID!`](#id) | ID of the user. | -| <a id="mergerequestreviewerlocation"></a>`location` | [`String`](#string) | The location of the user. | +| <a id="mergerequestreviewerlocation"></a>`location` | [`String`](#string) | Location of the user. | | <a id="mergerequestreviewermergerequestinteraction"></a>`mergeRequestInteraction` | [`UserMergeRequestInteraction`](#usermergerequestinteraction) | Details of this user's interactions with the merge request. | | <a id="mergerequestreviewername"></a>`name` | [`String!`](#string) | Human-readable name of the user. | | <a id="mergerequestreviewernamespace"></a>`namespace` | [`Namespace`](#namespace) | Personal namespace of the user. | @@ -11030,7 +11551,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="mergerequestreviewerassignedmergerequestsreviewerusername"></a>`reviewerUsername` | [`String`](#string) | Username of the reviewer. | | <a id="mergerequestreviewerassignedmergerequestssort"></a>`sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | | <a id="mergerequestreviewerassignedmergerequestssourcebranches"></a>`sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | -| <a id="mergerequestreviewerassignedmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | A merge request state. If provided, all resolved merge requests will have this state. | +| <a id="mergerequestreviewerassignedmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | <a id="mergerequestreviewerassignedmergerequeststargetbranches"></a>`targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | ##### `MergeRequestReviewer.authoredMergeRequests` @@ -11059,9 +11580,26 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="mergerequestreviewerauthoredmergerequestsreviewerusername"></a>`reviewerUsername` | [`String`](#string) | Username of the reviewer. | | <a id="mergerequestreviewerauthoredmergerequestssort"></a>`sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | | <a id="mergerequestreviewerauthoredmergerequestssourcebranches"></a>`sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | -| <a id="mergerequestreviewerauthoredmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | A merge request state. If provided, all resolved merge requests will have this state. | +| <a id="mergerequestreviewerauthoredmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | <a id="mergerequestreviewerauthoredmergerequeststargetbranches"></a>`targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | +##### `MergeRequestReviewer.groups` + +Groups where the user has access. Will always return `null` if `paginatable_namespace_drop_down_for_project_creation` feature flag is disabled. + +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="mergerequestreviewergroupspermissionscope"></a>`permissionScope` | [`GroupPermission`](#grouppermission) | Filter by permissions the user has on groups. | +| <a id="mergerequestreviewergroupssearch"></a>`search` | [`String`](#string) | Search by group name or path. | + ##### `MergeRequestReviewer.reviewRequestedMergeRequests` Merge requests assigned to the user for review. @@ -11088,7 +11626,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="mergerequestreviewerreviewrequestedmergerequestsprojectpath"></a>`projectPath` | [`String`](#string) | The full-path of the project the authored merge requests should be in. Incompatible with projectId. | | <a id="mergerequestreviewerreviewrequestedmergerequestssort"></a>`sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | | <a id="mergerequestreviewerreviewrequestedmergerequestssourcebranches"></a>`sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | -| <a id="mergerequestreviewerreviewrequestedmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | A merge request state. If provided, all resolved merge requests will have this state. | +| <a id="mergerequestreviewerreviewrequestedmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | <a id="mergerequestreviewerreviewrequestedmergerequeststargetbranches"></a>`targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | ##### `MergeRequestReviewer.snippets` @@ -11106,7 +11644,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mergerequestreviewersnippetsids"></a>`ids` | [`[SnippetID!]`](#snippetid) | Array of global snippet IDs. For example, `gid://gitlab/ProjectSnippet/1`. | -| <a id="mergerequestreviewersnippetstype"></a>`type` | [`TypeEnum`](#typeenum) | The type of snippet. | +| <a id="mergerequestreviewersnippetstype"></a>`type` | [`TypeEnum`](#typeenum) | Type of snippet. | | <a id="mergerequestreviewersnippetsvisibility"></a>`visibility` | [`VisibilityScopesEnum`](#visibilityscopesenum) | Visibility of the snippet. | ##### `MergeRequestReviewer.starredProjects` @@ -11161,12 +11699,12 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="mergerequestreviewertodosaction"></a>`action` | [`[TodoActionEnum!]`](#todoactionenum) | The action to be filtered. | -| <a id="mergerequestreviewertodosauthorid"></a>`authorId` | [`[ID!]`](#id) | The ID of an author. | -| <a id="mergerequestreviewertodosgroupid"></a>`groupId` | [`[ID!]`](#id) | The ID of a group. | -| <a id="mergerequestreviewertodosprojectid"></a>`projectId` | [`[ID!]`](#id) | The ID of a project. | -| <a id="mergerequestreviewertodosstate"></a>`state` | [`[TodoStateEnum!]`](#todostateenum) | The state of the todo. | -| <a id="mergerequestreviewertodostype"></a>`type` | [`[TodoTargetEnum!]`](#todotargetenum) | The type of the todo. | +| <a id="mergerequestreviewertodosaction"></a>`action` | [`[TodoActionEnum!]`](#todoactionenum) | Action to be filtered. | +| <a id="mergerequestreviewertodosauthorid"></a>`authorId` | [`[ID!]`](#id) | ID of an author. | +| <a id="mergerequestreviewertodosgroupid"></a>`groupId` | [`[ID!]`](#id) | ID of a group. | +| <a id="mergerequestreviewertodosprojectid"></a>`projectId` | [`[ID!]`](#id) | ID of a project. | +| <a id="mergerequestreviewertodosstate"></a>`state` | [`[TodoStateEnum!]`](#todostateenum) | State of the todo. | +| <a id="mergerequestreviewertodostype"></a>`type` | [`[TodoTargetEnum!]`](#todotargetenum) | Type of the todo. | ### `Metadata` @@ -11285,7 +11823,7 @@ Contains statistics about a milestone. | <a id="namespaceistemporarystorageincreaseenabled"></a>`isTemporaryStorageIncreaseEnabled` | [`Boolean!`](#boolean) | Status of the temporary storage increase. | | <a id="namespacelfsenabled"></a>`lfsEnabled` | [`Boolean`](#boolean) | Indicates if Large File Storage (LFS) is enabled for namespace. | | <a id="namespacename"></a>`name` | [`String!`](#string) | Name of the namespace. | -| <a id="namespacepackagesettings"></a>`packageSettings` | [`PackageSettings`](#packagesettings) | The package settings for the namespace. | +| <a id="namespacepackagesettings"></a>`packageSettings` | [`PackageSettings`](#packagesettings) | Package settings for the namespace. | | <a id="namespacepath"></a>`path` | [`String!`](#string) | Path of the namespace. | | <a id="namespacerepositorysizeexcessprojectcount"></a>`repositorySizeExcessProjectCount` | [`Int!`](#int) | Number of projects in the root namespace where the repository size exceeds the limit. | | <a id="namespacerequestaccessenabled"></a>`requestAccessEnabled` | [`Boolean`](#boolean) | Indicates if users can request access to namespace. | @@ -11364,9 +11902,9 @@ Represents the network policy. | <a id="notebodyhtml"></a>`bodyHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `note`. | | <a id="noteconfidential"></a>`confidential` | [`Boolean`](#boolean) | Indicates if this note is confidential. | | <a id="notecreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp of the note creation. | -| <a id="notediscussion"></a>`discussion` | [`Discussion`](#discussion) | The discussion this note is a part of. | +| <a id="notediscussion"></a>`discussion` | [`Discussion`](#discussion) | Discussion this note is a part of. | | <a id="noteid"></a>`id` | [`NoteID!`](#noteid) | ID of the note. | -| <a id="noteposition"></a>`position` | [`DiffPosition`](#diffposition) | The position of this note on a diff. | +| <a id="noteposition"></a>`position` | [`DiffPosition`](#diffposition) | Position of this note on a diff. | | <a id="noteproject"></a>`project` | [`Project`](#project) | Project associated with the note. | | <a id="noteresolvable"></a>`resolvable` | [`Boolean!`](#boolean) | Indicates if the object can be resolved. | | <a id="noteresolved"></a>`resolved` | [`Boolean!`](#boolean) | Indicates if the object is resolved. | @@ -11423,10 +11961,10 @@ The rotation participant and color palette. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="oncallparticipanttypecolorpalette"></a>`colorPalette` | [`String`](#string) | The color palette to assign to the on-call user. For example "blue". | -| <a id="oncallparticipanttypecolorweight"></a>`colorWeight` | [`String`](#string) | The color weight to assign to for the on-call user, for example "500". Max 4 chars. For easy identification of the user. | +| <a id="oncallparticipanttypecolorpalette"></a>`colorPalette` | [`String`](#string) | Color palette to assign to the on-call user. For example "blue". | +| <a id="oncallparticipanttypecolorweight"></a>`colorWeight` | [`String`](#string) | Color weight to assign to for the on-call user, for example "500". Max 4 chars. For easy identification of the user. | | <a id="oncallparticipanttypeid"></a>`id` | [`IncidentManagementOncallParticipantID!`](#incidentmanagementoncallparticipantid) | ID of the on-call participant. | -| <a id="oncallparticipanttypeuser"></a>`user` | [`UserCore!`](#usercore) | The user who is participating. | +| <a id="oncallparticipanttypeuser"></a>`user` | [`UserCore!`](#usercore) | User who is participating. | ### `OncallRotationActivePeriodType` @@ -11436,8 +11974,8 @@ Active period time range for on-call rotation. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="oncallrotationactiveperiodtypeendtime"></a>`endTime` | [`String`](#string) | The end of the rotation active period. | -| <a id="oncallrotationactiveperiodtypestarttime"></a>`startTime` | [`String`](#string) | The start of the rotation active period. | +| <a id="oncallrotationactiveperiodtypeendtime"></a>`endTime` | [`String`](#string) | End of the rotation active period. | +| <a id="oncallrotationactiveperiodtypestarttime"></a>`startTime` | [`String`](#string) | Start of the rotation active period. | ### `Package` @@ -11468,10 +12006,10 @@ Represents a composer JSON file. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="packagecomposerjsontypelicense"></a>`license` | [`String`](#string) | The license set in the Composer JSON file. | -| <a id="packagecomposerjsontypename"></a>`name` | [`String`](#string) | The name set in the Composer JSON file. | -| <a id="packagecomposerjsontypetype"></a>`type` | [`String`](#string) | The type set in the Composer JSON file. | -| <a id="packagecomposerjsontypeversion"></a>`version` | [`String`](#string) | The version set in the Composer JSON file. | +| <a id="packagecomposerjsontypelicense"></a>`license` | [`String`](#string) | License set in the Composer JSON file. | +| <a id="packagecomposerjsontypename"></a>`name` | [`String`](#string) | Name set in the Composer JSON file. | +| <a id="packagecomposerjsontypetype"></a>`type` | [`String`](#string) | Type set in the Composer JSON file. | +| <a id="packagecomposerjsontypeversion"></a>`version` | [`String`](#string) | Version set in the Composer JSON file. | ### `PackageDependency` @@ -11519,7 +12057,7 @@ Represents a package details in the Package Registry. Note that this type is in | <a id="packagedetailstypetags"></a>`tags` | [`PackageTagConnection`](#packagetagconnection) | Package tags. (see [Connections](#connections)) | | <a id="packagedetailstypeupdatedat"></a>`updatedAt` | [`Time!`](#time) | Date of most recent update. | | <a id="packagedetailstypeversion"></a>`version` | [`String`](#string) | Version string. | -| <a id="packagedetailstypeversions"></a>`versions` | [`PackageConnection`](#packageconnection) | The other versions of the package. (see [Connections](#connections)) | +| <a id="packagedetailstypeversions"></a>`versions` | [`PackageConnection`](#packageconnection) | Other versions of the package. (see [Connections](#connections)) | ### `PackageFile` @@ -11529,7 +12067,7 @@ Represents a package file. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="packagefilecreatedat"></a>`createdAt` | [`Time!`](#time) | The created date. | +| <a id="packagefilecreatedat"></a>`createdAt` | [`Time!`](#time) | Created date. | | <a id="packagefiledownloadpath"></a>`downloadPath` | [`String!`](#string) | Download path of the package file. | | <a id="packagefilefilemd5"></a>`fileMd5` | [`String`](#string) | Md5 of the package file. | | <a id="packagefilefilemetadata"></a>`fileMetadata` | [`PackageFileMetadata`](#packagefilemetadata) | File metadata. | @@ -11538,7 +12076,7 @@ Represents a package file. | <a id="packagefilefilesha256"></a>`fileSha256` | [`String`](#string) | Sha256 of the package file. | | <a id="packagefileid"></a>`id` | [`PackagesPackageFileID!`](#packagespackagefileid) | ID of the file. | | <a id="packagefilesize"></a>`size` | [`String!`](#string) | Size of the package file. | -| <a id="packagefileupdatedat"></a>`updatedAt` | [`Time!`](#time) | The updated date. | +| <a id="packagefileupdatedat"></a>`updatedAt` | [`Time!`](#time) | Updated date. | ### `PackageFileRegistry` @@ -11578,10 +12116,10 @@ Represents a package tag. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="packagetagcreatedat"></a>`createdAt` | [`Time!`](#time) | The created date. | -| <a id="packagetagid"></a>`id` | [`ID!`](#id) | The ID of the tag. | -| <a id="packagetagname"></a>`name` | [`String!`](#string) | The name of the tag. | -| <a id="packagetagupdatedat"></a>`updatedAt` | [`Time!`](#time) | The updated date. | +| <a id="packagetagcreatedat"></a>`createdAt` | [`Time!`](#time) | Created date. | +| <a id="packagetagid"></a>`id` | [`ID!`](#id) | ID of the tag. | +| <a id="packagetagname"></a>`name` | [`String!`](#string) | Name of the tag. | +| <a id="packagetagupdatedat"></a>`updatedAt` | [`Time!`](#time) | Updated date. | ### `PageInfo` @@ -11596,6 +12134,23 @@ Information about pagination in a connection. | <a id="pageinfohaspreviouspage"></a>`hasPreviousPage` | [`Boolean!`](#boolean) | When paginating backwards, are there more items?. | | <a id="pageinfostartcursor"></a>`startCursor` | [`String`](#string) | When paginating backwards, the cursor to continue. | +### `PagesDeploymentRegistry` + +Represents the Geo replication and verification state of a pages_deployment. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="pagesdeploymentregistrycreatedat"></a>`createdAt` | [`Time`](#time) | Timestamp when the PagesDeploymentRegistry was created. | +| <a id="pagesdeploymentregistryid"></a>`id` | [`ID!`](#id) | ID of the PagesDeploymentRegistry. | +| <a id="pagesdeploymentregistrylastsyncfailure"></a>`lastSyncFailure` | [`String`](#string) | Error message during sync of the PagesDeploymentRegistry. | +| <a id="pagesdeploymentregistrylastsyncedat"></a>`lastSyncedAt` | [`Time`](#time) | Timestamp of the most recent successful sync of the PagesDeploymentRegistry. | +| <a id="pagesdeploymentregistrypagesdeploymentid"></a>`pagesDeploymentId` | [`ID!`](#id) | ID of the Pages Deployment. | +| <a id="pagesdeploymentregistryretryat"></a>`retryAt` | [`Time`](#time) | Timestamp after which the PagesDeploymentRegistry should be resynced. | +| <a id="pagesdeploymentregistryretrycount"></a>`retryCount` | [`Int`](#int) | Number of consecutive failed sync attempts of the PagesDeploymentRegistry. | +| <a id="pagesdeploymentregistrystate"></a>`state` | [`RegistryState`](#registrystate) | Sync state of the PagesDeploymentRegistry. | + ### `PathLock` Represents a file or directory in the project repository that has been locked. @@ -11605,8 +12160,8 @@ Represents a file or directory in the project repository that has been locked. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="pathlockid"></a>`id` | [`PathLockID!`](#pathlockid) | ID of the path lock. | -| <a id="pathlockpath"></a>`path` | [`String`](#string) | The locked path. | -| <a id="pathlockuser"></a>`user` | [`UserCore`](#usercore) | The user that has locked this path. | +| <a id="pathlockpath"></a>`path` | [`String`](#string) | Locked path. | +| <a id="pathlockuser"></a>`user` | [`UserCore`](#usercore) | User that has locked this path. | ### `Pipeline` @@ -11653,7 +12208,7 @@ Represents a file or directory in the project repository that has been locked. ##### `Pipeline.job` -A specific job in this pipeline, either by name or ID. +Specific job in this pipeline, either by name or ID. Returns [`CiJob`](#cijob). @@ -11767,17 +12322,17 @@ Represents vulnerability finding of a security report on the pipeline. | ---- | ---- | ----------- | | <a id="pipelinesecurityreportfindingconfidence"></a>`confidence` | [`String`](#string) | Type of the security report that found the vulnerability. | | <a id="pipelinesecurityreportfindingdescription"></a>`description` | [`String`](#string) | Description of the vulnerability finding. | -| <a id="pipelinesecurityreportfindingfalsepositive"></a>`falsePositive` | [`Boolean`](#boolean) | Indicates whether the vulnerability is a false positive. Available only when feature flag `vulnerability_flags` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. | +| <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 vulnerabilit finding. | | <a id="pipelinesecurityreportfindinglocation"></a>`location` | [`VulnerabilityLocation`](#vulnerabilitylocation) | Location metadata for the vulnerability. Its fields depend on the type of security scan that found the vulnerability. | | <a id="pipelinesecurityreportfindingname"></a>`name` | [`String`](#string) | Name of the vulnerability finding. | -| <a id="pipelinesecurityreportfindingproject"></a>`project` | [`Project`](#project) | The project on which the vulnerability finding was found. | +| <a id="pipelinesecurityreportfindingproject"></a>`project` | [`Project`](#project) | Project on which the vulnerability finding was found. | | <a id="pipelinesecurityreportfindingprojectfingerprint"></a>`projectFingerprint` | [`String`](#string) | Name of the vulnerability 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) | URL to the vulnerability's details page. | -| <a id="pipelinesecurityreportfindingstate"></a>`state` | [`VulnerabilityState`](#vulnerabilitystate) | The finding status. | +| <a id="pipelinesecurityreportfindingstate"></a>`state` | [`VulnerabilityState`](#vulnerabilitystate) | Finding status. | | <a id="pipelinesecurityreportfindinguuid"></a>`uuid` | [`String`](#string) | Name of the vulnerability finding. | ### `Project` @@ -11798,16 +12353,16 @@ Represents vulnerability finding of a security report on the pipeline. | <a id="projectclusteragents"></a>`clusterAgents` | [`ClusterAgentConnection`](#clusteragentconnection) | Cluster agents associated with the project. (see [Connections](#connections)) | | <a id="projectcodecoveragesummary"></a>`codeCoverageSummary` | [`CodeCoverageSummary`](#codecoveragesummary) | Code coverage summary associated with the project. | | <a id="projectcomplianceframeworks"></a>`complianceFrameworks` | [`ComplianceFrameworkConnection`](#complianceframeworkconnection) | Compliance frameworks associated with the project. (see [Connections](#connections)) | -| <a id="projectcontainerexpirationpolicy"></a>`containerExpirationPolicy` | [`ContainerExpirationPolicy`](#containerexpirationpolicy) | The container expiration policy of the project. | +| <a id="projectcontainerexpirationpolicy"></a>`containerExpirationPolicy` | [`ContainerExpirationPolicy`](#containerexpirationpolicy) | Container expiration policy of the project. | | <a id="projectcontainerregistryenabled"></a>`containerRegistryEnabled` | [`Boolean`](#boolean) | Indicates if Container Registry is enabled for the current user. | | <a id="projectcontainerrepositoriescount"></a>`containerRepositoriesCount` | [`Int!`](#int) | Number of container repositories in the project. | | <a id="projectcreatedat"></a>`createdAt` | [`Time`](#time) | Timestamp of the project creation. | | <a id="projectdastprofiles"></a>`dastProfiles` | [`DastProfileConnection`](#dastprofileconnection) | DAST Profiles associated with the project. (see [Connections](#connections)) | -| <a id="projectdastscannerprofiles"></a>`dastScannerProfiles` | [`DastScannerProfileConnection`](#dastscannerprofileconnection) | The DAST scanner profiles associated with the project. (see [Connections](#connections)) | +| <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="projectdora"></a>`dora` | [`Dora`](#dora) | The project's DORA metrics. | +| <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. | | <a id="projectgrafanaintegration"></a>`grafanaIntegration` | [`GrafanaIntegration`](#grafanaintegration) | Grafana integration details for the project. | @@ -11835,7 +12390,7 @@ Represents vulnerability finding of a security report on the pipeline. | <a id="projectpipelineanalytics"></a>`pipelineAnalytics` | [`PipelineAnalytics`](#pipelineanalytics) | Pipeline analytics. | | <a id="projectprintingmergerequestlinkenabled"></a>`printingMergeRequestLinkEnabled` | [`Boolean`](#boolean) | Indicates if a link to create or view a merge request should display after a push to Git repositories of the project from the command line. | | <a id="projectpublicjobs"></a>`publicJobs` | [`Boolean`](#boolean) | Indicates if there is public access to pipelines and job details of the project, including output logs and artifacts. | -| <a id="projectpushrules"></a>`pushRules` | [`PushRules`](#pushrules) | The project's push rules settings. | +| <a id="projectpushrules"></a>`pushRules` | [`PushRules`](#pushrules) | Project's push rules settings. | | <a id="projectremovesourcebranchaftermerge"></a>`removeSourceBranchAfterMerge` | [`Boolean`](#boolean) | Indicates if `Delete source branch` option should be enabled by default for all new merge requests of the project. | | <a id="projectrepository"></a>`repository` | [`Repository`](#repository) | Git repository of the project. | | <a id="projectrepositorysizeexcess"></a>`repositorySizeExcess` | [`Float`](#float) | Size of repository that exceeds the limit in bytes. | @@ -11854,7 +12409,7 @@ Represents vulnerability finding of a security report on the pipeline. | <a id="projectsshurltorepo"></a>`sshUrlToRepo` | [`String`](#string) | URL to connect to the project via SSH. | | <a id="projectstarcount"></a>`starCount` | [`Int!`](#int) | Number of times the project has been starred. | | <a id="projectstatistics"></a>`statistics` | [`ProjectStatistics`](#projectstatistics) | Statistics of the project. | -| <a id="projectsuggestioncommitmessage"></a>`suggestionCommitMessage` | [`String`](#string) | The commit message used to apply merge request suggestions. | +| <a id="projectsuggestioncommitmessage"></a>`suggestionCommitMessage` | [`String`](#string) | Commit message used to apply merge request suggestions. | | <a id="projecttaglist"></a>`tagList` **{warning-solid}** | [`String`](#string) | **Deprecated** in 13.12. Use `topics`. | | <a id="projectterraformstates"></a>`terraformStates` | [`TerraformStateConnection`](#terraformstateconnection) | Terraform states associated with the project. (see [Connections](#connections)) | | <a id="projecttopics"></a>`topics` | [`[String!]`](#string) | List of project topics. | @@ -12069,6 +12624,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | | <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. Ignored if `dast_failed_site_validations` feature flag is disabled. | ##### `Project.environment` @@ -12140,7 +12696,7 @@ Returns [`Issue`](#issue). | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="projectissueassigneeid"></a>`assigneeId` | [`String`](#string) | ID of a user assigned to the issues, "none" and "any" values are supported. | +| <a id="projectissueassigneeid"></a>`assigneeId` | [`String`](#string) | ID of a user assigned to the issues. Wildcard values "NONE" and "ANY" are supported. | | <a id="projectissueassigneeusername"></a>`assigneeUsername` **{warning-solid}** | [`String`](#string) | **Deprecated** in 13.11. Use `assigneeUsernames`. | | <a id="projectissueassigneeusernames"></a>`assigneeUsernames` | [`[String!]`](#string) | Usernames of users assigned to the issue. | | <a id="projectissueauthorusername"></a>`authorUsername` | [`String`](#string) | Username of the author of the issue. | @@ -12156,6 +12712,7 @@ Returns [`Issue`](#issue). | <a id="projectissuelabelname"></a>`labelName` | [`[String]`](#string) | Labels applied to this issue. | | <a id="projectissuemilestonetitle"></a>`milestoneTitle` | [`[String]`](#string) | Milestone applied to this issue. | | <a id="projectissuemilestonewildcardid"></a>`milestoneWildcardId` | [`MilestoneWildcardId`](#milestonewildcardid) | Filter issues by milestone ID wildcard. | +| <a id="projectissuemyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. Wildcard values "NONE" and "ANY" are supported. | | <a id="projectissuenot"></a>`not` | [`NegatedIssueFilterInput`](#negatedissuefilterinput) | Negated arguments. | | <a id="projectissuesearch"></a>`search` | [`String`](#string) | Search query for issue title or description. | | <a id="projectissuesort"></a>`sort` | [`IssueSort`](#issuesort) | Sort issues by this criteria. | @@ -12175,7 +12732,7 @@ Returns [`IssueStatusCountsType`](#issuestatuscountstype). | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="projectissuestatuscountsassigneeid"></a>`assigneeId` | [`String`](#string) | ID of a user assigned to the issues, "none" and "any" values are supported. | +| <a id="projectissuestatuscountsassigneeid"></a>`assigneeId` | [`String`](#string) | ID of a user assigned to the issues. Wildcard values "NONE" and "ANY" are supported. | | <a id="projectissuestatuscountsassigneeusername"></a>`assigneeUsername` **{warning-solid}** | [`String`](#string) | **Deprecated** in 13.11. Use `assigneeUsernames`. | | <a id="projectissuestatuscountsassigneeusernames"></a>`assigneeUsernames` | [`[String!]`](#string) | Usernames of users assigned to the issue. | | <a id="projectissuestatuscountsauthorusername"></a>`authorUsername` | [`String`](#string) | Username of the author of the issue. | @@ -12188,6 +12745,7 @@ Returns [`IssueStatusCountsType`](#issuestatuscountstype). | <a id="projectissuestatuscountslabelname"></a>`labelName` | [`[String]`](#string) | Labels applied to this issue. | | <a id="projectissuestatuscountsmilestonetitle"></a>`milestoneTitle` | [`[String]`](#string) | Milestone applied to this issue. | | <a id="projectissuestatuscountsmilestonewildcardid"></a>`milestoneWildcardId` | [`MilestoneWildcardId`](#milestonewildcardid) | Filter issues by milestone ID wildcard. | +| <a id="projectissuestatuscountsmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. Wildcard values "NONE" and "ANY" are supported. | | <a id="projectissuestatuscountsnot"></a>`not` | [`NegatedIssueFilterInput`](#negatedissuefilterinput) | Negated arguments. | | <a id="projectissuestatuscountssearch"></a>`search` | [`String`](#string) | Search query for issue title or description. | | <a id="projectissuestatuscountstypes"></a>`types` | [`[IssueType!]`](#issuetype) | Filter issues by the given issue types. | @@ -12208,7 +12766,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="projectissuesassigneeid"></a>`assigneeId` | [`String`](#string) | ID of a user assigned to the issues, "none" and "any" values are supported. | +| <a id="projectissuesassigneeid"></a>`assigneeId` | [`String`](#string) | ID of a user assigned to the issues. Wildcard values "NONE" and "ANY" are supported. | | <a id="projectissuesassigneeusername"></a>`assigneeUsername` **{warning-solid}** | [`String`](#string) | **Deprecated** in 13.11. Use `assigneeUsernames`. | | <a id="projectissuesassigneeusernames"></a>`assigneeUsernames` | [`[String!]`](#string) | Usernames of users assigned to the issue. | | <a id="projectissuesauthorusername"></a>`authorUsername` | [`String`](#string) | Username of the author of the issue. | @@ -12224,6 +12782,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="projectissueslabelname"></a>`labelName` | [`[String]`](#string) | Labels applied to this issue. | | <a id="projectissuesmilestonetitle"></a>`milestoneTitle` | [`[String]`](#string) | Milestone applied to this issue. | | <a id="projectissuesmilestonewildcardid"></a>`milestoneWildcardId` | [`MilestoneWildcardId`](#milestonewildcardid) | Filter issues by milestone ID wildcard. | +| <a id="projectissuesmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. Wildcard values "NONE" and "ANY" are supported. | | <a id="projectissuesnot"></a>`not` | [`NegatedIssueFilterInput`](#negatedissuefilterinput) | Negated arguments. | | <a id="projectissuessearch"></a>`search` | [`String`](#string) | Search query for issue title or description. | | <a id="projectissuessort"></a>`sort` | [`IssueSort`](#issuesort) | Sort issues by this criteria. | @@ -12296,7 +12855,7 @@ four standard [pagination arguments](#connection-pagination-arguments): ##### `Project.label` -A label available on this project. +Label available on this project. Returns [`Label`](#label). @@ -12321,7 +12880,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | | <a id="projectlabelsincludeancestorgroups"></a>`includeAncestorGroups` | [`Boolean`](#boolean) | Include labels from ancestor groups. | -| <a id="projectlabelssearchterm"></a>`searchTerm` | [`String`](#string) | A search term to find labels with. | +| <a id="projectlabelssearchterm"></a>`searchTerm` | [`String`](#string) | Search term to find labels with. | ##### `Project.mergeRequest` @@ -12360,7 +12919,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="projectmergerequestsreviewerusername"></a>`reviewerUsername` | [`String`](#string) | Username of the reviewer. | | <a id="projectmergerequestssort"></a>`sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | | <a id="projectmergerequestssourcebranches"></a>`sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | -| <a id="projectmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | A merge request state. If provided, all resolved merge requests will have this state. | +| <a id="projectmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | <a id="projectmergerequeststargetbranches"></a>`targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | ##### `Project.milestones` @@ -12377,16 +12936,16 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="projectmilestonescontainingdate"></a>`containingDate` | [`Time`](#time) | A date that the milestone contains. | +| <a id="projectmilestonescontainingdate"></a>`containingDate` | [`Time`](#time) | Date the milestone contains. | | <a id="projectmilestonesenddate"></a>`endDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.end. | | <a id="projectmilestonesids"></a>`ids` | [`[ID!]`](#id) | Array of global milestone IDs, e.g., `"gid://gitlab/Milestone/1"`. | | <a id="projectmilestonesincludeancestors"></a>`includeAncestors` | [`Boolean`](#boolean) | Also return milestones in the project's parent group and its ancestors. | -| <a id="projectmilestonessearchtitle"></a>`searchTitle` | [`String`](#string) | A search string for the title. | +| <a id="projectmilestonessearchtitle"></a>`searchTitle` | [`String`](#string) | Search string for the title. | | <a id="projectmilestonessort"></a>`sort` | [`MilestoneSort`](#milestonesort) | Sort milestones by this criteria. | | <a id="projectmilestonesstartdate"></a>`startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | | <a id="projectmilestonesstate"></a>`state` | [`MilestoneStateEnum`](#milestonestateenum) | Filter milestones by state. | | <a id="projectmilestonestimeframe"></a>`timeframe` | [`Timeframe`](#timeframe) | List items overlapping the given timeframe. | -| <a id="projectmilestonestitle"></a>`title` | [`String`](#string) | The title of the milestone. | +| <a id="projectmilestonestitle"></a>`title` | [`String`](#string) | Title of the milestone. | ##### `Project.networkPolicies` @@ -12402,7 +12961,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="projectnetworkpoliciesenvironmentid"></a>`environmentId` | [`EnvironmentID`](#environmentid) | The global ID of the environment to filter policies. | +| <a id="projectnetworkpoliciesenvironmentid"></a>`environmentId` | [`EnvironmentID`](#environmentid) | Global ID of the environment to filter policies. | ##### `Project.packages` @@ -12453,6 +13012,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | <a id="projectpipelinesref"></a>`ref` | [`String`](#string) | Filter pipelines by the ref they are run for. | | <a id="projectpipelinessha"></a>`sha` | [`String`](#string) | Filter pipelines by the sha of the commit they are run for. | +| <a id="projectpipelinessource"></a>`source` | [`String`](#string) | Filter pipelines by their source. Will be ignored if `dast_view_scans` feature flag is disabled. | | <a id="projectpipelinesstatus"></a>`status` | [`PipelineStatusEnum`](#pipelinestatusenum) | Filter pipelines by their status. | ##### `Project.projectMembers` @@ -12482,7 +13042,7 @@ Returns [`Release`](#release). | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="projectreleasetagname"></a>`tagName` | [`String!`](#string) | The name of the tag associated to the release. | +| <a id="projectreleasetagname"></a>`tagName` | [`String!`](#string) | Name of the tag associated to the release. | ##### `Project.releases` @@ -12513,7 +13073,7 @@ Returns [`Requirement`](#requirement). | <a id="projectrequirementauthorusername"></a>`authorUsername` | [`[String!]`](#string) | Filter requirements by author username. | | <a id="projectrequirementiid"></a>`iid` | [`ID`](#id) | IID of the requirement, e.g., "1". | | <a id="projectrequirementiids"></a>`iids` | [`[ID!]`](#id) | List of IIDs of requirements, e.g., `[1, 2]`. | -| <a id="projectrequirementlasttestreportstate"></a>`lastTestReportState` | [`RequirementStatusFilter`](#requirementstatusfilter) | The state of latest requirement test report. | +| <a id="projectrequirementlasttestreportstate"></a>`lastTestReportState` | [`RequirementStatusFilter`](#requirementstatusfilter) | State of latest requirement test report. | | <a id="projectrequirementsearch"></a>`search` | [`String`](#string) | Search query for requirement title. | | <a id="projectrequirementsort"></a>`sort` | [`Sort`](#sort) | List requirements by sort order. | | <a id="projectrequirementstate"></a>`state` | [`RequirementState`](#requirementstate) | Filter requirements by state. | @@ -12535,7 +13095,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="projectrequirementsauthorusername"></a>`authorUsername` | [`[String!]`](#string) | Filter requirements by author username. | | <a id="projectrequirementsiid"></a>`iid` | [`ID`](#id) | IID of the requirement, e.g., "1". | | <a id="projectrequirementsiids"></a>`iids` | [`[ID!]`](#id) | List of IIDs of requirements, e.g., `[1, 2]`. | -| <a id="projectrequirementslasttestreportstate"></a>`lastTestReportState` | [`RequirementStatusFilter`](#requirementstatusfilter) | The state of latest requirement test report. | +| <a id="projectrequirementslasttestreportstate"></a>`lastTestReportState` | [`RequirementStatusFilter`](#requirementstatusfilter) | State of latest requirement test report. | | <a id="projectrequirementssearch"></a>`search` | [`String`](#string) | Search query for requirement title. | | <a id="projectrequirementssort"></a>`sort` | [`Sort`](#sort) | List requirements by sort order. | | <a id="projectrequirementsstate"></a>`state` | [`RequirementState`](#requirementstate) | Filter requirements by state. | @@ -12770,6 +13330,7 @@ Represents a Project Membership. | <a id="projectstatisticscommitcount"></a>`commitCount` | [`Float!`](#float) | Commit count of the project. | | <a id="projectstatisticslfsobjectssize"></a>`lfsObjectsSize` | [`Float!`](#float) | Large File Storage (LFS) object size of the project in bytes. | | <a id="projectstatisticspackagessize"></a>`packagesSize` | [`Float!`](#float) | Packages size of the project in bytes. | +| <a id="projectstatisticspipelineartifactssize"></a>`pipelineArtifactsSize` | [`Float`](#float) | CI Pipeline artifacts size in bytes. | | <a id="projectstatisticsrepositorysize"></a>`repositorySize` | [`Float!`](#float) | Repository size of the project in bytes. | | <a id="projectstatisticssnippetssize"></a>`snippetsSize` | [`Float`](#float) | Snippets size of the project in bytes. | | <a id="projectstatisticsstoragesize"></a>`storageSize` | [`Float!`](#float) | Storage size of the project in bytes. | @@ -12784,7 +13345,7 @@ The alert condition for Prometheus. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="prometheusalerthumanizedtext"></a>`humanizedText` | [`String!`](#string) | The human-readable text of the alert condition. | +| <a id="prometheusalerthumanizedtext"></a>`humanizedText` | [`String!`](#string) | Human-readable text of the alert condition. | | <a id="prometheusalertid"></a>`id` | [`ID!`](#id) | ID of the alert condition. | ### `PushRules` @@ -12838,7 +13399,7 @@ Represents a release. | ---- | ---- | ----------- | | <a id="releaseassets"></a>`assets` | [`ReleaseAssets`](#releaseassets) | Assets of the release. | | <a id="releaseauthor"></a>`author` | [`UserCore`](#usercore) | User that created the release. | -| <a id="releasecommit"></a>`commit` | [`Commit`](#commit) | The commit associated with the 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`. | @@ -12957,9 +13518,9 @@ Returns [`[String!]`](#string). | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="repositorybranchnameslimit"></a>`limit` | [`Int!`](#int) | The number of branch names to return. | -| <a id="repositorybranchnamesoffset"></a>`offset` | [`Int!`](#int) | The number of branch names to skip. | -| <a id="repositorybranchnamessearchpattern"></a>`searchPattern` | [`String!`](#string) | The pattern to search for branch names by. | +| <a id="repositorybranchnameslimit"></a>`limit` | [`Int!`](#int) | Number of branch names to return. | +| <a id="repositorybranchnamesoffset"></a>`offset` | [`Int!`](#int) | Number of branch names to skip. | +| <a id="repositorybranchnamessearchpattern"></a>`searchPattern` | [`String!`](#string) | Pattern to search for branch names by. | ##### `Repository.paginatedTree` @@ -12975,9 +13536,9 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="repositorypaginatedtreepath"></a>`path` | [`String`](#string) | The path to get the tree for. Default value is the root of the repository. | +| <a id="repositorypaginatedtreepath"></a>`path` | [`String`](#string) | Path to get the tree for. Default value is the root of the repository. | | <a id="repositorypaginatedtreerecursive"></a>`recursive` | [`Boolean`](#boolean) | Used to get a recursive tree. Default is false. | -| <a id="repositorypaginatedtreeref"></a>`ref` | [`String`](#string) | The commit ref to get the tree for. Default value is HEAD. | +| <a id="repositorypaginatedtreeref"></a>`ref` | [`String`](#string) | Commit ref to get the tree for. Default value is HEAD. | ##### `Repository.tree` @@ -12989,9 +13550,9 @@ Returns [`Tree`](#tree). | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="repositorytreepath"></a>`path` | [`String`](#string) | The path to get the tree for. Default value is the root of the repository. | +| <a id="repositorytreepath"></a>`path` | [`String`](#string) | Path to get the tree for. Default value is the root of the repository. | | <a id="repositorytreerecursive"></a>`recursive` | [`Boolean`](#boolean) | Used to get a recursive tree. Default is false. | -| <a id="repositorytreeref"></a>`ref` | [`String`](#string) | The commit ref to get the tree for. Default value is HEAD. | +| <a id="repositorytreeref"></a>`ref` | [`String`](#string) | Commit ref to get the tree for. Default value is HEAD. | ### `RepositoryBlob` @@ -13002,7 +13563,7 @@ Returns [`Tree`](#tree). | <a id="repositoryblobcanmodifyblob"></a>`canModifyBlob` | [`Boolean`](#boolean) | Whether the current user can modify the blob. | | <a id="repositoryblobeditblobpath"></a>`editBlobPath` | [`String`](#string) | Web path to edit the blob in the old-style editor. | | <a id="repositoryblobexternalstorageurl"></a>`externalStorageUrl` | [`String`](#string) | Web path to download the raw blob via external storage, if enabled. | -| <a id="repositoryblobfiletype"></a>`fileType` | [`String`](#string) | The expected format of the blob based on the extension. | +| <a id="repositoryblobfiletype"></a>`fileType` | [`String`](#string) | Expected format of the blob based on the extension. | | <a id="repositoryblobforkandeditpath"></a>`forkAndEditPath` | [`String`](#string) | Web path to edit this blob using a forked project. | | <a id="repositoryblobid"></a>`id` | [`ID!`](#id) | ID of the blob. | | <a id="repositoryblobideeditpath"></a>`ideEditPath` | [`String`](#string) | Web path to edit this blob in the Web IDE. | @@ -13013,10 +13574,10 @@ Returns [`Tree`](#tree). | <a id="repositorybloboid"></a>`oid` | [`String!`](#string) | OID of the blob. | | <a id="repositoryblobpath"></a>`path` | [`String!`](#string) | Path of the blob. | | <a id="repositoryblobplaindata"></a>`plainData` | [`String`](#string) | Blob plain highlighted data. | -| <a id="repositoryblobrawblob"></a>`rawBlob` | [`String`](#string) | The raw content of the blob. | +| <a id="repositoryblobrawblob"></a>`rawBlob` | [`String`](#string) | Raw content of the blob. | | <a id="repositoryblobrawpath"></a>`rawPath` | [`String`](#string) | Web path to download the raw blob. | | <a id="repositoryblobrawsize"></a>`rawSize` | [`Int`](#int) | Size (in bytes) of the blob, or the blob target if stored externally. | -| <a id="repositoryblobrawtextblob"></a>`rawTextBlob` | [`String`](#string) | The raw content of the blob, if the blob is text data. | +| <a id="repositoryblobrawtextblob"></a>`rawTextBlob` | [`String`](#string) | Raw content of the blob, if the blob is text data. | | <a id="repositoryblobreplacepath"></a>`replacePath` | [`String`](#string) | Web path to replace the blob content. | | <a id="repositoryblobrichviewer"></a>`richViewer` | [`BlobViewer`](#blobviewer) | Blob content rich viewer. | | <a id="repositoryblobsimpleviewer"></a>`simpleViewer` | [`BlobViewer!`](#blobviewer) | Blob content simple viewer. | @@ -13096,15 +13657,15 @@ Counts of requirements by their state. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="rootstoragestatisticsbuildartifactssize"></a>`buildArtifactsSize` | [`Float!`](#float) | The CI artifacts size in bytes. | -| <a id="rootstoragestatisticslfsobjectssize"></a>`lfsObjectsSize` | [`Float!`](#float) | The LFS objects size in bytes. | -| <a id="rootstoragestatisticspackagessize"></a>`packagesSize` | [`Float!`](#float) | The packages size in bytes. | -| <a id="rootstoragestatisticspipelineartifactssize"></a>`pipelineArtifactsSize` | [`Float!`](#float) | The CI pipeline artifacts size in bytes. | -| <a id="rootstoragestatisticsrepositorysize"></a>`repositorySize` | [`Float!`](#float) | The Git repository size in bytes. | -| <a id="rootstoragestatisticssnippetssize"></a>`snippetsSize` | [`Float!`](#float) | The snippets size in bytes. | -| <a id="rootstoragestatisticsstoragesize"></a>`storageSize` | [`Float!`](#float) | The total storage in bytes. | -| <a id="rootstoragestatisticsuploadssize"></a>`uploadsSize` | [`Float!`](#float) | The uploads size in bytes. | -| <a id="rootstoragestatisticswikisize"></a>`wikiSize` | [`Float!`](#float) | The wiki size in bytes. | +| <a id="rootstoragestatisticsbuildartifactssize"></a>`buildArtifactsSize` | [`Float!`](#float) | CI artifacts size in bytes. | +| <a id="rootstoragestatisticslfsobjectssize"></a>`lfsObjectsSize` | [`Float!`](#float) | LFS objects size in bytes. | +| <a id="rootstoragestatisticspackagessize"></a>`packagesSize` | [`Float!`](#float) | Packages size in bytes. | +| <a id="rootstoragestatisticspipelineartifactssize"></a>`pipelineArtifactsSize` | [`Float!`](#float) | CI pipeline artifacts size in bytes. | +| <a id="rootstoragestatisticsrepositorysize"></a>`repositorySize` | [`Float!`](#float) | Git repository size in bytes. | +| <a id="rootstoragestatisticssnippetssize"></a>`snippetsSize` | [`Float!`](#float) | Snippets size in bytes. | +| <a id="rootstoragestatisticsstoragesize"></a>`storageSize` | [`Float!`](#float) | Total storage in bytes. | +| <a id="rootstoragestatisticsuploadssize"></a>`uploadsSize` | [`Float!`](#float) | Uploads size in bytes. | +| <a id="rootstoragestatisticswikisize"></a>`wikiSize` | [`Float!`](#float) | Wiki size in bytes. | ### `RunnerArchitecture` @@ -13221,8 +13782,8 @@ Represents a resource scanned by a security scan. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="scannedresourcerequestmethod"></a>`requestMethod` | [`String`](#string) | The HTTP request method used to access the URL. | -| <a id="scannedresourceurl"></a>`url` | [`String`](#string) | The URL scanned by the scanner. | +| <a id="scannedresourcerequestmethod"></a>`requestMethod` | [`String`](#string) | HTTP request method used to access the URL. | +| <a id="scannedresourceurl"></a>`url` | [`String`](#string) | URL scanned by the scanner. | ### `SecurityReportSummary` @@ -13238,6 +13799,7 @@ Represents summary of a security report. | <a id="securityreportsummarycoveragefuzzing"></a>`coverageFuzzing` | [`SecurityReportSummarySection`](#securityreportsummarysection) | Aggregated counts for the `coverage_fuzzing` scan. | | <a id="securityreportsummarydast"></a>`dast` | [`SecurityReportSummarySection`](#securityreportsummarysection) | Aggregated counts for the `dast` scan. | | <a id="securityreportsummarydependencyscanning"></a>`dependencyScanning` | [`SecurityReportSummarySection`](#securityreportsummarysection) | Aggregated counts for the `dependency_scanning` scan. | +| <a id="securityreportsummarygeneric"></a>`generic` | [`SecurityReportSummarySection`](#securityreportsummarysection) | Aggregated counts for the `generic` scan. | | <a id="securityreportsummarysast"></a>`sast` | [`SecurityReportSummarySection`](#securityreportsummarysection) | Aggregated counts for the `sast` scan. | | <a id="securityreportsummarysecretdetection"></a>`secretDetection` | [`SecurityReportSummarySection`](#securityreportsummarysection) | Aggregated counts for the `secret_detection` scan. | @@ -13249,7 +13811,7 @@ Represents a section of a summary of a security report. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="securityreportsummarysectionscannedresources"></a>`scannedResources` | [`ScannedResourceConnection`](#scannedresourceconnection) | A list of the first 20 scanned resources. (see [Connections](#connections)) | +| <a id="securityreportsummarysectionscannedresources"></a>`scannedResources` | [`ScannedResourceConnection`](#scannedresourceconnection) | List of the first 20 scanned resources. (see [Connections](#connections)) | | <a id="securityreportsummarysectionscannedresourcescount"></a>`scannedResourcesCount` | [`Int`](#int) | Total number of scanned resources. | | <a id="securityreportsummarysectionscannedresourcescsvpath"></a>`scannedResourcesCsvPath` | [`String`](#string) | Path to download all the scanned resources in CSV format. | | <a id="securityreportsummarysectionscans"></a>`scans` | [`ScanConnection!`](#scanconnection) | List of security scans ran for the type. (see [Connections](#connections)) | @@ -13448,7 +14010,7 @@ Represents a snippet entry. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="snippetauthor"></a>`author` | [`UserCore`](#usercore) | The owner of the snippet. | +| <a id="snippetauthor"></a>`author` | [`UserCore`](#usercore) | Owner of the snippet. | | <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`. | @@ -13457,7 +14019,7 @@ Represents a snippet entry. | <a id="snippethttpurltorepo"></a>`httpUrlToRepo` | [`String`](#string) | HTTP URL to the snippet repository. | | <a id="snippetid"></a>`id` | [`SnippetID!`](#snippetid) | ID of the snippet. | | <a id="snippetnotes"></a>`notes` | [`NoteConnection!`](#noteconnection) | All notes on this noteable. (see [Connections](#connections)) | -| <a id="snippetproject"></a>`project` | [`Project`](#project) | The project the snippet is associated with. | +| <a id="snippetproject"></a>`project` | [`Project`](#project) | Project the snippet is associated with. | | <a id="snippetrawurl"></a>`rawUrl` | [`String!`](#string) | Raw URL of the snippet. | | <a id="snippetsshurltorepo"></a>`sshUrlToRepo` | [`String`](#string) | SSH URL to the snippet repository. | | <a id="snippettitle"></a>`title` | [`String!`](#string) | Title of the snippet. | @@ -13499,7 +14061,7 @@ Represents the snippet blob. | <a id="snippetblobpath"></a>`path` | [`String`](#string) | Blob path. | | <a id="snippetblobplaindata"></a>`plainData` | [`String`](#string) | Blob plain highlighted data. | | <a id="snippetblobrawpath"></a>`rawPath` | [`String!`](#string) | Blob raw content endpoint path. | -| <a id="snippetblobrawplaindata"></a>`rawPlainData` | [`String`](#string) | The raw content of the blob, if the blob is text data. | +| <a id="snippetblobrawplaindata"></a>`rawPlainData` | [`String`](#string) | Raw content of the blob, if the blob is text data. | | <a id="snippetblobrenderedastext"></a>`renderedAsText` | [`Boolean!`](#boolean) | Shows whether the blob is rendered as text. | | <a id="snippetblobrichdata"></a>`richData` | [`String`](#string) | Blob highlighted data. | | <a id="snippetblobrichviewer"></a>`richViewer` | [`SnippetBlobViewer`](#snippetblobviewer) | Blob content rich viewer. | @@ -13599,9 +14161,9 @@ Completion status of tasks. | ---- | ---- | ----------- | | <a id="terraformstatecreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp the Terraform state was created. | | <a id="terraformstateid"></a>`id` | [`ID!`](#id) | ID of the Terraform state. | -| <a id="terraformstatelatestversion"></a>`latestVersion` | [`TerraformStateVersion`](#terraformstateversion) | The latest version of the Terraform state. | +| <a id="terraformstatelatestversion"></a>`latestVersion` | [`TerraformStateVersion`](#terraformstateversion) | Latest version of the Terraform state. | | <a id="terraformstatelockedat"></a>`lockedAt` | [`Time`](#time) | Timestamp the Terraform state was locked. | -| <a id="terraformstatelockedbyuser"></a>`lockedByUser` | [`UserCore`](#usercore) | The user currently holding a lock on the Terraform state. | +| <a id="terraformstatelockedbyuser"></a>`lockedByUser` | [`UserCore`](#usercore) | User currently holding a lock on the Terraform state. | | <a id="terraformstatename"></a>`name` | [`String!`](#string) | Name of the Terraform state. | | <a id="terraformstateupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp the Terraform state was updated. | @@ -13612,10 +14174,10 @@ Completion status of tasks. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="terraformstateversioncreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp the version was created. | -| <a id="terraformstateversioncreatedbyuser"></a>`createdByUser` | [`UserCore`](#usercore) | The user that created this version. | +| <a id="terraformstateversioncreatedbyuser"></a>`createdByUser` | [`UserCore`](#usercore) | User that created this version. | | <a id="terraformstateversiondownloadpath"></a>`downloadPath` | [`String`](#string) | URL for downloading the version's JSON file. | | <a id="terraformstateversionid"></a>`id` | [`ID!`](#id) | ID of the Terraform state version. | -| <a id="terraformstateversionjob"></a>`job` | [`CiJob`](#cijob) | The job that created this version. | +| <a id="terraformstateversionjob"></a>`job` | [`CiJob`](#cijob) | Job that created this version. | | <a id="terraformstateversionserial"></a>`serial` | [`Int`](#int) | Serial number of the version. | | <a id="terraformstateversionupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp the version was updated. | @@ -13750,8 +14312,8 @@ Represents measured stats metrics for timeboxes. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="timeboxmetricscount"></a>`count` | [`Int!`](#int) | The count metric. | -| <a id="timeboxmetricsweight"></a>`weight` | [`Int!`](#int) | The weight metric. | +| <a id="timeboxmetricscount"></a>`count` | [`Int!`](#int) | Count metric. | +| <a id="timeboxmetricsweight"></a>`weight` | [`Int!`](#int) | Weight metric. | ### `TimeboxReport` @@ -13770,13 +14332,13 @@ Represents a historically accurate report about the timebox. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="timelogissue"></a>`issue` | [`Issue`](#issue) | The issue that logged time was added to. | -| <a id="timelogmergerequest"></a>`mergeRequest` | [`MergeRequest`](#mergerequest) | The merge request that logged time was added to. | -| <a id="timelognote"></a>`note` | [`Note`](#note) | The note where the quick action to add the logged time was executed. | +| <a id="timelogissue"></a>`issue` | [`Issue`](#issue) | Issue that logged time was added to. | +| <a id="timelogmergerequest"></a>`mergeRequest` | [`MergeRequest`](#mergerequest) | Merge request that logged time was added to. | +| <a id="timelognote"></a>`note` | [`Note`](#note) | Note where the quick action was executed to add the logged time. | | <a id="timelogspentat"></a>`spentAt` | [`Time`](#time) | Timestamp of when the time tracked was spent at. | -| <a id="timelogsummary"></a>`summary` | [`String`](#string) | The summary of how the time was spent. | -| <a id="timelogtimespent"></a>`timeSpent` | [`Int!`](#int) | The time spent displayed in seconds. | -| <a id="timeloguser"></a>`user` | [`UserCore!`](#usercore) | The user that logged the time. | +| <a id="timelogsummary"></a>`summary` | [`String`](#string) | Summary of how the time was spent. | +| <a id="timelogtimespent"></a>`timeSpent` | [`Int!`](#int) | Time spent displayed in seconds. | +| <a id="timeloguser"></a>`user` | [`UserCore!`](#usercore) | User that logged the time. | ### `Todo` @@ -13787,12 +14349,12 @@ Representing a to-do entry. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="todoaction"></a>`action` | [`TodoActionEnum!`](#todoactionenum) | Action of the to-do item. | -| <a id="todoauthor"></a>`author` | [`UserCore!`](#usercore) | The author of this to-do item. | +| <a id="todoauthor"></a>`author` | [`UserCore!`](#usercore) | Author of this to-do item. | | <a id="todobody"></a>`body` | [`String!`](#string) | Body of the to-do item. | | <a id="todocreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp this to-do item was created. | | <a id="todogroup"></a>`group` | [`Group`](#group) | Group this to-do item is associated with. | | <a id="todoid"></a>`id` | [`ID!`](#id) | ID of the to-do item. | -| <a id="todoproject"></a>`project` | [`Project`](#project) | The project this to-do item is associated with. | +| <a id="todoproject"></a>`project` | [`Project`](#project) | Project this to-do item is associated with. | | <a id="todostate"></a>`state` | [`TodoStateEnum!`](#todostateenum) | State of the to-do item. | | <a id="todotargettype"></a>`targetType` | [`TodoTargetEnum!`](#todotargetenum) | Target type of the to-do item. | @@ -13824,6 +14386,23 @@ Represents a directory. | <a id="treeentrywebpath"></a>`webPath` | [`String`](#string) | Web path for the tree entry (directory). | | <a id="treeentryweburl"></a>`webUrl` | [`String`](#string) | Web URL for the tree entry (directory). | +### `UploadRegistry` + +Represents the Geo replication and verification state of an upload. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="uploadregistrycreatedat"></a>`createdAt` | [`Time`](#time) | Timestamp when the UploadRegistry was created. | +| <a id="uploadregistryfileid"></a>`fileId` | [`ID!`](#id) | ID of the Upload. | +| <a id="uploadregistryid"></a>`id` | [`ID!`](#id) | ID of the UploadRegistry. | +| <a id="uploadregistrylastsyncfailure"></a>`lastSyncFailure` | [`String`](#string) | Error message during sync of the UploadRegistry. | +| <a id="uploadregistrylastsyncedat"></a>`lastSyncedAt` | [`Time`](#time) | Timestamp of the most recent successful sync of the UploadRegistry. | +| <a id="uploadregistryretryat"></a>`retryAt` | [`Time`](#time) | Timestamp after which the UploadRegistry should be resynced. | +| <a id="uploadregistryretrycount"></a>`retryCount` | [`Int`](#int) | Number of consecutive failed sync attempts of the UploadRegistry. | +| <a id="uploadregistrystate"></a>`state` | [`RegistryState`](#registrystate) | Sync state of the UploadRegistry. | + ### `UsageTrendsMeasurement` Represents a recorded measurement (object count) for the Admins. @@ -13833,8 +14412,8 @@ Represents a recorded measurement (object count) for the Admins. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="usagetrendsmeasurementcount"></a>`count` | [`Int!`](#int) | Object count. | -| <a id="usagetrendsmeasurementidentifier"></a>`identifier` | [`MeasurementIdentifier!`](#measurementidentifier) | The type of objects being measured. | -| <a id="usagetrendsmeasurementrecordedat"></a>`recordedAt` | [`Time`](#time) | The time the measurement was recorded. | +| <a id="usagetrendsmeasurementidentifier"></a>`identifier` | [`MeasurementIdentifier!`](#measurementidentifier) | Type of objects being measured. | +| <a id="usagetrendsmeasurementrecordedat"></a>`recordedAt` | [`Time`](#time) | Time the measurement was recorded. | ### `UserCallout` @@ -13860,7 +14439,7 @@ Core represention of a GitLab user. | <a id="usercoregroupcount"></a>`groupCount` | [`Int`](#int) | Group count for the user. | | <a id="usercoregroupmemberships"></a>`groupMemberships` | [`GroupMemberConnection`](#groupmemberconnection) | Group memberships of the user. (see [Connections](#connections)) | | <a id="usercoreid"></a>`id` | [`ID!`](#id) | ID of the user. | -| <a id="usercorelocation"></a>`location` | [`String`](#string) | The location of the user. | +| <a id="usercorelocation"></a>`location` | [`String`](#string) | Location of the user. | | <a id="usercorename"></a>`name` | [`String!`](#string) | Human-readable name of the user. | | <a id="usercorenamespace"></a>`namespace` | [`Namespace`](#namespace) | Personal namespace of the user. | | <a id="usercoreprojectmemberships"></a>`projectMemberships` | [`ProjectMemberConnection`](#projectmemberconnection) | Project memberships of the user. (see [Connections](#connections)) | @@ -13900,7 +14479,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="usercoreassignedmergerequestsreviewerusername"></a>`reviewerUsername` | [`String`](#string) | Username of the reviewer. | | <a id="usercoreassignedmergerequestssort"></a>`sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | | <a id="usercoreassignedmergerequestssourcebranches"></a>`sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | -| <a id="usercoreassignedmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | A merge request state. If provided, all resolved merge requests will have this state. | +| <a id="usercoreassignedmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | <a id="usercoreassignedmergerequeststargetbranches"></a>`targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | ##### `UserCore.authoredMergeRequests` @@ -13929,9 +14508,26 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="usercoreauthoredmergerequestsreviewerusername"></a>`reviewerUsername` | [`String`](#string) | Username of the reviewer. | | <a id="usercoreauthoredmergerequestssort"></a>`sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | | <a id="usercoreauthoredmergerequestssourcebranches"></a>`sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | -| <a id="usercoreauthoredmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | A merge request state. If provided, all resolved merge requests will have this state. | +| <a id="usercoreauthoredmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | <a id="usercoreauthoredmergerequeststargetbranches"></a>`targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | +##### `UserCore.groups` + +Groups where the user has access. Will always return `null` if `paginatable_namespace_drop_down_for_project_creation` feature flag is disabled. + +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="usercoregroupspermissionscope"></a>`permissionScope` | [`GroupPermission`](#grouppermission) | Filter by permissions the user has on groups. | +| <a id="usercoregroupssearch"></a>`search` | [`String`](#string) | Search by group name or path. | + ##### `UserCore.reviewRequestedMergeRequests` Merge requests assigned to the user for review. @@ -13958,7 +14554,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="usercorereviewrequestedmergerequestsprojectpath"></a>`projectPath` | [`String`](#string) | The full-path of the project the authored merge requests should be in. Incompatible with projectId. | | <a id="usercorereviewrequestedmergerequestssort"></a>`sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | | <a id="usercorereviewrequestedmergerequestssourcebranches"></a>`sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | -| <a id="usercorereviewrequestedmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | A merge request state. If provided, all resolved merge requests will have this state. | +| <a id="usercorereviewrequestedmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | <a id="usercorereviewrequestedmergerequeststargetbranches"></a>`targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | ##### `UserCore.snippets` @@ -13976,7 +14572,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | | <a id="usercoresnippetsids"></a>`ids` | [`[SnippetID!]`](#snippetid) | Array of global snippet IDs. For example, `gid://gitlab/ProjectSnippet/1`. | -| <a id="usercoresnippetstype"></a>`type` | [`TypeEnum`](#typeenum) | The type of snippet. | +| <a id="usercoresnippetstype"></a>`type` | [`TypeEnum`](#typeenum) | Type of snippet. | | <a id="usercoresnippetsvisibility"></a>`visibility` | [`VisibilityScopesEnum`](#visibilityscopesenum) | Visibility of the snippet. | ##### `UserCore.starredProjects` @@ -14031,12 +14627,12 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="usercoretodosaction"></a>`action` | [`[TodoActionEnum!]`](#todoactionenum) | The action to be filtered. | -| <a id="usercoretodosauthorid"></a>`authorId` | [`[ID!]`](#id) | The ID of an author. | -| <a id="usercoretodosgroupid"></a>`groupId` | [`[ID!]`](#id) | The ID of a group. | -| <a id="usercoretodosprojectid"></a>`projectId` | [`[ID!]`](#id) | The ID of a project. | -| <a id="usercoretodosstate"></a>`state` | [`[TodoStateEnum!]`](#todostateenum) | The state of the todo. | -| <a id="usercoretodostype"></a>`type` | [`[TodoTargetEnum!]`](#todotargetenum) | The type of the todo. | +| <a id="usercoretodosaction"></a>`action` | [`[TodoActionEnum!]`](#todoactionenum) | Action to be filtered. | +| <a id="usercoretodosauthorid"></a>`authorId` | [`[ID!]`](#id) | ID of an author. | +| <a id="usercoretodosgroupid"></a>`groupId` | [`[ID!]`](#id) | ID of a group. | +| <a id="usercoretodosprojectid"></a>`projectId` | [`[ID!]`](#id) | ID of a project. | +| <a id="usercoretodosstate"></a>`state` | [`[TodoStateEnum!]`](#todostateenum) | State of the todo. | +| <a id="usercoretodostype"></a>`type` | [`[TodoTargetEnum!]`](#todotargetenum) | Type of the todo. | ### `UserMergeRequestInteraction` @@ -14053,7 +14649,7 @@ fields relate to interactions between the two entities. | <a id="usermergerequestinteractionapproved"></a>`approved` | [`Boolean!`](#boolean) | Whether this user has approved this merge request. | | <a id="usermergerequestinteractioncanmerge"></a>`canMerge` | [`Boolean!`](#boolean) | Whether this user can merge this merge request. | | <a id="usermergerequestinteractioncanupdate"></a>`canUpdate` | [`Boolean!`](#boolean) | Whether this user can update this merge request. | -| <a id="usermergerequestinteractionreviewstate"></a>`reviewState` | [`MergeRequestReviewState`](#mergerequestreviewstate) | The state of the review by this user. | +| <a id="usermergerequestinteractionreviewstate"></a>`reviewState` | [`MergeRequestReviewState`](#mergerequestreviewstate) | State of the review by this user. | | <a id="usermergerequestinteractionreviewed"></a>`reviewed` | [`Boolean!`](#boolean) | Whether this user has provided a review for this merge request. | ### `UserPermissions` @@ -14101,15 +14697,15 @@ Represents a vulnerability. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="vulnerabilityconfirmedat"></a>`confirmedAt` | [`Time`](#time) | Timestamp of when the vulnerability state was changed to confirmed. | -| <a id="vulnerabilityconfirmedby"></a>`confirmedBy` | [`UserCore`](#usercore) | The user that confirmed the vulnerability. | +| <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="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)) | | <a id="vulnerabilitydismissedat"></a>`dismissedAt` | [`Time`](#time) | Timestamp of when the vulnerability state was changed to dismissed. | -| <a id="vulnerabilitydismissedby"></a>`dismissedBy` | [`UserCore`](#usercore) | The user that dismissed the vulnerability. | +| <a id="vulnerabilitydismissedby"></a>`dismissedBy` | [`UserCore`](#usercore) | User that dismissed the vulnerability. | | <a id="vulnerabilityexternalissuelinks"></a>`externalIssueLinks` | [`VulnerabilityExternalIssueLinkConnection!`](#vulnerabilityexternalissuelinkconnection) | List of external issue links related to the vulnerability. (see [Connections](#connections)) | -| <a id="vulnerabilityfalsepositive"></a>`falsePositive` | [`Boolean`](#boolean) | Indicates whether the vulnerability is a false positive. Available only when feature flag `vulnerability_flags` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. | +| <a id="vulnerabilityfalsepositive"></a>`falsePositive` | [`Boolean`](#boolean) | Indicates whether the vulnerability is a false positive. | | <a id="vulnerabilityhassolutions"></a>`hasSolutions` | [`Boolean`](#boolean) | Indicates whether there is a solution available for this vulnerability. | | <a id="vulnerabilityid"></a>`id` | [`ID!`](#id) | GraphQL ID of the vulnerability. | | <a id="vulnerabilityidentifiers"></a>`identifiers` | [`[VulnerabilityIdentifier!]!`](#vulnerabilityidentifier) | Identifiers of the vulnerability. | @@ -14117,10 +14713,10 @@ Represents a vulnerability. | <a id="vulnerabilitymergerequest"></a>`mergeRequest` | [`MergeRequest`](#mergerequest) | Merge request that fixes the vulnerability. | | <a id="vulnerabilitynotes"></a>`notes` | [`NoteConnection!`](#noteconnection) | All notes on this noteable. (see [Connections](#connections)) | | <a id="vulnerabilityprimaryidentifier"></a>`primaryIdentifier` | [`VulnerabilityIdentifier`](#vulnerabilityidentifier) | Primary identifier of the vulnerability. | -| <a id="vulnerabilityproject"></a>`project` | [`Project`](#project) | The project on which the vulnerability was found. | -| <a id="vulnerabilityreporttype"></a>`reportType` | [`VulnerabilityReportType`](#vulnerabilityreporttype) | Type of the security report that found the vulnerability (SAST, DEPENDENCY_SCANNING, CONTAINER_SCANNING, DAST, SECRET_DETECTION, COVERAGE_FUZZING, API_FUZZING, CLUSTER_IMAGE_SCANNING). `Scan Type` in the UI. | +| <a id="vulnerabilityproject"></a>`project` | [`Project`](#project) | Project on which the vulnerability was found. | +| <a id="vulnerabilityreporttype"></a>`reportType` | [`VulnerabilityReportType`](#vulnerabilityreporttype) | Type of the security report that found the vulnerability (SAST, DEPENDENCY_SCANNING, CONTAINER_SCANNING, DAST, SECRET_DETECTION, COVERAGE_FUZZING, API_FUZZING, CLUSTER_IMAGE_SCANNING, GENERIC). `Scan Type` in the UI. | | <a id="vulnerabilityresolvedat"></a>`resolvedAt` | [`Time`](#time) | Timestamp of when the vulnerability state was changed to resolved. | -| <a id="vulnerabilityresolvedby"></a>`resolvedBy` | [`UserCore`](#usercore) | The user that resolved the vulnerability. | +| <a id="vulnerabilityresolvedby"></a>`resolvedBy` | [`UserCore`](#usercore) | User that resolved the vulnerability. | | <a id="vulnerabilityresolvedondefaultbranch"></a>`resolvedOnDefaultBranch` | [`Boolean!`](#boolean) | Indicates whether the vulnerability is fixed on the default branch or not. | | <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). | @@ -14198,7 +14794,7 @@ Represents the vulnerability details commit field. | <a id="vulnerabilitydetailcommitdescription"></a>`description` | [`String`](#string) | Description of the field. | | <a id="vulnerabilitydetailcommitfieldname"></a>`fieldName` | [`String`](#string) | Name of the field. | | <a id="vulnerabilitydetailcommitname"></a>`name` | [`String`](#string) | Name of the field. | -| <a id="vulnerabilitydetailcommitvalue"></a>`value` | [`String!`](#string) | The commit SHA value. | +| <a id="vulnerabilitydetailcommitvalue"></a>`value` | [`String!`](#string) | Commit SHA value. | ### `VulnerabilityDetailDiff` @@ -14357,7 +14953,7 @@ Represents an issue link of a vulnerability. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="vulnerabilityissuelinkid"></a>`id` | [`ID!`](#id) | GraphQL ID of the vulnerability. | -| <a id="vulnerabilityissuelinkissue"></a>`issue` | [`Issue!`](#issue) | The issue attached to issue link. | +| <a id="vulnerabilityissuelinkissue"></a>`issue` | [`Issue!`](#issue) | Issue attached to issue link. | | <a id="vulnerabilityissuelinklinktype"></a>`linkType` | [`VulnerabilityIssueLinkType!`](#vulnerabilityissuelinktype) | Type of the issue link. | ### `VulnerabilityLocationContainerScanning` @@ -14412,6 +15008,16 @@ Represents the location of a vulnerability found by a dependency security scan. | <a id="vulnerabilitylocationdependencyscanningdependency"></a>`dependency` | [`VulnerableDependency`](#vulnerabledependency) | Dependency containing the vulnerability. | | <a id="vulnerabilitylocationdependencyscanningfile"></a>`file` | [`String`](#string) | Path to the vulnerable file. | +### `VulnerabilityLocationGeneric` + +Represents the location of a vulnerability found by a generic scanner. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="vulnerabilitylocationgenericdescription"></a>`description` | [`String`](#string) | Free-form description of where the vulnerability is located. | + ### `VulnerabilityLocationSast` Represents the location of a vulnerability found by a SAST scan. @@ -14497,8 +15103,8 @@ Represents a vulnerable dependency. Used in vulnerability location data. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="vulnerabledependencypackage"></a>`package` | [`VulnerablePackage`](#vulnerablepackage) | The package associated with the vulnerable dependency. | -| <a id="vulnerabledependencyversion"></a>`version` | [`String`](#string) | The version of the vulnerable dependency. | +| <a id="vulnerabledependencypackage"></a>`package` | [`VulnerablePackage`](#vulnerablepackage) | Package associated with the vulnerable dependency. | +| <a id="vulnerabledependencyversion"></a>`version` | [`String`](#string) | Version of the vulnerable dependency. | ### `VulnerablePackage` @@ -14508,7 +15114,7 @@ Represents a vulnerable package. Used in vulnerability dependency data. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="vulnerablepackagename"></a>`name` | [`String`](#string) | The name of the vulnerable package. | +| <a id="vulnerablepackagename"></a>`name` | [`String`](#string) | Name of the vulnerable package. | ### `VulnerableProjectsByGrade` @@ -14698,8 +15304,8 @@ Values for YAML processor result. | Value | Description | | ----- | ----------- | -| <a id="ciconfigstatusinvalid"></a>`INVALID` | The configuration file is not valid. | -| <a id="ciconfigstatusvalid"></a>`VALID` | The configuration file is valid. | +| <a id="ciconfigstatusinvalid"></a>`INVALID` | Configuration file is not valid. | +| <a id="ciconfigstatusvalid"></a>`VALID` | Configuration file is valid. | ### `CiJobStatus` @@ -14827,10 +15433,10 @@ Status of the tags cleanup of a container repository. | Value | Description | | ----- | ----------- | -| <a id="containerrepositorycleanupstatusongoing"></a>`ONGOING` | The tags cleanup is ongoing. | -| <a id="containerrepositorycleanupstatusscheduled"></a>`SCHEDULED` | The tags cleanup is scheduled and is going to be executed shortly. | -| <a id="containerrepositorycleanupstatusunfinished"></a>`UNFINISHED` | The tags cleanup has been partially executed. There are still remaining tags to delete. | -| <a id="containerrepositorycleanupstatusunscheduled"></a>`UNSCHEDULED` | The tags cleanup is not scheduled. This is the default state. | +| <a id="containerrepositorycleanupstatusongoing"></a>`ONGOING` | Tags cleanup is ongoing. | +| <a id="containerrepositorycleanupstatusscheduled"></a>`SCHEDULED` | Tags cleanup is scheduled and is going to be executed shortly. | +| <a id="containerrepositorycleanupstatusunfinished"></a>`UNFINISHED` | Tags cleanup has been partially executed. There are still remaining tags to delete. | +| <a id="containerrepositorycleanupstatusunscheduled"></a>`UNSCHEDULED` | Tags cleanup is not scheduled. This is the default state. | ### `ContainerRepositorySort` @@ -14858,6 +15464,17 @@ Status of a container repository. | <a id="containerrepositorystatusdelete_failed"></a>`DELETE_FAILED` | Delete Failed status. | | <a id="containerrepositorystatusdelete_scheduled"></a>`DELETE_SCHEDULED` | Delete Scheduled status. | +### `DastProfileCadenceUnit` + +Unit for the duration of Dast Profile Cadence. + +| Value | Description | +| ----- | ----------- | +| <a id="dastprofilecadenceunitday"></a>`DAY` | DAST Profile Cadence duration in days. | +| <a id="dastprofilecadenceunitmonth"></a>`MONTH` | DAST Profile Cadence duration in months. | +| <a id="dastprofilecadenceunitweek"></a>`WEEK` | DAST Profile Cadence duration in weeks. | +| <a id="dastprofilecadenceunityear"></a>`YEAR` | DAST Profile Cadence duration in years. | + ### `DastScanTypeEnum` | Value | Description | @@ -14875,6 +15492,15 @@ Status of a container repository. | <a id="dastsiteprofilevalidationstatusenumpassed_validation"></a>`PASSED_VALIDATION` | Site validation process finished successfully. | | <a id="dastsiteprofilevalidationstatusenumpending_validation"></a>`PENDING_VALIDATION` | Site validation process has not started. | +### `DastSiteValidationStatusEnum` + +| Value | Description | +| ----- | ----------- | +| <a id="dastsitevalidationstatusenumfailed_validation"></a>`FAILED_VALIDATION` | Site validation process finished but failed. | +| <a id="dastsitevalidationstatusenuminprogress_validation"></a>`INPROGRESS_VALIDATION` | Site validation process is in progress. | +| <a id="dastsitevalidationstatusenumpassed_validation"></a>`PASSED_VALIDATION` | Site validation process finished successfully. | +| <a id="dastsitevalidationstatusenumpending_validation"></a>`PENDING_VALIDATION` | Site validation process has not started. | + ### `DastSiteValidationStrategyEnum` | Value | Description | @@ -14960,7 +15586,7 @@ Type of file the position refers to. | Value | Description | | ----- | ----------- | | <a id="diffpositiontypeimage"></a>`image` | An image. | -| <a id="diffpositiontypetext"></a>`text` | A text file. | +| <a id="diffpositiontypetext"></a>`text` | Text file. | ### `DoraMetricBucketingInterval` @@ -15074,6 +15700,14 @@ Group member relation. | <a id="groupmemberrelationdirect"></a>`DIRECT` | Members in the group itself. | | <a id="groupmemberrelationinherited"></a>`INHERITED` | Members in the group's ancestor groups. | +### `GroupPermission` + +User permission on groups. + +| Value | Description | +| ----- | ----------- | +| <a id="grouppermissioncreate_projects"></a>`CREATE_PROJECTS` | Groups where the user can create projects. | + ### `HealthStatus` Health status of an issue or epic. @@ -15143,6 +15777,8 @@ Values for sorting issues. | <a id="issuesortseverity_desc"></a>`SEVERITY_DESC` | Severity from more critical to less critical. | | <a id="issuesortsla_due_at_asc"></a>`SLA_DUE_AT_ASC` | Issues with earliest SLA due time shown first. | | <a id="issuesortsla_due_at_desc"></a>`SLA_DUE_AT_DESC` | Issues with latest SLA due time shown first. | +| <a id="issuesorttitle_asc"></a>`TITLE_ASC` | Title by ascending order. | +| <a id="issuesorttitle_desc"></a>`TITLE_DESC` | Title by descending order. | | <a id="issuesortupdated_asc"></a>`UPDATED_ASC` | Updated at ascending order. | | <a id="issuesortupdated_desc"></a>`UPDATED_DESC` | Updated at descending order. | | <a id="issuesortweight_asc"></a>`WEIGHT_ASC` | Weight by ascending order. | @@ -15189,12 +15825,12 @@ State of a GitLab iteration. | Value | Description | | ----- | ----------- | -| <a id="iterationstateall"></a>`all` | | -| <a id="iterationstateclosed"></a>`closed` | | -| <a id="iterationstatecurrent"></a>`current` | | -| <a id="iterationstateopened"></a>`opened` | | +| <a id="iterationstateall"></a>`all` | Any iteration. | +| <a id="iterationstateclosed"></a>`closed` | Closed iteration. | +| <a id="iterationstatecurrent"></a>`current` | Current iteration. | +| <a id="iterationstateopened"></a>`opened` | Open iteration. | | <a id="iterationstatestarted"></a>`started` **{warning-solid}** | **Deprecated** in 14.1. Use current instead. | -| <a id="iterationstateupcoming"></a>`upcoming` | | +| <a id="iterationstateupcoming"></a>`upcoming` | Upcoming iteration. | ### `IterationWildcardId` @@ -15374,10 +16010,10 @@ Milestone ID wildcard values. | Value | Description | | ----- | ----------- | -| <a id="milestonewildcardidany"></a>`ANY` | A milestone is assigned. | +| <a id="milestonewildcardidany"></a>`ANY` | Milestone is assigned. | | <a id="milestonewildcardidnone"></a>`NONE` | No milestone is assigned. | -| <a id="milestonewildcardidstarted"></a>`STARTED` | An open, started milestone (start date <= today). | -| <a id="milestonewildcardidupcoming"></a>`UPCOMING` | An open milestone due in the future (due date >= today). | +| <a id="milestonewildcardidstarted"></a>`STARTED` | Milestone assigned is open and started (start date <= today). | +| <a id="milestonewildcardidupcoming"></a>`UPCOMING` | Milestone assigned is due closest in the future (due date > today). | ### `MoveType` @@ -15385,8 +16021,8 @@ The position to which the adjacent object should be moved. | Value | Description | | ----- | ----------- | -| <a id="movetypeafter"></a>`after` | The adjacent object will be moved after the object that is being moved. | -| <a id="movetypebefore"></a>`before` | The adjacent object will be moved before the object that is being moved. | +| <a id="movetypeafter"></a>`after` | Adjacent object is moved after the object that is being moved. | +| <a id="movetypebefore"></a>`before` | Adjacent object is moved before the object that is being moved. | ### `MutationOperationMode` @@ -15421,8 +16057,8 @@ Negated Milestone ID wildcard values. | Value | Description | | ----- | ----------- | -| <a id="negatedmilestonewildcardidstarted"></a>`STARTED` | An open, started milestone (start date <= today). | -| <a id="negatedmilestonewildcardidupcoming"></a>`UPCOMING` | An open milestone due in the future (due date >= today). | +| <a id="negatedmilestonewildcardidstarted"></a>`STARTED` | Milestone assigned is open and yet to be started (start date > today). | +| <a id="negatedmilestonewildcardidupcoming"></a>`UPCOMING` | Milestone assigned is open but due in the past (due date <= today). | ### `NetworkPolicyKind` @@ -15430,8 +16066,8 @@ Kind of the network policy. | Value | Description | | ----- | ----------- | -| <a id="networkpolicykindciliumnetworkpolicy"></a>`CiliumNetworkPolicy` | The policy kind of Cilium Network Policy. | -| <a id="networkpolicykindnetworkpolicy"></a>`NetworkPolicy` | The policy kind of Network Policy. | +| <a id="networkpolicykindciliumnetworkpolicy"></a>`CiliumNetworkPolicy` | Policy kind of Cilium Network Policy. | +| <a id="networkpolicykindnetworkpolicy"></a>`NetworkPolicy` | Policy kind of Network Policy. | ### `OncallRotationUnitEnum` @@ -15590,8 +16226,8 @@ State of a requirement. | Value | Description | | ----- | ----------- | -| <a id="requirementstatearchived"></a>`ARCHIVED` | | -| <a id="requirementstateopened"></a>`OPENED` | | +| <a id="requirementstatearchived"></a>`ARCHIVED` | Archived requirement. | +| <a id="requirementstateopened"></a>`OPENED` | Open requirement. | ### `RequirementStatusFilter` @@ -15599,9 +16235,18 @@ Status of a requirement based on last test report. | Value | Description | | ----- | ----------- | -| <a id="requirementstatusfilterfailed"></a>`FAILED` | | +| <a id="requirementstatusfilterfailed"></a>`FAILED` | Failed test report. | | <a id="requirementstatusfiltermissing"></a>`MISSING` | Requirements without any test report. | -| <a id="requirementstatusfilterpassed"></a>`PASSED` | | +| <a id="requirementstatusfilterpassed"></a>`PASSED` | Passed test report. | + +### `RunnerMembershipFilter` + +Values for filtering runners in namespaces. + +| Value | Description | +| ----- | ----------- | +| <a id="runnermembershipfilterdescendants"></a>`DESCENDANTS` | Include runners that have either a direct relationship or a relationship with descendants. These can be project runners or group runners (in the case where group is queried). | +| <a id="runnermembershipfilterdirect"></a>`DIRECT` | Include runners that have a direct relationship. | ### `SastUiComponentSize` @@ -15609,9 +16254,9 @@ Size of UI component in SAST configuration page. | Value | Description | | ----- | ----------- | -| <a id="sastuicomponentsizelarge"></a>`LARGE` | The size of UI component in SAST configuration page is large. | -| <a id="sastuicomponentsizemedium"></a>`MEDIUM` | The size of UI component in SAST configuration page is medium. | -| <a id="sastuicomponentsizesmall"></a>`SMALL` | The size of UI component in SAST configuration page is small. | +| <a id="sastuicomponentsizelarge"></a>`LARGE` | Size of UI component in SAST configuration page is large. | +| <a id="sastuicomponentsizemedium"></a>`MEDIUM` | Size of UI component in SAST configuration page is medium. | +| <a id="sastuicomponentsizesmall"></a>`SMALL` | Size of UI component in SAST configuration page is small. | ### `SecurityReportTypeEnum` @@ -15632,14 +16277,14 @@ The type of the security scanner. | Value | Description | | ----- | ----------- | -| <a id="securityscannertypeapi_fuzzing"></a>`API_FUZZING` | | -| <a id="securityscannertypecluster_image_scanning"></a>`CLUSTER_IMAGE_SCANNING` | | -| <a id="securityscannertypecontainer_scanning"></a>`CONTAINER_SCANNING` | | -| <a id="securityscannertypecoverage_fuzzing"></a>`COVERAGE_FUZZING` | | -| <a id="securityscannertypedast"></a>`DAST` | | -| <a id="securityscannertypedependency_scanning"></a>`DEPENDENCY_SCANNING` | | -| <a id="securityscannertypesast"></a>`SAST` | | -| <a id="securityscannertypesecret_detection"></a>`SECRET_DETECTION` | | +| <a id="securityscannertypeapi_fuzzing"></a>`API_FUZZING` | API Fuzzing scanner. | +| <a id="securityscannertypecluster_image_scanning"></a>`CLUSTER_IMAGE_SCANNING` | Cluster Image Scanning scanner. | +| <a id="securityscannertypecontainer_scanning"></a>`CONTAINER_SCANNING` | Container Scanning scanner. | +| <a id="securityscannertypecoverage_fuzzing"></a>`COVERAGE_FUZZING` | Coverage Fuzzing scanner. | +| <a id="securityscannertypedast"></a>`DAST` | DAST scanner. | +| <a id="securityscannertypedependency_scanning"></a>`DEPENDENCY_SCANNING` | Dependency Scanning scanner. | +| <a id="securityscannertypesast"></a>`SAST` | SAST scanner. | +| <a id="securityscannertypesecret_detection"></a>`SECRET_DETECTION` | Secret Detection scanner. | ### `SentryErrorStatus` @@ -15741,8 +16386,8 @@ State of a test report. | Value | Description | | ----- | ----------- | -| <a id="testreportstatefailed"></a>`FAILED` | | -| <a id="testreportstatepassed"></a>`PASSED` | | +| <a id="testreportstatefailed"></a>`FAILED` | Failed test report. | +| <a id="testreportstatepassed"></a>`PASSED` | Passed test report. | ### `TodoActionEnum` @@ -15762,19 +16407,19 @@ State of a test report. | Value | Description | | ----- | ----------- | -| <a id="todostateenumdone"></a>`done` | The state of the todo is done. | -| <a id="todostateenumpending"></a>`pending` | The state of the todo is pending. | +| <a id="todostateenumdone"></a>`done` | State of the todo is done. | +| <a id="todostateenumpending"></a>`pending` | State of the todo is pending. | ### `TodoTargetEnum` | Value | Description | | ----- | ----------- | -| <a id="todotargetenumalert"></a>`ALERT` | An Alert. | -| <a id="todotargetenumcommit"></a>`COMMIT` | A Commit. | -| <a id="todotargetenumdesign"></a>`DESIGN` | A Design. | +| <a id="todotargetenumalert"></a>`ALERT` | Alert. | +| <a id="todotargetenumcommit"></a>`COMMIT` | Commit. | +| <a id="todotargetenumdesign"></a>`DESIGN` | Design. | | <a id="todotargetenumepic"></a>`EPIC` | An Epic. | -| <a id="todotargetenumissue"></a>`ISSUE` | An Issue. | -| <a id="todotargetenummergerequest"></a>`MERGEREQUEST` | A MergeRequest. | +| <a id="todotargetenumissue"></a>`ISSUE` | Issue. | +| <a id="todotargetenummergerequest"></a>`MERGEREQUEST` | Merge request. | ### `TypeEnum` @@ -15789,7 +16434,6 @@ Name of the feature that the callout is for. | Value | Description | | ----- | ----------- | -| <a id="usercalloutfeaturenameenumaccount_recovery_regular_check"></a>`ACCOUNT_RECOVERY_REGULAR_CHECK` | Callout feature name for account_recovery_regular_check. | | <a id="usercalloutfeaturenameenumactive_user_count_threshold"></a>`ACTIVE_USER_COUNT_THRESHOLD` | Callout feature name for active_user_count_threshold. | | <a id="usercalloutfeaturenameenumbuy_pipeline_minutes_notification_dot"></a>`BUY_PIPELINE_MINUTES_NOTIFICATION_DOT` | Callout feature name for buy_pipeline_minutes_notification_dot. | | <a id="usercalloutfeaturenameenumcanary_deployment"></a>`CANARY_DEPLOYMENT` | Callout feature name for canary_deployment. | @@ -15818,6 +16462,7 @@ Name of the feature that the callout is for. | <a id="usercalloutfeaturenameenumthreat_monitoring_info"></a>`THREAT_MONITORING_INFO` | Callout feature name for threat_monitoring_info. | | <a id="usercalloutfeaturenameenumtrial_status_reminder_d14"></a>`TRIAL_STATUS_REMINDER_D14` | Callout feature name for trial_status_reminder_d14. | | <a id="usercalloutfeaturenameenumtrial_status_reminder_d3"></a>`TRIAL_STATUS_REMINDER_D3` | Callout feature name for trial_status_reminder_d3. | +| <a id="usercalloutfeaturenameenumtwo_factor_auth_recovery_settings_check"></a>`TWO_FACTOR_AUTH_RECOVERY_SETTINGS_CHECK` | Callout feature name for two_factor_auth_recovery_settings_check. | | <a id="usercalloutfeaturenameenumultimate_trial"></a>`ULTIMATE_TRIAL` | Callout feature name for ultimate_trial. | | <a id="usercalloutfeaturenameenumunfinished_tag_cleanup_callout"></a>`UNFINISHED_TAG_CLEANUP_CALLOUT` | Callout feature name for unfinished_tag_cleanup_callout. | | <a id="usercalloutfeaturenameenumweb_ide_alert_dismissed"></a>`WEB_IDE_ALERT_DISMISSED` | Callout feature name for web_ide_alert_dismissed. | @@ -15829,9 +16474,9 @@ Possible states of a user. | Value | Description | | ----- | ----------- | -| <a id="userstateactive"></a>`active` | The user is active and is able to use the system. | -| <a id="userstateblocked"></a>`blocked` | The user has been blocked and is prevented from using the system. | -| <a id="userstatedeactivated"></a>`deactivated` | The user is no longer active and is unable to use the system. | +| <a id="userstateactive"></a>`active` | User is active and is able to use the system. | +| <a id="userstateblocked"></a>`blocked` | User has been blocked and is prevented from using the system. | +| <a id="userstatedeactivated"></a>`deactivated` | User is no longer active and is unable to use the system. | ### `VisibilityLevelsEnum` @@ -15845,9 +16490,23 @@ Possible states of a user. | Value | Description | | ----- | ----------- | -| <a id="visibilityscopesenuminternal"></a>`internal` | The snippet is visible for any logged in user except external users. | -| <a id="visibilityscopesenumprivate"></a>`private` | The snippet is visible only to the snippet creator. | -| <a id="visibilityscopesenumpublic"></a>`public` | The snippet can be accessed without any authentication. | +| <a id="visibilityscopesenuminternal"></a>`internal` | Snippet is visible for any logged in user except external users. | +| <a id="visibilityscopesenumprivate"></a>`private` | Snippet is visible only to the snippet creator. | +| <a id="visibilityscopesenumpublic"></a>`public` | Snippet can be accessed without any authentication. | + +### `VulnerabilityConfidence` + +Confidence that a given vulnerability is present in the codebase. + +| Value | Description | +| ----- | ----------- | +| <a id="vulnerabilityconfidenceconfirmed"></a>`CONFIRMED` | Confirmed confidence. | +| <a id="vulnerabilityconfidenceexperimental"></a>`EXPERIMENTAL` | Experimental confidence. | +| <a id="vulnerabilityconfidencehigh"></a>`HIGH` | High confidence. | +| <a id="vulnerabilityconfidenceignore"></a>`IGNORE` | Ignore confidence. | +| <a id="vulnerabilityconfidencelow"></a>`LOW` | Low confidence. | +| <a id="vulnerabilityconfidencemedium"></a>`MEDIUM` | Medium confidence. | +| <a id="vulnerabilityconfidenceunknown"></a>`UNKNOWN` | Unknown confidence. | ### `VulnerabilityDismissalReason` @@ -15883,11 +16542,11 @@ The grade of the vulnerable project. | Value | Description | | ----- | ----------- | -| <a id="vulnerabilitygradea"></a>`A` | | -| <a id="vulnerabilitygradeb"></a>`B` | | -| <a id="vulnerabilitygradec"></a>`C` | | -| <a id="vulnerabilitygraded"></a>`D` | | -| <a id="vulnerabilitygradef"></a>`F` | | +| <a id="vulnerabilitygradea"></a>`A` | A grade. | +| <a id="vulnerabilitygradeb"></a>`B` | B grade. | +| <a id="vulnerabilitygradec"></a>`C` | C grade. | +| <a id="vulnerabilitygraded"></a>`D` | D grade. | +| <a id="vulnerabilitygradef"></a>`F` | F grade. | ### `VulnerabilityIssueLinkType` @@ -15895,8 +16554,8 @@ The type of the issue link related to a vulnerability. | Value | Description | | ----- | ----------- | -| <a id="vulnerabilityissuelinktypecreated"></a>`CREATED` | | -| <a id="vulnerabilityissuelinktyperelated"></a>`RELATED` | | +| <a id="vulnerabilityissuelinktypecreated"></a>`CREATED` | Issue is created for the vulnerability. | +| <a id="vulnerabilityissuelinktyperelated"></a>`RELATED` | Has a related issue. | ### `VulnerabilityReportType` @@ -15904,14 +16563,15 @@ The type of the security scan that found the vulnerability. | Value | Description | | ----- | ----------- | -| <a id="vulnerabilityreporttypeapi_fuzzing"></a>`API_FUZZING` | | -| <a id="vulnerabilityreporttypecluster_image_scanning"></a>`CLUSTER_IMAGE_SCANNING` | | -| <a id="vulnerabilityreporttypecontainer_scanning"></a>`CONTAINER_SCANNING` | | -| <a id="vulnerabilityreporttypecoverage_fuzzing"></a>`COVERAGE_FUZZING` | | -| <a id="vulnerabilityreporttypedast"></a>`DAST` | | -| <a id="vulnerabilityreporttypedependency_scanning"></a>`DEPENDENCY_SCANNING` | | -| <a id="vulnerabilityreporttypesast"></a>`SAST` | | -| <a id="vulnerabilityreporttypesecret_detection"></a>`SECRET_DETECTION` | | +| <a id="vulnerabilityreporttypeapi_fuzzing"></a>`API_FUZZING` | API Fuzzing report. | +| <a id="vulnerabilityreporttypecluster_image_scanning"></a>`CLUSTER_IMAGE_SCANNING` | Cluster Image Scanning report. | +| <a id="vulnerabilityreporttypecontainer_scanning"></a>`CONTAINER_SCANNING` | Container Scanning report. | +| <a id="vulnerabilityreporttypecoverage_fuzzing"></a>`COVERAGE_FUZZING` | Coverage Fuzzing report. | +| <a id="vulnerabilityreporttypedast"></a>`DAST` | DAST report. | +| <a id="vulnerabilityreporttypedependency_scanning"></a>`DEPENDENCY_SCANNING` | Dependency Scanning report. | +| <a id="vulnerabilityreporttypegeneric"></a>`GENERIC` | Generic report. | +| <a id="vulnerabilityreporttypesast"></a>`SAST` | SAST report. | +| <a id="vulnerabilityreporttypesecret_detection"></a>`SECRET_DETECTION` | Secret Detection report. | ### `VulnerabilitySeverity` @@ -15919,12 +16579,12 @@ The severity of the vulnerability. | Value | Description | | ----- | ----------- | -| <a id="vulnerabilityseveritycritical"></a>`CRITICAL` | | -| <a id="vulnerabilityseverityhigh"></a>`HIGH` | | -| <a id="vulnerabilityseverityinfo"></a>`INFO` | | -| <a id="vulnerabilityseveritylow"></a>`LOW` | | -| <a id="vulnerabilityseveritymedium"></a>`MEDIUM` | | -| <a id="vulnerabilityseverityunknown"></a>`UNKNOWN` | | +| <a id="vulnerabilityseveritycritical"></a>`CRITICAL` | Critical severity. | +| <a id="vulnerabilityseverityhigh"></a>`HIGH` | High severity. | +| <a id="vulnerabilityseverityinfo"></a>`INFO` | Info severity. | +| <a id="vulnerabilityseveritylow"></a>`LOW` | Low severity. | +| <a id="vulnerabilityseveritymedium"></a>`MEDIUM` | Medium severity. | +| <a id="vulnerabilityseverityunknown"></a>`UNKNOWN` | Unknown severity. | ### `VulnerabilitySort` @@ -15949,10 +16609,10 @@ The state of the vulnerability. | Value | Description | | ----- | ----------- | -| <a id="vulnerabilitystateconfirmed"></a>`CONFIRMED` | | -| <a id="vulnerabilitystatedetected"></a>`DETECTED` | | -| <a id="vulnerabilitystatedismissed"></a>`DISMISSED` | | -| <a id="vulnerabilitystateresolved"></a>`RESOLVED` | | +| <a id="vulnerabilitystateconfirmed"></a>`CONFIRMED` | Confirmed vulnerability. | +| <a id="vulnerabilitystatedetected"></a>`DETECTED` | Detected vulnerability. | +| <a id="vulnerabilitystatedismissed"></a>`DISMISSED` | Dismissed vulnerability. | +| <a id="vulnerabilitystateresolved"></a>`RESOLVED` | Resolved vulnerability. | ### `WeightWildcardId` @@ -16072,12 +16732,24 @@ A `CustomEmojiID` is a global ID. It is encoded as a string. An example `CustomEmojiID` is: `"gid://gitlab/CustomEmoji/1"`. +### `CustomerRelationsOrganizationID` + +A `CustomerRelationsOrganizationID` is a global ID. It is encoded as a string. + +An example `CustomerRelationsOrganizationID` is: `"gid://gitlab/CustomerRelations::Organization/1"`. + ### `DastProfileID` A `DastProfileID` is a global ID. It is encoded as a string. An example `DastProfileID` is: `"gid://gitlab/Dast::Profile/1"`. +### `DastProfileScheduleID` + +A `DastProfileScheduleID` is a global ID. It is encoded as a string. + +An example `DastProfileScheduleID` is: `"gid://gitlab/Dast::ProfileSchedule/1"`. + ### `DastScannerProfileID` A `DastScannerProfileID` is a global ID. It is encoded as a string. @@ -16550,6 +17222,7 @@ One of: - [`VulnerabilityLocationCoverageFuzzing`](#vulnerabilitylocationcoveragefuzzing) - [`VulnerabilityLocationDast`](#vulnerabilitylocationdast) - [`VulnerabilityLocationDependencyScanning`](#vulnerabilitylocationdependencyscanning) +- [`VulnerabilityLocationGeneric`](#vulnerabilitylocationgeneric) - [`VulnerabilityLocationSast`](#vulnerabilitylocationsast) - [`VulnerabilityLocationSecretDetection`](#vulnerabilitylocationsecretdetection) @@ -16614,16 +17287,16 @@ Implementations: | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="designfieldsdiffrefs"></a>`diffRefs` | [`DiffRefs!`](#diffrefs) | The diff refs for this design. | +| <a id="designfieldsdiffrefs"></a>`diffRefs` | [`DiffRefs!`](#diffrefs) | Diff refs for this design. | | <a id="designfieldsevent"></a>`event` | [`DesignVersionEvent!`](#designversionevent) | How this design was changed in the current version. | -| <a id="designfieldsfilename"></a>`filename` | [`String!`](#string) | The filename of the design. | -| <a id="designfieldsfullpath"></a>`fullPath` | [`String!`](#string) | The full path to the design file. | -| <a id="designfieldsid"></a>`id` | [`ID!`](#id) | The ID of this design. | -| <a id="designfieldsimage"></a>`image` | [`String!`](#string) | The URL of the full-sized image. | +| <a id="designfieldsfilename"></a>`filename` | [`String!`](#string) | Filename of the design. | +| <a id="designfieldsfullpath"></a>`fullPath` | [`String!`](#string) | Full path to the design file. | +| <a id="designfieldsid"></a>`id` | [`ID!`](#id) | ID of this design. | +| <a id="designfieldsimage"></a>`image` | [`String!`](#string) | URL of the full-sized image. | | <a id="designfieldsimagev432x230"></a>`imageV432x230` | [`String`](#string) | The URL of the design resized to fit within the bounds of 432x230. This will be `null` if the image has not been generated. | -| <a id="designfieldsissue"></a>`issue` | [`Issue!`](#issue) | The issue the design belongs to. | -| <a id="designfieldsnotescount"></a>`notesCount` | [`Int!`](#int) | The total count of user-created notes for this design. | -| <a id="designfieldsproject"></a>`project` | [`Project!`](#project) | The project the design belongs to. | +| <a id="designfieldsissue"></a>`issue` | [`Issue!`](#issue) | Issue the design belongs to. | +| <a id="designfieldsnotescount"></a>`notesCount` | [`Int!`](#int) | Total count of user-created notes for this design. | +| <a id="designfieldsproject"></a>`project` | [`Project!`](#project) | Project the design belongs to. | #### `Entry` @@ -16655,7 +17328,7 @@ Implementations: | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="eventableevents"></a>`events` | [`EventConnection`](#eventconnection) | A list of events associated with the object. (see [Connections](#connections)) | +| <a id="eventableevents"></a>`events` | [`EventConnection`](#eventconnection) | List of events associated with the object. (see [Connections](#connections)) | #### `MemberInterface` @@ -16776,7 +17449,7 @@ Implementations: | <a id="usergroupcount"></a>`groupCount` | [`Int`](#int) | Group count for the user. | | <a id="usergroupmemberships"></a>`groupMemberships` | [`GroupMemberConnection`](#groupmemberconnection) | Group memberships of the user. (see [Connections](#connections)) | | <a id="userid"></a>`id` | [`ID!`](#id) | ID of the user. | -| <a id="userlocation"></a>`location` | [`String`](#string) | The location of the user. | +| <a id="userlocation"></a>`location` | [`String`](#string) | Location of the user. | | <a id="username"></a>`name` | [`String!`](#string) | Human-readable name of the user. | | <a id="usernamespace"></a>`namespace` | [`Namespace`](#namespace) | Personal namespace of the user. | | <a id="userprojectmemberships"></a>`projectMemberships` | [`ProjectMemberConnection`](#projectmemberconnection) | Project memberships of the user. (see [Connections](#connections)) | @@ -16816,7 +17489,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="userassignedmergerequestsreviewerusername"></a>`reviewerUsername` | [`String`](#string) | Username of the reviewer. | | <a id="userassignedmergerequestssort"></a>`sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | | <a id="userassignedmergerequestssourcebranches"></a>`sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | -| <a id="userassignedmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | A merge request state. If provided, all resolved merge requests will have this state. | +| <a id="userassignedmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | <a id="userassignedmergerequeststargetbranches"></a>`targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | ###### `User.authoredMergeRequests` @@ -16845,9 +17518,26 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="userauthoredmergerequestsreviewerusername"></a>`reviewerUsername` | [`String`](#string) | Username of the reviewer. | | <a id="userauthoredmergerequestssort"></a>`sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | | <a id="userauthoredmergerequestssourcebranches"></a>`sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | -| <a id="userauthoredmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | A merge request state. If provided, all resolved merge requests will have this state. | +| <a id="userauthoredmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | <a id="userauthoredmergerequeststargetbranches"></a>`targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | +###### `User.groups` + +Groups where the user has access. Will always return `null` if `paginatable_namespace_drop_down_for_project_creation` feature flag is disabled. + +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="usergroupspermissionscope"></a>`permissionScope` | [`GroupPermission`](#grouppermission) | Filter by permissions the user has on groups. | +| <a id="usergroupssearch"></a>`search` | [`String`](#string) | Search by group name or path. | + ###### `User.reviewRequestedMergeRequests` Merge requests assigned to the user for review. @@ -16874,7 +17564,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="userreviewrequestedmergerequestsprojectpath"></a>`projectPath` | [`String`](#string) | The full-path of the project the authored merge requests should be in. Incompatible with projectId. | | <a id="userreviewrequestedmergerequestssort"></a>`sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | | <a id="userreviewrequestedmergerequestssourcebranches"></a>`sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | -| <a id="userreviewrequestedmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | A merge request state. If provided, all resolved merge requests will have this state. | +| <a id="userreviewrequestedmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | <a id="userreviewrequestedmergerequeststargetbranches"></a>`targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | ###### `User.snippets` @@ -16892,7 +17582,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | | <a id="usersnippetsids"></a>`ids` | [`[SnippetID!]`](#snippetid) | Array of global snippet IDs. For example, `gid://gitlab/ProjectSnippet/1`. | -| <a id="usersnippetstype"></a>`type` | [`TypeEnum`](#typeenum) | The type of snippet. | +| <a id="usersnippetstype"></a>`type` | [`TypeEnum`](#typeenum) | Type of snippet. | | <a id="usersnippetsvisibility"></a>`visibility` | [`VisibilityScopesEnum`](#visibilityscopesenum) | Visibility of the snippet. | ###### `User.starredProjects` @@ -16947,12 +17637,12 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="usertodosaction"></a>`action` | [`[TodoActionEnum!]`](#todoactionenum) | The action to be filtered. | -| <a id="usertodosauthorid"></a>`authorId` | [`[ID!]`](#id) | The ID of an author. | -| <a id="usertodosgroupid"></a>`groupId` | [`[ID!]`](#id) | The ID of a group. | -| <a id="usertodosprojectid"></a>`projectId` | [`[ID!]`](#id) | The ID of a project. | -| <a id="usertodosstate"></a>`state` | [`[TodoStateEnum!]`](#todostateenum) | The state of the todo. | -| <a id="usertodostype"></a>`type` | [`[TodoTargetEnum!]`](#todotargetenum) | The type of the todo. | +| <a id="usertodosaction"></a>`action` | [`[TodoActionEnum!]`](#todoactionenum) | Action to be filtered. | +| <a id="usertodosauthorid"></a>`authorId` | [`[ID!]`](#id) | ID of an author. | +| <a id="usertodosgroupid"></a>`groupId` | [`[ID!]`](#id) | ID of a group. | +| <a id="usertodosprojectid"></a>`projectId` | [`[ID!]`](#id) | ID of a project. | +| <a id="usertodosstate"></a>`state` | [`[TodoStateEnum!]`](#todostateenum) | State of the todo. | +| <a id="usertodostype"></a>`type` | [`[TodoTargetEnum!]`](#todotargetenum) | Type of the todo. | ## Input types @@ -16970,7 +17660,7 @@ Field that are available while modifying the custom mapping attributes for an HT | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="alertmanagementpayloadalertfieldinputfieldname"></a>`fieldName` | [`AlertManagementPayloadAlertFieldName!`](#alertmanagementpayloadalertfieldname) | A GitLab alert field name. | +| <a id="alertmanagementpayloadalertfieldinputfieldname"></a>`fieldName` | [`AlertManagementPayloadAlertFieldName!`](#alertmanagementpayloadalertfieldname) | GitLab alert field name. | | <a id="alertmanagementpayloadalertfieldinputlabel"></a>`label` | [`String`](#string) | Human-readable label of the payload path. | | <a id="alertmanagementpayloadalertfieldinputpath"></a>`path` | [`[PayloadAlertFieldPathSegment!]!`](#payloadalertfieldpathsegment) | Path to value inside payload JSON. | | <a id="alertmanagementpayloadalertfieldinputtype"></a>`type` | [`AlertManagementPayloadAlertFieldType!`](#alertmanagementpayloadalertfieldtype) | Type of the parsed value. | @@ -16992,7 +17682,8 @@ Field that are available while modifying the custom mapping attributes for an HT | <a id="boardissueinputiterationwildcardid"></a>`iterationWildcardId` | [`IterationWildcardId`](#iterationwildcardid) | Filter by iteration ID wildcard. | | <a id="boardissueinputlabelname"></a>`labelName` | [`[String]`](#string) | Filter by label name. | | <a id="boardissueinputmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Filter by milestone title. | -| <a id="boardissueinputmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | +| <a id="boardissueinputmilestonewildcardid"></a>`milestoneWildcardId` | [`MilestoneWildcardId`](#milestonewildcardid) | Filter by milestone ID wildcard. | +| <a id="boardissueinputmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. Wildcard values "NONE" and "ANY" are supported. | | <a id="boardissueinputnot"></a>`not` | [`NegatedBoardIssueInput`](#negatedboardissueinput) | List of negated arguments. | | <a id="boardissueinputreleasetag"></a>`releaseTag` | [`String`](#string) | Filter by release tag. | | <a id="boardissueinputsearch"></a>`search` | [`String`](#string) | Search query for issue title or description. | @@ -17006,7 +17697,7 @@ Field that are available while modifying the custom mapping attributes for an HT | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="commitactionaction"></a>`action` | [`CommitActionMode!`](#commitactionmode) | The action to perform, create, delete, move, update, chmod. | +| <a id="commitactionaction"></a>`action` | [`CommitActionMode!`](#commitactionmode) | Action to perform: create, delete, move, update, or chmod. | | <a id="commitactioncontent"></a>`content` | [`String`](#string) | Content of the file. | | <a id="commitactionencoding"></a>`encoding` | [`CommitEncoding`](#commitencoding) | Encoding of the file. Default is text. | | <a id="commitactionexecutefilemode"></a>`executeFilemode` | [`Boolean`](#boolean) | Enables/disables the execute flag on the file. | @@ -17025,6 +17716,30 @@ Field that are available while modifying the custom mapping attributes for an HT | <a id="complianceframeworkinputname"></a>`name` | [`String`](#string) | New name for the compliance framework. | | <a id="complianceframeworkinputpipelineconfigurationfullpath"></a>`pipelineConfigurationFullPath` | [`String`](#string) | Full path of the compliance pipeline configuration stored in a project repository, such as `.gitlab/.compliance-gitlab-ci.yml@compliance/hipaa` **(ULTIMATE)**. | +### `DastProfileCadenceInput` + +Represents DAST Profile Cadence. + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="dastprofilecadenceinputduration"></a>`duration` | [`Int`](#int) | Duration of the DAST Profile Cadence. | +| <a id="dastprofilecadenceinputunit"></a>`unit` | [`DastProfileCadenceUnit`](#dastprofilecadenceunit) | Unit for the duration of DAST Profile Cadence. | + +### `DastProfileScheduleInput` + +Input type for DAST Profile Schedules. + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="dastprofilescheduleinputactive"></a>`active` | [`Boolean`](#boolean) | Status of a Dast Profile Schedule. | +| <a id="dastprofilescheduleinputcadence"></a>`cadence` | [`DastProfileCadenceInput`](#dastprofilecadenceinput) | Cadence of a Dast Profile Schedule. | +| <a id="dastprofilescheduleinputstartsat"></a>`startsAt` | [`Time`](#time) | Start time of a Dast Profile Schedule. | +| <a id="dastprofilescheduleinputtimezone"></a>`timezone` | [`String`](#string) | Time Zone for the Start time of a Dast Profile Schedule. | + ### `DastSiteProfileAuthInput` Input type for DastSiteProfile authentication. @@ -17034,11 +17749,11 @@ Input type for DastSiteProfile authentication. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="dastsiteprofileauthinputenabled"></a>`enabled` | [`Boolean`](#boolean) | Indicates whether authentication is enabled. | -| <a id="dastsiteprofileauthinputpassword"></a>`password` | [`String`](#string) | The password to authenticate with on the target website. | -| <a id="dastsiteprofileauthinputpasswordfield"></a>`passwordField` | [`String`](#string) | The name of password field at the sign-in HTML form. | +| <a id="dastsiteprofileauthinputpassword"></a>`password` | [`String`](#string) | Password to authenticate with on the target website. | +| <a id="dastsiteprofileauthinputpasswordfield"></a>`passwordField` | [`String`](#string) | Name of password field at the sign-in HTML form. | | <a id="dastsiteprofileauthinputurl"></a>`url` | [`String`](#string) | The URL of the page containing the sign-in HTML form on the target website. | -| <a id="dastsiteprofileauthinputusername"></a>`username` | [`String`](#string) | The username to authenticate with on the target website. | -| <a id="dastsiteprofileauthinputusernamefield"></a>`usernameField` | [`String`](#string) | The name of username field at the sign-in HTML form. | +| <a id="dastsiteprofileauthinputusername"></a>`username` | [`String`](#string) | Username to authenticate with on the target website. | +| <a id="dastsiteprofileauthinputusernamefield"></a>`usernameField` | [`String`](#string) | Name of username field at the sign-in HTML form. | ### `DiffImagePositionInput` @@ -17061,8 +17776,8 @@ Input type for DastSiteProfile authentication. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="diffpathsinputnewpath"></a>`newPath` | [`String`](#string) | The path of the file on the head sha. | -| <a id="diffpathsinputoldpath"></a>`oldPath` | [`String`](#string) | The path of the file on the start sha. | +| <a id="diffpathsinputnewpath"></a>`newPath` | [`String`](#string) | Path of the file on the HEAD SHA. | +| <a id="diffpathsinputoldpath"></a>`oldPath` | [`String`](#string) | Path of the file on the start SHA. | ### `DiffPositionInput` @@ -17085,7 +17800,7 @@ Input type for DastSiteProfile authentication. | ---- | ---- | ----------- | | <a id="epicfiltersauthorusername"></a>`authorUsername` | [`String`](#string) | Filter by author username. | | <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. | +| <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="epicfilterssearch"></a>`search` | [`String`](#string) | Search query for epic title or description. | @@ -17097,10 +17812,10 @@ A node of an epic tree. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="epictreenodefieldsinputtypeadjacentreferenceid"></a>`adjacentReferenceId` | [`EpicTreeSortingID`](#epictreesortingid) | The ID of the epic_issue or issue that the actual epic or issue is switched with. | -| <a id="epictreenodefieldsinputtypeid"></a>`id` | [`EpicTreeSortingID!`](#epictreesortingid) | The ID of the epic_issue or epic that is being moved. | +| <a id="epictreenodefieldsinputtypeadjacentreferenceid"></a>`adjacentReferenceId` | [`EpicTreeSortingID`](#epictreesortingid) | ID of the epic issue or issue the epic or issue is switched with. | +| <a id="epictreenodefieldsinputtypeid"></a>`id` | [`EpicTreeSortingID!`](#epictreesortingid) | ID of the epic issue or epic that is being moved. | | <a id="epictreenodefieldsinputtypenewparentid"></a>`newParentId` | [`EpicID`](#epicid) | ID of the new parent epic. | -| <a id="epictreenodefieldsinputtyperelativeposition"></a>`relativePosition` | [`MoveType`](#movetype) | The type of the switch, after or before allowed. | +| <a id="epictreenodefieldsinputtyperelativeposition"></a>`relativePosition` | [`MoveType`](#movetype) | Type of switch. Valid values are `after` or `before`. | ### `EscalationRuleInput` @@ -17110,10 +17825,10 @@ Represents an escalation rule. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="escalationruleinputelapsedtimeseconds"></a>`elapsedTimeSeconds` | [`Int!`](#int) | The time in seconds before the rule is activated. | -| <a id="escalationruleinputoncallscheduleiid"></a>`oncallScheduleIid` | [`ID`](#id) | The on-call schedule to notify. | -| <a id="escalationruleinputstatus"></a>`status` | [`EscalationRuleStatus!`](#escalationrulestatus) | The status required to prevent the rule from activating. | -| <a id="escalationruleinputusername"></a>`username` | [`String`](#string) | The username of the user to notify. | +| <a id="escalationruleinputelapsedtimeseconds"></a>`elapsedTimeSeconds` | [`Int!`](#int) | Time in seconds before the rule is activated. | +| <a id="escalationruleinputoncallscheduleiid"></a>`oncallScheduleIid` | [`ID`](#id) | On-call schedule to notify. | +| <a id="escalationruleinputstatus"></a>`status` | [`EscalationRuleStatus!`](#escalationrulestatus) | Status required to prevent the rule from activating. | +| <a id="escalationruleinputusername"></a>`username` | [`String`](#string) | Username of the user to notify. | ### `JiraUsersMappingInputType` @@ -17148,7 +17863,8 @@ Represents an escalation rule. | <a id="negatedboardissueinputiterationwildcardid"></a>`iterationWildcardId` | [`NegatedIterationWildcardId`](#negatediterationwildcardid) | Filter by iteration ID wildcard. | | <a id="negatedboardissueinputlabelname"></a>`labelName` | [`[String]`](#string) | Filter by label name. | | <a id="negatedboardissueinputmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Filter by milestone title. | -| <a id="negatedboardissueinputmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | +| <a id="negatedboardissueinputmilestonewildcardid"></a>`milestoneWildcardId` | [`MilestoneWildcardId`](#milestonewildcardid) | Filter by milestone ID wildcard. | +| <a id="negatedboardissueinputmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. Wildcard values "NONE" and "ANY" are supported. | | <a id="negatedboardissueinputreleasetag"></a>`releaseTag` | [`String`](#string) | Filter by release tag. | | <a id="negatedboardissueinputtypes"></a>`types` | [`[IssueType!]`](#issuetype) | Filter by the given issue types. | | <a id="negatedboardissueinputweight"></a>`weight` | [`String`](#string) | Filter by weight. | @@ -17161,7 +17877,7 @@ Represents an escalation rule. | ---- | ---- | ----------- | | <a id="negatedepicboardissueinputauthorusername"></a>`authorUsername` | [`String`](#string) | Filter by author username. | | <a id="negatedepicboardissueinputlabelname"></a>`labelName` | [`[String]`](#string) | Filter by label name. | -| <a id="negatedepicboardissueinputmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | +| <a id="negatedepicboardissueinputmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. Wildcard values "NONE" and "ANY" are supported. | ### `NegatedEpicFilterInput` @@ -17181,6 +17897,7 @@ Represents an escalation rule. | ---- | ---- | ----------- | | <a id="negatedissuefilterinputassigneeid"></a>`assigneeId` | [`String`](#string) | ID of a user not assigned to the issues. | | <a id="negatedissuefilterinputassigneeusernames"></a>`assigneeUsernames` | [`[String!]`](#string) | Usernames of users not assigned to the issue. | +| <a id="negatedissuefilterinputauthorusername"></a>`authorUsername` | [`String`](#string) | Username of a user who didn't author the issue. | | <a id="negatedissuefilterinputepicid"></a>`epicId` | [`String`](#string) | ID of an epic not associated with the issues. | | <a id="negatedissuefilterinputiids"></a>`iids` | [`[String!]`](#string) | List of IIDs of issues to exclude. For example, `[1, 2]`. | | <a id="negatedissuefilterinputiterationid"></a>`iterationId` | [`[ID!]`](#id) | List of iteration Global IDs not applied to the issue. | @@ -17188,6 +17905,7 @@ Represents an escalation rule. | <a id="negatedissuefilterinputlabelname"></a>`labelName` | [`[String!]`](#string) | Labels not applied to this issue. | | <a id="negatedissuefilterinputmilestonetitle"></a>`milestoneTitle` | [`[String!]`](#string) | Milestone not applied to this issue. | | <a id="negatedissuefilterinputmilestonewildcardid"></a>`milestoneWildcardId` | [`NegatedMilestoneWildcardId`](#negatedmilestonewildcardid) | Filter by negated milestone wildcard values. | +| <a id="negatedissuefilterinputmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | | <a id="negatedissuefilterinputweight"></a>`weight` | [`String`](#string) | Weight not applied to the issue. | ### `OncallRotationActivePeriodInputType` @@ -17198,8 +17916,8 @@ Active period time range for on-call rotation. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="oncallrotationactiveperiodinputtypeendtime"></a>`endTime` | [`String!`](#string) | The end of the rotation active period in 24 hour format, for example "18:30". | -| <a id="oncallrotationactiveperiodinputtypestarttime"></a>`startTime` | [`String!`](#string) | The start of the rotation active period in 24 hour format, for example "18:30". | +| <a id="oncallrotationactiveperiodinputtypeendtime"></a>`endTime` | [`String!`](#string) | End of the rotation active period in 24 hour format. For example, "18:30". | +| <a id="oncallrotationactiveperiodinputtypestarttime"></a>`startTime` | [`String!`](#string) | Start of the rotation active period in 24 hour format. For example, "18:30". | ### `OncallRotationDateInputType` @@ -17209,8 +17927,8 @@ Date input type for on-call rotation. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="oncallrotationdateinputtypedate"></a>`date` | [`String!`](#string) | The date component of the date in YYYY-MM-DD format. | -| <a id="oncallrotationdateinputtypetime"></a>`time` | [`String!`](#string) | The time component of the date in 24hr HH:MM format. | +| <a id="oncallrotationdateinputtypedate"></a>`date` | [`String!`](#string) | Date component of the date in YYYY-MM-DD format. | +| <a id="oncallrotationdateinputtypetime"></a>`time` | [`String!`](#string) | Time component of the date in 24hr HH:MM format. | ### `OncallRotationLengthInputType` @@ -17220,8 +17938,8 @@ The rotation length of the on-call rotation. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="oncallrotationlengthinputtypelength"></a>`length` | [`Int!`](#int) | The rotation length of the on-call rotation. | -| <a id="oncallrotationlengthinputtypeunit"></a>`unit` | [`OncallRotationUnitEnum!`](#oncallrotationunitenum) | The unit of the rotation length of the on-call rotation. | +| <a id="oncallrotationlengthinputtypelength"></a>`length` | [`Int!`](#int) | Rotation length of the on-call rotation. | +| <a id="oncallrotationlengthinputtypeunit"></a>`unit` | [`OncallRotationUnitEnum!`](#oncallrotationunitenum) | Unit of the rotation length of the on-call rotation. | ### `OncallUserInputType` @@ -17231,9 +17949,9 @@ The rotation user and color palette. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="oncalluserinputtypecolorpalette"></a>`colorPalette` | [`DataVisualizationColorEnum`](#datavisualizationcolorenum) | A value of DataVisualizationColorEnum. The color from the palette to assign to the on-call user. | -| <a id="oncalluserinputtypecolorweight"></a>`colorWeight` | [`DataVisualizationWeightEnum`](#datavisualizationweightenum) | A value of DataVisualizationWeightEnum. The color weight to assign to for the on-call user. Note: To view on-call schedules in GitLab, do not provide a value below 500. A value between 500 and 950 ensures sufficient contrast. | -| <a id="oncalluserinputtypeusername"></a>`username` | [`String!`](#string) | The username of the user to participate in the on-call rotation, such as `user_one`. | +| <a id="oncalluserinputtypecolorpalette"></a>`colorPalette` | [`DataVisualizationColorEnum`](#datavisualizationcolorenum) | Value of DataVisualizationColorEnum. The color from the palette to assign to the on-call user. | +| <a id="oncalluserinputtypecolorweight"></a>`colorWeight` | [`DataVisualizationWeightEnum`](#datavisualizationweightenum) | Color weight to assign to for the on-call user. To view on-call schedules in GitLab, do not provide a value below 500. A value between 500 and 950 ensures sufficient contrast. | +| <a id="oncalluserinputtypeusername"></a>`username` | [`String!`](#string) | Username of the user to participate in the on-call rotation. For example, `"user_one"`. | ### `ReleaseAssetLinkInput` @@ -17244,7 +17962,7 @@ Fields that are available when modifying a release asset link. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="releaseassetlinkinputdirectassetpath"></a>`directAssetPath` | [`String`](#string) | Relative path for a direct asset link. | -| <a id="releaseassetlinkinputlinktype"></a>`linkType` | [`ReleaseAssetLinkType`](#releaseassetlinktype) | The type of the asset link. | +| <a id="releaseassetlinkinputlinktype"></a>`linkType` | [`ReleaseAssetLinkType`](#releaseassetlinktype) | Type of the asset link. | | <a id="releaseassetlinkinputname"></a>`name` | [`String!`](#string) | Name of the asset link. | | <a id="releaseassetlinkinputurl"></a>`url` | [`String!`](#string) | URL of the asset link. | @@ -17256,7 +17974,7 @@ Fields that are available when modifying release assets. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="releaseassetsinputlinks"></a>`links` | [`[ReleaseAssetLinkInput!]`](#releaseassetlinkinput) | A list of asset links to associate to the release. | +| <a id="releaseassetsinputlinks"></a>`links` | [`[ReleaseAssetLinkInput!]`](#releaseassetlinkinput) | List of asset links to associate to the release. | ### `SastCiConfigurationAnalyzersEntityInput` @@ -17315,8 +18033,8 @@ A time-frame defined as a closed inclusive range of two dates. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="timeframeend"></a>`end` | [`Date!`](#date) | The end of the range. | -| <a id="timeframestart"></a>`start` | [`Date!`](#date) | The start of the range. | +| <a id="timeframeend"></a>`end` | [`Date!`](#date) | End of the range. | +| <a id="timeframestart"></a>`start` | [`Date!`](#date) | Start of the range. | ### `UpdateDiffImagePositionInput` @@ -17328,3 +18046,14 @@ A time-frame defined as a closed inclusive range of two dates. | <a id="updatediffimagepositioninputwidth"></a>`width` | [`Int`](#int) | Total width of the image. | | <a id="updatediffimagepositioninputx"></a>`x` | [`Int`](#int) | X position of the note. | | <a id="updatediffimagepositioninputy"></a>`y` | [`Int`](#int) | Y position of the note. | + +### `VulnerabilityIdentifierInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="vulnerabilityidentifierinputexternalid"></a>`externalId` | [`String`](#string) | External ID of the vulnerability identifier. | +| <a id="vulnerabilityidentifierinputexternaltype"></a>`externalType` | [`String`](#string) | External type of the vulnerability identifier. | +| <a id="vulnerabilityidentifierinputname"></a>`name` | [`String!`](#string) | Name of the vulnerability identifier. | +| <a id="vulnerabilityidentifierinputurl"></a>`url` | [`String!`](#string) | URL of the vulnerability identifier. | diff --git a/doc/api/graphql/removed_items.md b/doc/api/graphql/removed_items.md index 1c425d5f1d5..0048148ab11 100644 --- a/doc/api/graphql/removed_items.md +++ b/doc/api/graphql/removed_items.md @@ -12,7 +12,7 @@ According to our [process for removing items](index.md#deprecation-and-removal-p ## GitLab 14.0 -Fields removed in [GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63293): +Fields [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63293) in GitLab 14.0: ### GraphQL Mutations @@ -38,7 +38,7 @@ Fields removed in [GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/merge_req ## GitLab 13.6 -Fields removed in [GitLab 13.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44866): +Fields [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44866) in GitLab 13.6: | Field name | GraphQL type | Deprecated in | Use instead | |----------------------|--------------------------|---------------|----------------------------| diff --git a/doc/api/graphql/users_example.md b/doc/api/graphql/users_example.md index 8fbfb67d166..0658a9402e7 100644 --- a/doc/api/graphql/users_example.md +++ b/doc/api/graphql/users_example.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/engineering/ux/technical-writing/#assignments --- -# Query users with GraphQL +# Query users with GraphQL **(FREE)** This page describes how you can use the GraphiQL explorer to query users. diff --git a/doc/api/group_activity_analytics.md b/doc/api/group_activity_analytics.md index 003c96b65fa..9206b0a1bd6 100644 --- a/doc/api/group_activity_analytics.md +++ b/doc/api/group_activity_analytics.md @@ -4,7 +4,7 @@ group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Group Activity Analytics API +# Group Activity Analytics API **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/26460) in GitLab 12.9. diff --git a/doc/api/group_badges.md b/doc/api/group_badges.md index 463507bf583..1e830237b50 100644 --- a/doc/api/group_badges.md +++ b/doc/api/group_badges.md @@ -4,7 +4,7 @@ group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Group badges API +# Group badges API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17082) in GitLab 10.6. diff --git a/doc/api/group_boards.md b/doc/api/group_boards.md index eaa7b57e520..6178a3fdc04 100644 --- a/doc/api/group_boards.md +++ b/doc/api/group_boards.md @@ -76,7 +76,7 @@ Example response: ] ``` -Users on GitLab [Premium or higher](https://about.gitlab.com/pricing/) see +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) see different parameters, due to the ability to have multiple group boards. Example response: @@ -192,7 +192,7 @@ Example response: } ``` -Users on GitLab [Premium or higher](https://about.gitlab.com/pricing/) see +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) see different parameters, due to the ability to have multiple group issue boards. Example response: @@ -244,7 +244,7 @@ Example response: ## Create a group issue board **(PREMIUM)** -Creates a Group Issue Board. +Creates a group issue board. ```plaintext POST /groups/:id/boards @@ -283,7 +283,7 @@ Example response: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5954) in GitLab 11.1. -Updates a Group Issue Board. +Updates a group issue board. ```plaintext PUT /groups/:id/boards/:board_id @@ -351,7 +351,7 @@ Example response: ## Delete a group issue board **(PREMIUM)** -Deletes a Group Issue Board. +Deletes a group issue board. ```plaintext DELETE /groups/:id/boards/:board_id @@ -452,7 +452,7 @@ Example response: ## New group issue board list -Creates a new Issue Board list. +Creates an issue board list. ```plaintext POST /groups/:id/boards/:board_id/lists @@ -493,7 +493,7 @@ Example response: ## Edit group issue board list -Updates an existing Issue Board list. This call is used to change list position. +Updates an existing issue board list. This call is used to change list position. ```plaintext PUT /groups/:id/boards/:board_id/lists/:list_id diff --git a/doc/api/group_import_export.md b/doc/api/group_import_export.md index d2bcac6332a..0a431cfdfbf 100644 --- a/doc/api/group_import_export.md +++ b/doc/api/group_import_export.md @@ -4,7 +4,7 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Group Import/Export API +# Group Import/Export API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20353) in GitLab 12.8. diff --git a/doc/api/group_labels.md b/doc/api/group_labels.md index 25102e32360..04a619c8fa9 100644 --- a/doc/api/group_labels.md +++ b/doc/api/group_labels.md @@ -13,7 +13,7 @@ It allows users to list, create, update, and delete group labels. Furthermore, u unsubscribe from group labels. NOTE: -The `description_html` - was added to response JSON in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413). +The `description_html` - was [added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) to response JSON in GitLab 12.7. ## List group labels @@ -26,7 +26,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. | -| `with_counts` | boolean | no | Whether or not to include issue and merge request counts. Defaults to `false`. _([Introduced in GitLab 12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31543))_ | +| `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 | | `only_group_labels` | boolean | no | Toggle to include only group labels or also project labels. Defaults to `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259024) in GitLab 13.6 | diff --git a/doc/api/group_level_variables.md b/doc/api/group_level_variables.md index f816f2dc173..7c51de47bc7 100644 --- a/doc/api/group_level_variables.md +++ b/doc/api/group_level_variables.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/engineering/ux/technical-writing/#assignments --- -# Group-level Variables API +# Group-level Variables API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/34519) in GitLab 9.5 diff --git a/doc/api/group_milestones.md b/doc/api/group_milestones.md index d7de3272005..8b9c09ef1a0 100644 --- a/doc/api/group_milestones.md +++ b/doc/api/group_milestones.md @@ -32,7 +32,7 @@ Parameters: | `state` | string | no | Return only `active` or `closed` milestones | | `title` | string | no | Return only the milestones having the given `title` | | `search` | string | no | Return only milestones with a title or description matching the provided string | -| `include_parent_milestones` | boolean | optional | Include milestones from parent group and its ancestors. Introduced in [GitLab 13.4](https://gitlab.com/gitlab-org/gitlab/-/issues/196066) | +| `include_parent_milestones` | boolean | optional | Include milestones from parent group and its ancestors. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196066) in GitLab 13.4 | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/milestones" diff --git a/doc/api/group_protected_environments.md b/doc/api/group_protected_environments.md index ddd9ca891d8..0e1cd149c51 100644 --- a/doc/api/group_protected_environments.md +++ b/doc/api/group_protected_environments.md @@ -7,17 +7,11 @@ type: concepts, howto # Group-level protected environments API **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215888) in [GitLab Premium](https://about.gitlab.com/pricing/) 14.0. -> - [Deployed behind a feature flag](../user/feature_flags.md), disabled by default. -> - Disabled on GitLab.com. -> - Not recommended for production use. -> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](../ci/environments/protected_environments.md#enable-or-disable-group-level-protected-environments). **(FREE SELF)** +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215888) in GitLab 14.0. [Deployed behind the `group_level_protected_environments` flag](../administration/feature_flags.md), disabled by default. +> - [Feature flag `group_level_protected_environments`](https://gitlab.com/gitlab-org/gitlab/-/issues/331085) removed in GitLab 14.3. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/331085) in GitLab 14.3. -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. - -Read more about [group-level protected environments](../ci/environments/protected_environments.md#group-level-protected-environments), +Read more about [group-level protected environments](../ci/environments/protected_environments.md#group-level-protected-environments). ## Valid access levels diff --git a/doc/api/group_relations_export.md b/doc/api/group_relations_export.md index 2f9c1e381df..4dbf0f6d54c 100644 --- a/doc/api/group_relations_export.md +++ b/doc/api/group_relations_export.md @@ -4,7 +4,7 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Group Relations Export API +# Group Relations Export API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/59978) in GitLab 13.12. diff --git a/doc/api/group_wikis.md b/doc/api/group_wikis.md index e1470a2cdd7..17337934a92 100644 --- a/doc/api/group_wikis.md +++ b/doc/api/group_wikis.md @@ -7,7 +7,7 @@ type: reference, api # Group wikis API **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212199) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212199) in GitLab 13.5. The [group wikis](../user/project/wiki/index.md#group-wikis) API is available only in APIv4. An API for [project wikis](wikis.md) is also available. diff --git a/doc/api/groups.md b/doc/api/groups.md index 3831aef10c9..bd4c7de567c 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -4,7 +4,7 @@ group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Groups API +# Groups API **(FREE)** ## List groups @@ -13,6 +13,11 @@ 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). +When accessed without authentication, this endpoint also supports [keyset pagination](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. + Parameters: | Attribute | Type | Required | Description | @@ -764,6 +769,10 @@ For GitLab 14.0 and later, the [limit cannot be disabled](https://gitlab.com/git ## New group +NOTE: +On GitLab SaaS, you must use the GitLab UI to create groups without a parent group. You cannot +use the API to do this. + Creates a new project group. Available only for users who can create groups. ```plaintext @@ -795,10 +804,6 @@ Parameters: | `shared_runners_minutes_limit` | integer | no | **(PREMIUM SELF)** Pipeline minutes quota for this group (included in plan). Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0` | | `extra_shared_runners_minutes_limit` | integer | no | **(PREMIUM SELF)** Extra pipeline minutes quota for this group (purchased in addition to the minutes included in the plan). | -NOTE: -On GitLab SaaS, you must use the GitLab UI to create groups without a parent group. You cannot -use the API to do this. - ### Options for `default_branch_protection` The `default_branch_protection` attribute determines whether developers and maintainers can push to the applicable [default branch](../user/project/repository/branches/default.md), as described in the following table: @@ -1338,7 +1343,7 @@ DELETE /groups/:id/share/:group_id ## Push Rules **(PREMIUM)** -> Introduced in [GitLab](https://about.gitlab.com/pricing/) 13.4. +> Introduced in GitLab 13.4. ### Get group push rules **(PREMIUM)** @@ -1370,7 +1375,7 @@ GET /groups/:id/push_rule } ``` -Users on GitLab [Premium or higher](https://about.gitlab.com/pricing/) also see +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `commit_committer_check` and `reject_unsigned_commits` parameters: ```json diff --git a/doc/api/index.md b/doc/api/index.md index 12d01828803..7b599b6ae0a 100644 --- a/doc/api/index.md +++ b/doc/api/index.md @@ -125,7 +125,7 @@ There are several ways you can authenticate with the GitLab API: - [Personal access tokens](../user/profile/personal_access_tokens.md) - [Project access tokens](../user/project/settings/project_access_tokens.md) - [Session cookie](#session-cookie) -- [GitLab CI/CD job token](#gitlab-cicd-job-token) **(Specific endpoints only)** +- [GitLab CI/CD job token](../ci/jobs/ci_job_token.md) **(Specific endpoints only)** Project access tokens are supported by: @@ -208,118 +208,6 @@ 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. -### GitLab CI/CD job token - -When a pipeline job is about to run, GitLab generates a unique token and injects it as the -[`CI_JOB_TOKEN` predefined variable](../ci/variables/predefined_variables.md). - -You can use a GitLab CI/CD job token to authenticate with specific API endpoints: - -- Packages: - - [Package Registry](../user/packages/package_registry/index.md). To push to the - Package Registry, you can use [deploy tokens](../user/project/deploy_tokens/index.md). - - [Container Registry](../user/packages/container_registry/index.md) - (the `$CI_REGISTRY_PASSWORD` is `$CI_JOB_TOKEN`). - - [Container Registry API](container_registry.md) (scoped to the job's project, when the `ci_job_token_scope` feature flag is enabled) -- [Get job artifacts](job_artifacts.md#get-job-artifacts). -- [Get job token's job](jobs.md#get-job-tokens-job). -- [Pipeline triggers](pipeline_triggers.md), using the `token=` parameter. -- [Release creation](releases/index.md#create-a-release). -- [Terraform plan](../user/infrastructure/index.md). - -The token has the same permissions to access the API as the user that triggers the -pipeline. Therefore, this user must be assigned to [a role that has the required privileges](../user/permissions.md). - -The token is valid only while the pipeline job runs. After the job finishes, you can't -use the token anymore. - -A job token can access a project's resources without any configuration, but it might -give extra permissions that aren't necessary. There is [a proposal](https://gitlab.com/groups/gitlab-org/-/epics/3559) -to redesign the feature for more strategic control of the access permissions. - -#### GitLab CI/CD job token security - -To make sure that this token doesn't leak, GitLab: - -- Masks the job token in job logs. -- Grants permissions to the job token only when the job is running. - -To make sure that this token doesn't leak, you should also configure -your [runners](../ci/runners/README.md) to be secure. Avoid: - -- Using Docker's `privileged` mode if the machines are re-used. -- Using the [`shell` executor](https://docs.gitlab.com/runner/executors/shell.html) when jobs - run on the same machine. - -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 - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328553) in GitLab 14.1. -> - [Deployed behind a feature flag](../user/feature_flags.md), disabled by default. -> - Disabled on GitLab.com. -> - Not recommended for production use. -> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-ci-job-token-scope-limit). **(FREE SELF)** - -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. - -You can limit the access scope of a project's CI/CD job token to increase the -job token's security. A job token might give extra permissions that aren't necessary -to access specific private resources. Limiting the job token access scope reduces the risk of a leaked -token being used to access private data that the user associated to the job can access. - -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. -Other projects can be added and removed by maintainers with access to both projects. - -This setting is enabled by default for all new projects, and disabled by default in projects -created before GitLab 14.1. It is strongly recommended that project maintainers enable this -setting at all times, and configure the allowlist for cross-project access if needed. - -For example, when the setting is enabled, jobs in a pipeline in project `A` have -a `CI_JOB_TOKEN` scope limited to project `A`. If the job needs to use the token -to make an API request to a private project `B`, then `B` must be added to the allowlist for `A`. -If project `B` is public or internal, it doesn't need to be added to the allowlist. -The job token scope is only for controlling access to private projects. - -To enable and configure the job token scope limit: - -1. On the top bar, select **Menu > Projects** and find your project. -1. On the left sidebar, select **Settings > CI/CD**. -1. Expand **Token Access**. -1. Toggle **Limit CI_JOB_TOKEN access** to enabled. -1. (Optional) Add existing projects to the token's access scope. The user adding a - project must have the [maintainer role](../user/permissions.md) in both projects. - -If the job token scope limit is disabled, the token can potentially be used to authenticate -API requests to all projects accessible to the user that triggered the job. - -There is [a proposal](https://gitlab.com/groups/gitlab-org/-/epics/3559) to improve -the feature with more strategic control of the access permissions. - -##### Enable or disable CI job token scope limit **(FREE SELF)** - -The GitLab CI/CD job token access scope limit is under development and not ready for production -use. It is deployed behind a feature flag that is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../administration/feature_flags.md) -can enable it. - -To enable it: - -```ruby -Feature.enable(:ci_scoped_job_token) -``` - -To disable it: - -```ruby -Feature.disable(:ci_scoped_job_token) -``` - ### Impersonation tokens Impersonation tokens are a type of [personal access token](../user/profile/personal_access_tokens.md). @@ -574,22 +462,43 @@ The response header includes a link to the next page. For example: ```http HTTP/1.1 200 OK ... -Links: <https://gitlab.example.com/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc&id_after=42>; rel="next" 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 is scheduled to be removed in GitLab 14.0 to be aligned with the +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. -The link to the next page contains an additional filter `id_after=42` that -excludes already-retrieved records. The type of filter depends on the -`order_by` option used, and we may have more than one additional filter. - 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. @@ -601,9 +510,10 @@ pagination headers. Keyset-based pagination is supported only for selected resources and ordering options: -| Resource | Order | -|-------------------------|-------| -| [Projects](projects.md) | `order_by=id` only. | +| 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 | ## Path parameters @@ -675,7 +585,7 @@ send the payload body: ```shell curl --request POST --header "Content-Type: application/json" \ - --data '{"name":"<example-name>", "description":"<example-description"}' "https://gitlab/api/v4/projects" + --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 @@ -705,7 +615,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ --form "namespace=email" \ --form "path=impapi" \ ---form "file=@/path/to/somefile.txt" +--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" @@ -718,7 +628,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ ```shell curl --globoff --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ -"https://gitlab.example.com/api/v4/projects/169/pipeline?ref=master&variables[][key]=VAR1&variables[][value]=hello&variables[][key]=VAR2&variables[][value]=world" +"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" \ diff --git a/doc/api/instance_clusters.md b/doc/api/instance_clusters.md index ae94fdb137c..4e0ec3bd433 100644 --- a/doc/api/instance_clusters.md +++ b/doc/api/instance_clusters.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Instance clusters API **(FREE)** +# Instance clusters API **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36001) in GitLab 13.2. diff --git a/doc/api/instance_level_ci_variables.md b/doc/api/instance_level_ci_variables.md index de6fd958aa6..2b2579425b5 100644 --- a/doc/api/instance_level_ci_variables.md +++ b/doc/api/instance_level_ci_variables.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/engineering/ux/technical-writing/#assignments --- -# Instance-level CI/CD variables API +# Instance-level CI/CD variables API **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14108) in GitLab 13.0 > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/218249) in GitLab 13.2. diff --git a/doc/api/issue_links.md b/doc/api/issue_links.md index d4f59d10316..ac26d2a3d17 100644 --- a/doc/api/issue_links.md +++ b/doc/api/issue_links.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Issue links API **(FREE)** -> The simple "relates to" relationship [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212329) to [GitLab Free](https://about.gitlab.com/pricing/) in 13.4. +> The simple "relates to" relationship [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212329) to GitLab Free in 13.4. ## List issue relations diff --git a/doc/api/issues.md b/doc/api/issues.md index feec9b31747..97d0fd3ce8f 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -20,7 +20,7 @@ Read more on [pagination](index.md#pagination). WARNING: The `reference` attribute in responses is deprecated in favor of `references`. -Introduced in [GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20354). +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20354) in GitLab 12.6. NOTE: The `references.relative` attribute is relative to the group or project of the issue being requested. @@ -61,18 +61,19 @@ GET /issues?state=opened | `confidential` | boolean | no | Filter confidential or public issues. | | `created_after` | datetime | no | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _(Introduced in [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/233420))_ | +| `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), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233420) in GitLab 13.3)_ | | `iids[]` | integer array | no | Return only the issues having the given `iid` | | `in` | string | no | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description` | -| `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _(Introduced in [GitLab 13.12](https://gitlab.com/gitlab-org/gitlab/-/issues/260375))_ | +| `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260375) in GitLab 13.12)_ | | `iteration_id` **(PREMIUM)** | integer | no | Return issues assigned to the given iteration ID. `None` returns issues that do not belong to an iteration. `Any` returns issues that belong to an iteration. Mutually exclusive with `iteration_title`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | | `iteration_title` **(PREMIUM)** | string | no | Return issues assigned to the iteration with the given title. Similar to `iteration_id` and mutually exclusive with `iteration_id`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | | `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | -| `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | +| `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. Using `None` or `Any` will be [deprecated in the future](https://gitlab.com/gitlab-org/gitlab/-/issues/336044). Please use `milestone_id` attribute instead. `milestone` and `milestone_id` are mutually exclusive. | +| `milestone_id` | string | no | Returns issues assigned to milestones with a given timebox value (`None`, `Any`, `Upcoming`, and `Started`). `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. `Upcoming` lists all issues assigned to milestones due in the future. `Started` lists all issues assigned to open, started milestones. `milestone` and `milestone_id` are mutually exclusive. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335939) in GitLab 14.3)_ | | `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14016) in GitLab 10.0)_ | -| `non_archived` | boolean | no | Return issues only from non-archived projects. If `false`, the response returns issues from both archived and non-archived projects. Default is `true`. _(Introduced in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/197170))_ | -| `not` | Hash | no | Return issues that do not match the parameters supplied. Accepts: `assignee_id`, `assignee_username`, `author_id`, `author_username`, `iids`, `iteration_id`, `iteration_title`, `labels`, `milestone`, and `weight`. | -| `order_by` | string | no | Return issues ordered by `created_at`, `updated_at`, `priority`, `due_date`, `relative_position`, `label_priority`, `milestone_due`, `popularity`, `weight` fields. Default is `created_at` | +| `non_archived` | boolean | no | Return issues only from non-archived projects. If `false`, the response returns issues from both archived and non-archived projects. Default is `true`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197170) in GitLab 13.0)_ | +| `not` | Hash | no | Return issues that do not match the parameters supplied. Accepts: `assignee_id`, `assignee_username`, `author_id`, `author_username`, `iids`, `iteration_id`, `iteration_title`, `labels`, `milestone`, `milestone_id` and `weight`. | +| `order_by` | string | no | Return issues ordered by `created_at`, `due_date`, `label_priority`, `milestone_due`, `popularity`, `priority`, `relative_position`, `title`, `updated_at`, or `weight` fields. Default is `created_at`. | | `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5. [Changed to snake_case](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18935) in GitLab 11.0)_ | | `search` | string | no | Search issues against their `title` and `description` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | @@ -80,7 +81,7 @@ GET /issues?state=opened | `updated_after` | datetime | no | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `updated_before` | datetime | no | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `weight` **(PREMIUM)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | -| `with_labels_details` | boolean | no | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. The `description_html` attribute was introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413)| +| `with_labels_details` | boolean | no | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. The `description_html` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) in GitLab 12.7| ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/issues" @@ -224,11 +225,11 @@ The `assignee` column is deprecated. We now show it as a single-sized array `ass to the GitLab EE API. WARNING: -The `epic_iid` attribute is deprecated and [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). +The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. Please use `iid` of the `epic` attribute instead. NOTE: -The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). +The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. @@ -267,16 +268,16 @@ GET /groups/:id/issues?state=opened | `confidential` | boolean | no | Filter confidential or public issues. | | `created_after` | datetime | no | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _(Introduced in [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/233420))_ | +| `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), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233420) in GitLab 13.3)_ | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](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 in [GitLab 13.12](https://gitlab.com/gitlab-org/gitlab/-/issues/260375))_ | +| `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260375) in GitLab 13.12)_ | | `iteration_id` **(PREMIUM)** | integer | no | Return issues assigned to the given iteration ID. `None` returns issues that do not belong to an iteration. `Any` returns issues that belong to an iteration. Mutually exclusive with `iteration_title`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | | `iteration_title` **(PREMIUM)** | string | no | Return issues assigned to the iteration with the given title. Similar to `iteration_id` and mutually exclusive with `iteration_id`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | | `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | | `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | | `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14016) in GitLab 10.0)_ | -| `non_archived` | boolean | no | Return issues from non archived projects. Default is true. _(Introduced in [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23785))_ | +| `non_archived` | boolean | no | Return issues from non archived projects. Default is true. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23785) in GitLab 12.8)_ | | `not` | Hash | no | Return issues that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `my_reaction_emoji`, `search`, `in` | | `order_by` | string | no | Return issues ordered by `created_at`, `updated_at`, `priority`, `due_date`, `relative_position`, `label_priority`, `milestone_due`, `popularity`, `weight` fields. Default is `created_at` | | `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5. [Changed to snake_case](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18935) in GitLab 11.0)_ | @@ -286,7 +287,7 @@ GET /groups/:id/issues?state=opened | `updated_after` | datetime | no | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `updated_before` | datetime | no | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `weight` **(PREMIUM)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | -| `with_labels_details` | boolean | no | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. The `description_html` attribute was introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) | +| `with_labels_details` | boolean | no | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. The `description_html` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) in GitLab 12.7 | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/4/issues" @@ -428,11 +429,11 @@ WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. WARNING: -The `epic_iid` attribute is deprecated and [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). +The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. Please use `iid` of the `epic` attribute instead. NOTE: -The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). +The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. @@ -471,10 +472,10 @@ GET /projects/:id/issues?state=opened | `confidential` | boolean | no | Filter confidential or public issues. | | `created_after` | datetime | no | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _(Introduced in [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/233420))_ | +| `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), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233420) in GitLab 13.3)_ | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](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 in [GitLab 13.12](https://gitlab.com/gitlab-org/gitlab/-/issues/260375))_ | +| `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260375) in GitLab 13.12)_ | | `iteration_id` **(PREMIUM)** | integer | no | Return issues assigned to the given iteration ID. `None` returns issues that do not belong to an iteration. `Any` returns issues that belong to an iteration. Mutually exclusive with `iteration_title`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | | `iteration_title` **(PREMIUM)** | string | no | Return issues assigned to the iteration with the given title. Similar to `iteration_id` and mutually exclusive with `iteration_id`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | | `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | @@ -489,7 +490,7 @@ GET /projects/:id/issues?state=opened | `updated_after` | datetime | no | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `updated_before` | datetime | no | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `weight` **(PREMIUM)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | -| `with_labels_details` | boolean | no | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. `description_html` was introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) | +| `with_labels_details` | boolean | no | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. `description_html` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) in GitLab 12.7 | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues" @@ -638,11 +639,11 @@ WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. WARNING: -The `epic_iid` attribute is deprecated and [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). +The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. Please use `iid` of the `epic` attribute instead. NOTE: -The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed +The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. ## Single issue @@ -803,11 +804,11 @@ The `assignee` column is deprecated. We now show it as a single-sized array `ass to the GitLab EE API. WARNING: -The `epic_iid` attribute is deprecated, and [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). +The `epic_iid` attribute is deprecated, and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. Please use `iid` of the `epic` attribute instead. NOTE: -The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). +The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. @@ -964,11 +965,11 @@ WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. WARNING: -The `epic_iid` attribute is deprecated and [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). +The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. Please use `iid` of the `epic` attribute instead. NOTE: -The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed +The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. ## New issue @@ -991,7 +992,7 @@ POST /projects/:id/issues | `discussion_to_resolve` | string | no | The ID of a discussion to resolve. This fills out the issue with a default description and mark the discussion as resolved. Use in combination with `merge_request_to_resolve_discussions_of`. | | `due_date` | string | no | The due date. Date time string in the format `YYYY-MM-DD`, for example `2016-03-11` | | `epic_id` **(PREMIUM)** | 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 in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157)) | +| `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 ID or [URL-encoded path of the project](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`. | @@ -1114,11 +1115,11 @@ WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. WARNING: -The `epic_iid` attribute is deprecated and [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). +The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. Please use `iid` of the `epic` attribute instead. NOTE: -The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed +The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. ## Rate limits @@ -1161,7 +1162,7 @@ PUT /projects/:id/issues/:issue_iid | `discussion_locked` | boolean | no | Flag indicating if the issue's discussion is locked. If the discussion is locked only project members can add or edit comments. | | `due_date` | string | no | The due date. Date time string in the format `YYYY-MM-DD`, for example `2016-03-11` | | `epic_id` **(PREMIUM)** | 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 in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157)) | +| `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 ID or [URL-encoded path of the project](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`. | @@ -1289,11 +1290,11 @@ Issues created by users on GitLab Ultimate include the `health_status` property: ``` NOTE: -The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed +The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. WARNING: -The `epic_iid` attribute is deprecated and [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). +The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. Please use `iid` of the `epic` attribute instead. WARNING: @@ -1479,11 +1480,11 @@ WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. WARNING: -The `epic_iid` attribute is deprecated and [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). +The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. Please use `iid` of the `epic` attribute instead. NOTE: -The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed +The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. ## Subscribe to an issue @@ -1624,11 +1625,11 @@ WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. WARNING: -The `epic_iid` attribute is deprecated and [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). +The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. Please use `iid` of the `epic` attribute instead. NOTE: -The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed +The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. ## Unsubscribe from an issue @@ -1822,7 +1823,7 @@ WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. NOTE: -The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed +The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. ## Promote an issue to an epic **(PREMIUM)** diff --git a/doc/api/job_artifacts.md b/doc/api/job_artifacts.md index 0a39400dfd4..6d8c256d5aa 100644 --- a/doc/api/job_artifacts.md +++ b/doc/api/job_artifacts.md @@ -4,7 +4,7 @@ group: Testing info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Job Artifacts API +# Job Artifacts API **(FREE)** ## Get job artifacts @@ -20,7 +20,7 @@ GET /projects/:id/jobs/:job_id/artifacts |-------------|----------------|----------|--------------------------------------------------------------------------------------------------------------| | `id` | integer/string | yes | ID or [URL-encoded path of the project](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/triggers/index.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | +| `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 inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | Example request using the `PRIVATE-TOKEN` header: @@ -85,7 +85,7 @@ Parameters | `id` | integer/string | yes | ID or [URL-encoded path of the project](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/triggers/index.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | +| `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 inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | Example request using the `PRIVATE-TOKEN` header: @@ -146,7 +146,7 @@ Parameters | `id` | integer/string | yes | ID or [URL-encoded path of the project](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/triggers/index.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | +| `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 inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | Example request: @@ -188,7 +188,7 @@ Parameters: | `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. | -| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/triggers/index.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | +| `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 inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | Example request: diff --git a/doc/api/jobs.md b/doc/api/jobs.md index 42774b80b27..ac8b756beac 100644 --- a/doc/api/jobs.md +++ b/doc/api/jobs.md @@ -466,7 +466,7 @@ Example of response ## Get Kubernetes Agents by `CI_JOB_TOKEN` **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/324269) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.11. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/324269) in GitLab 13.11. Retrieve the job that generated the `CI_JOB_TOKEN`, along with a list of allowed GitLab Kubernetes Agents. diff --git a/doc/api/labels.md b/doc/api/labels.md index 1606df03afb..a8cb56f1573 100644 --- a/doc/api/labels.md +++ b/doc/api/labels.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Interact with [labels](../user/project/labels.md) using the REST API. NOTE: -The `description_html` - was added to response JSON in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413). +The `description_html` - was [added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) to response JSON in GitLab 12.7. ## List labels @@ -24,7 +24,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 | -| `with_counts` | boolean | no | Whether or not to include issue and merge request counts. Defaults to `false`. _([Introduced in GitLab 12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31543))_ | +| `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 | diff --git a/doc/api/lint.md b/doc/api/lint.md index a47bb028248..9f95b9a94ae 100644 --- a/doc/api/lint.md +++ b/doc/api/lint.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Pipeline Execution +group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Validate the CI YAML configuration Checks if CI/CD YAML configuration is valid. This endpoint validates basic CI/CD -configuration syntax. It doesn't have any namespace specific context. +configuration syntax. It doesn't have any namespace-specific context. Access to this endpoint does not require authentication when the instance [allows new sign ups](../user/admin_area/settings/sign_up_restrictions.md#disable-new-sign-ups) diff --git a/doc/api/members.md b/doc/api/members.md index 4b383efd792..0b8cf686b8c 100644 --- a/doc/api/members.md +++ b/doc/api/members.md @@ -4,7 +4,7 @@ group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Group and project members API +# Group and project members API **(FREE)** ## Valid access levels @@ -92,7 +92,7 @@ Gets a list of group or project members viewable by the authenticated user, incl If a user is a member of this group or project and also of one or more ancestor groups, only its membership with the highest `access_level` is returned. -([Improved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56677)] in GitLab 13.11.) +([Improved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56677) in GitLab 13.11.) This represents the effective permission of the user. This function takes pagination parameters `page` and `per_page` to restrict the list of users. @@ -552,7 +552,7 @@ Example response: "state": "active", "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", "web_url": "http://192.168.1.8:3000/root", - "expires_at": "2012-10-22T14:13:35Z", + "expires_at": "2012-10-22", "access_level": 40, "email": "john@example.com", "override": false diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md index ef8af608466..b4403e1d9b9 100644 --- a/doc/api/merge_request_approvals.md +++ b/doc/api/merge_request_approvals.md @@ -81,7 +81,7 @@ POST /projects/:id/approvals > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11877) in GitLab 12.3. > - Moved to GitLab Premium in 13.9. -> - `protected_branches` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7. +> - `protected_branches` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460) in GitLab 12.7. You can request information about a project's approval rules using the following endpoint: @@ -954,7 +954,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/approve | `id` | integer or string | yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of the merge request | | `sha` | string | no | The `HEAD` of the merge request | -| `approval_password` **(PREMIUM)** | string | 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. | +| `approval_password` | string | 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. | The `sha` parameter works in the same way as when [accepting a merge request](merge_requests.md#accept-mr): if it is passed, then it must diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index b90f0e70a02..98af228a064 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -222,7 +222,7 @@ Parameters: ] ``` -Users on GitLab Premium or higher also see +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `approvals_before_merge` parameter: ```json @@ -418,7 +418,7 @@ The `merge_status` field may hold one of the following values: | `cannot_be_merged` | There are merge conflicts between the source and target branches | | `cannot_be_merged_recheck` | Currently unchecked. Before the current changes, there were conflicts | -Users on GitLab Premium or higher also see +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `approvals_before_merge` parameter: ```json @@ -460,8 +460,8 @@ Parameters: | `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | | `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request. | | `labels` | string | no | Return merge requests matching a comma separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. | -| `with_labels_details` | boolean | no | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. Introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413).| -| `with_merge_status_recheck` | boolean | no | If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Default is `false`. Introduced in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890). | +| `with_labels_details` | boolean | no | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) in GitLab 12.7.| +| `with_merge_status_recheck` | boolean | no | If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890) in GitLab 13.0. | | `created_after` | datetime | no | Return merge requests created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | | `created_before` | datetime | no | Return merge requests created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | | `updated_after` | datetime | no | Return merge requests updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | @@ -478,7 +478,7 @@ Parameters: | `source_branch` | string | no | Return merge requests with the given source branch. | | `target_branch` | string | no | Return merge requests with the given target branch. | | `search` | string | no | Search merge requests against their `title` and `description`. | -| `non_archived` | boolean | no | Return merge requests from non archived projects only. Default is true. _(Introduced in [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23809))_. | +| `non_archived` | boolean | no | Return merge requests from non archived projects only. Default is true. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23809) in GitLab 12.8)_. | | `not` | Hash | no | Return 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`. | ```json @@ -592,7 +592,7 @@ Parameters: ] ``` -Users on GitLab Premium or higher also see +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `approvals_before_merge` parameter: ```json @@ -625,7 +625,7 @@ Parameters: |----------------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------| | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. | -| `render_html` | integer | no | If `true` response includes rendered HTML for title and description. | +| `render_html` | boolean | no | If `true` response includes rendered HTML for title and description. | | `include_diverged_commits_count` | boolean | no | If `true` response includes the commits behind the target branch. | | `include_rebase_in_progress` | boolean | no | If `true` response includes whether a rebase operation is in progress. | @@ -764,7 +764,7 @@ Parameters: } ``` -Users on GitLab Premium also see +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `approvals_before_merge` parameter: ```json @@ -1014,7 +1014,7 @@ The new pipeline can be: - A detached merge request pipeline. - A [pipeline for merged results](../ci/pipelines/pipelines_for_merged_results.md) - if the [project setting is enabled](../ci/pipelines/pipelines_for_merged_results.md#enable-pipelines-for-merged-results). + if the [project setting is enabled](../ci/pipelines/pipelines_for_merged_results.md#enable-pipelines-for-merged-results). **(PREMIUM)** ```plaintext POST /projects/:id/merge_requests/:merge_request_iid/pipelines @@ -1375,7 +1375,7 @@ Must include at least one non-required attribute from above. } ``` -Users on GitLab Premium or higher also see +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `approvals_before_merge` parameter: ```json @@ -1561,7 +1561,7 @@ Parameters: } ``` -Users on GitLab Premium also see +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `approvals_before_merge` parameter: ```json @@ -1750,7 +1750,7 @@ Parameters: } ``` -Users on GitLab Premium or higher also see +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `approvals_before_merge` parameter: ```json @@ -2051,7 +2051,7 @@ Example response: } ``` -Users on GitLab Premium also see +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `approvals_before_merge` parameter: ```json @@ -2211,7 +2211,7 @@ Example response: } ``` -Users on GitLab Premium or higher also see +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `approvals_before_merge` parameter: ```json diff --git a/doc/api/metrics_dashboard_annotations.md b/doc/api/metrics_dashboard_annotations.md index b2f1e52f194..feba57a7ced 100644 --- a/doc/api/metrics_dashboard_annotations.md +++ b/doc/api/metrics_dashboard_annotations.md @@ -7,7 +7,7 @@ type: concepts, howto # Dashboard annotations API **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29089) in GitLab 12.10 behind a disabled feature flag. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29089) in GitLab 12.10 behind a disabled feature flag. Metrics dashboard annotations allow you to indicate events on your graphs at a single point in time or over a time span. diff --git a/doc/api/metrics_user_starred_dashboards.md b/doc/api/metrics_user_starred_dashboards.md index 603d307f4b7..f615ddaaa71 100644 --- a/doc/api/metrics_user_starred_dashboards.md +++ b/doc/api/metrics_user_starred_dashboards.md @@ -43,7 +43,7 @@ Example Response: ## Remove a star from a dashboard -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31892) in GitLab 13.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31892) in GitLab 13.0. ```plaintext DELETE /projects/:id/metrics/user_starred_dashboards diff --git a/doc/api/milestones.md b/doc/api/milestones.md index 183d8b4799b..84b4e2fe39d 100644 --- a/doc/api/milestones.md +++ b/doc/api/milestones.md @@ -32,7 +32,7 @@ Parameters: | `state` | string | optional | Return only `active` or `closed` milestones | | `title` | string | optional | Return only the milestones having the given `title` | | `search` | string | optional | Return only milestones with a title or description matching the provided string | -| `include_parent_milestones` | boolean | optional | Include group milestones from parent group and its ancestors. Introduced in [GitLab 13.4](https://gitlab.com/gitlab-org/gitlab/-/issues/196066) | +| `include_parent_milestones` | boolean | optional | Include group milestones from parent group and its ancestors. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196066) in GitLab 13.4 | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/milestones" diff --git a/doc/api/notification_settings.md b/doc/api/notification_settings.md index 390ba7dbd79..4b70a643263 100644 --- a/doc/api/notification_settings.md +++ b/doc/api/notification_settings.md @@ -199,7 +199,7 @@ Example responses: } ``` -Users on GitLab [Ultimate](https://about.gitlab.com/pricing/) also see the `new_epic` +Users on [GitLab Ultimate](https://about.gitlab.com/pricing/) also see the `new_epic` parameter: ```json diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md index ce455c89d1a..abf9d7af229 100644 --- a/doc/api/oauth2.md +++ b/doc/api/oauth2.md @@ -5,7 +5,7 @@ group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# GitLab as an OAuth2 provider +# GitLab as an OAuth 2.0 provider **(FREE)** This document covers using the [OAuth2](https://oauth.net/2/) protocol to allow other services to access GitLab resources on user's behalf. @@ -15,9 +15,9 @@ other services, see the [OAuth2 authentication service provider](../integration/ documentation. This functionality is based on the [doorkeeper Ruby gem](https://github.com/doorkeeper-gem/doorkeeper). -## Supported OAuth2 flows +## Supported OAuth 2.0 flows -GitLab currently supports the following authorization flows: +GitLab supports the following authorization flows: - **Authorization code with [Proof Key for Code Exchange (PKCE)](https://tools.ietf.org/html/rfc7636):** Most secure. Without PKCE, you'd have to include client secrets on mobile clients, @@ -26,14 +26,13 @@ GitLab currently supports the following authorization flows: server-side apps. - **Implicit grant:** Originally designed for user-agent only apps, such as single page web apps running on GitLab Pages). - The [IETF](https://tools.ietf.org/html/draft-ietf-oauth-security-topics-09#section-2.1.2) + The [Internet Engineering Task Force (IETF)](https://tools.ietf.org/html/draft-ietf-oauth-security-topics-09#section-2.1.2) recommends against Implicit grant flow. - **Resource owner password credentials:** To be used **only** for securely hosted, first-party services. GitLab recommends against use of this flow. The draft specification for [OAuth 2.1](https://oauth.net/2.1/) specifically omits both the -Implicit grant and Resource Owner Password Credentials flows. - it will be deprecated in the next OAuth specification version. +Implicit grant and Resource Owner Password Credentials flows. It will be deprecated in the next OAuth specification version. Refer to the [OAuth RFC](https://tools.ietf.org/html/rfc6749) to find out how all those flows work and pick the right one for your use case. @@ -57,7 +56,7 @@ parameter, which are securely bound to the user agent", with each request to the For production, please use HTTPS for your `redirect_uri`. For development, GitLab allows insecure HTTP redirect URIs. -As OAuth2 bases its security entirely on the transport layer, you should not use unprotected +As OAuth 2.0 bases its security entirely on the transport layer, you should not use unprotected URIs. For more information, see the [OAuth 2.0 RFC](https://tools.ietf.org/html/rfc6749#section-3.1.2.1) and the [OAuth 2.0 Threat Model RFC](https://tools.ietf.org/html/rfc6819#section-4.4.2.1). These factors are particularly important when using the @@ -83,7 +82,11 @@ Before starting the flow, generate the `STATE`, the `CODE_VERIFIER` and the `COD which use the characters `A-Z`, `a-z`, `0-9`, `-`, `.`, `_`, and `~`. - The `CODE_CHALLENGE` is an URL-safe base64-encoded string of the SHA256 hash of the `CODE_VERIFIER` + - The SHA256 hash must be in binary format before encoding. - In Ruby, you can set that up with `Base64.urlsafe_encode64(Digest::SHA256.digest(CODE_VERIFIER), padding: false)`. + - For reference, a `CODE_VERIFIER` string of `ks02i3jdikdo2k0dkfodf3m39rjfjsdk0wk349rj3jrhf` when hashed + and encoded using the Ruby snippet above produces a `CODE_CHALLENGE` string + of `2i0WFA-0AerkjQm4X4oDEhqA17QIAKNjXpagHBXmO_U`. 1. Request authorization code. To do that, you should redirect the user to the `/oauth/authorize` page with the following query parameters: @@ -123,7 +126,7 @@ Before starting the flow, generate the `STATE`, the `CODE_VERIFIER` and the `COD "created_at": 1607635748 } ``` - + 1. To retrieve a new `access_token`, use the `refresh_token` parameter. Refresh tokens may be used even after the `access_token` itself expires. This request: - Invalidates the existing `access_token` and `refresh_token`. @@ -135,7 +138,7 @@ Before starting the flow, generate the `STATE`, the `CODE_VERIFIER` and the `COD ``` Example response: - + ```json { "access_token": "c97d1fe52119f38c7f67f0a14db68d60caa35ddc86fd12401718b649dcfa9c68", @@ -203,7 +206,7 @@ be used as a CSRF token. "created_at": 1607635748 } ``` - + 1. To retrieve a new `access_token`, use the `refresh_token` parameter. Refresh tokens may be used even after the `access_token` itself expires. This request: - Invalidates the existing `access_token` and `refresh_token`. @@ -245,12 +248,13 @@ scheduled to be removed for existing applications. We recommend that you use [Authorization code with PKCE](#authorization-code-with-proof-key-for-code-exchange-pkce) instead. If you choose to use Implicit flow, be sure to verify the `application id` (or `client_id`) associated with the access token before granting -access to the data, as described in [Retrieving the token information](#retrieving-the-token-information)). +access to the data. To learn more, read +[Retrieving the token information](#retrieve-the-token-information)). Unlike the authorization code flow, the client receives an `access token` -immediately as a result of the authorization request. The flow does not use -the client secret or the authorization code because all of the application code -and storage is easily accessible on client browsers and mobile devices. +immediately as a result of the authorization request. The flow does not use the +client secret or the authorization code, as the application +code and storage is accessible on client browsers and mobile devices. To request the access token, you should redirect the user to the `/oauth/authorize` endpoint using `token` response type: @@ -367,10 +371,11 @@ or you can put the token to the Authorization header: curl --header "Authorization: Bearer OAUTH-TOKEN" "https://gitlab.example.com/api/v4/user" ``` -## Retrieving the token information +## Retrieve the token information -To verify the details of a token, use the `token/info` endpoint provided by the Doorkeeper gem. -For more information, see [`/oauth/token/info`](https://github.com/doorkeeper-gem/doorkeeper/wiki/API-endpoint-descriptions-and-examples#get----oauthtokeninfo). +To verify the details of a token, use the `token/info` endpoint provided by the +Doorkeeper gem. For more information, see +[`/oauth/token/info`](https://github.com/doorkeeper-gem/doorkeeper/wiki/API-endpoint-descriptions-and-examples#get----oauthtokeninfo). You must supply the access token, either: @@ -407,9 +412,10 @@ prevent breaking changes introduced in [doorkeeper 5.0.2](https://github.com/doo Don't rely on these fields as they are slated for removal in a later release. -## OAuth2 tokens and GitLab registries +## OAuth 2.0 tokens and GitLab registries -Standard OAuth2 tokens support different degrees of access to GitLab registries, as they: +Standard OAuth 2.0 tokens support different degrees of access to GitLab +registries, as they: - Do not allow users to authenticate to: - The GitLab [Container registry](../user/packages/container_registry/index.md#authenticate-with-the-container-registry). diff --git a/doc/api/packages.md b/doc/api/packages.md index 73092e68c82..a75b2e376fa 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -4,7 +4,7 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Packages API +# Packages API **(FREE)** This is the API documentation of [GitLab Packages](../administration/packages/index.md). diff --git a/doc/api/packages/composer.md b/doc/api/packages/composer.md index 4f8e0a23c9c..b3a27519729 100644 --- a/doc/api/packages/composer.md +++ b/doc/api/packages/composer.md @@ -4,7 +4,7 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Composer API +# Composer API **(FREE)** This is the API documentation for [Composer Packages](../../user/packages/composer_repository/index.md). @@ -108,13 +108,14 @@ V1. GET group/:id/-/packages/composer/:package_name$:sha ``` -Note the `$` symbol in the URL. When making requests, you may need to use the URL-encoded version of -the symbol `%24` (see example below). +Note the `$` symbol in the URL. When making requests, you may need the +URL-encoded version of the symbol `%24`. Refer to the example after +the table: -| Attribute | Type | Required | Description | -| -------------- | ------ | -------- | ----------- | -| `id` | string | yes | The ID or full path of the group. | -| `package_name` | string | yes | The name of the package. | +| Attribute | Type | Required | Description | +|----------------|--------|----------|---------------------------------------------------------------------------------------| +| `id` | string | yes | The ID or full path of the group. | +| `package_name` | string | yes | The name of the package. | | `sha` | string | yes | The SHA digest of the package, provided by the [V1 packages list](#v1-packages-list). | ```shell diff --git a/doc/api/packages/conan.md b/doc/api/packages/conan.md index 88ed2524173..f5d08ed7ef8 100644 --- a/doc/api/packages/conan.md +++ b/doc/api/packages/conan.md @@ -4,7 +4,7 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Conan API +# Conan API **(FREE)** This is the API documentation for [Conan Packages](../../user/packages/conan_repository/index.md). diff --git a/doc/api/packages/go_proxy.md b/doc/api/packages/go_proxy.md index 2f81435db42..ffafc387951 100644 --- a/doc/api/packages/go_proxy.md +++ b/doc/api/packages/go_proxy.md @@ -4,7 +4,7 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Go Proxy API +# Go Proxy API **(FREE SELF)** This is the API documentation for [Go Packages](../../user/packages/go_proxy/index.md). This API is behind a feature flag that is disabled by default. GitLab administrators with access to diff --git a/doc/api/packages/helm.md b/doc/api/packages/helm.md index f1d5f24cd99..8c3b9869368 100644 --- a/doc/api/packages/helm.md +++ b/doc/api/packages/helm.md @@ -4,7 +4,7 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Helm API +# Helm API **(FREE)** This is the API documentation for [Helm](../../user/packages/helm_repository/index.md). @@ -38,14 +38,14 @@ GET projects/:id/packages/helm/:channel/index.yaml ```shell curl --user <username>:<personal_access_token> \ - https://gitlab.example.com/api/v4/projects/1/packages/helm/stable/index.yaml + "https://gitlab.example.com/api/v4/projects/1/packages/helm/stable/index.yaml" ``` Write the output to a file: ```shell curl --user <username>:<personal_access_token> \ - https://gitlab.example.com/api/v4/projects/1/packages/helm/stable/index.yaml \ + "https://gitlab.example.com/api/v4/projects/1/packages/helm/stable/index.yaml" \ --remote-name ``` @@ -67,7 +67,7 @@ GET projects/:id/packages/helm/:channel/charts/:file_name.tgz ```shell curl --user <username>:<personal_access_token> \ - https://gitlab.example.com/api/v4/projects/1/packages/helm/stable/charts/mychart.tgz \ + "https://gitlab.example.com/api/v4/projects/1/packages/helm/stable/charts/mychart.tgz" \ --remote-name ``` @@ -91,5 +91,5 @@ POST projects/:id/packages/helm/api/:channel/charts curl --request POST \ --form 'chart=@mychart.tgz' \ --user <username>:<personal_access_token> \ - https://gitlab.example.com/api/v4/projects/1/packages/helm/api/stable/charts + "https://gitlab.example.com/api/v4/projects/1/packages/helm/api/stable/charts" ``` diff --git a/doc/api/packages/maven.md b/doc/api/packages/maven.md index d03c9be3060..b4b3d579ffb 100644 --- a/doc/api/packages/maven.md +++ b/doc/api/packages/maven.md @@ -4,7 +4,7 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Maven API +# Maven API **(FREE)** This is the API documentation for [Maven Packages](../../user/packages/maven_repository/index.md). diff --git a/doc/api/packages/npm.md b/doc/api/packages/npm.md index 3992a042915..24ac1a640c9 100644 --- a/doc/api/packages/npm.md +++ b/doc/api/packages/npm.md @@ -4,7 +4,7 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.example/handbook/engineering/ux/technical-writing/#assignments --- -# npm API +# npm API **(FREE)** This is the API documentation for [npm Packages](../../user/packages/npm_registry/index.md). @@ -58,11 +58,11 @@ Upload a package. PUT projects/:id/packages/npm/:package_name ``` -| Attribute | Type | Required | Description | -| ----------------- | ------ | -------- | ----------- | -| `id` | string | yes | The ID or full path of the project. | -| `package_name` | string | yes | The name of the package. | -| `versions` | string | yes | Package version info. | +| Attribute | Type | Required | Description | +|----------------|--------|----------|-------------------------------------| +| `id` | string | yes | The ID or full path of the project. | +| `package_name` | string | yes | The name of the package. | +| `versions` | string | yes | Package version information. | ```shell curl --request PUT diff --git a/doc/api/packages/nuget.md b/doc/api/packages/nuget.md index d19e2dfa65b..aee3a4fe542 100644 --- a/doc/api/packages/nuget.md +++ b/doc/api/packages/nuget.md @@ -4,7 +4,7 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about..example/handbook/engineering/ux/technical-writing/#assignments --- -# NuGet API +# NuGet API **(FREE)** This is the API documentation for [NuGet Packages](../../user/packages/nuget_repository/index.md). @@ -73,7 +73,7 @@ curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v Write the output to a file: ```shell -curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download/MyNuGetPkg/1.3.0.17/mynugetpkg.1.3.0.17.nupkg" >> MyNuGetPkg.1.3.0.17.nupkg +curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download/MyNuGetPkg/1.3.0.17/mynugetpkg.1.3.0.17.nupkg" > MyNuGetPkg.1.3.0.17.nupkg ``` This writes the downloaded file to `MyNuGetPkg.1.3.0.17.nupkg` in the current directory. diff --git a/doc/api/packages/pypi.md b/doc/api/packages/pypi.md index dd301e9fab8..a1c96d03297 100644 --- a/doc/api/packages/pypi.md +++ b/doc/api/packages/pypi.md @@ -4,7 +4,7 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# PyPI API +# PyPI API **(FREE)** This is the API documentation for [PyPI Packages](../../user/packages/pypi_repository/index.md). @@ -47,7 +47,8 @@ To write the output to a file: curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/groups/1/packages/pypi/files/5y57017232013c8ac80647f4ca153k3726f6cba62d055cd747844ed95b3c65ff/my.pypi.package-0.0.1.tar.gz" >> my.pypi.package-0.0.1.tar.gz ``` -This writes the downloaded file to `my.pypi.package-0.0.1.tar.gz` in the current directory. +This writes the downloaded file to `my.pypi.package-0.0.1.tar.gz` in the current +directory. ## Group level simple API entry point @@ -106,7 +107,7 @@ GET projects/:id/packages/pypi/files/:sha256/:file_identifier | --------- | ---- | -------- | ----------- | | `id` | string | yes | The ID or full path of the project. | | `sha256` | string | yes | PyPI package file sha256 check sum. | -| `file_identifier` | string | yes | The PyPI package file name. | +| `file_identifier` | string | yes | The PyPI package filename. | ```shell curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/pypi/files/5y57017232013c8ac80647f4ca153k3726f6cba62d055cd747844ed95b3c65ff/my.pypi.package-0.0.1.tar.gz" @@ -118,7 +119,8 @@ To write the output to a file: curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/pypi/files/5y57017232013c8ac80647f4ca153k3726f6cba62d055cd747844ed95b3c65ff/my.pypi.package-0.0.1.tar.gz" >> my.pypi.package-0.0.1.tar.gz ``` -This writes the downloaded file to `my.pypi.package-0.0.1.tar.gz` in the current directory. +This writes the downloaded file to `my.pypi.package-0.0.1.tar.gz` in the current +directory. ## Project-level simple API entry point diff --git a/doc/api/packages/rubygems.md b/doc/api/packages/rubygems.md index 426548d5ed2..10dcaafda42 100644 --- a/doc/api/packages/rubygems.md +++ b/doc/api/packages/rubygems.md @@ -4,7 +4,7 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Ruby gems API +# Ruby gems API **(FREE SELF)** This is the API documentation for [Ruby gems](../../user/packages/rubygems_registry/index.md). diff --git a/doc/api/pages.md b/doc/api/pages.md index ef6523520de..f81a3c3c72b 100644 --- a/doc/api/pages.md +++ b/doc/api/pages.md @@ -4,7 +4,7 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Pages API +# Pages API **(FREE)** Endpoints for managing [GitLab Pages](https://about.gitlab.com/stages-devops-lifecycle/pages/). diff --git a/doc/api/pages_domains.md b/doc/api/pages_domains.md index 46d92db9853..47a8df3875e 100644 --- a/doc/api/pages_domains.md +++ b/doc/api/pages_domains.md @@ -4,7 +4,7 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Pages domains API +# Pages domains API **(FREE)** Endpoints for connecting custom domain(s) and TLS certificates in [GitLab Pages](https://about.gitlab.com/stages-devops-lifecycle/pages/). diff --git a/doc/api/personal_access_tokens.md b/doc/api/personal_access_tokens.md index 4949bf504fa..b96ee81f673 100644 --- a/doc/api/personal_access_tokens.md +++ b/doc/api/personal_access_tokens.md @@ -4,14 +4,14 @@ group: Compliance info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Personal access tokens API +# Personal access tokens API **(FREE)** You can read more about [personal access tokens](../user/profile/personal_access_tokens.md#personal-access-tokens). ## List personal access tokens -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227264) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/270200) to [GitLab Free](https://about.gitlab.com/pricing/) in 13.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227264) in GitLab 13.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/270200) from GitLab Ultimate to GitLab Free in 13.6. Get a list of personal access tokens. @@ -70,8 +70,8 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a ## Revoke a personal access token -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216004) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/270200) to [GitLab Free](https://about.gitlab.com/pricing/) in 13.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216004) in GitLab 13.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/270200) from GitLab Ultimate to GitLab Free in 13.6. Revoke a personal access token. diff --git a/doc/api/pipeline_triggers.md b/doc/api/pipeline_triggers.md index 2fe3f487ebc..5472e5bc334 100644 --- a/doc/api/pipeline_triggers.md +++ b/doc/api/pipeline_triggers.md @@ -38,6 +38,9 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a ] ``` +The trigger token is displayed in full if the trigger token was created by the authenticated +user. Trigger tokens created by other users are shortened to four characters. + ## Get trigger details Get details of project's build trigger. diff --git a/doc/api/pipelines.md b/doc/api/pipelines.md index ad7336bba8f..f3c30a414ea 100644 --- a/doc/api/pipelines.md +++ b/doc/api/pipelines.md @@ -32,10 +32,10 @@ GET /projects/:id/pipelines | `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 | 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`. | | `ref` | string | no | The ref of pipelines | | `sha` | string | no | The SHA of pipelines | | `yaml_errors`| boolean | no | Returns pipelines with invalid configurations | -| `name`| string | no | _([Deprecated in GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/336953))_ The name of the user who triggered pipelines | | `username`| string | no | The username of the user who triggered pipelines | | `updated_after` | datetime | no | Return pipelines updated after the specified date. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | | `updated_before` | datetime | no | Return pipelines updated before the specified date. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | @@ -55,6 +55,7 @@ Example of response "iid": 12, "project_id": 1, "status": "pending", + "soure": "push", "ref": "new-pipeline", "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", "web_url": "https://example.com/foo/bar/pipelines/47", @@ -66,6 +67,7 @@ Example of response "iid": 13, "project_id": 1, "status": "pending", + "soure": "web", "ref": "new-pipeline", "sha": "eb94b618fb5865b26e80fdd8ae531b7a63ad851a", "web_url": "https://example.com/foo/bar/pipelines/48", @@ -212,7 +214,7 @@ Sample response: ### Get a pipeline's test report summary -> Introduced in [GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/65471) +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/65471) in GitLab 14.2. NOTE: This API route is part of the [Unit test report](../ci/unit_test_reports.md) feature. diff --git a/doc/api/plan_limits.md b/doc/api/plan_limits.md index c89c7b46d54..52152dd6e14 100644 --- a/doc/api/plan_limits.md +++ b/doc/api/plan_limits.md @@ -4,7 +4,7 @@ group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Plan limits API **(FREE)** +# Plan limits API **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/54232) in GitLab 13.10. diff --git a/doc/api/project_aliases.md b/doc/api/project_aliases.md index 1638bb644c2..0d130f6f484 100644 --- a/doc/api/project_aliases.md +++ b/doc/api/project_aliases.md @@ -7,7 +7,7 @@ type: reference, api # Project Aliases API **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3264) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3264) in GitLab 12.1. All methods require administrator authorization. diff --git a/doc/api/project_clusters.md b/doc/api/project_clusters.md index 2b4976510bb..bb05e4788d0 100644 --- a/doc/api/project_clusters.md +++ b/doc/api/project_clusters.md @@ -294,7 +294,7 @@ Parameters: | `platform_kubernetes_attributes[token]` | string | no | The token to authenticate against Kubernetes | | `platform_kubernetes_attributes[ca_cert]` | string | no | TLS certificate. Required if API is using a self-signed TLS certificate. | | `platform_kubernetes_attributes[namespace]` | string | no | The unique namespace related to the project | -| `environment_scope` | string | no | The associated environment to the cluster **(PREMIUM)** | +| `environment_scope` | string | no | The associated environment to the cluster | NOTE: `name`, `api_url`, `ca_cert` and `token` can only be updated if the cluster was added diff --git a/doc/api/project_level_variables.md b/doc/api/project_level_variables.md index e596b25ca22..2dcef40aacb 100644 --- a/doc/api/project_level_variables.md +++ b/doc/api/project_level_variables.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, api --- -# Project-level Variables API +# Project-level Variables API **(FREE)** ## List project variables diff --git a/doc/api/project_vulnerabilities.md b/doc/api/project_vulnerabilities.md index 2035d17aa3f..7ba359587f6 100644 --- a/doc/api/project_vulnerabilities.md +++ b/doc/api/project_vulnerabilities.md @@ -7,7 +7,7 @@ type: reference, api # Project Vulnerabilities API **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10242) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10242) in GitLab 12.6. WARNING: This API is in an alpha stage and considered unstable. diff --git a/doc/api/projects.md b/doc/api/projects.md index a510f05df58..29e3cdf6cbf 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -55,7 +55,7 @@ GET /projects | `min_access_level` | integer | **{dotted-circle}** No | Limit by current user minimal [access level](members.md#valid-access-levels). | | `order_by` | string | **{dotted-circle}** No | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, `last_activity_at`, or `similarity` fields. `repository_size`, `storage_size`, `packages_size` or `wiki_size` fields are only allowed for admins. `similarity` ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332890) in GitLab 14.1) is only available when searching and is limited to projects that the current user is a member of. Default is `created_at`. | | `owned` | boolean | **{dotted-circle}** No | Limit by projects explicitly owned by the current user. | -| `repository_checksum_failed` **(PREMIUM)** | boolean | **{dotted-circle}** No | Limit projects where the repository checksum calculation has failed ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6137) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2). | +| `repository_checksum_failed` **(PREMIUM)** | boolean | **{dotted-circle}** No | Limit projects where the repository checksum calculation has failed ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6137) in GitLab 11.2). | | `repository_storage` | string | **{dotted-circle}** No | Limit results to projects stored on `repository_storage`. _(admins only)_ | | `search_namespaces` | boolean | **{dotted-circle}** No | Include ancestor namespaces when matching search criteria. Default is `false`. | | `search` | string | **{dotted-circle}** No | Return list of projects matching the search criteria. | @@ -65,7 +65,7 @@ GET /projects | `statistics` | boolean | **{dotted-circle}** No | Include project statistics. Only available to Reporter or higher level role members. | | `topic` | string | **{dotted-circle}** No | Comma-separated topic names. Limit results to projects that match all of given topics. See `topics` attribute. | | `visibility` | string | **{dotted-circle}** No | Limit by visibility `public`, `internal`, or `private`. | -| `wiki_checksum_failed` **(PREMIUM)** | boolean | **{dotted-circle}** No | Limit projects where the wiki checksum calculation has failed ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6137) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2). | +| `wiki_checksum_failed` **(PREMIUM)** | boolean | **{dotted-circle}** No | Limit projects where the wiki checksum calculation has failed ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6137) in GitLab 11.2). | | `with_custom_attributes` | boolean | **{dotted-circle}** No | Include [custom attributes](custom_attributes.md) in response. _(admins only)_ | | `with_issues_enabled` | boolean | **{dotted-circle}** No | Limit by enabled issues feature. | | `with_merge_requests_enabled` | boolean | **{dotted-circle}** No | Limit by enabled merge requests feature. | @@ -2428,7 +2428,7 @@ POST /projects/:id/housekeeping ## Push Rules **(PREMIUM)** -### Get project push rules **(PREMIUM)** +### Get project push rules Get the [push rules](../push_rules/push_rules.md#enabling-push-rules) of a project. @@ -2474,7 +2474,7 @@ parameters: } ``` -### Add project push rule **(PREMIUM)** +### Add project push rule Adds a push rule to a specified project. @@ -2486,7 +2486,7 @@ POST /projects/:id/push_rule |-----------------------------------------|----------------|------------------------|-------------| | `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` **(PREMIUM)** | boolean | **{dotted-circle}** No | Users can only push commits to this repository that were committed with one of their own verified emails. | +| `commit_committer_check` | boolean | **{dotted-circle}** No | Users can only push commits to this repository that were committed with one of their own verified emails. | | `commit_message_negative_regex` | string | **{dotted-circle}** No | No commit message is allowed to match this, for example `ssh\:\/\/`. | | `commit_message_regex` | string | **{dotted-circle}** No | All commit messages must match this, for example `Fixed \d+\..*`. | | `deny_delete_tag` | boolean | **{dotted-circle}** No | Deny deleting a tag. | @@ -2495,9 +2495,9 @@ POST /projects/:id/push_rule | `max_file_size` | integer | **{dotted-circle}** No | Maximum file size (MB). | | `member_check` | boolean | **{dotted-circle}** No | Restrict commits by author (email) to existing GitLab users. | | `prevent_secrets` | boolean | **{dotted-circle}** No | GitLab rejects any files that are likely to contain secrets. | -| `reject_unsigned_commits` **(PREMIUM)** | boolean | **{dotted-circle}** No | Reject commit when it's not signed through GPG. | +| `reject_unsigned_commits` | boolean | **{dotted-circle}** No | Reject commit when it's not signed through GPG. | -### Edit project push rule **(PREMIUM)** +### Edit project push rule Edits a push rule for a specified project. @@ -2509,7 +2509,7 @@ PUT /projects/:id/push_rule |-----------------------------------------|----------------|------------------------|-------------| | `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` **(PREMIUM)** | boolean | **{dotted-circle}** No | Users can only push commits to this repository that were committed with one of their own verified emails. | +| `commit_committer_check` | boolean | **{dotted-circle}** No | Users can only push commits to this repository that were committed with one of their own verified emails. | | `commit_message_negative_regex` | string | **{dotted-circle}** No | No commit message is allowed to match this, for example `ssh\:\/\/`. | | `commit_message_regex` | string | **{dotted-circle}** No | All commit messages must match this, for example `Fixed \d+\..*`. | | `deny_delete_tag` | boolean | **{dotted-circle}** No | Deny deleting a tag. | @@ -2518,7 +2518,7 @@ PUT /projects/:id/push_rule | `max_file_size` | integer | **{dotted-circle}** No | Maximum file size (MB). | | `member_check` | boolean | **{dotted-circle}** No | Restrict commits by author (email) to existing GitLab users. | | `prevent_secrets` | boolean | **{dotted-circle}** No | GitLab rejects any files that are likely to contain secrets. | -| `reject_unsigned_commits` **(PREMIUM)** | boolean | **{dotted-circle}** No | Reject commits when they are not GPG signed. | +| `reject_unsigned_commits` | boolean | **{dotted-circle}** No | Reject commits when they are not GPG signed. | ### Delete project push rule diff --git a/doc/api/protected_environments.md b/doc/api/protected_environments.md index 9a64e676ad9..82bb1e55e77 100644 --- a/doc/api/protected_environments.md +++ b/doc/api/protected_environments.md @@ -7,7 +7,7 @@ type: concepts, howto # Protected environments API **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30595) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30595) in GitLab 12.8. ## Valid access levels diff --git a/doc/api/releases/index.md b/doc/api/releases/index.md index 35bf24c586c..72627783947 100644 --- a/doc/api/releases/index.md +++ b/doc/api/releases/index.md @@ -4,7 +4,7 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Releases API +# Releases API **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41766) in GitLab 11.7. > - Using this API you can manipulate GitLab [Release](../../user/project/releases/index.md) entries. @@ -21,7 +21,7 @@ For authentication, the Releases API accepts either: - A [Personal Access Token](../../user/profile/personal_access_tokens.md) using the `PRIVATE-TOKEN` header. -- The [GitLab CI/CD job token](../index.md#gitlab-cicd-job-token) `$CI_JOB_TOKEN` using +- The [GitLab CI/CD job token](../../ci/jobs/ci_job_token.md) `$CI_JOB_TOKEN` using the `JOB-TOKEN` header. ## List Releases @@ -89,8 +89,8 @@ Example response: "state":"closed", "created_at":"2019-07-12T19:45:44.256Z", "updated_at":"2019-07-12T19:45:44.256Z", - "due_date":"2019-08-16T11:00:00.256Z", - "start_date":"2019-07-30T12:00:00.256Z", + "due_date":"2019-08-16", + "start_date":"2019-07-30", "web_url":"https://gitlab.example.com/root/awesome-app/-/milestones/1", "issue_stats": { "total": 98, @@ -106,8 +106,8 @@ Example response: "state":"closed", "created_at":"2019-07-16T14:00:12.256Z", "updated_at":"2019-07-16T14:00:12.256Z", - "due_date":"2019-08-16T11:00:00.256Z", - "start_date":"2019-07-30T12:00:00.256Z", + "due_date":"2019-08-16", + "start_date":"2019-07-30", "web_url":"https://gitlab.example.com/root/awesome-app/-/milestones/2", "issue_stats": { "total": 24, @@ -292,8 +292,8 @@ Example response: "state":"closed", "created_at":"2019-07-12T19:45:44.256Z", "updated_at":"2019-07-12T19:45:44.256Z", - "due_date":"2019-08-16T11:00:00.256Z", - "start_date":"2019-07-30T12:00:00.256Z", + "due_date":"2019-08-16", + "start_date":"2019-07-30", "web_url":"https://gitlab.example.com/root/awesome-app/-/milestones/1", "issue_stats": { "total": 98, @@ -309,8 +309,8 @@ Example response: "state":"closed", "created_at":"2019-07-16T14:00:12.256Z", "updated_at":"2019-07-16T14:00:12.256Z", - "due_date":"2019-08-16T11:00:00.256Z", - "start_date":"2019-07-30T12:00:00.256Z", + "due_date":"2019-08-16", + "start_date":"2019-07-30", "web_url":"https://gitlab.example.com/root/awesome-app/-/milestones/2", "issue_stats": { "total": 24, @@ -434,8 +434,8 @@ Example response: "state":"closed", "created_at":"2019-07-12T19:45:44.256Z", "updated_at":"2019-07-12T19:45:44.256Z", - "due_date":"2019-08-16T11:00:00.256Z", - "start_date":"2019-07-30T12:00:00.256Z", + "due_date":"2019-08-16", + "start_date":"2019-07-30", "web_url":"https://gitlab.example.com/root/awesome-app/-/milestones/1", "issue_stats": { "total": 99, @@ -451,8 +451,8 @@ Example response: "state":"closed", "created_at":"2019-07-16T14:00:12.256Z", "updated_at":"2019-07-16T14:00:12.256Z", - "due_date":"2019-08-16T11:00:00.256Z", - "start_date":"2019-07-30T12:00:00.256Z", + "due_date":"2019-08-16", + "start_date":"2019-07-30", "web_url":"https://gitlab.example.com/root/awesome-app/-/milestones/2", "issue_stats": { "total": 24, @@ -499,7 +499,7 @@ Example response: ### Group milestones **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235391) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235391) in GitLab 13.5. Group milestones associated with the project may be specified in the `milestones` array for [Create a release](#create-a-release) and [Update a release](#update-a-release) @@ -508,7 +508,7 @@ adding milestones for ancestor groups raises an error. ## Collect release evidence **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199065) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199065) in GitLab 12.10. Create Evidence for an existing Release. @@ -600,8 +600,8 @@ Example response: "state":"active", "created_at":"2019-09-01T13:00:00.256Z", "updated_at":"2019-09-01T13:00:00.256Z", - "due_date":"2019-09-20T13:00:00.256Z", - "start_date":"2019-09-05T12:00:00.256Z", + "due_date":"2019-09-20", + "start_date":"2019-09-05", "web_url":"https://gitlab.example.com/root/awesome-app/-/milestones/3", "issue_stats": { "opened": 11, diff --git a/doc/api/releases/links.md b/doc/api/releases/links.md index 2f8dc363124..c9d183b8351 100644 --- a/doc/api/releases/links.md +++ b/doc/api/releases/links.md @@ -4,7 +4,7 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Release links API +# Release links API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41766) in GitLab 11.7. diff --git a/doc/api/repositories.md b/doc/api/repositories.md index 9d464c94d99..1c9136d22ac 100644 --- a/doc/api/repositories.md +++ b/doc/api/repositories.md @@ -200,7 +200,8 @@ Example response: "deleted_file": false }], "compare_timeout": false, - "compare_same_ref": false + "compare_same_ref": false, + "web_url": "https://gitlab.example.com/thedude/gitlab-foss/-/compare/ae73cb07c9eeaf35924a10f713b364d32b2dd34f...0b4bc9a49b562e85de7cc9e834518ea6828729b9" } ``` @@ -214,7 +215,7 @@ GET /projects/:id/repository/contributors ``` WARNING: -The `additions` and `deletions` attributes are deprecated [as of GitLab 13.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39653), because they [always return `0`](https://gitlab.com/gitlab-org/gitlab/-/issues/233119). +The `additions` and `deletions` attributes are [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39653) as of GitLab 13.4, because they [always return `0`](https://gitlab.com/gitlab-org/gitlab/-/issues/233119). Supported attributes: @@ -447,6 +448,10 @@ You can set the following variables in this file: - `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: @@ -507,7 +512,7 @@ follows: {% each entries %} - [{{ title }}]({{ commit.reference }})\ -{% if author.contributor %} by {{ author.reference }}{% end %}\ +{% if author.credit %} by {{ author.reference }}{% end %}\ {% if merge_request %} ([merge request]({{ merge_request.reference }})){% end %} {% end %} @@ -597,7 +602,7 @@ template: | {% each entries %} - [{{ title }}]({{ commit.reference }})\ - {% if author.contributor %} by {{ author.reference }}{% end %} + {% if author.credit %} by {{ author.reference }}{% end %} {% end %} @@ -633,8 +638,11 @@ In an entry, the following variables are available (here `foo.bar` means that - `commit.trailers`: an object containing all the Git trailers that were present in the commit body. - `author.reference`: a reference to the commit author (for example, `@alice`). -- `author.contributor`: a boolean set to `true` when the author is an external - contributor, otherwise this is set to `false`. +- `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. - `merge_request.reference`: a reference to the merge request that first introduced the change (for example, `gitlab-org/gitlab!50063`). diff --git a/doc/api/resource_access_tokens.md b/doc/api/resource_access_tokens.md index 3532cfda47b..fa1e7aace9a 100644 --- a/doc/api/resource_access_tokens.md +++ b/doc/api/resource_access_tokens.md @@ -4,7 +4,7 @@ group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Project access tokens API +# Project access tokens API **(FREE)** You can read more about [project access tokens](../user/project/settings/project_access_tokens.md). diff --git a/doc/api/resource_label_events.md b/doc/api/resource_label_events.md index c5292059c0f..9c05d32c992 100644 --- a/doc/api/resource_label_events.md +++ b/doc/api/resource_label_events.md @@ -95,7 +95,7 @@ Parameters: curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/resource_label_events/1" ``` -## Epics **(ULTIMATE)** +## Epics **(PREMIUM)** ### List group epic label events diff --git a/doc/api/runners.md b/doc/api/runners.md index 9e48331cdea..bfdf2d49100 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -4,7 +4,7 @@ group: Runner info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Runners API +# Runners API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/2640) in GitLab 8.5. @@ -41,7 +41,6 @@ GET /runners?scope=active GET /runners?type=project_type GET /runners?status=active GET /runners?tag_list=tag1,tag2 -GET /runners?search=gitlab ``` | Attribute | Type | Required | Description | @@ -50,7 +49,6 @@ GET /runners?search=gitlab | `type` | string | no | The type of runners to show, one of: `instance_type`, `group_type`, `project_type` | | `status` | string | no | The status of runners to show, one of: `active`, `paused`, `online`, `offline` | | `tag_list` | string array | no | List of the runner's tags | -| `search` | string | no | The full token or partial description text to match | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners" @@ -85,7 +83,7 @@ Example response: ] ``` -## List all runners +## List all runners **(FREE SELF)** Get a list of all runners in the GitLab instance (specific and shared). Access is restricted to users with `admin` privileges. @@ -160,6 +158,8 @@ Example response: ] ``` +To view more than the first 20 runners, use [pagination](index.md#pagination). + ## Get runner's details Get details of a runner. @@ -246,8 +246,8 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab ``` NOTE: -The `token` attribute in the response was deprecated [in GitLab 12.10](https://gitlab.com/gitlab-org/gitlab/-/issues/214320). -and removed in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/214322). +The `token` attribute in the response was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/214320) in GitLab 12.10. +and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/214322) in GitLab 13.0. Example response: @@ -675,3 +675,48 @@ Response: |-----------|---------------------------------| | 200 | Credentials are valid | | 403 | Credentials are invalid | + +## Reset instance's runner registration token + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30942) in GitLab 14.3. + +Resets the runner registration token for the GitLab instance. + +```plaintext +POST /runners/reset_registration_token +``` + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/runners/reset_registration_token" +``` + +## Reset project's runner registration token + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30942) in GitLab 14.3. + +Resets the runner registration token for a project. + +```plaintext +POST /projects/:id/runners/reset_registration_token +``` + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/projects/9/runners/reset_registration_token" +``` + +## Reset group's runner registration token + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30942) in GitLab 14.3. + +Resets the runner registration token for a group. + +```plaintext +POST /groups/:id/runners/reset_registration_token +``` + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/groups/9/runners/reset_registration_token" +``` diff --git a/doc/api/scim.md b/doc/api/scim.md index 42580ba65b6..2d9cc148412 100644 --- a/doc/api/scim.md +++ b/doc/api/scim.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # SCIM API (SYSTEM ONLY) **(PREMIUM SAAS)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9388) in GitLab Premium 11.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9388) in GitLab 11.10. The SCIM API implements the [RFC7644 protocol](https://tools.ietf.org/html/rfc7644). As this API is for **system** use for SCIM provider integration, it is subject to change without notice. diff --git a/doc/api/services.md b/doc/api/services.md index 8daaa532ff4..cf6c5ec511b 100644 --- a/doc/api/services.md +++ b/doc/api/services.md @@ -503,7 +503,7 @@ GET /projects/:id/services/emails-on-push ## Confluence service -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220934) in GitLab 13.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220934) in GitLab 13.2. Replaces the link to the internal wiki with a link to a Confluence Cloud Workspace. @@ -659,7 +659,7 @@ PUT /projects/:id/services/hangouts-chat ``` NOTE: -Specific event parameters (for example, `push_events` flag) were [introduced in v10.4](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11435) +Specific event parameters (for example, `push_events` flag) were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11435) in GitLab 10.4. Parameters: @@ -1119,7 +1119,7 @@ PUT /projects/:id/services/slack ``` NOTE: -Specific event parameters (for example, `push_events` flag and `push_channel`) were [introduced in v10.4](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11435) +Specific event parameters (for example, `push_events` flag and `push_channel`) were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11435) in GitLab 10.4. Parameters: @@ -1153,6 +1153,8 @@ Parameters: | `tag_push_events` | boolean | false | Enable notifications for tag push events | | `wiki_page_channel` | string | false | The name of the channel to receive wiki page events notifications | | `wiki_page_events` | boolean | false | Enable notifications for wiki page events | +| `vulnerability_channel` | string | false | **(ULTIMATE)** The name of the channel to receive vulnerability event notifications. | +| `vulnerability_events` | boolean | false | **(ULTIMATE)** Enable notifications for vulnerability events | ### Delete Slack service @@ -1229,7 +1231,7 @@ PUT /projects/:id/services/mattermost ``` NOTE: -Specific event parameters (for example, `push_events` flag and `push_channel`) were [introduced in v10.4](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11435) +Specific event parameters (for example, `push_events` flag and `push_channel`) were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11435) in GitLab 10.4. Parameters: @@ -1250,6 +1252,7 @@ Parameters: | `confidential_note_events` | boolean | false | Enable notifications for confidential note events | | `pipeline_events` | boolean | false | Enable notifications for pipeline events | | `wiki_page_events` | boolean | false | Enable notifications for wiki page events | +| `vulnerability_events` | boolean | false | **(ULTIMATE)** Enable notifications for vulnerability events | | `push_channel` | string | false | The name of the channel to receive push events notifications | | `issue_channel` | string | false | The name of the channel to receive issues events notifications | | `confidential_issue_channel` | string | false | The name of the channel to receive confidential issues events notifications | @@ -1259,6 +1262,7 @@ Parameters: | `tag_push_channel` | string | false | The name of the channel to receive tag push events notifications | | `pipeline_channel` | string | false | The name of the channel to receive pipeline events notifications | | `wiki_page_channel` | string | false | The name of the channel to receive wiki page events notifications | +| `vulnerability_channel` | string | false | **(ULTIMATE)** The name of the channel to receive vulnerability events notifications | ### Delete Mattermost notifications service @@ -1361,7 +1365,7 @@ GET /projects/:id/services/jenkins A continuous integration and build server NOTE: -This service was [removed in v13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/1600) +This service was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/1600) in GitLab 13.0. ### Create/Edit Jenkins CI (Deprecated) service diff --git a/doc/api/settings.md b/doc/api/settings.md index d49359b5d43..6b1faa0402f 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -96,7 +96,7 @@ Example response: } ``` -Users on GitLab [Premium or Ultimate](https://about.gitlab.com/pricing/) may also see +Users on [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) may also see the `file_template_project_id`, `delayed_project_deletion`, `deletion_adjourned_period`, or the `geo_node_allowed_ips` parameters: ```json @@ -197,7 +197,7 @@ Example response: } ``` -Users on GitLab [Premium or Ultimate](https://about.gitlab.com/pricing/) may also see +Users on [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) may also see these parameters: - `file_template_project_id` @@ -334,7 +334,7 @@ listed in the descriptions of the relevant settings. | `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. | | `local_markdown_version` | integer | no | Increase this value when any cached Markdown should be invalidated. | -| `mailgun_signing_key` | string | no | The Mailgun HTTP webhook signing key for receiving events from webhook | +| `mailgun_signing_key` | string | no | The Mailgun HTTP webhook signing key for receiving events from webhook. | | `mailgun_events_enabled` | boolean | no | Enable Mailgun event receiver. | | `maintenance_mode_message` | string | no | **(PREMIUM)** Message displayed when instance is in maintenance mode. | | `maintenance_mode` | boolean | no | **(PREMIUM)** When instance is in maintenance mode, non-administrative users can sign in with read-only access and make read-only API requests. | @@ -386,6 +386,9 @@ listed in the descriptions of the relevant settings. | `shared_runners_enabled` | boolean | no | (**If enabled, requires:** `shared_runners_text` and `shared_runners_minutes`) Enable shared runners for new projects. | | `shared_runners_minutes` | integer | required by: `shared_runners_enabled` | **(PREMIUM)** Set the maximum number of pipeline minutes that a group can use on shared runners per month. | | `shared_runners_text` | string | required by: `shared_runners_enabled` | Shared runners text. | +| `sidekiq_job_limiter_mode` | string | no | `track` or `compress`. Sets the behavior for [Sidekiq job size limits](../user/admin_area/settings/sidekiq_job_limits.md). Default: 'compress'. | +| `sidekiq_job_limiter_compression_threshold_bytes` | integer | no | The threshold in bytes at which Sidekiq jobs are compressed before being stored in Redis. Default: 100 000 bytes (100KB). | +| `sidekiq_job_limiter_limit_bytes` | integer | no | The threshold in bytes at which Sidekiq jobs are rejected. Default: 0 bytes (doesn't reject any job). | | `sign_in_text` | string | no | Text on the login page. | | `signin_enabled` | string | no | (Deprecated: Use `password_authentication_enabled_for_web` instead) Flag indicating if password authentication is enabled for the web interface. | | `signup_enabled` | boolean | no | Enable registration. Default is `true`. | @@ -412,15 +415,22 @@ listed in the descriptions of the relevant settings. | `throttle_authenticated_web_enabled` | boolean | no | (**If enabled, requires:** `throttle_authenticated_web_period_in_seconds` and `throttle_authenticated_web_requests_per_period`) Enable authenticated web request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). | | `throttle_authenticated_web_period_in_seconds` | integer | required by:<br>`throttle_authenticated_web_enabled` | Rate limit period in seconds. | | `throttle_authenticated_web_requests_per_period` | integer | required by:<br>`throttle_authenticated_web_enabled` | Max requests per period per user. | -| `throttle_unauthenticated_enabled` | boolean | no | (**If enabled, requires:** `throttle_unauthenticated_period_in_seconds` and `throttle_unauthenticated_requests_per_period`) Enable unauthenticated request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). | -| `throttle_unauthenticated_period_in_seconds` | integer | required by:<br>`throttle_unauthenticated_enabled` | Rate limit period in seconds. | -| `throttle_unauthenticated_requests_per_period` | integer | required by:<br>`throttle_unauthenticated_enabled` | Max requests per period per IP. | +| `throttle_unauthenticated_enabled` | boolean | no | ([Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/335300) in GitLab 14.3. Use `throttle_unauthenticated_web_enabled` or `throttle_unauthenticated_api_enabled` instead.) (**If enabled, requires:** `throttle_unauthenticated_period_in_seconds` and `throttle_unauthenticated_requests_per_period`) Enable unauthenticated web request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). | +| `throttle_unauthenticated_period_in_seconds` | integer | required by:<br>`throttle_unauthenticated_enabled` | ([Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/335300) in GitLab 14.3. Use `throttle_unauthenticated_web_period_in_seconds` or `throttle_unauthenticated_api_period_in_seconds` instead.) Rate limit period in seconds. | +| `throttle_unauthenticated_requests_per_period` | integer | required by:<br>`throttle_unauthenticated_enabled` | ([Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/335300) in GitLab 14.3. Use `throttle_unauthenticated_web_requests_per_period` or `throttle_unauthenticated_api_requests_per_period` instead.) Max requests per period per IP. | +| `throttle_unauthenticated_api_enabled` | boolean | no | (**If enabled, requires:** `throttle_unauthenticated_api_period_in_seconds` and `throttle_unauthenticated_api_requests_per_period`) Enable unauthenticated API request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). | +| `throttle_unauthenticated_api_period_in_seconds` | integer | required by:<br>`throttle_unauthenticated_api_enabled` | Rate limit period in seconds. | +| `throttle_unauthenticated_api_requests_per_period` | integer | required by:<br>`throttle_unauthenticated_api_enabled` | Max requests per period per IP. | +| `throttle_unauthenticated_web_enabled` | boolean | no | (**If enabled, requires:** `throttle_unauthenticated_web_period_in_seconds` and `throttle_unauthenticated_web_requests_per_period`) Enable unauthenticated web request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). | +| `throttle_unauthenticated_web_period_in_seconds` | integer | required by:<br>`throttle_unauthenticated_web_enabled` | Rate limit period in seconds. | +| `throttle_unauthenticated_web_requests_per_period` | integer | required by:<br>`throttle_unauthenticated_web_enabled` | Max requests per period per IP. | | `time_tracking_limit_to_hours` | boolean | no | Limit display of time tracking units to hours. Default is `false`. | | `two_factor_grace_period` | integer | required by: `require_two_factor_authentication` | Amount of time (in hours) that users are allowed to skip forced configuration of two-factor authentication. | | `unique_ips_limit_enabled` | boolean | no | (**If enabled, requires:** `unique_ips_limit_per_user` and `unique_ips_limit_time_window`) Limit sign in from multiple IPs. | | `unique_ips_limit_per_user` | integer | required by: `unique_ips_limit_enabled` | Maximum number of IPs per user. | | `unique_ips_limit_time_window` | integer | required by: `unique_ips_limit_enabled` | How many seconds an IP is counted towards the limit. | | `usage_ping_enabled` | boolean | no | Every week GitLab reports license usage back to GitLab, Inc. | +| `user_deactivation_emails_enabled` | boolean | no | Send an email to users upon account deactivation. | | `user_default_external` | boolean | no | Newly registered users are external by default. | | `user_default_internal_regex` | string | no | Specify an email address regex pattern to identify default internal users. | | `user_oauth_applications` | boolean | no | Allow users to register any application to use GitLab as an OAuth provider. | diff --git a/doc/api/statistics.md b/doc/api/statistics.md index a57838e6496..75dfa0de705 100644 --- a/doc/api/statistics.md +++ b/doc/api/statistics.md @@ -4,7 +4,7 @@ group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Application statistics API +# Application statistics API **(FREE SELF)** ## Get current application statistics diff --git a/doc/api/status_checks.md b/doc/api/status_checks.md index 25ccd5d767a..0c72ee37348 100644 --- a/doc/api/status_checks.md +++ b/doc/api/status_checks.md @@ -42,9 +42,9 @@ GET /projects/:id/merge_requests/:merge_request_iid/status_checks ] ``` -## Set approval status of an external status check +## Set status of an external status check -For a single merge request, use the API to inform GitLab that a merge request has been approved by an external service. +For a single merge request, use the API to inform GitLab that a merge request has passed a check by an external service. ```plaintext POST /projects/:id/merge_requests/:merge_request_iid/status_check_responses @@ -62,7 +62,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/status_check_responses NOTE: `sha` must be the SHA at the `HEAD` of the merge request's source branch. -## Get project external status checks **(ULTIMATE)** +## Get project external status checks You can request information about a project's external status checks using the following endpoint: @@ -97,7 +97,7 @@ GET /projects/:id/external_status_checks ] ``` -## Create external status check **(ULTIMATE)** +## Create external status check You can create a new external status check for a project using the following endpoint: @@ -116,7 +116,7 @@ defined external service. This includes confidential merge requests. | `external_url` | string | yes | URL of status check resource | | `protected_branch_ids` | `array<Integer>` | no | IDs of protected branches to scope the rule by | -## Delete external status check **(ULTIMATE)** +## Delete external status check You can delete an external status check for a project using the following endpoint: @@ -129,7 +129,7 @@ DELETE /projects/:id/external_status_checks/:check_id | `rule_id` | integer | yes | ID of an status check | | `id` | integer | yes | ID of a project | -## Update external status check **(ULTIMATE)** +## Update external status check You can update an existing external status check for a project using the following endpoint: diff --git a/doc/api/system_hooks.md b/doc/api/system_hooks.md index 39a3ccb2bc3..3587016ac6b 100644 --- a/doc/api/system_hooks.md +++ b/doc/api/system_hooks.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/engineering/ux/technical-writing/#assignments --- -# System hooks API +# System hooks API **(FREE SELF)** All methods require administrator authorization. You can configure the URL endpoint of the system hooks from the GitLab user interface: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. Select **System Hooks** (`/admin/hooks`). Read more about [system hooks](../system_hooks/system_hooks.md). diff --git a/doc/api/templates/dockerfiles.md b/doc/api/templates/dockerfiles.md index 2d7e926561f..5f862201571 100644 --- a/doc/api/templates/dockerfiles.md +++ b/doc/api/templates/dockerfiles.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Dockerfiles API +# Dockerfiles API **(FREE)** GitLab provides an API endpoint for instance-level Dockerfile templates. Default templates are defined at diff --git a/doc/api/templates/gitignores.md b/doc/api/templates/gitignores.md index f1bf8120574..71b791de16a 100644 --- a/doc/api/templates/gitignores.md +++ b/doc/api/templates/gitignores.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# .gitignore API +# .gitignore API **(FREE)** In GitLab, the `/gitignores` endpoint returns a list of Git `.gitignore` templates. For more information, see the [Git documentation for `.gitignore`](https://git-scm.com/docs/gitignore). diff --git a/doc/api/templates/gitlab_ci_ymls.md b/doc/api/templates/gitlab_ci_ymls.md index 82abe598cf6..abed008218c 100644 --- a/doc/api/templates/gitlab_ci_ymls.md +++ b/doc/api/templates/gitlab_ci_ymls.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# GitLab CI YMLs API +# GitLab CI YMLs API **(FREE)** In GitLab, there is an API endpoint available to work with GitLab CI/CD YMLs. For more information on CI/CD pipeline configuration in GitLab, see the diff --git a/doc/api/templates/licenses.md b/doc/api/templates/licenses.md index e7eaa6eb3e0..adba4f75255 100644 --- a/doc/api/templates/licenses.md +++ b/doc/api/templates/licenses.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Licenses API +# Licenses API **(FREE)** In GitLab, there is an API endpoint available for working with various open source license templates. For more information on the terms of various diff --git a/doc/api/usage_data.md b/doc/api/usage_data.md index 00d87c89faf..f244c681086 100644 --- a/doc/api/usage_data.md +++ b/doc/api/usage_data.md @@ -11,7 +11,7 @@ The Service Data API is associated with [Service Ping](../development/service_pi ## Export metric definitions as a single YAML file -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57270) in GitLab 13.11. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57270) in GitLab 13.11. Export all metric definitions as a single YAML file, similar to the [Metrics Dictionary](https://gitlab-org.gitlab.io/growth/product-intelligence/metric-dictionary), for easier importing. @@ -37,7 +37,7 @@ Example response: product_group: group::global search product_category: global_search value_type: number - status: data_available + status: active time_frame: 28d data_source: redis_hll distribution: diff --git a/doc/api/users.md b/doc/api/users.md index 6ba751bd292..dfd2f6cc87d 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -4,7 +4,7 @@ group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Users API +# Users API **(FREE)** ## List users @@ -39,7 +39,7 @@ GET /users ] ``` -You can also search for users by name or primary email using `?search=`. For example. `/users?search=John`. +You can also search for users by name, username, primary email, or secondary email, by using `?search=`. For example. `/users?search=John`. In addition, you can lookup users by username: @@ -124,7 +124,6 @@ GET /users "created_at": "2012-05-23T08:00:58Z", "is_admin": false, "bio": "", - "bio_html": "", "location": null, "skype": "", "linkedin": "", @@ -164,7 +163,6 @@ GET /users "created_at": "2012-05-23T08:01:01Z", "is_admin": false, "bio": "", - "bio_html": "", "location": null, "skype": "", "linkedin": "", @@ -191,7 +189,7 @@ GET /users ] ``` -Users on GitLab [Premium or higher](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit`, `extra_shared_runners_minutes_limit`, `is_auditor`, and `using_license_seat` parameters. +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit`, `extra_shared_runners_minutes_limit`, `is_auditor`, and `using_license_seat` parameters. ```json [ @@ -207,7 +205,7 @@ Users on GitLab [Premium or higher](https://about.gitlab.com/pricing/) also see ] ``` -Users on GitLab [Premium or higher](https://about.gitlab.com/pricing/) also see +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `group_saml` provider option and `provisioned_by_group_id` parameter: ```json @@ -261,7 +259,7 @@ GET /users?with_custom_attributes=true ## Single user -Get a single user. +Get a single user. This endpoint can be accessed without authentication. ### For user @@ -283,7 +281,6 @@ Parameters: "web_url": "http://localhost:3000/john_smith", "created_at": "2012-05-23T08:00:58Z", "bio": "", - "bio_html": "", "bot": false, "location": null, "public_email": "john@example.com", @@ -322,7 +319,6 @@ Example Responses: "created_at": "2012-05-23T08:00:58Z", "is_admin": false, "bio": "", - "bio_html": "", "location": null, "public_email": "john@example.com", "skype": "", @@ -361,7 +357,7 @@ Example Responses: NOTE: The `plan` and `trial` parameters are only available on GitLab Enterprise Edition. -Users on GitLab [Premium or higher](https://about.gitlab.com/pricing/) also see +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit`, `is_auditor`, and `extra_shared_runners_minutes_limit` parameters. ```json @@ -375,7 +371,7 @@ the `shared_runners_minutes_limit`, `is_auditor`, and `extra_shared_runners_minu } ``` -Users on GitLab.com [Premium or higher](https://about.gitlab.com/pricing/) also +Users on [GitLab.com Premium or higher](https://about.gitlab.com/pricing/) also see the `group_saml` option and `provisioned_by_group_id` parameter: ```json @@ -551,7 +547,6 @@ GET /user "web_url": "http://localhost:3000/john_smith", "created_at": "2012-05-23T08:00:58Z", "bio": "", - "bio_html": "", "location": null, "public_email": "john@example.com", "skype": "", @@ -601,7 +596,6 @@ GET /user "created_at": "2012-05-23T08:00:58Z", "is_admin": false, "bio": "", - "bio_html": "", "location": null, "public_email": "john@example.com", "skype": "", @@ -633,7 +627,7 @@ GET /user } ``` -Users on GitLab [Premium or higher](https://about.gitlab.com/pricing/) also see these +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see these parameters: - `shared_runners_minutes_limit` @@ -668,7 +662,7 @@ Example response: ## Get the status of a user -Get the status of a user. +Get the status of a user. This endpoint can be accessed without authentication. ```plaintext GET /users/:id_or_username/status @@ -812,7 +806,7 @@ Example response: ### Followers and following -Get the followers of a user. +Get the followers of a user. This endpoint can be accessed without authentication. ```plaintext GET /users/:id/followers @@ -1467,6 +1461,46 @@ Returns: - `404 User Not Found` if the user cannot be found. - `403 Forbidden` if the user cannot be activated because they are blocked by an administrator or by LDAP synchronization. +## Ban user + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327354) in GitLab 14.3. + +Bans the specified user. Available only for admin. + +```plaintext +POST /users/:id/ban +``` + +Parameters: + +- `id` (required) - ID of specified user + +Returns: + +- `201 OK` on success. +- `404 User Not Found` if user cannot be found. +- `403 Forbidden` when trying to ban a user that is not active. + +## Unban user + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327354) in GitLab 14.3. + +Unbans the specified user. Available only for admin. + +```plaintext +POST /users/:id/unban +``` + +Parameters: + +- `id` (required) - ID of specified user + +Returns: + +- `201 OK` on success. +- `404 User Not Found` if the user cannot be found. +- `403 Forbidden` when trying to unban a user that is not banned. + ### Get user contribution events Please refer to the [Events API documentation](events.md#get-user-contribution-events) @@ -1564,6 +1598,45 @@ Example Responses: { "message": "The user you are trying to approve is not pending approval" } ``` +## Reject user + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339925) in GitLab 14.3. + +Rejects specified user that is [pending approval](../user/admin_area/moderate_users.md#users-pending-approval). Available only for administrators. + +```plaintext +POST /users/:id/reject +``` + +Parameters: + +- `id` (required) - ID of specified user + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/reject" +``` + +Returns: + +- `200 OK` on success. +- `403 Forbidden` if not authenticated as an administrator. +- `404 User Not Found` if user cannot be found. +- `409 Conflict` if user is not pending approval. + +Example Responses: + +```json +{ "message": "Success" } +``` + +```json +{ "message": "404 User Not Found" } +``` + +```json +{ "message": "User does not have a pending request" } +``` + ## Get an impersonation token of a user > Requires admin permissions. diff --git a/doc/api/v3_to_v4.md b/doc/api/v3_to_v4.md index 8875e4daa87..3fba95c1fb3 100644 --- a/doc/api/v3_to_v4.md +++ b/doc/api/v3_to_v4.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # API V3 to API V4 WARNING: -The GitLab API v3 was removed in [GitLab 11.0](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/36819). +The GitLab API v3 was [removed](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/36819) in GitLab 11.0. For information about the current version of the GitLab API, read the [API documentation](index.md). diff --git a/doc/api/version.md b/doc/api/version.md index b23930e70f9..b076993f00e 100644 --- a/doc/api/version.md +++ b/doc/api/version.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/engineering/ux/technical-writing/#assignments --- -# Version API +# Version API **(FREE)** > Introduced in GitLab 8.13. diff --git a/doc/api/vulnerabilities.md b/doc/api/vulnerabilities.md index b18a837de26..1c6f7a760e6 100644 --- a/doc/api/vulnerabilities.md +++ b/doc/api/vulnerabilities.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Vulnerabilities API **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10242) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10242) in GitLab 12.6. NOTE: The former Vulnerabilities API was renamed to Vulnerability Findings API diff --git a/doc/api/vulnerability_exports.md b/doc/api/vulnerability_exports.md index 4240d363ff0..9395a4ee5de 100644 --- a/doc/api/vulnerability_exports.md +++ b/doc/api/vulnerability_exports.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Vulnerability export API **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197494) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. [Updated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30397) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197494) in GitLab 12.10. [Updated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30397) in GitLab 13.0. WARNING: This API is in an alpha stage and considered unstable. @@ -198,7 +198,7 @@ The response is `404 Not Found` if the vulnerability export is not finished yet Example response: ```csv -Group Name,Project Name,Scanner Type,Scanner Name,Status,Vulnerability,Details,Additional Info,Severity,CVE,CWE,Other Identifiers +Group Name,Project Name,Tool,Scanner Name,Status,Vulnerability,Details,Additional Info,Severity,CVE,CWE,Other Identifiers Gitlab.org,Defend,container_scanning,Trivy,detected,CVE-2017-16997 in glibc,,CVE-2017-16997 in glibc,critical,CVE-2017-16997 Gitlab.org,Defend,container_scanning,Trivy,detected,CVE-2017-18269 in glibc,,CVE-2017-18269 in glibc,critical,CVE-2017-18269 Gitlab.org,Defend,container_scanning,Trivy,detected,CVE-2018-1000001 in glibc,,CVE-2018-1000001 in glibc,high,CVE-2018-1000001 diff --git a/doc/api/vulnerability_findings.md b/doc/api/vulnerability_findings.md index c7f045a67a0..dfc6074a1aa 100644 --- a/doc/api/vulnerability_findings.md +++ b/doc/api/vulnerability_findings.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Vulnerability Findings API **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/19029) in GitLab Ultimate 12.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/19029) in GitLab 12.5. NOTE: This API resource is renamed from Vulnerabilities to Vulnerability Findings because the Vulnerabilities are reserved diff --git a/doc/architecture/blueprints/composable_codebase_using_rails_engines/index.md b/doc/architecture/blueprints/composable_codebase_using_rails_engines/index.md index 92717dc1fe9..095eaaec23f 100644 --- a/doc/architecture/blueprints/composable_codebase_using_rails_engines/index.md +++ b/doc/architecture/blueprints/composable_codebase_using_rails_engines/index.md @@ -6,6 +6,9 @@ comments: false description: 'Making a GitLab codebase composable - allowing to run parts of the application' --- +NOTE: +Due to our focus on improving the overall availability of GitLab.com and reducing tech debt, we do not have capacity to act on this blueprint. We will re-evaluate in Q1-FY23. + # Composable GitLab codebase - using Rails Engines The one of the major risks of a single codebase is an infinite growth of the whole diff --git a/doc/architecture/blueprints/container_registry_metadata_database/index.md b/doc/architecture/blueprints/container_registry_metadata_database/index.md index b71517de061..f52635baf7b 100644 --- a/doc/architecture/blueprints/container_registry_metadata_database/index.md +++ b/doc/architecture/blueprints/container_registry_metadata_database/index.md @@ -77,12 +77,12 @@ The single entrypoint for the registry is the [HTTP API](https://gitlab.com/gitl | Operation | UI | Background | Observations | | ------------------------------------------------------------ | ------------------ | ------------------------ | ------------------------------------------------------------ | -| [Check API version](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#api-version-check) | :heavy_check_mark: | :heavy_check_mark: | Used globally to ensure that the registry supports the Docker Distribution V2 API, as well as for identifying whether GitLab Rails is talking to the GitLab Container Registry or a third-party one (used to toggle features only available in the former). | -| [List repository tags](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#listing-image-tags) | :heavy_check_mark: | :heavy_check_mark: | Used to list and show tags in the UI. Used to list tags in the background for [cleanup policies](../../../user/packages/container_registry/#cleanup-policy) and [Geo replication](../../../administration/geo/replication/docker_registry.md). | -| [Check if manifest exists](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#existing-manifests) | :heavy_check_mark: | :heavy_multiplication_x: | Used to get the digest of a manifest by tag. This is then used to pull the manifest and show the tag details in the UI. | -| [Pull manifest](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#pulling-an-image-manifest) | :heavy_check_mark: | :heavy_multiplication_x: | Used to show the image size and the manifest digest in the tag details UI. | -| [Pull blob](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#pulling-a-layer) | :heavy_check_mark: | :heavy_multiplication_x: | Used to show the configuration digest and the creation date in the tag details UI. | -| [Delete tag](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#deleting-a-tag) | :heavy_check_mark: | :heavy_check_mark: | Used to delete a tag from the UI and in background (cleanup policies). | +| [Check API version](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#api-version-check) | **{check-circle}** Yes | **{check-circle}** Yes | Used globally to ensure that the registry supports the Docker Distribution V2 API, as well as for identifying whether GitLab Rails is talking to the GitLab Container Registry or a third-party one (used to toggle features only available in the former). | +| [List repository tags](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#listing-image-tags) | **{check-circle}** Yes | **{check-circle}** Yes | Used to list and show tags in the UI. Used to list tags in the background for [cleanup policies](../../../user/packages/container_registry/#cleanup-policy) and [Geo replication](../../../administration/geo/replication/docker_registry.md). | +| [Check if manifest exists](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#existing-manifests) | **{check-circle}** Yes | **{dotted-circle}** No | Used to get the digest of a manifest by tag. This is then used to pull the manifest and show the tag details in the UI. | +| [Pull manifest](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#pulling-an-image-manifest) | **{check-circle}** Yes | **{dotted-circle}** No | Used to show the image size and the manifest digest in the tag details UI. | +| [Pull blob](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#pulling-a-layer) | **{check-circle}** Yes | **{dotted-circle}** No | Used to show the configuration digest and the creation date in the tag details UI. | +| [Delete tag](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#deleting-a-tag) | **{check-circle}** Yes | **{check-circle}** Yes | Used to delete a tag from the UI and in background (cleanup policies). | A valid authentication token is generated in GitLab Rails and embedded in all these requests before sending them to the registry. @@ -211,22 +211,22 @@ This is a list of all the registry HTTP API operations and how they depend on th | Operation | Method | Path | Requires Database | Requires Storage | Used by GitLab Rails * | |--------------------------------------------------------------------------------------------------------------------------------|----------|-----------------------------------------|-------------------|------------------|------------------------| -| [Check API version](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#api-version-check) | `GET` | `/v2/` | ✖ | ✖ | ✔ | -| [List repositories](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#listing-repositories) | `GET` | `/v2/_catalog` | ✔ | ✖ | ✖ | -| [List repository tags](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#listing-image-tags) | `GET` | `/v2/<name>/tags/list` | ✔ | ✖ | ✔ | -| [Delete tag](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#deleting-a-tag) | `DELETE` | `/v2/<name>/tags/reference/<reference>` | ✔ | ✖ | ✔ | -| [Check if manifest exists](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#existing-manifests) | `HEAD` | `/v2/<name>/manifests/<reference>` | ✔ | ✖ | ✔ | -| [Pull manifest](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#pulling-an-image-manifest) | `GET` | `/v2/<name>/manifests/<reference>` | ✔ | ✖ | ✔ | -| [Push manifest](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#pushing-an-image-manifest) | `PUT` | `/v2/<name>/manifests/<reference>` | ✔ | ✖ | ✖ | -| [Delete manifest](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#deleting-an-image) | `DELETE` | `/v2/<name>/manifests/<reference>` | ✔ | ✖ | ✖ | -| [Check if blob exists](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#existing-layers) | `HEAD` | `/v2/<name>/blobs/<digest>` | ✔ | ✖ | ✖ | -| [Pull blob](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#fetch-blob) | `GET` | `/v2/<name>/blobs/<digest>` | ✔ | ✔ | ✔ | -| [Delete blob](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#delete-blob) | `DELETE` | `/v2/<name>/blobs/<digest>` | ✔ | ✖ | ✖ | -| [Start blob upload](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#starting-an-upload) | `POST` | `/v2/<name>/blobs/uploads/` | ✔ | ✔ | ✖ | -| [Check blob upload status](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#get-blob-upload) | `GET` | `/v2/<name>/blobs/uploads/<uuid>` | ✔ | ✔ | ✖ | -| [Push blob chunk](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#chunked-upload-1) | `PATCH` | `/v2/<name>/blobs/uploads/<uuid>` | ✔ | ✔ | ✖ | -| [Complete blob upload](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#put-blob-upload) | `PUT` | `/v2/<name>/blobs/uploads/<uuid>` | ✔ | ✔ | ✖ | -| [Cancel blob upload](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#canceling-an-upload) | `DELETE` | `/v2/<name>/blobs/uploads/<uuid>` | ✔ | ✔ | ✖ | +| [Check API version](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#api-version-check) | `GET` | `/v2/` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | +| [List repositories](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#listing-repositories) | `GET` | `/v2/_catalog` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | +| [List repository tags](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#listing-image-tags) | `GET` | `/v2/<name>/tags/list` | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | +| [Delete tag](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#deleting-a-tag) | `DELETE` | `/v2/<name>/tags/reference/<reference>` | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | +| [Check if manifest exists](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#existing-manifests) | `HEAD` | `/v2/<name>/manifests/<reference>` | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | +| [Pull manifest](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#pulling-an-image-manifest) | `GET` | `/v2/<name>/manifests/<reference>` | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | +| [Push manifest](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#pushing-an-image-manifest) | `PUT` | `/v2/<name>/manifests/<reference>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | +| [Delete manifest](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#deleting-an-image) | `DELETE` | `/v2/<name>/manifests/<reference>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | +| [Check if blob exists](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#existing-layers) | `HEAD` | `/v2/<name>/blobs/<digest>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | +| [Pull blob](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#fetch-blob) | `GET` | `/v2/<name>/blobs/<digest>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | +| [Delete blob](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#delete-blob) | `DELETE` | `/v2/<name>/blobs/<digest>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | +| [Start blob upload](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#starting-an-upload) | `POST` | `/v2/<name>/blobs/uploads/` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | +| [Check blob upload status](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#get-blob-upload) | `GET` | `/v2/<name>/blobs/uploads/<uuid>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | +| [Push blob chunk](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#chunked-upload-1) | `PATCH` | `/v2/<name>/blobs/uploads/<uuid>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | +| [Complete blob upload](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#put-blob-upload) | `PUT` | `/v2/<name>/blobs/uploads/<uuid>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | +| [Cancel blob upload](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#canceling-an-upload) | `DELETE` | `/v2/<name>/blobs/uploads/<uuid>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | `*` Please refer to the [list of interactions between registry and Rails](#from-gitlab-rails-to-registry) to know why and how. diff --git a/doc/architecture/blueprints/database/scalability/patterns/img/db_terminology_v14_2.png b/doc/architecture/blueprints/database/scalability/patterns/img/db_terminology_v14_2.png Binary files differdeleted file mode 100644 index 85ba1360f06..00000000000 --- a/doc/architecture/blueprints/database/scalability/patterns/img/db_terminology_v14_2.png +++ /dev/null diff --git a/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_licenses_calls_v14_2.png b/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_licenses_calls_v14_2.png Binary files differindex f6ae995391c..ec0f6470bdd 100644 --- a/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_licenses_calls_v14_2.png +++ b/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_licenses_calls_v14_2.png diff --git a/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_licenses_fixed_v14_2.png b/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_licenses_fixed_v14_2.png Binary files differindex dcfaae230d3..40abdd1e238 100644 --- a/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_licenses_fixed_v14_2.png +++ b/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_licenses_fixed_v14_2.png diff --git a/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_readwriteratio_v14_2.png b/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_readwriteratio_v14_2.png Binary files differindex 9b85f814bc1..0aa14675b5d 100644 --- a/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_readwriteratio_v14_2.png +++ b/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_readwriteratio_v14_2.png diff --git a/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_subscriptions_reads_v14_2.png b/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_subscriptions_reads_v14_2.png Binary files differindex 4f448841e48..66f5ec4bbc1 100644 --- a/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_subscriptions_reads_v14_2.png +++ b/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_subscriptions_reads_v14_2.png diff --git a/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_subscriptions_writes_v14_2.png b/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_subscriptions_writes_v14_2.png Binary files differindex e4f5756051f..c1d0193ccf0 100644 --- a/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_subscriptions_writes_v14_2.png +++ b/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_subscriptions_writes_v14_2.png diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index 87c7af2030d..29a03fe06ab 100644 --- a/doc/ci/caching/index.md +++ b/doc/ci/caching/index.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Pipeline Execution +group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: index, concepts, howto --- @@ -37,15 +37,15 @@ can't link to files outside it. - Define artifacts per job. - Subsequent jobs in later stages of the same pipeline can use artifacts. - Different projects cannot share artifacts. - -Artifacts expire after 30 days unless you define an [expiration time](../yaml/index.md#artifactsexpire_in). -Use [dependencies](../yaml/index.md#dependencies) to control which jobs fetch the artifacts. +- Artifacts expire after 30 days by default. You can define a custom [expiration time](../yaml/index.md#artifactsexpire_in). +- The latest artifacts do not expire if [keep latest artifacts](../pipelines/job_artifacts.md#keep-artifacts-from-most-recent-successful-jobs) is enabled. +- Use [dependencies](../yaml/index.md#dependencies) to control which jobs fetch the artifacts. ## Good caching practices To ensure maximum availability of the cache, do one or more of the following: -- [Tag your runners](../runners/configure_runners.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) and use the tag on jobs +- [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 a `key`](../yaml/index.md#cachekey) that fits your workflow. For example, diff --git a/doc/ci/chatops/index.md b/doc/ci/chatops/index.md index a461147661c..a2d9cf9054d 100644 --- a/doc/ci/chatops/index.md +++ b/doc/ci/chatops/index.md @@ -7,8 +7,8 @@ type: index, concepts, howto # GitLab ChatOps **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4466) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6. -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24780) to [GitLab Free](https://about.gitlab.com/pricing/) in 11.9. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4466) in GitLab Ultimate 10.6. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24780) to GitLab Free in 11.9. GitLab ChatOps provides a method to interact with CI/CD jobs through chat services like Slack. Many organizations' discussion, collaboration, and troubleshooting takes diff --git a/doc/ci/ci_cd_for_external_repos/github_integration.md b/doc/ci/ci_cd_for_external_repos/github_integration.md index 60a939496d6..70a9c8fc775 100644 --- a/doc/ci/ci_cd_for_external_repos/github_integration.md +++ b/doc/ci/ci_cd_for_external_repos/github_integration.md @@ -29,7 +29,7 @@ repositories: 1. In GitHub, create a token: 1. Open <https://github.com/settings/tokens/new>. - 1. Create a **Personal Access Token**. + 1. Create a **Personal Access Token**. 1. Enter a **Token description** and update the scope to allow `repo` and `admin:repo_hook` so that GitLab can access your project, update commit statuses, and create a web hook to notify GitLab of new commits. @@ -57,7 +57,7 @@ To manually enable GitLab CI/CD for your repository: 1. In GitHub, create a token: 1. Open <https://github.com/settings/tokens/new>. - 1. Create a **Personal Access Token**. + 1. Create a **Personal Access Token**. 1. Enter a **Token description** and update the scope to allow `repo` so that GitLab can access your project and update commit statuses. 1. In GitLab, create a project: diff --git a/doc/ci/ci_cd_for_external_repos/index.md b/doc/ci/ci_cd_for_external_repos/index.md index 27c808791e5..365e2ee31de 100644 --- a/doc/ci/ci_cd_for_external_repos/index.md +++ b/doc/ci/ci_cd_for_external_repos/index.md @@ -7,7 +7,7 @@ type: index, howto # GitLab CI/CD for external repositories **(PREMIUM)** ->[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4642) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.6. +>[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4642) in GitLab 10.6. GitLab CI/CD can be used with: @@ -38,7 +38,7 @@ To connect to an external repository: ## Pipelines for external pull requests -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/65139) in GitLab Premium 12.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/65139) in GitLab 12.3. When using GitLab CI/CD with an [external repository on GitHub](github_integration.md), it's possible to run a pipeline in the context of a Pull Request. diff --git a/doc/ci/cloud_deployment/index.md b/doc/ci/cloud_deployment/index.md index a4b4fd9fd16..25b87366a30 100644 --- a/doc/ci/cloud_deployment/index.md +++ b/doc/ci/cloud_deployment/index.md @@ -95,7 +95,7 @@ GitLab provides a series of [CI templates that you can include in your project]( To automate deployments of your application to your [Amazon Elastic Container Service](https://aws.amazon.com/ecs/) (AWS ECS) cluster, you can `include` the `AWS/Deploy-ECS.gitlab-ci.yml` template in your `.gitlab-ci.yml` file. -GitLab also provides [Docker images](https://gitlab.com/gitlab-org/cloud-deploy/-/tree/master/aws) that can be used in your `gitlab-ci.yml` file to simplify working with AWS: +GitLab also provides [Docker images](https://gitlab.com/gitlab-org/cloud-deploy/-/tree/master/aws) that can be used in your `.gitlab-ci.yml` file to simplify working with AWS: - Use `registry.gitlab.com/gitlab-org/cloud-deploy/aws-base:latest` to use AWS CLI commands. - Use `registry.gitlab.com/gitlab-org/cloud-deploy/aws-ecs:latest` to deploy your application to AWS ECS. diff --git a/doc/ci/directed_acyclic_graph/index.md b/doc/ci/directed_acyclic_graph/index.md index d965d4b83f9..11ba1e40b3e 100644 --- a/doc/ci/directed_acyclic_graph/index.md +++ b/doc/ci/directed_acyclic_graph/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Directed Acyclic Graph +# Directed Acyclic Graph **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47063) in GitLab 12.2. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/206902) in GitLab 12.10. diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index c56bc9a4dc8..d5adedc611c 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -23,7 +23,7 @@ To enable Docker commands for your CI/CD jobs, you can use: - [Docker socket binding](#use-docker-socket-binding) If you don't want to execute a runner in privileged mode, -but want to use `docker build`, you can also [use kaniko](using_kaniko.md). +but want to use `docker build`, you can also use [`kaniko`](using_kaniko.md) or [`buildah`](https://github.com/containers/buildah). If you are using shared runners on GitLab.com, [learn more about how these runners are configured](../runners/index.md). diff --git a/doc/ci/enable_or_disable_ci.md b/doc/ci/enable_or_disable_ci.md index 421bca9e324..65c907b8e7b 100644 --- a/doc/ci/enable_or_disable_ci.md +++ b/doc/ci/enable_or_disable_ci.md @@ -7,34 +7,33 @@ type: howto # How to enable or disable GitLab CI/CD **(FREE)** -To effectively use GitLab CI/CD, you need: +To use GitLab CI/CD, you need: - A valid [`.gitlab-ci.yml`](yaml/index.md) file present at the root directory of your project. -- A [runner](runners/index.md) properly set up. +- A [runner](runners/index.md) ready to run jobs. You can read our [quick start guide](quick_start/index.md) to get you started. -If you are using an external CI/CD server like Jenkins or Drone CI, it is advised -to disable GitLab CI/CD in order to not have any conflicts with the commits status +If you use an external CI/CD server like Jenkins or Drone CI, you can +disable GitLab CI/CD to avoid conflicts with the commits status API. -GitLab CI/CD is exposed by using the `/pipelines` and `/jobs` pages of a project. -Disabling GitLab CI/CD in a project does not delete any previous jobs. -In fact, the `/pipelines` and `/jobs` pages can still be accessed, although -it's hidden from the left sidebar menu. +GitLab CI/CD is enabled by default on all new projects. You can: -GitLab CI/CD is enabled by default on new installations and can be disabled -either: +- Disable GitLab CI/CD [under each project's settings](#enable-cicd-in-a-project). +- Set GitLab CI/CD to be [disabled in all new projects on an instance](../administration/cicd.md). -- Individually under each project's settings. -- Site-wide by modifying the settings in `gitlab.yml` and `gitlab.rb` for source - and Omnibus installations respectively. +If you disable GitLab CI/CD in a project: -This only applies to pipelines run as part of GitLab CI/CD. This doesn't enable or disable -pipelines that are run from an [external integration](../user/project/integrations/overview.md#integrations-listing). +- The **CI/CD** item in the left sidebar is removed. +- The `/pipelines` and `/jobs` pages are no longer available. +- Existing jobs and pipelines are not deleted. Re-enable CI/CD to access them again. -## Per-project user setting +The project or instance settings do not enable or disable pipelines run in an +[external integration](../user/project/integrations/overview.md#integrations-listing). + +## Enable CI/CD in a project To enable or disable GitLab CI/CD pipelines in your project: @@ -51,54 +50,6 @@ To enable or disable GitLab CI/CD pipelines in your project: Press **Save changes** for the settings to take effect. -## Make GitLab CI/CD disabled by default in new projects - -You can set GitLab CI/CD to be disabled by default in all new projects by modifying the settings in: - -- `gitlab.yml` for source installations. -- `gitlab.rb` for Omnibus GitLab installations. - -Existing projects that already had CI/CD enabled are unchanged. Also, this setting only changes -the project default, so project owners can still enable CI/CD in the project settings. - -For installations from source: - -1. Open `gitlab.yml` with your editor and set `builds` to `false`: - - ```yaml - ## Default project features settings - default_projects_features: - issues: true - merge_requests: true - wiki: true - snippets: false - builds: false - ``` - -1. Save the `gitlab.yml` file. - -1. Restart GitLab: - - ```shell - sudo service gitlab restart - ``` - -For Omnibus GitLab installations: - -1. Edit `/etc/gitlab/gitlab.rb` and add this line: - - ```ruby - gitlab_rails['gitlab_default_projects_features_builds'] = false - ``` - -1. Save the `/etc/gitlab/gitlab.rb` file. - -1. Reconfigure GitLab: - - ```shell - sudo gitlab-ctl reconfigure - ``` - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/ci/environments/deployment_safety.md b/doc/ci/environments/deployment_safety.md index 4e34cc7ce38..1b34b520007 100644 --- a/doc/ci/environments/deployment_safety.md +++ b/doc/ci/environments/deployment_safety.md @@ -136,10 +136,10 @@ connect the CD project to your development projects by using [multi-project pipe A `.gitlab-ci.yml` may contain rules to deploy an application to the production server. This deployment usually runs automatically after pushing a merge request. To prevent developers from -changing the `gitlab-ci.yml`, you can define it in a different repository. The configuration can +changing the `.gitlab-ci.yml`, you can define it in a different repository. The configuration can reference a file in another project with a completely different set of permissions (similar to [separating a project for deployments](#separate-project-for-deployments)). -In this scenario, the `gitlab-ci.yml` is publicly accessible, but can only be edited by users with +In this scenario, the `.gitlab-ci.yml` is publicly accessible, but can only be edited by users with appropriate permissions in the other project. For more information, see [Custom CI/CD configuration path](../pipelines/settings.md#specify-a-custom-cicd-configuration-file). diff --git a/doc/ci/environments/environments_dashboard.md b/doc/ci/environments/environments_dashboard.md index ae459b9016c..8ff31827ae7 100644 --- a/doc/ci/environments/environments_dashboard.md +++ b/doc/ci/environments/environments_dashboard.md @@ -7,7 +7,7 @@ type: reference # Environments Dashboard **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3713) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3713) in GitLab 12.5. The Environments Dashboard provides a cross-project environment-based view that lets you see the big picture diff --git a/doc/ci/environments/incremental_rollouts.md b/doc/ci/environments/incremental_rollouts.md index e473d52f957..bc52fd1f16c 100644 --- a/doc/ci/environments/incremental_rollouts.md +++ b/doc/ci/environments/incremental_rollouts.md @@ -43,7 +43,7 @@ number of pods that are defined for the deployment, which are configured when th cluster is created. For example, if your application has 10 pods and a 10% rollout job runs, the new instance of the -application is deployed to a single pod while the remaining nine are present the previous instance. +application is deployed to a single pod while the rest of the pods show the previous instance of the application. First we [define the template as manual](https://gitlab.com/gl-release/incremental-rollout-example/blob/master/.gitlab-ci.yml#L100-103): @@ -135,5 +135,5 @@ to switch to a different deployment. Both deployments are running in parallel, a can be switched to at any time. An [example deployable application](https://gitlab.com/gl-release/blue-green-example) -is available, with a [`gitlab-ci.yml` CI/CD configuration file](https://gitlab.com/gl-release/blue-green-example/blob/master/.gitlab-ci.yml) +is available, with a [`.gitlab-ci.yml` CI/CD configuration file](https://gitlab.com/gl-release/blue-green-example/blob/master/.gitlab-ci.yml) that demonstrates blue-green deployments. diff --git a/doc/ci/environments/index.md b/doc/ci/environments/index.md index 1b4d8890c6e..6bac004fcdf 100644 --- a/doc/ci/environments/index.md +++ b/doc/ci/environments/index.md @@ -99,7 +99,7 @@ deploy_review: script: - echo "Deploy a review app" environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG url: https://$CI_ENVIRONMENT_SLUG.example.com rules: - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH @@ -109,9 +109,9 @@ deploy_review: In this example: -- The `name` is `review/$CI_COMMIT_REF_NAME`. Because the [environment name](../yaml/index.md#environmentname) +- 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_NAME`, but because this value +- 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. @@ -177,7 +177,7 @@ You can find the play button in the pipelines, environments, deployments, and jo If you are deploying to a [Kubernetes cluster](../../user/project/clusters/index.md) associated with your project, you can configure these deployments from your -`gitlab-ci.yml` file. +`.gitlab-ci.yml` file. NOTE: Kubernetes configuration isn't supported for Kubernetes clusters that are @@ -385,7 +385,7 @@ deploy_review: script: - echo "Deploy a review app" environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG url: https://$CI_ENVIRONMENT_SLUG.example.com on_stop: stop_review rules: @@ -396,7 +396,7 @@ stop_review: script: - echo "Remove review app" environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG action: stop rules: - if: $CI_MERGE_REQUEST_ID @@ -440,7 +440,7 @@ is created or updated. The environment runs until `stop_review_app` is executed: review_app: script: deploy-review-app environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG on_stop: stop_review_app auto_stop_in: 1 week rules: @@ -449,7 +449,7 @@ review_app: stop_review_app: script: stop-review-app environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG action: stop rules: - if: $CI_MERGE_REQUEST_ID @@ -538,7 +538,7 @@ then in the UI, the environments are grouped under that heading:  The following example shows how to start your environment names with `review`. -The `$CI_COMMIT_REF_NAME` variable is populated with the branch name at runtime: +The `$CI_COMMIT_REF_SLUG` variable is populated with the branch name at runtime: ```yaml deploy_review: @@ -546,7 +546,7 @@ deploy_review: script: - echo "Deploy a review app" environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG ``` ### Environment incident management @@ -566,7 +566,7 @@ to get alerts when there are critical issues that need immediate attention. #### View the latest alerts for environments **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214634) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214634) in GitLab 13.4. If you [set up alerts for Prometheus metrics](../../operations/metrics/alerts.md), alerts for environments are shown on the environments page. The alert with the highest @@ -582,7 +582,7 @@ deployment tab from the environment page and select which deployment to roll bac #### Auto Rollback **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35404) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35404) in GitLab 13.7. In a typical Continuous Deployment workflow, the CI pipeline tests every commit before deploying to production. However, problematic code can still make it to production. For example, inefficient code @@ -682,9 +682,9 @@ fetch = +refs/environments/*:refs/remotes/origin/environments/* ### Scope environments with specs -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2112) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.4. -> - [Environment scoping for CI/CD variables was moved to all tiers](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30779) in GitLab 12.2. -> - [Environment scoping for Group CI/CD variables](https://gitlab.com/gitlab-org/gitlab/-/issues/2874) added to GitLab Premium in 13.11. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2112) in GitLab Premium 9.4. +> - Environment scoping for CI/CD variables was [moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30779) from GitLab Premium to GitLab Free in 12.2. +> - Environment scoping for Group CI/CD variables [added](https://gitlab.com/gitlab-org/gitlab/-/issues/2874) to GitLab Premium in 13.11. You can limit the environment scope of a CI/CD variable by defining which environments it can be available for. @@ -728,11 +728,24 @@ like [Review Apps](../review_apps/index.md) (`review/*`). The most specific spec takes precedence over the other wildcard matching. In this case, 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 an environment through the UI is not possible. +Instead, you need to delete the old environment and create a new one: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Deployments > Environments**. +1. Find the environment and stop it. +1. Delete the environment. +1. Create a new environment with your preferred name. + ## Related topics - [Use GitLab CI to deploy to multiple environments (blog post)](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/) - [Review Apps](../review_apps/index.md): Use dynamic environments to deploy your code for every branch. -- [Deploy Boards](../../user/project/deploy_boards.md): View the status of your applications running on Kubernetes. +- [Deploy boards](../../user/project/deploy_boards.md): View the status of your applications running on Kubernetes. - [Protected environments](protected_environments.md): Determine who can deploy code to your environments. - [Environments Dashboard](../environments/environments_dashboard.md): View a summary of each environment's operational health. **(PREMIUM)** @@ -763,14 +776,14 @@ To ensure the `action: stop` can always run when needed, you can: deploy_review: stage: deploy environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG url: https://$CI_ENVIRONMENT_SLUG.example.com on_stop: stop_review stop_review: stage: deploy environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG action: stop when: manual ``` @@ -790,7 +803,7 @@ To ensure the `action: stop` can always run when needed, you can: deploy_review: stage: deploy environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG url: https://$CI_ENVIRONMENT_SLUG.example.com on_stop: stop_review @@ -799,7 +812,7 @@ To ensure the `action: stop` can always run when needed, you can: needs: - deploy_review environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG action: stop when: manual ``` diff --git a/doc/ci/environments/protected_environments.md b/doc/ci/environments/protected_environments.md index 3cd4ebdbdf1..b31e51b35fc 100644 --- a/doc/ci/environments/protected_environments.md +++ b/doc/ci/environments/protected_environments.md @@ -7,7 +7,7 @@ type: concepts, howto # Protected environments **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6303) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6303) in GitLab 11.3. [Environments](../environments/index.md) can be used for different reasons: @@ -157,15 +157,9 @@ For more information, see [Deployment safety](deployment_safety.md). ## Group-level protected environments -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215888) in [GitLab Premium](https://about.gitlab.com/pricing/) 14.0. -> - [Deployed behind a feature flag](../../user/feature_flags.md), disabled by default. -> - Disabled on GitLab.com. -> - Not recommended for production use. -> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-group-level-protected-environments). **(FREE SELF)** - -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. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215888) in GitLab 14.0. [Deployed behind the `group_level_protected_environments` flag](../../administration/feature_flags.md), disabled by default. +> - [Feature flag `group_level_protected_environments`](https://gitlab.com/gitlab-org/gitlab/-/issues/331085) removed in GitLab 14.3. +> - [Generally Available](https://gitlab.com/gitlab-org/gitlab/-/issues/331085) on GitLab and on GitLab.com in 14.3. Typically, large enterprise organizations have an explicit permission boundary between [developers and operators](https://about.gitlab.com/topics/devops/). @@ -251,7 +245,7 @@ To protect a group-level environment: 1. Make sure your environments have the correct [`deployment_tier`](index.md#deployment-tier-of-environments) defined in - `gitlab-ci.yml`. + `.gitlab-ci.yml`. 1. Configure the group-level protected environments via the [REST API](../../api/group_protected_environments.md). @@ -259,25 +253,6 @@ NOTE: Configuration [via the UI](https://gitlab.com/gitlab-org/gitlab/-/issues/325249) is scheduled for a later release. -### Enable or disable Group-level protected environments **(FREE SELF)** - -Group-level protected environments is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can enable it. - -To enable it: - -```ruby -Feature.enable(:group_level_protected_environments) -``` - -To disable it: - -```ruby -Feature.disable(:group_level_protected_environments) -``` - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/ci/examples/end_to_end_testing_webdriverio/index.md b/doc/ci/examples/end_to_end_testing_webdriverio/index.md index 7a6d692cd43..06074d6edc2 100644 --- a/doc/ci/examples/end_to_end_testing_webdriverio/index.md +++ b/doc/ci/examples/end_to_end_testing_webdriverio/index.md @@ -11,7 +11,7 @@ description: 'Confidence checking your entire app every time a new feature is ad <!-- vale off --> -# End-to-end testing with GitLab CI/CD and WebdriverIO +# End-to-end testing with GitLab CI/CD and WebdriverIO **(FREE)** [Review Apps](../../review_apps/index.md) are great: for every merge request (or branch, for that matter), the new code can be copied and deployed to a fresh production-like live @@ -20,7 +20,7 @@ environment, reducing the effort to assess the impact of changes. Thus, when we and it will immediately be clear that the application can still be properly built and deployed. After all, you can _see_ it running! -<img src="img/deployed_dependency_update.png" alt="dependencies.io"> + However, looking at the freshly deployed code to check whether it still looks and behaves as expected is repetitive manual work, which means it is a prime candidate for automation. This is diff --git a/doc/ci/examples/index.md b/doc/ci/examples/index.md index 0569bb281b9..2c2c6ecd30f 100644 --- a/doc/ci/examples/index.md +++ b/doc/ci/examples/index.md @@ -6,7 +6,7 @@ comments: false type: index --- -# GitLab CI/CD Examples +# GitLab CI/CD Examples **(FREE)** This page contains links to a variety of examples that can help you understand how to implement [GitLab CI/CD](../README.md) for your specific use case. @@ -33,7 +33,7 @@ The following table lists examples with step-by-step tutorials that are containe | npm with semantic-release | [Publish npm packages to the GitLab Package Registry using semantic-release](semantic-release.md). | | PHP with Laravel, Envoy | [Test and deploy Laravel applications with GitLab CI/CD and Envoy](laravel_with_gitlab_and_envoy/index.md). | | PHP with npm, SCP | [Running Composer and npm scripts with deployment via SCP in GitLab CI/CD](deployment/composer-npm-deploy.md). | -| PHP with PHPunit, `atoum` | [Testing PHP projects](php.md). | +| PHP with PHPunit, `atoum` | [Testing PHP projects](php.md). | | Secrets management with Vault | [Authenticating and Reading Secrets With HashiCorp Vault](authenticating-with-hashicorp-vault/index.md). | ### Contributed examples @@ -58,7 +58,7 @@ separate example projects: Get started with GitLab CI/CD and your favorite programming language or framework by using a `.gitlab-ci.yml` [template](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates). -When you create a `gitlab-ci.yml` file in the UI, you can +When you create a `.gitlab-ci.yml` file in the UI, you can choose one of these templates: - [Android (`Android.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Android.gitlab-ci.yml) @@ -76,7 +76,7 @@ choose one of these templates: - [dotNET Core (`dotNET-Core.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/dotNET-Core.gitlab-ci.yml) - [Elixir (`Elixir.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Elixir.gitlab-ci.yml) - [Flutter (`Flutter.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Flutter.gitlab-ci.yml) -- [goLang (`Go.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Go.gitlab-ci.yml) +- [Golang (`Go.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Go.gitlab-ci.yml) - [Gradle (`Gradle.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Gradle.gitlab-ci.yml) - [Grails (`Grails.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Grails.gitlab-ci.yml) - [iOS with fastlane (`iOS-Fastlane.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/iOS-Fastlane.gitlab-ci.yml) @@ -117,15 +117,16 @@ Note that older articles and videos may not reflect the state of the latest GitL For examples of setting up GitLab CI/CD for cloud-based environments, see: - [How to set up multi-account AWS SAM deployments with GitLab CI](https://about.gitlab.com/blog/2019/02/04/multi-account-aws-sam-deployments-with-gitlab-ci/) -- [Automating Kubernetes Deployments with GitLab CI/CD](https://www.youtube.com/watch?v=wEDRfAz6_Uw) +- Video: [Automating Kubernetes Deployments with GitLab CI/CD](https://www.youtube.com/watch?v=wEDRfAz6_Uw) - [How to autoscale continuous deployment with GitLab Runner on DigitalOcean](https://about.gitlab.com/blog/2018/06/19/autoscale-continuous-deployment-gitlab-runner-digital-ocean/) - [How to create a CI/CD pipeline with Auto Deploy to Kubernetes using GitLab and Helm](https://about.gitlab.com/blog/2017/09/21/how-to-create-ci-cd-pipeline-with-autodeploy-to-kubernetes-using-gitlab-and-helm/) -- [Demo - Deploying from GitLab to OpenShift Container Cluster](https://youtu.be/EwbhA53Jpp4) +- Video: [Demo - Deploying from GitLab to OpenShift Container Cluster](https://youtu.be/EwbhA53Jpp4) +- Tutorial: [Set up a GitLab.com Civo Kubernetes integration with GitPod](https://gitlab.com/k33g_org/k33g_org.gitlab.io/-/issues/82) See also the following video overviews: -- [Kubernetes, GitLab, and Cloud Native](https://www.youtube.com/watch?v=d-9awBxEbvQ). -- [Deploying to IBM Cloud with GitLab CI/CD](https://www.youtube.com/watch?v=6ZF4vgKMd-g). +- Video: [Kubernetes, GitLab, and Cloud Native](https://www.youtube.com/watch?v=d-9awBxEbvQ) +- Video: [Deploying to IBM Cloud with GitLab CI/CD](https://www.youtube.com/watch?v=6ZF4vgKMd-g) ### Customer stories @@ -160,7 +161,9 @@ For examples of others who have implemented GitLab CI/CD, see: ### Migrating to GitLab from third-party CI tools -- [Migrating from Jenkins to GitLab](https://youtu.be/RlEVGOpYF5Y) +- [Migrating from CircleCI to GitLab](../migration/circleci.md) +- [Migrating from Jenkins to GitLab](../migration/jenkins.md) +- Video: [Migrating from Jenkins to GitLab](https://youtu.be/RlEVGOpYF5Y) ### Integrating GitLab CI/CD with other systems diff --git a/doc/ci/index.md b/doc/ci/index.md index 9175c20f580..87b259af62a 100644 --- a/doc/ci/index.md +++ b/doc/ci/index.md @@ -9,33 +9,23 @@ type: index # GitLab CI/CD **(FREE)** -GitLab CI/CD is a tool built into GitLab for software development -through the [continuous methodologies](introduction/index.md): +GitLab CI/CD is a tool for software development using the continuous methodologies: -- Continuous Integration (CI) -- Continuous Delivery (CD) -- Continuous Deployment (CD) +- [Continuous Integration (CI)](introduction/index.md#continuous-integration) +- [Continuous Delivery (CD)](introduction/index.md#continuous-delivery) +- [Continuous Deployment (CD)](introduction/index.md#continuous-deployment) NOTE: Out-of-the-box management systems can decrease hours spent on maintaining toolchains by 10% or more. Watch our ["Mastering continuous software development"](https://about.gitlab.com/webcast/mastering-ci-cd/) -webcast to learn about continuous methods and how the GitLab built-in CI can help you simplify and scale software development. +webcast to learn about continuous methods and how GitLab CI/CD can help you simplify and scale software development. -Continuous Integration works by pushing small code chunks to your -application's codebase hosted in a Git repository, and to every -push, run a pipeline of scripts to build, test, and validate the -code changes before merging them into the main branch. - -Continuous Delivery and Deployment consist of a step further CI, -deploying your application to production at every -push to the default branch of the repository. - -These methodologies allow you to catch bugs and errors early in -the development cycle, ensuring that all the code deployed to +Use GitLab CI/CD to catch bugs and errors early in +the development cycle. Ensure that all the code deployed to production complies with the code standards you established for your app. -GitLab can also automatically detect, build, test, deploy, and +GitLab CI/CD can automatically build, test, deploy, and monitor your applications by using [Auto DevOps](../topics/autodevops/index.md). For a complete overview of these methodologies and GitLab CI/CD, @@ -48,7 +38,7 @@ read the [Introduction to CI/CD with GitLab](introduction/index.md). <iframe src="https://www.youtube.com/embed/1iXFbchozdY" frameborder="0" allowfullscreen="true"> </iframe> </figure> -## Concepts +## GitLab CI/CD concepts GitLab CI/CD uses a number of concepts to describe and run your build and deploy. @@ -63,7 +53,7 @@ GitLab CI/CD uses a number of concepts to describe and run your build and deploy | [Pipeline efficiency](pipelines/pipeline_efficiency.md) | Configure your pipelines to run quickly and efficiently. | | [Test cases](test_cases/index.md) | Create testing scenarios. | -## Configuration +## GitLab CI/CD configuration GitLab CI/CD supports numerous configuration options: @@ -82,21 +72,20 @@ GitLab CI/CD supports numerous configuration options: Certain operations can only be performed according to the [user](../user/permissions.md#gitlab-cicd-permissions) and [job](../user/permissions.md#job-permissions) permissions. -## Feature set +## GitLab CI/CD features -Use the vast GitLab CI/CD to easily configure it for specific purposes. -Its feature set is listed on the table below according to DevOps stages. +GitLab CI/CD features, grouped by DevOps stage, include: | Feature | Description | |:------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------| | **Configure** | | | [Auto DevOps](../topics/autodevops/index.md) | Set up your app's entire lifecycle. | -| [ChatOps](chatops/index.md) | Trigger CI jobs from chat, with results sent back to the channel. | +| [ChatOps](chatops/index.md) | Trigger CI jobs from chat, with results sent back to the channel. | |-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------| | **Verify** | | | [Browser Performance Testing](../user/project/merge_requests/browser_performance_testing.md) | Quickly determine the browser performance impact of pending code changes. | | [Load Performance Testing](../user/project/merge_requests/load_performance_testing.md) | Quickly determine the server performance impact of pending code changes. | -| [CI services](services/index.md) | Link Docker containers with your base image. | +| [CI services](services/index.md) | Link Docker containers with your base image. | | [Code Quality](../user/project/merge_requests/code_quality.md) | Analyze your source code quality. | | [GitLab CI/CD for external repositories](ci_cd_for_external_repos/index.md) **(PREMIUM)** | Get the benefits of GitLab CI/CD combined with repositories in GitHub and Bitbucket Cloud. | | [Interactive Web Terminals](interactive_web_terminal/index.md) **(FREE SELF)** | Open an interactive web terminal to debug the running jobs. | @@ -107,7 +96,7 @@ Its feature set is listed on the table below according to DevOps stages. | [Auto Deploy](../topics/autodevops/stages.md#auto-deploy) | Deploy your application to a production environment in a Kubernetes cluster. | | [Building Docker images](docker/using_docker_build.md) | Maintain Docker-based projects using GitLab CI/CD. | | [Canary Deployments](../user/project/canary_deployments.md) | Ship features to only a portion of your pods and let a percentage of your user base to visit the temporarily deployed feature. | -| [Deploy Boards](../user/project/deploy_boards.md) | Check the current health and status of each CI/CD environment running on Kubernetes. | +| [Deploy boards](../user/project/deploy_boards.md) | Check the current health and status of each CI/CD environment running on Kubernetes. | | [Feature Flags](../operations/feature_flags.md) **(PREMIUM)** | Deploy your features behind Feature Flags. | | [GitLab Pages](../user/project/pages/index.md) | Deploy static websites. | | [GitLab Releases](../user/project/releases/index.md) | Add release notes to Git tags. | @@ -120,29 +109,29 @@ Its feature set is listed on the table below according to DevOps stages. | [License Compliance](../user/compliance/license_compliance/index.md) **(ULTIMATE)** | Search your project dependencies for their licenses. | | [Security Test reports](../user/application_security/index.md) **(ULTIMATE)** | Check for app vulnerabilities. | -## Examples +## GitLab CI/CD examples -Find example project code and tutorials for using GitLab CI/CD with a variety of app frameworks, languages, and platforms -on the [CI Examples](examples/README.md) page. +See the [CI/CD examples](examples/README.md) page for example project code and tutorials for +using GitLab CI/CD with various: -## Administration **(FREE SELF)** +- App frameworks +- Languages +- Platforms -As a GitLab administrator, you can change the default behavior -of GitLab CI/CD for: +## GitLab CI/CD Administration -- An [entire GitLab instance](../user/admin_area/settings/continuous_integration.md). -- Specific projects, using [pipelines settings](pipelines/settings.md). +You can change the default behavior of GitLab CI/CD for: + +- An entire GitLab instance in the [CI/CD administration settings](../administration/index.md#cicd-settings). +- Specific projects in the [pipelines settings](pipelines/settings.md). See also: -- [How to enable or disable GitLab CI/CD](enable_or_disable_ci.md). -- Other [CI administration settings](../administration/index.md#continuous-integration-settings). +- [Enable or disable GitLab CI/CD in a project](enable_or_disable_ci.md). ## References -### Why GitLab CI/CD? - -Learn more about: +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/). @@ -150,10 +139,10 @@ Learn more about: See also the [Why CI/CD?](https://docs.google.com/presentation/d/1OGgk2Tcxbpl7DJaIOzCX4Vqg3dlwfELC3u2jEeCBbDk) presentation. -### Breaking changes +### Major version changes (breaking) As GitLab CI/CD has evolved, certain breaking changes have -been necessary. These are: +been necessary. #### 13.0 diff --git a/doc/ci/interactive_web_terminal/index.md b/doc/ci/interactive_web_terminal/index.md index 7e72bd44503..5724c56b096 100644 --- a/doc/ci/interactive_web_terminal/index.md +++ b/doc/ci/interactive_web_terminal/index.md @@ -5,12 +5,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Interactive Web Terminals +# Interactive Web Terminals **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/50144) in GitLab 11.3. Interactive web terminals give the user access to a terminal in GitLab for -running one-off commands for their CI pipeline. Since this is giving the user +running one-off commands for their CI pipeline. You can think of it like a method for +debugging with SSH, but done directly from the job page. Since this is giving the user shell access to the environment where [GitLab Runner](https://docs.gitlab.com/runner/) is deployed, some [security precautions](../../administration/integration/terminal.md#security) were taken to protect the users. diff --git a/doc/ci/jobs/ci_job_token.md b/doc/ci/jobs/ci_job_token.md new file mode 100644 index 00000000000..70c22d566e5 --- /dev/null +++ b/doc/ci/jobs/ci_job_token.md @@ -0,0 +1,165 @@ +--- +stage: Verify +group: Pipeline Execution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# GitLab CI/CD job token + +When a pipeline job is about to run, GitLab generates a unique token and injects it as the +[`CI_JOB_TOKEN` predefined variable](../variables/predefined_variables.md). + +You can use a GitLab CI/CD job token to authenticate with specific API endpoints: + +- Packages: + - [Package Registry](../../user/packages/package_registry/index.md). To push to the + Package Registry, you can use [deploy tokens](../../user/project/deploy_tokens/index.md). + - [Container Registry](../../user/packages/container_registry/index.md) + (the `$CI_REGISTRY_PASSWORD` is `$CI_JOB_TOKEN`). + - [Container Registry API](../../api/container_registry.md) + (scoped to the job's project, when the `ci_job_token_scope` feature flag is enabled). +- [Get job artifacts](../../api/job_artifacts.md#get-job-artifacts). +- [Get job token's job](../../api/jobs.md#get-job-tokens-job). +- [Pipeline triggers](../../api/pipeline_triggers.md), using the `token=` parameter. +- [Release creation](../../api/releases/index.md#create-a-release). +- [Terraform plan](../../user/infrastructure/index.md). + +The token has the same permissions to access the API as the user that triggers the +pipeline. Therefore, this user must be assigned to [a role that has the required privileges](../../user/permissions.md#gitlab-cicd-permissions). + +The token is valid only while the pipeline job runs. After the job finishes, you can't +use the token anymore. + +A job token can access a project's resources without any configuration, but it might +give extra permissions that aren't necessary. There is [a proposal](https://gitlab.com/groups/gitlab-org/-/epics/3559) +to redesign the feature for more strategic control of the access permissions. + +You can also use the job token to authenticate and clone a repository from a private project +in a CI/CD job: + +```shell +git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.example.com/<namespace>/<project> +``` + +## GitLab CI/CD job token security + +To make sure that this token doesn't leak, GitLab: + +- Masks the job token in job logs. +- Grants permissions to the job token only when the job is running. + +To make sure that this token doesn't leak, you should also configure +your [runners](../runners/index.md) to be secure. Avoid: + +- Using Docker's `privileged` mode if the machines are re-used. +- Using the [`shell` executor](https://docs.gitlab.com/runner/executors/shell.html) when jobs + run on the same machine. + +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 + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328553) in GitLab 14.1. +> - [Deployed behind a feature flag](../../user/feature_flags.md), disabled by default. +> - Disabled on GitLab.com. +> - Not recommended for production use. +> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-ci-job-token-scope-limit). **(FREE SELF)** + +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. + +You can limit the access scope of a project's CI/CD job token to increase the +job token's security. A job token might give extra permissions that aren't necessary +to access specific private resources. Limiting the job token access scope reduces the risk of a leaked +token being used to access private data that the user associated to the job can access. + +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. +Other projects can be added and removed by maintainers with access to both projects. + +This setting is enabled by default for all new projects, and disabled by default in projects +created before GitLab 14.1. It is strongly recommended that project maintainers enable this +setting at all times, and configure the allowlist for cross-project access if needed. + +For example, when the setting is enabled, jobs in a pipeline in project `A` have +a `CI_JOB_TOKEN` scope limited to project `A`. If the job needs to use the token +to make an API request to a private project `B`, then `B` must be added to the allowlist for `A`. +If project `B` is public or internal, it doesn't need to be added to the allowlist. +The job token scope is only for controlling access to private projects. + +To enable and configure the job token scope limit: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Token Access**. +1. Toggle **Limit CI_JOB_TOKEN access** to enabled. +1. (Optional) Add existing projects to the token's access scope. The user adding a + project must have the [maintainer role](../../user/permissions.md) in both projects. + +If the job token scope limit is disabled, the token can potentially be used to authenticate +API requests to all projects accessible to the user that triggered the job. + +There is [a proposal](https://gitlab.com/groups/gitlab-org/-/epics/3559) to improve +the feature with more strategic control of the access permissions. + +### Enable or disable CI job token scope limit **(FREE SELF)** + +The GitLab CI/CD job token access scope limit is under development and not ready for production +use. It is deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:ci_scoped_job_token) +``` + +To disable it: + +```ruby +Feature.disable(:ci_scoped_job_token) +``` + +## Trigger a multi-project pipeline by using a CI job token + +> `CI_JOB_TOKEN` for multi-project pipelines was [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/31573) from GitLab Premium to GitLab Free in 12.4. + +You can use the `CI_JOB_TOKEN` to trigger [multi-project pipelines](../pipelines/multi_project_pipelines.md) +from a CI/CD job. A pipeline triggered this way creates a dependent pipeline relation +that is visible on the [pipeline graph](../pipelines/multi_project_pipelines.md#multi-project-pipeline-visualization). + +For example: + +```yaml +trigger_pipeline: + stage: deploy + script: + - curl --request POST --form "token=$CI_JOB_TOKEN" --form ref=main "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" + rules: + - if: $CI_COMMIT_TAG +``` + +If you use the `CI_PIPELINE_SOURCE` [predefined CI/CD variable](../variables/predefined_variables.md) +in a pipeline triggered this way, [the value is `pipeline` (not `triggered`)](../triggers/index.md#authentication-tokens). + +## 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. + +You can use the `CI_JOB_TOKEN` to access artifacts from a job created by a previous +pipeline. You must specify which job you want to retrieve the artifacts from: + +```yaml +build_submodule: + stage: test + script: + - apt update && apt install -y unzip + - curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/download?job=test&job_token=$CI_JOB_TOKEN" + - unzip artifacts.zip +``` + +Read more about the [jobs artifacts API](../../api/job_artifacts.md#download-the-artifacts-archive). diff --git a/doc/ci/jobs/img/job_group_v12_10.png b/doc/ci/jobs/img/job_group_v12_10.png Binary files differdeleted file mode 100644 index 27e6bfbfc0f..00000000000 --- a/doc/ci/jobs/img/job_group_v12_10.png +++ /dev/null diff --git a/doc/ci/jobs/img/pipeline_delayed_job_v14_2.png b/doc/ci/jobs/img/pipeline_delayed_job_v14_2.png Binary files differnew file mode 100644 index 00000000000..8dbb118406c --- /dev/null +++ b/doc/ci/jobs/img/pipeline_delayed_job_v14_2.png diff --git a/doc/ci/jobs/img/pipeline_grouped_jobs_v14_2.png b/doc/ci/jobs/img/pipeline_grouped_jobs_v14_2.png Binary files differnew file mode 100644 index 00000000000..28be633770b --- /dev/null +++ b/doc/ci/jobs/img/pipeline_grouped_jobs_v14_2.png diff --git a/doc/ci/jobs/img/pipeline_incremental_rollout.png b/doc/ci/jobs/img/pipeline_incremental_rollout.png Binary files differdeleted file mode 100644 index b3498e9a5a5..00000000000 --- a/doc/ci/jobs/img/pipeline_incremental_rollout.png +++ /dev/null diff --git a/doc/ci/jobs/img/pipelines_grouped.png b/doc/ci/jobs/img/pipelines_grouped.png Binary files differdeleted file mode 100644 index 82814754747..00000000000 --- a/doc/ci/jobs/img/pipelines_grouped.png +++ /dev/null diff --git a/doc/ci/jobs/index.md b/doc/ci/jobs/index.md index aa12e1181cb..54704d5574b 100644 --- a/doc/ci/jobs/index.md +++ b/doc/ci/jobs/index.md @@ -58,7 +58,7 @@ In each place, if you hover over the failed job you can see the reason it failed  -In [GitLab 10.8](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17814) and later, +In [GitLab 10.8 and later](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17814), you can also see the reason it failed on the Job detail page. ## The order of jobs in a pipeline @@ -99,7 +99,7 @@ You can recognize when a pipeline has grouped jobs if you don't see the retry or cancel button inside them. Hovering over them shows the number of grouped jobs. Click to expand them. - + To create a group of jobs, in the [CI/CD pipeline configuration file](../yaml/index.md), separate each job name with a number and one of the following: @@ -129,9 +129,7 @@ build ruby 3/3: - echo "ruby3" ``` -In the pipeline, the result is a group named `build ruby` with three jobs: - - +The pipeline graph displays a group named `build ruby` with three jobs. The jobs are ordered by comparing the numbers from left to right. You usually want the first number to be the index and the second number to be the total. @@ -179,7 +177,7 @@ For example, if you start rolling out new code and: - Users experience trouble with the new code, you can stop the timed incremental rollout by canceling the pipeline and [rolling](../environments/index.md#retry-or-roll-back-a-deployment) back to the last stable version. - + ## Expand and collapse job log sections diff --git a/doc/ci/jobs/job_control.md b/doc/ci/jobs/job_control.md index b8b05426297..ad2bbbc883c 100644 --- a/doc/ci/jobs/job_control.md +++ b/doc/ci/jobs/job_control.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Pipeline Execution +group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -225,7 +225,7 @@ check the value of the `$CI_PIPELINE_SOURCE` variable: | `pipeline` | For [multi-project pipelines](../pipelines/multi_project_pipelines.md) created by [using the API with `CI_JOB_TOKEN`](../pipelines/multi_project_pipelines.md#create-multi-project-pipelines-by-using-the-api), or the [`trigger`](../yaml/index.md#trigger) keyword. | | `push` | For pipelines triggered by a `git push` event, including for branches and tags. | | `schedule` | For [scheduled pipelines](../pipelines/schedules.md). | -| `trigger` | For pipelines created by using a [trigger token](../triggers/index.md#trigger-token). | +| `trigger` | For pipelines created by using a [trigger token](../triggers/index.md#authentication-tokens). | | `web` | For pipelines created by using **Run pipeline** button in the GitLab UI, from the project's **CI/CD > Pipelines** section. | | `webide` | For pipelines created by using the [WebIDE](../../user/project/web_ide/index.md). | @@ -290,6 +290,35 @@ You can use the `$` character for both variables and paths. For example, if the `$DOCKERFILES_DIR` variable exists, its value is used. If it does not exist, the `$` is interpreted as being part of a path. +## Reuse rules in different jobs + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322992) in GitLab 14.3. + +Use [`!reference` tags](../yaml/index.md#reference-tags) to reuse rules in different +jobs. You can combine `!reference` rules with regular job-defined rules: + +```yaml +.default_rules: + rules: + - if: $CI_PIPELINE_SOURCE == "schedule" + when: never + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH + +job1: + rules: + - !reference [.default_rules, rules] + script: + - echo "This job runs for the default branch, but not schedules." + +job2: + rules: + - !reference [.default_rules, rules] + - if: $CI_PIPELINE_SOURCE == "merge_request_event" + script: + - echo "This job runs for the default branch, but not schedules." + - echo "It also runs for merge requests." +``` + ## Specify when jobs run with `only` and `except` You can use [`only`](../yaml/index.md#only--except) and [`except`](../yaml/index.md#only--except) @@ -306,7 +335,7 @@ to control when to add jobs to pipelines. In the following example, `job` runs only for: - Git tags -- [Triggers](../triggers/index.md#trigger-token) +- [Triggers](../triggers/index.md#authentication-tokens) - [Scheduled pipelines](../pipelines/schedules.md) ```yaml diff --git a/doc/ci/large_repositories/index.md b/doc/ci/large_repositories/index.md index c3b0cd79d2c..07b4cd80d6a 100644 --- a/doc/ci/large_repositories/index.md +++ b/doc/ci/large_repositories/index.md @@ -5,11 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Optimizing GitLab for large repositories +# Optimize GitLab for large repositories **(FREE)** Large repositories consisting of more than 50k files in a worktree -often require special consideration because of -the time required to clone and check out. +may require more optimizations beyond +[pipeline efficiency](../pipelines/pipeline_efficiency.md) +because of the time required to clone and check out. GitLab and GitLab Runner handle this scenario well but require optimized configuration to efficiently perform its @@ -251,6 +252,8 @@ and does not require us to update each `.gitlab-ci.yml`. ## Pre-clone step +> [An issue exists](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/463) to remove the need for this optimization. + For very active repositories with a large number of references and files, you can also optimize your CI jobs by seeding repository data with GitLab Runner's [`pre_clone_script`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section). diff --git a/doc/ci/lint.md b/doc/ci/lint.md index 4e3ac8b9e93..e01bd6b79ff 100644 --- a/doc/ci/lint.md +++ b/doc/ci/lint.md @@ -3,11 +3,8 @@ stage: Verify group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -<!-- markdownlint-disable MD044 --> -<!-- vale gitlab.Spelling = NO --> -# Validate .gitlab-ci.yml syntax with the CI Lint tool -<!-- markdownlint-enable MD044 --> -<!-- vale gitlab.Spelling = YES --> + +# Validate `.gitlab-ci.yml` syntax with the CI Lint tool If you want to test the validity of your GitLab CI/CD configuration before committing the changes, you can use the CI Lint tool. This tool checks for syntax and logical diff --git a/doc/ci/migration/circleci.md b/doc/ci/migration/circleci.md index 106f5b3d819..efaae873588 100644 --- a/doc/ci/migration/circleci.md +++ b/doc/ci/migration/circleci.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Pipeline Execution +group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments comments: false type: index, howto @@ -121,11 +121,11 @@ stages: - test - deploy -job 1: +job1: stage: build script: make build dependencies -job 2: +job2: stage: build script: make build artifacts @@ -216,12 +216,12 @@ jobs: Example of the same workflow using `rules` in GitLab CI/CD: ```yaml -deploy_prod: +deploy: stage: deploy script: - - echo "Deploy to production server" + - echo "Deploy job" rules: - - if: '$CI_COMMIT_BRANCH == "main"' + - if: '$CI_COMMIT_BRANCH == "main" || $CI_COMMIT_BRANCH =~ /^rc-/' ``` ### Caching diff --git a/doc/ci/migration/jenkins.md b/doc/ci/migration/jenkins.md index 1a987a0ce47..925dff8751c 100644 --- a/doc/ci/migration/jenkins.md +++ b/doc/ci/migration/jenkins.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Pipeline Execution +group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments comments: false type: index, howto @@ -130,7 +130,7 @@ There are some important differences in the way runners work in comparison to ag - Runners can be set up as [shared across an instance, be added at the group level, or set up at the project level](../runners/runners_scope.md). They self-select jobs from the scopes you've defined automatically. -- You can also [use tags](../runners/configure_runners.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) for finer control, and +- You can also [use tags](../runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run) for finer control, and associate runners with specific jobs. For example, you can use a tag for jobs that require dedicated, more powerful, or specific hardware. - GitLab has [autoscaling for runners](https://docs.gitlab.com/runner/configuration/autoscale.html). @@ -199,7 +199,7 @@ GitLab takes advantage of our connected ecosystem to automatically pull these ki your Merge Requests, pipeline details pages, and other locations. You may find that you actually don't need to configure anything to have these appear. -If they aren't working as expected, or if you'd like to see what's available, our [CI feature index](../index.md#feature-set) has the full list +If they aren't working as expected, or if you'd like to see what's available, our [CI feature index](../index.md#gitlab-cicd-features) has the full list of bundled features and links to the documentation for each. ### Templates @@ -230,7 +230,7 @@ and is meant to be a mapping of concepts there to concepts in GitLab. The agent section is used to define how a pipeline executes. For GitLab, we use [runners](../runners/index.md) to provide this capability. You can configure your own runners in Kubernetes or on any host, or take advantage of our shared runner fleet (note that the shared runner fleet is only available for GitLab.com users). -We also support using [tags](../runners/configure_runners.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) to direct different jobs +We also support using [tags](../runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run) to direct different jobs to different runners (execution agents). The `agent` section also allows you to define which Docker images should be used for execution, for which we use diff --git a/doc/ci/pipeline_editor/index.md b/doc/ci/pipeline_editor/index.md index 7132d47d324..10a6d34b076 100644 --- a/doc/ci/pipeline_editor/index.md +++ b/doc/ci/pipeline_editor/index.md @@ -56,7 +56,7 @@ reflected in the CI lint. It displays the same results as the existing [CI Lint > - [Moved to **CI/CD > Editor**](https://gitlab.com/gitlab-org/gitlab/-/issues/263141) in GitLab 13.7. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/290117) in GitLab 13.12. -To view a visualization of your `gitlab-ci.yml` configuration, in your project, +To view a visualization of your `.gitlab-ci.yml` configuration, in your project, go to **CI/CD > Editor**, and then select the **Visualize** tab. The visualization shows all stages and jobs. Any [`needs`](../yaml/index.md#needs) relationships are displayed as lines connecting jobs together, showing the diff --git a/doc/ci/pipelines/img/manual_pipeline_v14_2.png b/doc/ci/pipelines/img/manual_pipeline_v14_2.png Binary files differnew file mode 100644 index 00000000000..df1c2a4760a --- /dev/null +++ b/doc/ci/pipelines/img/manual_pipeline_v14_2.png diff --git a/doc/ci/pipelines/img/pipelines.png b/doc/ci/pipelines/img/pipelines.png Binary files differdeleted file mode 100644 index a604fcb2587..00000000000 --- a/doc/ci/pipelines/img/pipelines.png +++ /dev/null diff --git a/doc/ci/pipelines/img/pipelines_graph_stage_view_v13_12.png b/doc/ci/pipelines/img/pipelines_graph_stage_view_v13_12.png Binary files differdeleted file mode 100644 index f2f38979e18..00000000000 --- a/doc/ci/pipelines/img/pipelines_graph_stage_view_v13_12.png +++ /dev/null diff --git a/doc/ci/pipelines/img/pipelines_graph_stage_view_v14_2.png b/doc/ci/pipelines/img/pipelines_graph_stage_view_v14_2.png Binary files differnew file mode 100644 index 00000000000..b0e9f63f743 --- /dev/null +++ b/doc/ci/pipelines/img/pipelines_graph_stage_view_v14_2.png diff --git a/doc/ci/pipelines/index.md b/doc/ci/pipelines/index.md index 22f18235f99..1eacc799636 100644 --- a/doc/ci/pipelines/index.md +++ b/doc/ci/pipelines/index.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Pipeline Execution +group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/ci/pipelines.html' type: reference @@ -122,6 +122,7 @@ you can filter the pipeline list by: - Branch name - Status ([GitLab 13.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/217617)) - Tag ([GitLab 13.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/217617)) +- Source ([GitLab 14.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/338347)) [Starting in GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/26621), you can change the pipeline column to display the pipeline ID or the pipeline IID. @@ -170,9 +171,6 @@ variables: You cannot set job-level variables to be pre-filled when you run a pipeline manually. -Pre-filled variables do not show up when the CI/CD configuration is [external to the project](settings.md#specify-a-custom-cicd-configuration-file). -See the [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/336184) for more details. - ### Run a pipeline by using a URL query string > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24146) in GitLab 12.5. @@ -212,11 +210,11 @@ allow you to require manual interaction before moving forward in the pipeline. You can do this straight from the pipeline graph. Just click the play button to execute that particular job. -For example, your pipeline might start automatically, but it requires manual action to -[deploy to production](../environments/index.md#configure-manual-deployments). In the example below, the `production` -stage has a job with a manual action. +For example, your pipeline can start automatically, but require a manual action to +[deploy to production](../environments/index.md#configure-manual-deployments). +In the example below, the `production` stage has a job with a manual action: - + #### Start multiple manual actions in a stage @@ -348,9 +346,9 @@ all the jobs in the pipeline. You can group the jobs by: -- Stage, which arranges jobs in the same stage together in the same column. +- Stage, which arranges jobs in the same stage together in the same column: -  +  - [Job dependencies](#view-job-dependencies-in-the-pipeline-graph), which arranges jobs based on their [`needs`](../yaml/index.md#needs) dependencies. @@ -361,21 +359,16 @@ you visualize the entire pipeline, including all cross-project inter-dependencie ### View job dependencies in the pipeline graph > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/298973) in GitLab 13.12. -> - [Deployed behind a feature flag](../../user/feature_flags.md), disabled by default. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/328538) in GitLab 13.12. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/328538) in GitLab 14.0. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/328538) in GitLab 14.2. -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. - You can arrange jobs in the pipeline graph based on their [`needs`](../yaml/index.md#needs) dependencies. Jobs in the leftmost column run first, and jobs that depend on them are grouped in the next columns. -For example, `build-job2` depends only on jobs in the first column, so it displays -in the second column from the left. `deploy-job2` depends on jobs in both the first +For example, `test-job1` depends only on jobs in the first column, so it displays +in the second column from the left. `deploy-job1` depends on jobs in both the first and second column and displays in the third column:  diff --git a/doc/ci/pipelines/multi_project_pipelines.md b/doc/ci/pipelines/multi_project_pipelines.md index 3007d91d1b4..d31ddcf736e 100644 --- a/doc/ci/pipelines/multi_project_pipelines.md +++ b/doc/ci/pipelines/multi_project_pipelines.md @@ -273,7 +273,7 @@ upstream_bridge: > [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/31573) to GitLab Free in 12.4. -When you use the [`CI_JOB_TOKEN` to trigger pipelines](../triggers/index.md#ci-job-token), +When you use the [`CI_JOB_TOKEN` to trigger pipelines](../jobs/ci_job_token.md), GitLab recognizes the source of the job token. The pipelines become related, so you can visualize their relationships on pipeline graphs. diff --git a/doc/ci/pipelines/parent_child_pipelines.md b/doc/ci/pipelines/parent_child_pipelines.md index b266a721d11..71f778d81b3 100644 --- a/doc/ci/pipelines/parent_child_pipelines.md +++ b/doc/ci/pipelines/parent_child_pipelines.md @@ -61,7 +61,8 @@ microservice_a: include: path/to/microservice_a.yml ``` -You can include multiple files when composing a child pipeline: +You can include multiple files when defining a child pipeline. The child pipeline's +configuration is composed of all configuration files merged together: ```yaml microservice_a: @@ -156,15 +157,11 @@ build a matrix of targets and architectures. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Create child pipelines using dynamically generated configurations](https://youtu.be/nMdfus2JWHM). -<!-- vale gitlab.Spelling = NO --> - We also have an example project using [Dynamic Child Pipelines with Jsonnet](https://gitlab.com/gitlab-org/project-templates/jsonnet) which shows how to use a data templating language to generate your `.gitlab-ci.yml` at runtime. You could use a similar process for other templating languages like -[Dhall](https://dhall-lang.org/) or [`ytt`](https://get-ytt.io/). - -<!-- vale gitlab.Spelling = NO --> +[Dhall](https://dhall-lang.org/) or [ytt](https://get-ytt.io/). The artifact path is parsed by GitLab, not the runner, so the path must match the syntax for the OS running GitLab. If GitLab is running on Linux but using a Windows diff --git a/doc/ci/pipelines/pipeline_efficiency.md b/doc/ci/pipelines/pipeline_efficiency.md index 91560a0420f..5c3cdd0633e 100644 --- a/doc/ci/pipelines/pipeline_efficiency.md +++ b/doc/ci/pipelines/pipeline_efficiency.md @@ -28,6 +28,7 @@ The easiest indicators to check for inefficient pipelines are the runtimes of th stages, and the total runtime of the pipeline itself. The total pipeline duration is heavily influenced by the: +- [Size of the repository](../large_repositories/index.md) - Total number of stages and jobs. - Dependencies between jobs. - The ["critical path"](#directed-acyclic-graphs-dag-visualization), which represents diff --git a/doc/ci/pipelines/settings.md b/doc/ci/pipelines/settings.md index b48c62dccc5..94d7e317104 100644 --- a/doc/ci/pipelines/settings.md +++ b/doc/ci/pipelines/settings.md @@ -124,7 +124,7 @@ If the CI/CD configuration file is on an external site, the URL must end with `. If the CI/CD configuration file is in a different project: -- The file must exist on its default branch. +- The file must exist on its default branch, or specify the branch as refname. - The path must be relative to the root directory in the other project. - The path must include the group and project name at the end. @@ -132,6 +132,7 @@ For example: - `.gitlab-ci.yml@mygroup/another-project` - `my/path/.my-custom-file.yml@mygroup/another-project` +- `my/path/.my-custom-file.yml@mygroup/another-project:refname` If the configuration file is in a separate project, you can more set more granular permissions. For example: diff --git a/doc/ci/quick_start/index.md b/doc/ci/quick_start/index.md index 257e170b0a5..e2381238318 100644 --- a/doc/ci/quick_start/index.md +++ b/doc/ci/quick_start/index.md @@ -7,8 +7,7 @@ type: reference # Get started with GitLab CI/CD **(FREE)** -Use this document to get started with -GitLab [continuous integration](https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/). +Use this document to get started with [GitLab CI/CD](../index.md). Before you start, make sure you have: @@ -126,7 +125,7 @@ The pipeline starts when the commit is committed. ```yaml default: - image: ruby:2.7.2 + image: ruby:2.7.4 ``` This command tells the runner to use a Ruby image from Docker Hub @@ -141,8 +140,22 @@ The pipeline starts when the commit is committed. [CI Lint tool](../lint.md), which is available in every project. - You can also use [CI/CD configuration visualization](../pipeline_editor/index.md#visualize-ci-configuration) to view a graphical representation of your `.gitlab-ci.yml` file. -- For the complete `.gitlab-ci.yml` syntax, see - [the `.gitlab-ci.yml` reference topic](../yaml/index.md). +- Each job contains scripts and stages: + - The [`default`](../yaml/index.md#custom-default-keyword-values) keyword is for + custom defaults, for example with [`before_script`](../yaml/index.md#before_script) + and [`after_script`](../yaml/index.md#after_script). + - [`stage`](../yaml/index.md#stage) describes the sequential execution of jobs. + Jobs in a single stage run in parallel as long as there are available runners. + - Use [Directed Acyclic Graphs (DAG)](../directed_acyclic_graph/index.md) keywords + to run jobs out of stage order. +- You can set additional configuration to customize how your jobs and stages perform: + - Use the [`rules`](../yaml/index.md#rules) keyword to specify when to run or skip jobs. + The `only` and `except` legacy keywords are still supported, but can't be used + with `rules` in the same job. + - Keep information across jobs and stages persistent in a pipeline with [`cache`](../yaml/index.md#cache)) + and [`artifacts`](../yaml/index.md#artifacts). These keywords are ways to store + dependencies and job output, even when using ephemeral runners for each job. +- For the complete `.gitlab-ci.yml` syntax, see [the full `.gitlab-ci.yml` reference topic](../yaml/index.md). ### View the status of your pipeline and jobs diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md index 8af04388f92..1b926d506c4 100644 --- a/doc/ci/review_apps/index.md +++ b/doc/ci/review_apps/index.md @@ -57,7 +57,7 @@ The process of configuring Review Apps is as follows: 1. Set up the infrastructure to host and deploy the Review Apps (check the [examples](#review-apps-examples) below). 1. [Install](https://docs.gitlab.com/runner/install/) and [configure](https://docs.gitlab.com/runner/commands/) a runner to do deployment. -1. Set up a job in `.gitlab-ci.yml` that uses the [predefined CI/CD variable](../variables/index.md) `${CI_COMMIT_REF_NAME}` +1. Set up a job in `.gitlab-ci.yml` that uses the [predefined CI/CD variable](../variables/index.md) `${CI_COMMIT_REF_SLUG}` to create dynamic environments and restrict it to run only on branches. Alternatively, you can get a YML template for this job by [enabling review apps](#enable-review-apps-button) for your project. 1. Optionally, set a job that [manually stops](../environments/index.md#stop-an-environment) the Review Apps. diff --git a/doc/ci/runners/build_cloud/macos/environment.md b/doc/ci/runners/build_cloud/macos/environment.md index e84b7d0a207..5336890b931 100644 --- a/doc/ci/runners/build_cloud/macos/environment.md +++ b/doc/ci/runners/build_cloud/macos/environment.md @@ -4,12 +4,12 @@ group: Runner info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# VM instances and images for Build Cloud for macOS +# VM instances and images for Build Cloud for macOS When you use the Build Cloud for macOS: -- Each of your jobs runs in a newly provisioned VM, which is dedicated to the specific job. -- The VM is active only for the duration of the job and immediately deleted. +- Each of your jobs runs in a newly provisioned VM, which is dedicated to the specific job. +- The VM is active only for the duration of the job and immediately deleted. ## VM types diff --git a/doc/ci/runners/build_cloud/macos_build_cloud.md b/doc/ci/runners/build_cloud/macos_build_cloud.md index 1400c7e08db..794bc2e597d 100644 --- a/doc/ci/runners/build_cloud/macos_build_cloud.md +++ b/doc/ci/runners/build_cloud/macos_build_cloud.md @@ -12,11 +12,11 @@ of all the capabilities of the GitLab single DevOps platform and not have to man build environment. Build Cloud runners for macOS are in [Beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta) -and shouldn't be relied upon for mission-critical production jobs. +and shouldn't be relied upon for mission-critical production jobs. ## Quickstart -To start using Build Cloud for macOS Beta, you must submit an access request issue. After your +To start using Build Cloud for macOS Beta, you must submit an access request [issue](https://gitlab.com/gitlab-com/macos-buildcloud-runners-beta/-/issues/new?issuable_template=beta_access_request). After your access has been granted and your build environment configured, you must configure your `.gitlab-ci.yml` pipeline file: diff --git a/doc/ci/runners/configure_runners.md b/doc/ci/runners/configure_runners.md index 2f845a05a4e..13897b934c5 100644 --- a/doc/ci/runners/configure_runners.md +++ b/doc/ci/runners/configure_runners.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Configuring runners +# Configuring runners **(FREE)** If you have installed your own runners, you can configure and secure them in GitLab. @@ -107,10 +107,10 @@ We're always looking for contributions that can mitigate these ### Reset the runner registration token for a project If you think that a registration token for a project was revealed, you should -reset it. A token can be used to register another runner for the project. That new runner -may then be used to obtain the values of secret variables or to clone project code. +reset it. A registration token can be used to register another runner for the project. +That new runner may then be used to obtain the values of secret variables or to clone project code. -To reset the token: +To reset the registration token: 1. Go to the project's **Settings > CI/CD**. 1. Expand the **General pipelines settings** section. @@ -124,6 +124,16 @@ any new runners to the project. If you are using any tools to provision and register new runners, the tokens used in those tools should be updated to reflect the value of the new token. +### Reset the runner authentication token + +If you think that an authentication token for a runner was revealed, you should +reset it. An attacker could use the token to [clone a runner](https://docs.gitlab.com/runner/security/#cloning-a-runner). + +To reset the authentication token, [unregister the runner](https://docs.gitlab.com/runner/commands/#gitlab-runner-unregister) +and then [register](https://docs.gitlab.com/runner/commands/#gitlab-runner-register) it again. + +To verify that the previous authentication token has been revoked, use the [Runners API](../../api/runners.md#verify-authentication-for-a-registered-runner). + ## Determine the IP address of a runner > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17286) in GitLab 10.6. @@ -142,7 +152,7 @@ different places. To view the IP address of a shared runner you must have admin access to the GitLab instance. To determine this: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Runners**. 1. Find the runner in the table and view the **IP Address** column. @@ -159,13 +169,13 @@ project.  -## Use tags to limit the number of jobs using the runner +## Use tags to control which jobs a runner can run You must set up a runner to be able to run all the different types of jobs that it may encounter on the projects it's shared over. This would be problematic for large amounts of projects, if it weren't for tags. -GitLab CI tags are not the same as Git tags. GitLab CI tags are associated with runners. +GitLab CI/CD tags are not the same as Git tags. GitLab CI/CD tags are associated with runners. Git tags are associated with commits. By tagging a runner for the types of jobs it can handle, you can make sure @@ -174,6 +184,8 @@ shared runners will [only run the jobs they are equipped to run](../yaml/index.m For instance, at GitLab we have runners tagged with `rails` if they contain the appropriate dependencies to run Rails test suites. +### Set a runner to run untagged jobs + When you [register a runner](https://docs.gitlab.com/runner/register/), its default behavior is to **only pick** [tagged jobs](../yaml/index.md#tags). To change this, you must have the [Owner role](../../user/permissions.md#project-members-permissions) for the project. @@ -228,6 +240,48 @@ Example 2: 1. A job that has no tags defined is executed and run. 1. A second job that has a `docker` tag defined is stuck. +### Use tags to run jobs on different platforms + +You can use tags to run different jobs on different platforms. For +example, if you have an OS X runner with tag `osx` and a Windows runner with tag +`windows`, you can run a job on each platform: + +```yaml +windows job: + stage: + - build + tags: + - windows + script: + - echo Hello, %USERNAME%! + +osx job: + stage: + - build + tags: + - osx + script: + - echo "Hello, $USER!" +``` + +### Use CI/CD variables in tags + +> Introduced in [GitLab 14.1](https://gitlab.com/gitlab-org/gitlab/-/issues/35742). + +You can use [CI/CD variables](../variables/index.md) with `tags` for dynamic runner selection: + +```yaml +variables: + KUBERNETES_RUNNER: kubernetes + + job: + tags: + - docker + - $KUBERNETES_RUNNER + script: + - echo "Hello runner selector feature" +``` + ## Configure runner behavior with variables You can use [CI/CD variables](../variables/index.md) to configure runner Git behavior @@ -546,7 +600,7 @@ the following stages: | Variable | Description | |---------------------------------|--------------------------------------------------------| | `ARTIFACT_DOWNLOAD_ATTEMPTS` | Number of attempts to download artifacts running a job | -| `EXECUTOR_JOB_SECTION_ATTEMPTS` | [In GitLab 12.10](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4450) and later, the number of attempts to run a section in a job after a [`No Such Container`](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4450) error ([Docker executor](https://docs.gitlab.com/runner/executors/docker.html) only). | +| `EXECUTOR_JOB_SECTION_ATTEMPTS` | In [GitLab 12.10 and later](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4450), the number of attempts to run a section in a job after a [`No Such Container`](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4450) error ([Docker executor](https://docs.gitlab.com/runner/executors/docker.html) only). | | `GET_SOURCES_ATTEMPTS` | Number of attempts to fetch sources running a job | | `RESTORE_CACHE_ATTEMPTS` | Number of attempts to restore the cache running a job | diff --git a/doc/ci/runners/index.md b/doc/ci/runners/index.md index 6642913a9d8..9acca60c4b4 100644 --- a/doc/ci/runners/index.md +++ b/doc/ci/runners/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# GitLab Build Cloud runners +# GitLab Build Cloud runners **(FREE)** If you are using self-managed GitLab or you want to use your own runners on GitLab.com, you can [install and configure your own runners](https://docs.gitlab.com/runner/install/). diff --git a/doc/ci/runners/runners_scope.md b/doc/ci/runners/runners_scope.md index 2af373384d2..b16957ae83c 100644 --- a/doc/ci/runners/runners_scope.md +++ b/doc/ci/runners/runners_scope.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# The scope of runners +# The scope of runners **(FREE)** Runners are available based on who you want to have access: @@ -168,7 +168,7 @@ You must have the [Owner role](../../user/permissions.md#group-members-permissio | Attribute | Description | | ------------ | ----------- | - | Type | Displays the runner type: `group` or `specific`, together with the optional states `locked` and `paused` | + | Type | Displays the runner type: `group` or `specific`, and the optional state `paused` | | Runner token | Token used to identify the runner, and that the runner uses to communicate with the GitLab instance | | Description | Description given to the runner when it was created | | Version | GitLab Runner version | @@ -242,10 +242,10 @@ You can configure a specific runner so it is "locked" and cannot be enabled for 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 runner: +To lock or unlock a specific runner: 1. Go to the project's **Settings > CI/CD** and expand the **Runners** section. -1. Find the runner you want to lock or unlock. Make sure it's enabled. +1. Find the specific runner you want to lock or unlock. Make sure it's enabled. You cannot lock shared or group runners. 1. Click the pencil button. 1. Check the **Lock to current projects** option. 1. Click **Save changes**. diff --git a/doc/ci/secrets/index.md b/doc/ci/secrets/index.md index d3c34a6922e..898d310598f 100644 --- a/doc/ci/secrets/index.md +++ b/doc/ci/secrets/index.md @@ -95,7 +95,7 @@ To configure your Vault server: ## Use Vault secrets in a CI job **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28321) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4 and GitLab Runner 13.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28321) in GitLab 13.4 and GitLab Runner 13.4. After [configuring your Vault server](#configure-your-vault-server), you can use the secrets stored in Vault by defining them with the `vault` keyword: diff --git a/doc/ci/services/gitlab.md b/doc/ci/services/gitlab.md index 558f53a9535..5ac66846ab7 100644 --- a/doc/ci/services/gitlab.md +++ b/doc/ci/services/gitlab.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Use GitLab as a microservice +# Use GitLab as a microservice **(FREE)** Many applications need to access JSON APIs, so application tests might need access to APIs too. The following example shows how to use GitLab as a microservice to give @@ -24,10 +24,9 @@ tests access to the GitLab API. GITLAB_ROOT_PASSWORD: "password" # to access the api with user root:password ``` -1. To set values for the `GITLAB_HTTPS` and `GITLAB_ROOT_PASSWORD`, - [assign them to a variable in the user interface](../variables/index.md#add-a-cicd-variable-to-a-project). - Then assign that variable to the corresponding variable in your - `.gitlab-ci.yml` file. +NOTE: +Variables set in the GitLab UI are not passed down to the service containers. +[Learn more](../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 c7891998a37..4114833d1c8 100644 --- a/doc/ci/services/index.md +++ b/doc/ci/services/index.md @@ -6,7 +6,7 @@ comments: false type: index --- -# Services +# Services **(FREE)** The `services` keyword defines a Docker image that runs during a `job` linked to the Docker image that the image keyword defines. This allows @@ -186,6 +186,34 @@ following these rules: To override the default behavior, you can [specify a service alias](#available-settings-for-services). +### Connecting services + +You can use inter-dependent services with complex jobs, like end-to-end tests where an +external API needs to communicate with its own database. + +For example, for an end-to-end test for a front-end application that uses an API, and where the API needs a database: + +```yaml +end-to-end-tests: + image: node:latest + services: + - name: selenium/standalone-firefox:${FIREFOX_VERSION} + alias: firefox + - name: registry.gitlab.com/organization/private-api:latest + alias: backend-api + - postgres:9.6.19 + variables: + FF_NETWORK_PER_BUILD: 1 + POSTGRES_PASSWORD: supersecretpassword + BACKEND_POSTGRES_HOST: postgres + script: + - npm install + - npm test +``` + +For this solution to work, you must use +[the networking mode that creates a new network for each job](https://docs.gitlab.com/runner/executors/docker.html#create-a-network-for-each-job). + ## Passing CI/CD variables to services You can also pass custom CI/CD [variables](../variables/index.md) @@ -311,6 +339,34 @@ services: The syntax of `command` is similar to [Dockerfile's `CMD`](https://docs.docker.com/engine/reference/builder/#cmd). +## Using `services` with `docker run` (Docker-in-Docker) side-by-side + +Containers started with `docker run` can also connect to services provided by GitLab. + +When booting the service is expensive or time consuming, you can use +this technique to run tests from different client environments, +while only booting up the tested service once. + +```yaml +access-service: + stage: build + image: docker:19.03.1 + services: + - docker:dind # necessary for docker run + - tutum/wordpress:latest + variables: + FF_NETWORK_PER_BUILD: "true" # activate container-to-container networking + script: | + docker run --rm --name curl \ + --volume "$(pwd)":"$(pwd)" \ + --workdir "$(pwd)" \ + --network=host \ + curlimages/curl:7.74.0 curl "http://tutum-wordpress" +``` + +For this solution to work, you must use +[the networking mode that creates a new network for each job](https://docs.gitlab.com/runner/executors/docker.html#create-a-network-for-each-job). + ## How Docker integration works Below is a high level overview of the steps performed by Docker during job diff --git a/doc/ci/services/mysql.md b/doc/ci/services/mysql.md index c691a6ef33d..d0ac123ba62 100644 --- a/doc/ci/services/mysql.md +++ b/doc/ci/services/mysql.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Using MySQL +# Using MySQL **(FREE)** Many applications depend on MySQL as their database, and you may need it for your tests to run. @@ -16,11 +16,9 @@ If you want to use a MySQL container, you can use [GitLab Runner](../runners/ind This example shows you how to set a username and password that GitLab uses to access the MySQL container. If you do not set a username and password, you must use `root`. -1. [Create CI/CD variables](../variables/index.md#custom-cicd-variables) for your - MySQL database and password by going to **Settings > CI/CD**, expanding **Variables**, - and clicking **Add Variable**. - - This example uses `$MYSQL_DB` and `$MYSQL_PASS` as the keys. +NOTE: +Variables set in the GitLab UI are not passed down to the service containers. +[Learn more](../variables/index.md). 1. To specify a MySQL image, add the following to your `.gitlab-ci.yml` file: @@ -39,8 +37,8 @@ This example shows you how to set a username and password that GitLab uses to ac ```yaml variables: # Configure mysql environment variables (https://hub.docker.com/_/mysql/) - MYSQL_DATABASE: $MYSQL_DB - MYSQL_ROOT_PASSWORD: $MYSQL_PASS + MYSQL_DATABASE: $MYSQL_DATABASE + MYSQL_ROOT_PASSWORD: $MYSQL_ROOT_PASSWORD ``` The MySQL container uses `MYSQL_DATABASE` and `MYSQL_ROOT_PASSWORD` to connect to the database. diff --git a/doc/ci/services/postgres.md b/doc/ci/services/postgres.md index 8d14e4795d2..62838e04969 100644 --- a/doc/ci/services/postgres.md +++ b/doc/ci/services/postgres.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Using PostgreSQL +# Using PostgreSQL **(FREE)** As many applications depend on PostgreSQL as their database, you eventually need it in order for your tests to run. Below you are guided how to @@ -16,6 +16,10 @@ do this with the Docker and Shell executors of GitLab Runner. If you're using [GitLab Runner](../runners/index.md) with the Docker executor, 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). + First, in your `.gitlab-ci.yml` add: ```yaml @@ -23,25 +27,19 @@ services: - postgres:12.2-alpine variables: - POSTGRES_DB: nice_marmot - POSTGRES_USER: runner - POSTGRES_PASSWORD: "" + POSTGRES_DB: $POSTGRES_DB + POSTGRES_USER: $POSTGRES_USER + POSTGRES_PASSWORD: $POSTGRES_PASSWORD POSTGRES_HOST_AUTH_METHOD: trust ``` -To set values for the `POSTGRES_DB`, `POSTGRES_USER`, -`POSTGRES_PASSWORD` and `POSTGRES_HOST_AUTH_METHOD`, -[assign them to a CI/CD variable in the user interface](../variables/index.md#custom-cicd-variables), -then assign that variable to the corresponding variable in your -`.gitlab-ci.yml` file. - And then configure your application to use the database, for example: ```yaml Host: postgres -User: runner -Password: '' -Database: nice_marmot +User: $PG_USER +Password: $PG_PASSWORD +Database: $PG_DB ``` If you're wondering why we used `postgres` for the `Host`, read more at diff --git a/doc/ci/services/redis.md b/doc/ci/services/redis.md index d8c7b805864..a3446fc2677 100644 --- a/doc/ci/services/redis.md +++ b/doc/ci/services/redis.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Using Redis +# Using Redis **(FREE)** As many applications depend on Redis as their key-value store, you eventually need it in order for your tests to run. Below you are guided how to diff --git a/doc/ci/triggers/index.md b/doc/ci/triggers/index.md index 880473d402d..a2dd4ac91d5 100644 --- a/doc/ci/triggers/index.md +++ b/doc/ci/triggers/index.md @@ -14,8 +14,8 @@ tag) with an API call. The following methods of authentication are supported: -- [Trigger token](#trigger-token) -- [CI job token](#ci-job-token) +- Trigger tokens: A unique trigger token can be obtained when [adding a new trigger](#adding-a-new-trigger). +- [CI job tokens](../jobs/ci_job_token.md). If using the `$CI_PIPELINE_SOURCE` [predefined CI/CD variable](../variables/predefined_variables.md) to limit which jobs run in a pipeline, the value could be either `pipeline` or `trigger`, @@ -28,71 +28,6 @@ depending on which trigger method is used. This also applies when using the `pipelines` or `triggers` keywords with the legacy [`only/except` basic syntax](../yaml/index.md#only--except). -### Trigger token - -A unique trigger token can be obtained when [adding a new trigger](#adding-a-new-trigger). - -WARNING: -Passing plain text tokens in public projects is a security issue. Potential -attackers can impersonate the user that exposed their trigger token publicly in -their `.gitlab-ci.yml` file. Use [CI/CD variables](../variables/index.md) -to protect trigger tokens. - -### CI job token - -You can use the `CI_JOB_TOKEN` [CI/CD variable](../variables/index.md#predefined-cicd-variables) (used to authenticate -with the [GitLab Container Registry](../../user/packages/container_registry/index.md)) in the following cases. - -#### When used with multi-project pipelines - -> - Use of `CI_JOB_TOKEN` for multi-project pipelines was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2017) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.3. -> - Use of `CI_JOB_TOKEN` for multi-project pipelines was [made available](https://gitlab.com/gitlab-org/gitlab/-/issues/31573) in all tiers in GitLab 12.4. - -This way of triggering can only be used when invoked inside `.gitlab-ci.yml`, -and it creates a dependent pipeline relation visible on the -[pipeline graph](../pipelines/multi_project_pipelines.md). For example: - -```yaml -trigger_pipeline: - stage: deploy - script: - - curl --request POST --form "token=$CI_JOB_TOKEN" --form ref=main "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" - rules: - - if: $CI_COMMIT_TAG -``` - -Pipelines triggered that way also expose a special variable: -`CI_PIPELINE_SOURCE=pipeline`. - -Read more about the [pipelines trigger API](../../api/pipeline_triggers.md). - -#### When a pipeline depends on the artifacts of another pipeline **(PREMIUM)** - -> The use of `CI_JOB_TOKEN` in the artifacts download API was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2346) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.5. - -With the introduction of dependencies between different projects, one of -them may need to access artifacts created by a previous one. This process -must be granted for authorized accesses, and it can be done using the -`CI_JOB_TOKEN` variable that identifies a specific job. For example: - -```yaml -build_submodule: - image: debian - stage: test - script: - - apt update && apt install -y unzip - - curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/download?job=test&job_token=$CI_JOB_TOKEN" - - unzip artifacts.zip - rules: - - if: $CI_COMMIT_TAG -``` - -This allows you to use that for multi-project pipelines and download artifacts -from any project to which you have access as this follows the same principles -with the [permission model](../../user/permissions.md#job-permissions). - -Read more about the [jobs API](../../api/job_artifacts.md#download-the-artifacts-archive). - ## Adding a new trigger Go to your @@ -106,6 +41,12 @@ overview of the time the triggers were last used.  +WARNING: +Passing plain text tokens in public projects is a security issue. Potential +attackers can impersonate the user that exposed their trigger token publicly in +their `.gitlab-ci.yml` file. Use [CI/CD variables](../variables/index.md) +to protect trigger tokens. + ## Revoking a trigger You can revoke a trigger any time by going at your project's diff --git a/doc/ci/troubleshooting.md b/doc/ci/troubleshooting.md index df9b20d1708..827a89fa99c 100644 --- a/doc/ci/troubleshooting.md +++ b/doc/ci/troubleshooting.md @@ -29,7 +29,7 @@ with your editor of choice. ### Verify syntax with CI Lint tool The [CI Lint tool](lint.md) is a simple way to ensure the syntax of a CI/CD configuration -file is correct. Paste in full `gitlab-ci.yml` files or individual jobs configuration, +file is correct. Paste in full `.gitlab-ci.yml` files or individual jobs configuration, to verify the basic syntax. When a `.gitlab-ci.yml` file is present in a project, you can also use the CI Lint @@ -49,7 +49,7 @@ and check if their values are what you expect. ## GitLab CI/CD documentation -The [complete `gitlab-ci.yml` reference](yaml/index.md) contains a full list of +The [complete `.gitlab-ci.yml` reference](yaml/index.md) contains a full list of every keyword you may need to use to configure your pipelines. You can also look at a large number of pipeline configuration [examples](examples/index.md) diff --git a/doc/ci/variables/index.md b/doc/ci/variables/index.md index a00b8b678ec..fa4bc6e39fb 100644 --- a/doc/ci/variables/index.md +++ b/doc/ci/variables/index.md @@ -20,6 +20,15 @@ You can use [predefined CI/CD variables](#predefined-cicd-variables) or define c - [Group CI/CD variables](#add-a-cicd-variable-to-a-group). - [Instance CI/CD variables](#add-a-cicd-variable-to-an-instance). +NOTE: +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`: + +```yaml +variables: + SA_PASSWORD: $SA_PASSWORD +``` + > 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/) @@ -116,7 +125,7 @@ Use the [`value` and `description`](../yaml/index.md#prefill-variables-in-manual 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). -### Use variables or `$` in other variables +### Use variables in other variables You can use variables inside other variables: @@ -129,7 +138,9 @@ job: - 'eval "$LS_CMD"' # Executes 'ls -al' ``` -If you do not want the `$` interpreted as the start of a variable, use `$$` instead: +#### Use the `$` character in variables + +If you do not want the `$` character interpreted as the start of a variable, use `$$` instead: ```yaml job: @@ -228,7 +239,7 @@ You can define instance variables via the UI or [API](../../api/instance_level_c To add an instance variable: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD** and expand the **Variables** section. 1. Select the **Add variable** button, and fill in the details: @@ -295,6 +306,26 @@ echo "$KUBE_CA_PEM" > "$(pwd)/kube.ca.pem" kubectl config set-cluster e2e --server="$KUBE_URL" --certificate-authority="$(pwd)/kube.ca.pem" ``` +#### Store multiple values in one variable + +It is not possible to 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, +then loop through the values with a script: + +```yaml +job1: + variables: + FOLDERS: src test docs + script: + - | + for FOLDER in $FOLDERS + do + echo "The path is root/${FOLDER}" + done +``` + ### Mask a CI/CD variable > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/13784) in GitLab 11.10 diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md index b5999a555c9..c8688d2433e 100644 --- a/doc/ci/variables/predefined_variables.md +++ b/doc/ci/variables/predefined_variables.md @@ -41,7 +41,8 @@ There are also [Kubernetes-specific deployment variables](../../user/project/clu | `CI_CONFIG_PATH` | 9.4 | 0.5 | The path to the CI/CD configuration file. Defaults to `.gitlab-ci.yml`. Read-only inside a running pipeline. | | `CI_DEBUG_TRACE` | all | 1.7 | `true` if [debug logging (tracing)](index.md#debug-logging) is enabled. | | `CI_DEFAULT_BRANCH` | 12.4 | all | The name of the project's default branch. | -| `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` | 13.7 | all | The image prefix for pulling images through the Dependency Proxy. | +| `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` | 13.7 | all | The top-level group image prefix for pulling images through the Dependency Proxy. | +| `CI_DEPENDENCY_PROXY_DIRECT_GROUP_IMAGE_PREFIX` | 14.3 | all | The direct group image prefix for pulling images through the Dependency Proxy. | | `CI_DEPENDENCY_PROXY_PASSWORD` | 13.7 | all | The password to pull images through the Dependency Proxy. | | `CI_DEPENDENCY_PROXY_SERVER` | 13.7 | all | The server for logging in to the Dependency Proxy. This is equivalent to `$CI_SERVER_HOST:$CI_SERVER_PORT`. | | `CI_DEPENDENCY_PROXY_USER` | 13.7 | all | The username to pull images through the Dependency Proxy. | @@ -62,7 +63,7 @@ There are also [Kubernetes-specific deployment variables](../../user/project/clu | `CI_JOB_NAME` | 9.0 | 0.5 | The name of the job. | | `CI_JOB_STAGE` | 9.0 | 0.5 | The name of the job's stage. | | `CI_JOB_STATUS` | all | 13.5 | The status of the job as each runner stage is executed. Use with [`after_script`](../yaml/index.md#after_script). Can be `success`, `failed`, or `canceled`. | -| `CI_JOB_TOKEN` | 9.0 | 1.2 | A token to authenticate with [certain API endpoints](../../api/index.md#gitlab-cicd-job-token). The token is valid as long as the job is running. | +| `CI_JOB_TOKEN` | 9.0 | 1.2 | A token to authenticate with [certain API endpoints](../jobs/ci_job_token.md). The token is valid as long as the job is running. | | `CI_JOB_URL` | 11.1 | 0.5 | The job details URL. | | `CI_JOB_STARTED_AT` | 13.10 | all | The UTC datetime when a job started, in [ISO 8601](https://tools.ietf.org/html/rfc3339#appendix-A) format. | | `CI_KUBERNETES_ACTIVE` | 13.0 | all | Only available if the pipeline has a Kubernetes cluster available for deployments. `true` when available. | @@ -82,7 +83,7 @@ There are also [Kubernetes-specific deployment variables](../../user/project/clu | `CI_PROJECT_ID` | all | all | The ID of the current project. This ID is unique across all projects on the GitLab instance. | | `CI_PROJECT_NAME` | 8.10 | 0.5 | The name of the directory for the project. For example if the project URL is `gitlab.example.com/group-name/project-1`, `CI_PROJECT_NAME` is `project-1`. | | `CI_PROJECT_NAMESPACE` | 8.10 | 0.5 | The project namespace (username or group name) of the job. | -| `CI_PROJECT_PATH_SLUG` | 9.3 | all | `$CI_PROJECT_PATH` in lowercase with characters that are not `a-z` or `0-9` replaced with `-`. Use in URLs and domain names. | +| `CI_PROJECT_PATH_SLUG` | 9.3 | all | `$CI_PROJECT_PATH` in lowercase with characters that are not `a-z` or `0-9` replaced with `-` and shortened to 63 bytes. Use in URLs and domain names. | | `CI_PROJECT_PATH` | 8.10 | 0.5 | The project namespace with the project name included. | | `CI_PROJECT_REPOSITORY_LANGUAGES` | 12.3 | all | A comma-separated, lowercase list of the languages used in the repository. For example `ruby,javascript,html,css`. | | `CI_PROJECT_ROOT_NAMESPACE` | 13.2 | 0.5 | The root project namespace (username or group name) of the job. For example, if `CI_PROJECT_NAMESPACE` is `root-group/child-group/grandchild-group`, `CI_PROJECT_ROOT_NAMESPACE` is `root-group`. | diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md index 8009687dbca..0f9339657fe 100644 --- a/doc/ci/variables/where_variables_can_be_used.md +++ b/doc/ci/variables/where_variables_can_be_used.md @@ -26,7 +26,7 @@ There are two places defined variables can be used. On the: |:-------------------------------------------|:-----------------|:-----------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `environment:url` | yes | GitLab | The variable expansion is made by the [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism) in GitLab.<br/><br/>Supported are all variables defined for a job (project/group variables, variables from `.gitlab-ci.yml`, variables from triggers, variables from pipeline schedules).<br/><br/>Not supported are variables defined in the GitLab Runner `config.toml` and variables created in the job's `script`. | | `environment:name` | yes | GitLab | Similar to `environment:url`, but the variables expansion doesn't support the following:<br/><br/>- Variables that are based on the environment's name (`CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_SLUG`).<br/>- Any other variables related to environment (currently only `CI_ENVIRONMENT_URL`).<br/>- [Persisted variables](#persisted-variables). | -| `resource_group` | yes | GitLab | Similar to `environment:url`, but the variables expansion doesn't support the following:<br/><br/>- Variables that are based on the environment's name (`CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_SLUG`).<br/>- Any other variables related to environment (currently only `CI_ENVIRONMENT_URL`).<br/>- [Persisted variables](#persisted-variables). | +| `resource_group` | yes | GitLab | Similar to `environment:url`, but the variables expansion doesn't support the following:<br/>- `CI_ENVIRONMENT_URL`<br/>- [Persisted variables](#persisted-variables) | | `include` | yes | GitLab | The variable expansion is made by the [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism) in GitLab. <br/><br/>Predefined project variables are supported: `GITLAB_FEATURES`, `CI_DEFAULT_BRANCH`, and all variables that start with `CI_PROJECT_` (for example `CI_PROJECT_NAME`). | | `variables` | yes | GitLab/Runner | The variable expansion is first made by the [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism) in GitLab, and then any unrecognized or unavailable variables are expanded by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism). | | `image` | yes | Runner | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | @@ -63,11 +63,11 @@ because the expansion is done in GitLab before any runner gets the job. #### Nested variable expansion -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/48627) in GitLab 13.10. -> - It's [deployed behind a feature flag](../../user/feature_flags.md), disabled by default. -> - It can be enabled or disabled for a single project. -> - It's disabled on GitLab.com. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enabling-the-nested-variable-expansion-feature). **(FREE SELF)** +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/48627) in GitLab 13.10. [Deployed behind the `variable_inside_variable` feature flag](../../user/feature_flags.md), disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/297382) in GitLab 14.3. + +FLAG: +On self-managed GitLab, by default this feature is disabled. To enable the feature per project or for your entire instance, ask an administrator to [enable the `variable_inside_variable` flag](../../administration/feature_flags.md). GitLab expands job variable values recursively before sending them to the runner. For example: @@ -86,29 +86,6 @@ References to unavailable variables are left intact. In this case, the runner [attempts to expand the variable value](#gitlab-runner-internal-variable-expansion-mechanism) at runtime. For example, a variable like `CI_BUILDS_DIR` is known by the runner only at runtime. -##### Enabling the nested variable expansion feature **(FREE SELF)** - -This feature comes with the `:variable_inside_variable` feature flag disabled by default. - -To enable this feature, ask a GitLab administrator with [Rails console access](../../administration/feature_flags.md#how-to-enable-and-disable-features-behind-flags) to run the -following command: - -```ruby -# For the instance -Feature.enable(:variable_inside_variable) -# For a single project -Feature.enable(:variable_inside_variable, Project.find(<project id>)) -``` - -To disable it: - -```ruby -# For the instance -Feature.disable(:variable_inside_variable) -# For a single project -Feature.disable(:variable_inside_variable, Project.find(<project id>)) -``` - ### GitLab Runner internal variable expansion mechanism - Supported: project/group variables, `.gitlab-ci.yml` variables, `config.toml` variables, and diff --git a/doc/ci/yaml/gitlab_ci_yaml.md b/doc/ci/yaml/gitlab_ci_yaml.md index 6cd900123e0..ea05aa45b0b 100644 --- a/doc/ci/yaml/gitlab_ci_yaml.md +++ b/doc/ci/yaml/gitlab_ci_yaml.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Pipeline Execution +group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- diff --git a/doc/ci/yaml/includes.md b/doc/ci/yaml/includes.md index 673a4e75c35..92bf44cca7f 100644 --- a/doc/ci/yaml/includes.md +++ b/doc/ci/yaml/includes.md @@ -1,76 +1,81 @@ --- stage: Verify -group: Pipeline Execution +group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- # GitLab CI/CD include examples **(FREE)** -In addition to the [`includes` examples](index.md#include) listed in the -[GitLab CI YAML reference](index.md), this page lists more variations of `include` -usage. +You can use [`include`](index.md#include) to include external YAML files in your CI/CD jobs. -## Single string or array of multiple values +## Include a single configuration file -You can include your extra YAML file(s) either as a single string or -an array of multiple values. The following examples are all valid. +To include a single configuration file, use either of these syntax options: -Single string with the `include:local` method implied: +- `include` by itself with a single file, which is the same as + [`include:local`](index.md#includelocal): -```yaml -include: '/templates/.after-script-template.yml' -``` + ```yaml + include: '/templates/.after-script-template.yml' + ``` -Array with `include` method implied: +- `include` with a single file, and you specify the `include` type: -```yaml -include: - - 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' - - '/templates/.after-script-template.yml' -``` + ```yaml + include: + remote: 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' + ``` -Single string with `include` method specified explicitly: +## Include an array of configuration files -```yaml -include: - remote: 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' -``` +You can include an array of configuration files: -Array with `include:remote` being the single item: +- If you do not specify an `include` type, the type defaults to [`include:local`](index.md#includelocal): -```yaml -include: - - remote: 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' -``` + ```yaml + include: + - 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' + - '/templates/.after-script-template.yml' + ``` -Array with multiple `include` methods specified explicitly: +- You can define a single item array: -```yaml -include: - - remote: 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' - - local: '/templates/.after-script-template.yml' - - template: Auto-DevOps.gitlab-ci.yml -``` + ```yaml + include: + - remote: 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' + ``` -Array mixed syntax: +- You can define an array and explicitly specify multiple `include` types: -```yaml -include: - - 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' - - '/templates/.after-script-template.yml' - - template: Auto-DevOps.gitlab-ci.yml - - project: 'my-group/my-project' - ref: main - file: '/templates/.gitlab-ci-template.yml' -``` + ```yaml + include: + - remote: 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' + - local: '/templates/.after-script-template.yml' + - template: Auto-DevOps.gitlab-ci.yml + ``` + +- You can define an array that combines both default and specific `include` type: + + ```yaml + include: + - 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' + - '/templates/.after-script-template.yml' + - template: Auto-DevOps.gitlab-ci.yml + - project: 'my-group/my-project' + ref: main + file: '/templates/.gitlab-ci-template.yml' + ``` -## Re-using a `before_script` template +## Use `default` configuration from an included configuration file -In the following example, the content of `.before-script-template.yml` is -automatically fetched and evaluated along with the content of `.gitlab-ci.yml`. +You can define a [`default`](index.md#custom-default-keyword-values) section in a +configuration file. When you use a `default` section with the `include` keyword, the defaults apply to +all jobs in the pipeline. -Content of `https://gitlab.com/awesome-project/raw/main/.before-script-template.yml`: +For example, you can use a `default` section with [`before_script`](index.md#before_script). + +Content of a custom configuration file named `/templates/.before-script-template.yml`: ```yaml default: @@ -83,19 +88,29 @@ default: Content of `.gitlab-ci.yml`: ```yaml -include: 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' +include: '/templates/.before-script-template.yml' -rspec: +rspec1: + script: + - bundle exec rspec + +rspec2: script: - bundle exec rspec ``` -## Overriding external template values +The default `before_script` commands execute in both `rspec` jobs, before the `script` commands. + +## Override included configuration values -The following example shows specific YAML-defined variables and details of the -`production` job from an include file being customized in `.gitlab-ci.yml`. +When you use the `include` keyword, you can override the included configuration values to adapt them +to your pipeline requirements. -Content of `https://company.com/autodevops-template.yml`: +The following example shows an `include` file that is customized in the +`.gitlab-ci.yml` file. Specific YAML-defined variables and details of the +`production` job are overridden. + +Content of a custom configuration file named `autodevops-template.yml`: ```yaml variables: @@ -136,17 +151,18 @@ production: url: https://domain.com ``` -In this case, the variables `POSTGRES_USER` and `POSTGRES_PASSWORD` along -with the environment URL of the `production` job defined in -`autodevops-template.yml` have been overridden by new values defined in -`.gitlab-ci.yml`. +The `POSTGRES_USER` and `POSTGRES_PASSWORD` variables +and the `environment:url` of the `production` job defined in the `.gitlab-ci.yml` file +override the values defined in the `autodevops-template.yml` file. The other keywords +do not change. This method is called *merging*. + +## Override included configuration arrays -The merging lets you extend and override dictionary mappings, but -you cannot add or modify items to an included array. For example, to add -an additional item to the production job script, you must repeat the -existing script items: +You can use merging to extend and override configuration in an included template, but +you cannot add or modify individual items in an array. For example, to add +an additional `notify_owner` command to the extended `production` job's `script` array: -Content of `https://company.com/autodevops-template.yml`: +Content of `autodevops-template.yml`: ```yaml production: @@ -159,7 +175,7 @@ production: Content of `.gitlab-ci.yml`: ```yaml -include: 'https://company.com/autodevops-template.yml' +include: 'autodevops-template.yml' stages: - production @@ -171,51 +187,32 @@ production: - notify_owner ``` -In this case, if `install_dependencies` and `deploy` were not repeated in -`.gitlab-ci.yml`, they would not be part of the script for the `production` -job in the combined CI configuration. +If `install_dependencies` and `deploy` are not repeated in +the `.gitlab-ci.yml` file, the `production` job would have only `notify_owner` in the script. -## Using nested includes +## Use nested includes -The examples below show how includes can be nested from different sources -using a combination of different methods. +You can nest `include` sections in configuration files that are then included +in another configuration. For example, for `include` keywords nested three deep: -In this example, `.gitlab-ci.yml` includes local the file `/.gitlab-ci/another-config.yml`: +Content of `.gitlab-ci.yml`: ```yaml include: - local: /.gitlab-ci/another-config.yml ``` -The `/.gitlab-ci/another-config.yml` includes a template and the `/templates/docker-workflow.yml` file -from another project: +Content of `/.gitlab-ci/another-config.yml`: ```yaml include: - - template: Bash.gitlab-ci.yml - - project: group/my-project - file: /templates/docker-workflow.yml + - local: /.gitlab-ci/config-defaults.yml ``` -The `/templates/docker-workflow.yml` present in `group/my-project` includes two local files -of the `group/my-project`: +Content of `/.gitlab-ci/config-defaults.yml`: ```yaml -include: - - local: /templates/docker-build.yml - - local: /templates/docker-testing.yml -``` - -Our `/templates/docker-build.yml` present in `group/my-project` adds a `docker-build` job: - -```yaml -docker-build: - script: docker build -t my-image . -``` - -Our second `/templates/docker-test.yml` present in `group/my-project` adds a `docker-test` job: - -```yaml -docker-test: - script: docker run my-image /run/tests.sh +default: + after_script: + - echo "Job complete." ``` diff --git a/doc/ci/yaml/index.md b/doc/ci/yaml/index.md index 63f626e524e..fb5748788f7 100644 --- a/doc/ci/yaml/index.md +++ b/doc/ci/yaml/index.md @@ -1,15 +1,11 @@ --- stage: Verify -group: Pipeline Execution +group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- -<!-- markdownlint-disable MD044 --> -<!-- vale gitlab.Spelling = NO --> -# Keyword reference for the .gitlab-ci.yml file **(FREE)** -<!-- vale gitlab.Spelling = YES --> -<!-- markdownlint-enable MD044 --> +# Keyword reference for the `.gitlab-ci.yml` file **(FREE)** This document lists the configuration options for your GitLab `.gitlab-ci.yml` file. @@ -331,7 +327,7 @@ include: #### Switch between branch pipelines and merge request pipelines -> [Introduced in](https://gitlab.com/gitlab-org/gitlab/-/issues/201845) GitLab 13.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/201845) in GitLab 13.8. To make the pipeline switch from branch pipelines to merge request pipelines after a merge request is created, add a `workflow: rules` section to your `.gitlab-ci.yml` file. @@ -386,7 +382,7 @@ does not block triggered pipelines. > [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/42861) to GitLab Free in 11.4. Use `include` to include external YAML files in your CI/CD configuration. -You can break down one long `gitlab-ci.yml` file into multiple files to increase readability, +You can break down one long `.gitlab-ci.yml` file into multiple files to increase readability, or reduce duplication of the same configuration in multiple places. You can also store template files in a central repository and `include` them in projects. @@ -434,7 +430,7 @@ In `include` sections in your `.gitlab-ci.yml` file, you can use: - [Project variables](../variables/index.md#add-a-cicd-variable-to-a-project) - [Group variables](../variables/index.md#add-a-cicd-variable-to-a-group) - [Instance variables](../variables/index.md#add-a-cicd-variable-to-an-instance) -- Project [predefined variables](../variables/predefined_variables.md). +- Project [predefined variables](../variables/predefined_variables.md). ```yaml include: @@ -450,12 +446,12 @@ that proposes expanding this feature to support more variables. #### `rules` with `include` -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276515) in GitLab 14.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276515) in GitLab 14.2. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/337507) in GitLab 14.3 and is ready for production use. +> - [Enabled with `ci_include_rules` flag](https://gitlab.com/gitlab-org/gitlab/-/issues/337507) for self-managed GitLab in GitLab 14.3 and is ready for production use. -NOTE: -On self-managed GitLab, by default this feature is not available. To make it available, -ask an administrator to [enable the `ci_include_rules` flag](../../administration/feature_flags.md). -On GitLab.com, this feature is not available. The feature is not ready for production use. +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature per project or for your entire instance, ask an administrator to [disable the `ci_include_rules` flag](../../administration/feature_flags.md). On GitLab.com, this feature is available. You can use [`rules`](#rules) with `include` to conditionally include other configuration files. You can only use `rules:if` in `include` with [certain variables](#variables-with-include). @@ -626,7 +622,7 @@ Use nested includes to compose a set of includes. You can have up to 100 includes, but you can't have duplicate includes. -In [GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/issues/28212) and later, the time limit +In [GitLab 12.4 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/28212), the time limit to resolve all files is 30 seconds. #### Additional `includes` examples @@ -1141,6 +1137,9 @@ The job is not added to the pipeline: - If no rules match. - If a rule matches and has `when: never`. +You can use [`!reference` tags](#reference-tags) to [reuse `rules` configuration](../jobs/job_control.md#reuse-rules-in-different-jobs) +in different jobs. + #### `rules:if` Use `rules:if` clauses to specify when to add a job to a pipeline: @@ -1368,7 +1367,7 @@ pipeline based on branch names or pipeline types. | `pushes` | For pipelines triggered by a `git push` event, including for branches and tags. | | `schedules` | For [scheduled pipelines](../pipelines/schedules.md). | | `tags` | When the Git reference for a pipeline is a tag. | - | `triggers` | For pipelines created by using a [trigger token](../triggers/index.md#trigger-token). | + | `triggers` | For pipelines created by using a [trigger token](../triggers/index.md#authentication-tokens). | | `web` | For pipelines created by using **Run pipeline** button in the GitLab UI, from the project's **CI/CD > Pipelines** section. | **Example of `only:refs` and `except:refs`**: @@ -1591,27 +1590,23 @@ production: #### Requirements and limitations -- In [GitLab 14.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/30632) you - can refer to jobs in the same stage as the job you are configuring. This feature is - enabled on GitLab.com and ready for production use. On self-managed [GitLab 14.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/30632) - this feature is available by default. To hide the feature, ask an administrator to - [disable the `ci_same_stage_job_needs` flag](../../administration/feature_flags.md). -- In GitLab 14.0 and older, you can only refer to jobs in earlier stages. -- In GitLab 13.9 and older, if `needs:` refers to a job that might not be added to - a pipeline because of `only`, `except`, or `rules`, the pipeline might fail to create. - The maximum number of jobs that a single job can need in the `needs:` array is limited: - For GitLab.com, the limit is 50. For more information, see our [infrastructure issue](https://gitlab.com/gitlab-com/gl-infra/infrastructure/-/issues/7541). - - For self-managed instances, the limit is: 50. This limit [can be changed](#changing-the-needs-job-limit). + - For self-managed instances, the default limit is 50. This limit [can be changed](#changing-the-needs-job-limit). - If `needs:` refers to a job that uses the [`parallel`](#parallel) keyword, it depends on all jobs created in parallel, not just one job. It also downloads artifacts from all the parallel jobs by default. If the artifacts have the same name, they overwrite each other and only the last one downloaded is saved. -- `needs:` is similar to `dependencies:` in that it must use jobs from prior stages, - meaning it's impossible to create circular dependencies. Depending on jobs in the - current stage is not possible either, but [an issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/30632). -- Stages must be explicitly defined for all jobs - that have the keyword `needs:` or are referred to by one. +- In [GitLab 14.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/30632) you + can refer to jobs in the same stage as the job you are configuring. This feature is + enabled on GitLab.com and ready for production use. On self-managed [GitLab 14.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/30632) + this feature is available by default. +- In GitLab 14.0 and older, you can only refer to jobs in earlier stages. Stages must be + explicitly defined for all jobs that use the `needs:` keyword, or are referenced + in a job's `needs:` section. +- In GitLab 13.9 and older, if `needs:` refers to a job that might not be added to + a pipeline because of `only`, `except`, or `rules`, the pipeline might fail to create. ##### Changing the `needs:` job limit **(FREE SELF)** @@ -1628,7 +1623,7 @@ To disable directed acyclic graphs (DAG), set the limit to `0`. #### Artifact downloads with `needs` -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14311) in GitLab v12.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14311) in GitLab 12.6. When a job uses `needs`, it no longer downloads all artifacts from previous stages by default, because jobs with `needs` can start before earlier stages complete. With @@ -1680,7 +1675,7 @@ with `needs`. #### Cross project artifact downloads with `needs` **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14311) in GitLab v12.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14311) in GitLab 12.7. Use `needs` to download artifacts from up to five jobs in pipelines: @@ -1753,7 +1748,7 @@ pipelines running on the same ref could override the artifacts. #### Artifact downloads to child pipelines -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/255983) in GitLab v13.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/255983) in GitLab 13.7. A [child pipeline](../pipelines/parent_child_pipelines.md) can download artifacts from a job in its parent pipeline or another child pipeline in the same parent-child pipeline hierarchy. @@ -1832,14 +1827,25 @@ rspec: ### `tags` +> - A limit of 50 tags per job [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/338929) in GitLab 14.3. +> - A limit of 50 tags per job [enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/339855) in GitLab 14.3. + Use `tags` to select a specific runner from the list of all runners that are available for the project. When you register a runner, you can specify the runner's tags, for -example `ruby`, `postgres`, `development`. +example `ruby`, `postgres`, or `development`. To pick up and run a job, a runner must +be assigned every tag listed in the job. + +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default:` section](#custom-default-keyword-values). + +**Possible inputs**: -In the following example, the job is run by a runner that -has both `ruby` and `postgres` tags defined. +- An array of tag names. +- [CI/CD variables](../runners/configure_runners.md#use-cicd-variables-in-tags) in GitLab 14.1 and later. + +**Example of `tags`**: ```yaml job: @@ -1848,75 +1854,56 @@ job: - postgres ``` -You can use tags to run different jobs on different platforms. For -example, if you have an OS X runner with tag `osx` and a Windows runner with tag -`windows`, you can run a job on each platform: +In this example, only runners with *both* the `ruby` and `postgres` tags can run the job. -```yaml -windows job: - stage: - - build - tags: - - windows - script: - - echo Hello, %USERNAME%! +**Additional details**: -osx job: - stage: - - build - tags: - - osx - script: - - echo "Hello, $USER!" -``` +- In [GitLab 14.3](https://gitlab.com/gitlab-org/gitlab/-/issues/338479) and later, + the number of tags must be less than `50`. -In [GitLab 14.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/35742), you can -use [CI/CD variables](../variables/index.md) with `tags` for dynamic runner selection: +**Related topics**: -```yaml -variables: - KUBERNETES_RUNNER: kubernetes - - job: - tags: - - docker - - $KUBERNETES_RUNNER - script: - - echo "Hello runner selector feature" -``` +- [Use tags to control which jobs a runner can run](../runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run). ### `allow_failure` -Use `allow_failure` when you want to let a job fail without impacting the rest of the CI -suite. The default value is `false`, except for [manual](../jobs/job_control.md#create-a-job-that-must-be-run-manually) jobs that use -the [`when: manual`](#when) syntax. +Use `allow_failure` to determine whether a pipeline should continue running when a job fails. + +- To let the pipeline continue running subsequent jobs, use `allow_failure: true`. +- To stop the pipeline from running subsequent jobs, use `allow_failure: false`. -In jobs that use [`rules:`](#rules), all jobs default to `allow_failure: false`, -*including* `when: manual` jobs. +When jobs are allowed to fail (`allow_failure: true`) an orange warning (**{status_warning}**) +indicates that a job failed. However, the pipeline is successful and the associated commit +is marked as passed with no warnings. -When `allow_failure` is set to `true` and the job fails, the job shows an orange warning in the UI. -However, the logical flow of the pipeline considers the job a -success/passed, and is not blocked. +This same warning is displayed when: -Assuming all other jobs are successful, the job's stage and its pipeline -show the same orange warning. However, the associated commit is marked as -"passed", without warnings. +- All other jobs in the stage are successful. +- All other jobs in the pipeline are successful. -In the following example, `job1` and `job2` run in parallel. If `job1` -fails, it doesn't stop the next stage from running, because it's marked with -`allow_failure: true`: +The default value for `allow_failure` is: + +- `true` for [manual jobs](../jobs/job_control.md#create-a-job-that-must-be-run-manually). +- `false` for manual jobs that also use [`rules`](#rules). +- `false` in all other cases. + +**Keyword type**: Job keyword. You can use it only as part of a job. + +**Possible inputs**: `true` or `false`. + +**Example of `allow_failure`**: ```yaml job1: stage: test script: - - execute_script_that_will_fail - allow_failure: true + - execute_script_1 job2: stage: test script: - - execute_script_that_will_succeed + - execute_script_2 + allow_failure: true job3: stage: deploy @@ -1924,14 +1911,35 @@ job3: - deploy_to_staging ``` +In this example, `job1` and `job2` run in parallel: + +- If `job1` fails, jobs in the `deploy` stage do not start. +- If `job2` fails, jobs in the `deploy` stage can still start. + +**Additional details**: + +- You can use `allow_failure` as a subkey of [`rules:`](#rulesallow_failure). +- You can use `allow_failure: false` with a manual job to create a [blocking manual job](../jobs/job_control.md#types-of-manual-jobs). + A blocked pipeline does not run any jobs in later stages until the manual job + is started and completes successfully. + #### `allow_failure:exit_codes` > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/273157) in GitLab 13.8. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/292024) in GitLab 13.9. -Use `allow_failure:exit_codes` to dynamically control if a job should be allowed -to fail. You can list which exit codes are not considered failures. The job fails -for any other exit code: +Use `allow_failure:exit_codes` to control when a job should be +allowed to fail. The job is `allow_failure: true` for any of the listed exit codes, +and `allow_failure` false for any other exit code. + +**Keyword type**: Job keyword. You can use it only as part of a job. + +**Possible inputs**: + +- A single exit code. +- An array of exit codes. + +**Example of `allow_failure`**: ```yaml test_job_1: @@ -2017,7 +2025,7 @@ In this example, the script: **Additional details**: -- In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/201938) and later, you +- In [GitLab 13.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/201938), you can use `when:manual` in the same job as [`trigger`](#trigger). In GitLab 13.4 and earlier, using them together causes the error `jobs:#{job-name} when should be on_success, on_failure or always`. - The default behavior of `allow_failure` changes to `true` with `when: manual`. @@ -2136,7 +2144,7 @@ review_app: stage: deploy script: make deploy-app environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG url: https://$CI_ENVIRONMENT_SLUG.example.com on_stop: stop_review_app @@ -2147,7 +2155,7 @@ stop_review_app: script: make delete-app when: manual environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG action: stop ``` @@ -2197,7 +2205,7 @@ For example, review_app: script: deploy-review-app environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG auto_stop_in: 1 day ``` @@ -2267,12 +2275,12 @@ deploy as review app: stage: deploy script: make deploy environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG url: https://$CI_ENVIRONMENT_SLUG.example.com/ ``` The `deploy as review app` job is marked as a deployment to dynamically -create the `review/$CI_COMMIT_REF_NAME` environment. `$CI_COMMIT_REF_NAME` +create the `review/$CI_COMMIT_REF_SLUG` environment. `$CI_COMMIT_REF_SLUG` is a [CI/CD variable](../variables/index.md) set by the runner. The `$CI_ENVIRONMENT_SLUG` variable is based on the environment name, but suitable for inclusion in URLs. If the `deploy as review app` job runs in a branch named @@ -2301,7 +2309,7 @@ Use the `cache:paths` keyword to choose which files or directories to cache. You can use wildcards that use [glob](https://en.wikipedia.org/wiki/Glob_(programming)) patterns: -- In [GitLab Runner 13.0](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620) and later, +- In [GitLab Runner 13.0 and later](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620), [`doublestar.Glob`](https://pkg.go.dev/github.com/bmatcuk/doublestar@v1.2.2?tab=doc#Match). - In GitLab Runner 12.10 and earlier, [`filepath.Match`](https://pkg.go.dev/path/filepath#Match). @@ -2377,7 +2385,7 @@ cache-job: ##### `cache:key:files` -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) in GitLab v12.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) in GitLab 12.5. Use the `cache:key:files` keyword to generate a new key when one or two specific files change. `cache:key:files` lets you reuse some caches, and rebuild them less often, @@ -2415,7 +2423,7 @@ fallback key is `default`. ##### `cache:key:prefix` -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) in GitLab v12.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) in GitLab 12.5. Use `cache:key:prefix` to combine a prefix with the SHA computed for [`cache:key:files`](#cachekeyfiles). @@ -2864,7 +2872,7 @@ Paths are relative to the project directory (`$CI_PROJECT_DIR`) and can't direct link outside it. You can use Wildcards that use [glob](https://en.wikipedia.org/wiki/Glob_(programming)) patterns and: -- In [GitLab Runner 13.0](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620) and later, +- In [GitLab Runner 13.0 and later](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620), [`doublestar.Glob`](https://pkg.go.dev/github.com/bmatcuk/doublestar@v1.2.2?tab=doc#Match). - In GitLab Runner 12.10 and earlier, [`filepath.Match`](https://pkg.go.dev/path/filepath#Match). @@ -3120,7 +3128,7 @@ dashboards. ##### `artifacts:reports:load_performance` **(PREMIUM)** -> - Introduced in [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35260) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35260) in GitLab 13.2. > - Requires GitLab Runner 11.5 and above. The `load_performance` report collects [Load Performance Testing metrics](../../user/project/merge_requests/load_performance_testing.md) @@ -3163,7 +3171,7 @@ marked as Satisfied. ##### `artifacts:reports:sast` > - Introduced in GitLab 11.5. -> - Made [available in all tiers](https://gitlab.com/groups/gitlab-org/-/epics/2098) in GitLab 13.3. +> - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) from GitLab Ultimate to GitLab Free in 13.3. > - Requires GitLab Runner 11.5 and above. The `sast` report collects [SAST vulnerabilities](../../user/application_security/sast/index.md) @@ -3176,8 +3184,7 @@ dashboards. ##### `artifacts:reports:secret_detection` > - Introduced in GitLab 13.1. -> - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/222788) in GitLab - 13.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/222788) to GitLab Free in 13.3. > - Requires GitLab Runner 11.5 and above. The `secret-detection` report collects [detected secrets](../../user/application_security/secret_detection/index.md) @@ -3192,10 +3199,10 @@ dashboards. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207528) in GitLab 13.0. > - Requires [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 and above. -The `terraform` report obtains a Terraform `tfplan.json` file. [JQ processing required to remove credentials](../../user/infrastructure/mr_integration.md#configure-terraform-report-artifacts). The collected Terraform +The `terraform` report obtains a Terraform `tfplan.json` file. [JQ processing required to remove credentials](../../user/infrastructure/iac/mr_integration.md#configure-terraform-report-artifacts). The collected Terraform plan report uploads to GitLab as an artifact and displays in merge requests. For more information, see -[Output `terraform plan` information into a merge request](../../user/infrastructure/mr_integration.md). +[Output `terraform plan` information into a merge request](../../user/infrastructure/iac/mr_integration.md). #### `artifacts:untracked` @@ -3404,7 +3411,22 @@ You can specify the number of [retry attempts for certain stages of job executio > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14887) in GitLab 12.3. -Use `timeout` to configure a timeout for a specific job. For example: +Use `timeout` to configure a timeout for a specific job. If the job runs for longer +than the timeout, the job fails. + +The job-level timeout can be longer than the [project-level timeout](../pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run). +but can't be longer than the [runner's timeout](../runners/configure_runners.md#set-maximum-job-timeout-for-a-runner). + +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default:` section](#custom-default-keyword-values). + +**Possible inputs**: A period of time written in natural language. For example, these are all equivalent: + +- `3600 seconds` +- `60 minutes` +- `one hour` + +**Example of `timeout`**: ```yaml build: @@ -3416,10 +3438,6 @@ test: timeout: 3h 30m ``` -The job-level timeout can exceed the -[project-level timeout](../pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run) but can't -exceed the runner-specific timeout. - ### `parallel` > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21480) in GitLab 11.5. @@ -3583,7 +3601,7 @@ deploystacks: ### `trigger` -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8997) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8997) in GitLab Premium 11.8. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199224) to GitLab Free in 12.8. Use `trigger` to define a downstream pipeline trigger. When GitLab starts a `trigger` job, @@ -3598,11 +3616,11 @@ You can use this keyword to create two different types of downstream pipelines: - [Multi-project pipelines](../pipelines/multi_project_pipelines.md#define-multi-project-pipelines-in-your-gitlab-ciyml-file) - [Child pipelines](../pipelines/parent_child_pipelines.md) -[In GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/197140/) and later, you can +In [GitLab 13.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/197140/), you can view which job triggered a downstream pipeline. In the [pipeline graph](../pipelines/index.md#visualize-pipelines), hover over the downstream pipeline job. -In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/201938) and later, you +In [GitLab 13.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/201938), you can use [`when:manual`](#when) in the same job as `trigger`. In GitLab 13.4 and earlier, using them together causes the error `jobs:#{job-name} when should be on_success, on_failure or always`. You [cannot start `manual` trigger jobs with the API](https://gitlab.com/gitlab-org/gitlab/-/issues/284086). @@ -3756,25 +3774,19 @@ The trigger token is different than the [`trigger`](#trigger) keyword. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32022) in GitLab 12.3. -Use `interruptible` to indicate that a running job should be canceled if made redundant by a newer pipeline run. -Defaults to `false` (uninterruptible). Jobs that have not started yet (pending) are considered interruptible -and safe to be cancelled. -This value is used only if the [automatic cancellation of redundant pipelines feature](../pipelines/settings.md#auto-cancel-redundant-pipelines) -is enabled. - -When enabled, a pipeline is immediately canceled when a new pipeline starts on the same branch if either of the following is true: +Use `interruptible` if a job should be canceled when a newer pipeline starts before the job completes. -- All jobs in the pipeline are set as interruptible. -- Any uninterruptible jobs have not started yet. +This keyword is used with the [automatic cancellation of redundant pipelines](../pipelines/settings.md#auto-cancel-redundant-pipelines) +feature. When enabled, a running job with `interruptible: true` can be cancelled when +a new pipeline starts on the same branch. -Set jobs as interruptible that can be safely canceled once started (for instance, a build job). +You can't cancel subsequent jobs after a job with `interruptible: false` starts. -In the following example, a new pipeline run causes an existing running pipeline to be: +**Keyword type**: Job keyword. You can use it only as part of a job. -- Canceled, if only `step-1` is running or pending. -- Not canceled, once `step-2` starts running. +**Possible inputs**: `true` or `false` (default). -After an uninterruptible job starts running, the pipeline cannot be canceled. +**Example of `interruptible`**: ```yaml stages: @@ -3800,15 +3812,27 @@ step-3: interruptible: true ``` +In this example, a new pipeline causes a running pipeline to be: + +- Canceled, if only `step-1` is running or pending. +- Not canceled, after `step-2` starts. + +**Additional details**: + +- Only set `interruptible: true` if the job can be safely canceled after it has started, + like a build job. Deployment jobs usually shouldn't be cancelled, to prevent partial deployments. +- To completely cancel a running pipeline, all jobs must have `interruptible: true`, + or `interruptible: false` jobs must not have started. + ### `resource_group` > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15536) in GitLab 12.7. -Sometimes running multiple jobs or pipelines at the same time in an environment +Sometimes running multiple jobs at the same time in an environment can lead to errors during the deployment. To avoid these errors, use the `resource_group` attribute to make sure that -the runner doesn't run certain jobs simultaneously. Resource groups behave similar +the runner doesn't run certain jobs concurrently. Resource groups behave similar to semaphores in other programming languages. When the `resource_group` keyword is defined for a job in the `.gitlab-ci.yml` file, @@ -4333,15 +4357,12 @@ name level and not in the `vault` section. ### `pages` -Use `pages` to upload static content to GitLab. The content -is then published as a website. You must: +Use `pages` to define a [GitLab Pages](../../user/project/pages/index.md) job that +uploads static content to GitLab. The content is then published as a website. -- Place any static content in a `public/` directory. -- Define [`artifacts`](#artifacts) with a path to the `public/` directory. +**Keyword type**: Job name. -The following example moves all files from the root of the project to the -`public/` directory. The `.public` workaround is so `cp` does not also copy -`public/` to itself in an infinite loop: +**Example of `pages`**: ```yaml pages: @@ -4357,7 +4378,15 @@ pages: - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH ``` -View the [GitLab Pages user documentation](../../user/project/pages/index.md). +This example moves all files from the root of the project to the `public/` directory. +The `.public` workaround is so `cp` does not also copy `public/` to itself in an infinite loop. + +**Additional details**: + +You must: + +- Place any static content in a `public/` directory. +- Define [`artifacts`](#artifacts) with a path to the `public/` directory. ### `inherit` @@ -4481,7 +4510,7 @@ deploy_review_job: You can use only integers and strings for the variable's name and value. -If you define a variable at the top level of the `gitlab-ci.yml` file, it is global, +If you define a variable at the top level of the `.gitlab-ci.yml` file, it is global, meaning it applies to all jobs. If you define a variable in a job, it's available to that job only. @@ -4495,7 +4524,7 @@ You can use [YAML anchors for variables](#yaml-anchors-for-variables). ### Prefill variables in manual pipelines -> [Introduced in](https://gitlab.com/gitlab-org/gitlab/-/issues/30101) GitLab 13.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30101) in GitLab 13.7. Use the `value` and `description` keywords to define [pipeline-level (global) variables that are prefilled](../pipelines/index.md#prefill-variables-in-manual-pipelines) when [running a pipeline manually](../pipelines/index.md#run-a-pipeline-manually): @@ -4763,6 +4792,7 @@ into templates. ### `!reference` tags > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/266173) in GitLab 13.9. +> - `rules` keyword support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322992) in GitLab 14.3. Use the `!reference` custom YAML tag to select keyword configuration from other job sections and reuse it in the current section. Unlike [YAML anchors](#anchors), you can diff --git a/doc/ci/yaml/script.md b/doc/ci/yaml/script.md index 93c1a6afe69..626ede21fa5 100644 --- a/doc/ci/yaml/script.md +++ b/doc/ci/yaml/script.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Pipeline Execution +group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- diff --git a/doc/development/adding_service_component.md b/doc/development/adding_service_component.md index 503d1b7e55b..f5acf0d26eb 100644 --- a/doc/development/adding_service_component.md +++ b/doc/development/adding_service_component.md @@ -47,8 +47,7 @@ Adding a new service follows the same [merge request workflow](contributing/merg The first iteration should be to add the ability to connect and use the service as an externally installed component. Often this involves providing settings in GitLab to connect to the service, or allow connections from it. And then shipping documentation on how to install and configure the service with GitLab. -NOTE: -[Elasticsearch](../integration/elasticsearch.md#installing-elasticsearch) is an example of a service that has been integrated this way. And many of the other services, including internal projects like Gitaly, started off as separately installed alternatives. +[Elasticsearch](../integration/elasticsearch.md#install-elasticsearch) is an example of a service that has been integrated this way. Many of the other services, including internal projects like Gitaly, started off as separately installed alternatives. **For services that depend on the existing GitLab codebase:** diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md index 40cc8f5ec45..9a17ac4c813 100644 --- a/doc/development/api_graphql_styleguide.md +++ b/doc/development/api_graphql_styleguide.md @@ -532,7 +532,7 @@ Example: ```ruby field :foo, GraphQL::Types::String, null: true, - description: 'Some test field. Will always return `null`' \ + description: 'Some test field. Returns `null`' \ 'if `my_feature_flag` feature flag is disabled.' def foo @@ -940,7 +940,9 @@ class PostResolver < BaseResolver end ``` -You should never re-use resolvers directly. Resolvers have a complex life-cycle, with +While you can use the same resolver class in two different places, +such as in two different fields where the same object is exposed, +you should never re-use resolver objects directly. Resolvers have a complex life-cycle, with authorization, readiness and resolution orchestrated by the framework, and at each stage [lazy values](#laziness) can be returned to take advantage of batching opportunities. Never instantiate a resolver or a mutation in application code. diff --git a/doc/development/application_limits.md b/doc/development/application_limits.md index b606cda1124..2075e7cda3c 100644 --- a/doc/development/application_limits.md +++ b/doc/development/application_limits.md @@ -40,9 +40,7 @@ It's recommended to create two separate migration script files. desired limit using `create_or_update_plan_limit` migration helper, such as: ```ruby - class InsertProjectHooksPlanLimits < ActiveRecord::Migration[5.2] - include Gitlab::Database::MigrationHelpers - + class InsertProjectHooksPlanLimits < Gitlab::Database::Migration[1.0] def up create_or_update_plan_limit('project_hooks', 'default', 0) create_or_update_plan_limit('project_hooks', 'free', 10) diff --git a/doc/development/architecture.md b/doc/development/architecture.md index a487e84d090..fe2b621da29 100644 --- a/doc/development/architecture.md +++ b/doc/development/architecture.md @@ -603,14 +603,14 @@ For monitoring deployed apps, see [Jaeger tracing documentation](../operations/t - Layer: Core Service - Process: `logrotate` -GitLab is comprised of a large number of services that all log. We started bundling our own Logrotate -as of GitLab 7.4 to make sure we were logging responsibly. This is just a packaged version of the common open source offering. +GitLab is comprised of a large number of services that all log. We bundle our own Logrotate +to make sure we were logging responsibly. This is just a packaged version of the common open source offering. #### Mattermost - [Project page](https://github.com/mattermost/mattermost-server/blob/master/README.md) - Configuration: - - [Omnibus](https://docs.gitlab.com/omnibus/gitlab-mattermost/) + - [Omnibus](../integration/mattermost/index.md) - [Charts](https://docs.mattermost.com/install/install-mmte-helm-gitlab-helm.html) - Layer: Core Service (Processor) - GitLab.com: [Mattermost](../user/project/integrations/mattermost.md) diff --git a/doc/development/avoiding_downtime_in_migrations.md b/doc/development/avoiding_downtime_in_migrations.md index b844415c94e..9418eafa487 100644 --- a/doc/development/avoiding_downtime_in_migrations.md +++ b/doc/development/avoiding_downtime_in_migrations.md @@ -95,9 +95,7 @@ renaming. For example ```ruby # A regular migration in db/migrate -class RenameUsersUpdatedAtToUpdatedAtTimestamp < ActiveRecord::Migration[4.2] - include Gitlab::Database::MigrationHelpers - +class RenameUsersUpdatedAtToUpdatedAtTimestamp < Gitlab::Database::Migration[1.0] disable_ddl_transaction! def up @@ -125,9 +123,7 @@ We can perform this cleanup using ```ruby # A post-deployment migration in db/post_migrate -class CleanupUsersUpdatedAtRename < ActiveRecord::Migration[4.2] - include Gitlab::Database::MigrationHelpers - +class CleanupUsersUpdatedAtRename < Gitlab::Database::Migration[1.0] disable_ddl_transaction! def up @@ -174,9 +170,7 @@ as follows: ```ruby # A regular migration in db/migrate -class ChangeUsersUsernameStringToText < ActiveRecord::Migration[4.2] - include Gitlab::Database::MigrationHelpers - +class ChangeUsersUsernameStringToText < Gitlab::Database::Migration[1.0] disable_ddl_transaction! def up @@ -195,9 +189,7 @@ Next we need to clean up our changes using a post-deployment migration: ```ruby # A post-deployment migration in db/post_migrate -class ChangeUsersUsernameStringToTextCleanup < ActiveRecord::Migration[4.2] - include Gitlab::Database::MigrationHelpers - +class ChangeUsersUsernameStringToTextCleanup < Gitlab::Database::Migration[1.0] disable_ddl_transaction! def up @@ -245,9 +237,7 @@ the work / load over a longer time period, without slowing down deployments. For example, to change the column type using a background migration: ```ruby -class ExampleMigration < ActiveRecord::Migration[4.2] - include Gitlab::Database::MigrationHelpers - +class ExampleMigration < Gitlab::Database::Migration[1.0] disable_ddl_transaction! class Issue < ActiveRecord::Base @@ -289,9 +279,7 @@ release) by a cleanup migration, which should steal from the queue and handle any remaining rows. For example: ```ruby -class MigrateRemainingIssuesClosedAt < ActiveRecord::Migration[4.2] - include Gitlab::Database::MigrationHelpers - +class MigrateRemainingIssuesClosedAt < Gitlab::Database::Migration[1.0] disable_ddl_transaction! class Issue < ActiveRecord::Base diff --git a/doc/development/background_migrations.md b/doc/development/background_migrations.md index 695c565ca83..c93b5b448f0 100644 --- a/doc/development/background_migrations.md +++ b/doc/development/background_migrations.md @@ -254,7 +254,7 @@ existing data. Since we're dealing with a lot of rows we'll schedule jobs in batches instead of doing this one by one: ```ruby -class ScheduleExtractServicesUrl < ActiveRecord::Migration[4.2] +class ScheduleExtractServicesUrl < Gitlab::Database::Migration[1.0] disable_ddl_transaction! def up @@ -281,7 +281,7 @@ jobs and manually run on any un-migrated rows. Such a migration would look like this: ```ruby -class ConsumeRemainingExtractServicesUrlJobs < ActiveRecord::Migration[4.2] +class ConsumeRemainingExtractServicesUrlJobs < Gitlab::Database::Migration[1.0] disable_ddl_transaction! def up @@ -463,8 +463,6 @@ end ```ruby # Post deployment migration -include Gitlab::Database::MigrationHelpers - MIGRATION = 'YourBackgroundMigrationName' DELAY_INTERVAL = 2.minutes.to_i # can be different BATCH_SIZE = 10_000 # can be different @@ -494,8 +492,6 @@ You can reschedule pending migrations from the `background_migration_jobs` table ```ruby # Post deployment migration -include Gitlab::Database::MigrationHelpers - MIGRATION = 'YourBackgroundMigrationName' DELAY_INTERVAL = 2.minutes @@ -511,3 +507,16 @@ end ``` See [`db/post_migrate/20210604070207_retry_backfill_traversal_ids.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/db/post_migrate/20210604070207_retry_backfill_traversal_ids.rb) for a full example. + +### Viewing failure error logs + +After running a background migration, if any jobs have failed, you can view the logs in [Kibana](https://log.gprd.gitlab.net/goto/3afc1393447c401d7602c1874793e2f6). +View the production Sidekiq log and filter for: + +- `json.class: BackgroundMigrationWorker` +- `json.job_status: fail` +- `json.args: <MyBackgroundMigrationClassName>` + +Looking at the `json.error_class`, `json.error_message` and `json.error_backtrace` values may be helpful in understanding why the jobs failed. + +Depending on when and how the failure occurred, you may find other helpful information by filtering with `json.class: <MyBackgroundMigrationClassName>`. diff --git a/doc/development/cascading_settings.md b/doc/development/cascading_settings.md index d1c5756fa2c..0fa0e220ba9 100644 --- a/doc/development/cascading_settings.md +++ b/doc/development/cascading_settings.md @@ -38,9 +38,11 @@ Settings are not cascading by default. To define a cascading setting, take the f `application_settings`. ```ruby - class AddDelayedProjectRemovalCascadingSetting < ActiveRecord::Migration[6.0] + class AddDelayedProjectRemovalCascadingSetting < Gitlab::Database::Migration[1.0] include Gitlab::Database::MigrationHelpers::CascadingNamespaceSettings + enable_lock_retries! + def up add_cascading_namespace_setting :delayed_project_removal, :boolean, default: false, null: false end diff --git a/doc/development/changelog.md b/doc/development/changelog.md index c96fe2c18c1..be46d61eb4c 100644 --- a/doc/development/changelog.md +++ b/doc/development/changelog.md @@ -98,6 +98,7 @@ EE: true database records created during Cycle Analytics model spec." - _Any_ contribution from a community member, no matter how small, **may** have a changelog entry regardless of these guidelines if the contributor wants one. +- Any [GLEX experiment](experiment_guide/gitlab_experiment.md) changes **should not** have a changelog entry. - [Removing](feature_flags/#changelog) a feature flag, when the new code is retained. ## Writing good changelog entries diff --git a/doc/development/cicd/cicd_reference_documentation_guide.md b/doc/development/cicd/cicd_reference_documentation_guide.md index 33bc416d8bc..aa3888cd866 100644 --- a/doc/development/cicd/cicd_reference_documentation_guide.md +++ b/doc/development/cicd/cicd_reference_documentation_guide.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Pipeline Execution +group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/development/cicd/index.md b/doc/development/cicd/index.md index 76c756b0e95..b4e32066ba8 100644 --- a/doc/development/cicd/index.md +++ b/doc/development/cicd/index.md @@ -16,7 +16,7 @@ to learn how to update the [reference page](../../ci/yaml/index.md). ## CI Architecture overview -The following is a simplified diagram of the CI architecture. Some details are left out in order to focus on +The following is a simplified diagram of the CI architecture. Some details are left out to focus on the main components.  @@ -73,7 +73,7 @@ which picks the next job and assigns it to the runner. At this point the job tra For more details read [Job scheduling](#job-scheduling)). While a job is being executed, the runner sends logs back to the server as well any possible artifacts -that need to be stored. Also, a job may depend on artifacts from previous jobs in order to run. In this +that must be stored. Also, a job may depend on artifacts from previous jobs to run. In this case the runner downloads them using a dedicated API endpoint. Artifacts are stored in object storage, while metadata is kept in the database. An important example of artifacts @@ -111,7 +111,7 @@ Once all jobs are completed for the current stage, the server "unlocks" all the ### Communication between runner and GitLab server -Once the runner is [registered](https://docs.gitlab.com/runner/register/) using the registration token, the server knows what type of jobs it can execute. This depends on: +After the runner is [registered](https://docs.gitlab.com/runner/register/) using the registration token, the server knows what type of jobs it can execute. This depends on: - The type of runner it is registered as: - a shared runner @@ -119,7 +119,7 @@ Once the runner is [registered](https://docs.gitlab.com/runner/register/) using - a project specific runner - Any associated tags. -The runner initiates the communication by requesting jobs to execute with `POST /api/v4/jobs/request`. Although this polling generally happens every few seconds we leverage caching via HTTP headers to reduce the server-side work load if the job queue doesn't change. +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. This API endpoint runs [`Ci::RegisterJobService`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/services/ci/register_job_service.rb), which: diff --git a/doc/development/cicd/templates.md b/doc/development/cicd/templates.md index 03823a4b712..3fc464e661f 100644 --- a/doc/development/cicd/templates.md +++ b/doc/development/cicd/templates.md @@ -178,10 +178,10 @@ This includes: - Repository/project requirements. - Expected behavior. -- Any places that need to be edited by users before using the template. +- Any places that must be edited by users before using the template. - If the template should be used by copy pasting it into a configuration file, or by using it with the `include` keyword in an existing pipeline. -- If any variables need to be saved in the project's CI/CD settings. +- If any variables must be saved in the project's CI/CD settings. ```yaml # Use this template to publish an application that uses the ABC server. @@ -289,9 +289,9 @@ If the `latest` template does not exist yet, you can copy [the stable template]( ### How to include an older stable template Users may want to use an older [stable template](#stable-version) that is not bundled -in the current GitLab package. For example, the stable templates in GitLab v13.0 and -GitLab v14.0 could be so different that a user wants to continue using the v13.0 template even -after upgrading to GitLab 14.0. +in the current GitLab package. For example, the stable templates in GitLab 13.0 and +GitLab 14.0 could be so different that a user wants to continue using the GitLab 13.0 +template even after upgrading to GitLab 14.0. You can add a note in the template or in documentation explaining how to use `include:remote` to include older template versions. If other templates are included with `include: template`, @@ -335,7 +335,7 @@ follow the progress. ## Testing -Each CI/CD template must be tested in order to make sure that it's safe to be published. +Each CI/CD template must be tested to make sure that it's safe to be published. ### Manual QA @@ -380,7 +380,7 @@ is updated in a major version GitLab release. A template could contain malicious code. For example, a template that contains the `export` shell command in a job might accidentally expose secret project CI/CD variables in a job log. -If you're unsure if it's secure or not, you need to ask security experts for cross-validation. +If you're unsure if it's secure or not, you must ask security experts for cross-validation. ## Contribute CI/CD template merge requests diff --git a/doc/development/code_intelligence/index.md b/doc/development/code_intelligence/index.md index 790ba1539b7..e1e2105298c 100644 --- a/doc/development/code_intelligence/index.md +++ b/doc/development/code_intelligence/index.md @@ -37,7 +37,7 @@ sequenceDiagram 1. The CI/CD job generates a document in an LSIF format (usually `dump.lsif`) using [an indexer](https://lsif.dev) for the language of a project. The format - [describes](https://github.com/sourcegraph/sourcegraph/blob/master/doc/user/code_intelligence/writing_an_indexer.md) + [describes](https://github.com/sourcegraph/sourcegraph/blob/main/doc/code_intelligence/explanations/writing_an_indexer.md) interactions between a method or function and its definition(s) or references. The document is marked to be stored as an LSIF report artifact. diff --git a/doc/development/code_review.md b/doc/development/code_review.md index d66f246ac8c..12cc63ef56d 100644 --- a/doc/development/code_review.md +++ b/doc/development/code_review.md @@ -10,7 +10,7 @@ This guide contains advice and best practices for performing code review, and having your code reviewed. All merge requests for GitLab CE and EE, whether written by a GitLab team member -or a volunteer contributor, must go through a code review process to ensure the +or a wider community member, must go through a code review process to ensure the code is effective, understandable, maintainable, and secure. ## Getting your merge request reviewed, approved, and merged @@ -35,7 +35,7 @@ If you need assistance with security scans or comments, feel free to include the Application Security Team (`@gitlab-com/gl-security/appsec`) in the review. Depending on the areas your merge request touches, it must be **approved** by one -or more [maintainers](https://about.gitlab.com/handbook/engineering/workflow/code-review/#maintainer): +or more [maintainers](https://about.gitlab.com/handbook/engineering/workflow/code-review/#maintainer). For approvals, we use the approval functionality found in the merge request widget. For reviewers, we use the [reviewer functionality](../user/project/merge_requests/getting_started.md#reviewer) in the sidebar. @@ -46,9 +46,11 @@ more than one approval, the last maintainer to review and approve merges it. ### Domain experts -Domain experts are team members who have substantial experience with a specific technology, product feature or area of the codebase. Team members are encouraged to self-identify as domain experts and add it to their [team profile](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/data/team.yml). +Domain experts are team members who have substantial experience with a specific technology, +product feature, or area of the codebase. Team members are encouraged to self-identify as +domain experts and add it to their [team profiles](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/data/team_members/person/README.md). -When self-identifying as a domain expert, it is recommended to assign the MR changing the `team.yml` to be merged by an already established Domain Expert or a corresponding Engineering Manager. +When self-identifying as a domain expert, it is recommended to assign the MR changing the `.yml` file to be merged by an already established Domain Expert or a corresponding Engineering Manager. We make the following assumption with regards to automatically being considered a domain expert: @@ -107,7 +109,7 @@ with [domain expertise](#domain-experts). 1. If your merge request includes adding a new JavaScript library (*1*)... - If the library significantly increases the [bundle size](https://gitlab.com/gitlab-org/frontend/playground/webpack-memory-metrics/-/blob/master/doc/report.md), it must - be **approved by a [frontend foundations member](https://about.gitlab.com/direction/create/ecosystem/frontend-ux-foundations/)**. + be **approved by a [frontend foundations member](https://about.gitlab.com/direction/ecosystem/foundations/)**. - If the license used by the new library hasn't been approved for use in GitLab, the license must be **approved by a [legal department member](https://about.gitlab.com/handbook/legal/)**. More information about license compatibility can be found in our @@ -117,11 +119,12 @@ with [domain expertise](#domain-experts). 1. If your merge request includes documentation changes, it must be **approved by a [Technical writer](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments)**, based on assignments in the appropriate [DevOps stage group](https://about.gitlab.com/handbook/product/categories/#devops-stages). +1. If your merge request includes changes to development guidelines, follow the [review process](index.md#development-guidelines-review) and get the approvals accordingly. 1. If your merge request includes end-to-end **and** non-end-to-end changes (*4*), it must be **approved by a [Software Engineer in Test](https://about.gitlab.com/handbook/engineering/quality/#individual-contributors)**. 1. If your merge request only includes end-to-end changes (*4*) **or** if the MR author is a [Software Engineer in Test](https://about.gitlab.com/handbook/engineering/quality/#individual-contributors), it must be **approved by a [Quality maintainer](https://about.gitlab.com/handbook/engineering/projects/#gitlab_maintainers_qa)** 1. If your merge request includes a new or updated [application limit](https://about.gitlab.com/handbook/product/product-processes/#introducing-application-limits), it must be **approved by a [product manager](https://about.gitlab.com/company/team/)**. -1. If your merge request includes Product Intelligence (telemetry or analytics) changes, it should be reviewed and approved by a [Product Intelligence engineer](https://gitlab.com/gitlab-org/growth/product_intelligence/engineers). +1. If your merge request includes Product Intelligence (telemetry or analytics) changes, it should be reviewed and approved by a [Product Intelligence engineer](https://gitlab.com/gitlab-org/growth/product-intelligence/engineers). 1. If your merge request includes an addition of, or changes to a [Feature spec](testing_guide/testing_levels.md#frontend-feature-tests), it must be **approved by a [Quality maintainer](https://about.gitlab.com/handbook/engineering/projects/#gitlab_maintainers_qa) or [Quality reviewer](https://about.gitlab.com/handbook/engineering/projects/#gitlab_reviewers_qa)**. 1. If your merge request introduces a new service to GitLab (Puma, Sidekiq, Gitaly are examples), it must be **approved by a [product manager](https://about.gitlab.com/company/team/)**. See the [process for adding a service component to GitLab](adding_service_component.md) for details. @@ -134,15 +137,60 @@ with [domain expertise](#domain-experts). the content. - (*4*): End-to-end changes include all files within the `qa` directory. -#### Security requirements +#### Acceptance checklist -View the updated documentation regarding [internal application security reviews](https://about.gitlab.com/handbook/engineering/security/#internal-application-security-reviews) for **when** and **how** to request a security review. +This checklist encourages the authors, reviewers, and maintainers of merge requests (MRs) to confirm changes were analyzed for high-impact risks to quality, performance, reliability, security, and maintainability. + +Using checklists improves quality in software engineering. This checklist is a straightforward tool to support and bolster the skills of contributors to the GitLab codebase. + +##### Quality + +See the [test engineering process](https://about.gitlab.com/handbook/engineering/quality/test-engineering/) for further quality guidelines. + +1. I have self-reviewed this MR per [code review guidelines](code_review.md). +1. For the code that this change impacts, I believe that the automated tests ([Testing Guide](testing_guide/index.md)) validate functionality that is highly important to users (including consideration of [all test levels](testing_guide/testing_levels.md)). +1. If the existing automated tests do not cover the above functionality, I have added the necessary additional tests or added an issue to describe the automation testing gap and linked it to this MR. +1. I have considered the technical aspects of this change's impact on GitLab.com hosted customers and self-managed customers. +1. I have considered the impact of this change on the frontend, backend, and database portions of the system where appropriate and applied the `~frontend`, `~backend`, and `~database` labels accordingly. +1. I have tested this MR in [all supported browsers](../install/requirements.md#supported-web-browsers), or determined that this testing is not needed. +1. I have confirmed that this change is [backwards compatible across updates](multi_version_compatibility.md), or I have decided that this does not apply. +1. I have properly separated EE content from FOSS, or this MR is FOSS only. + - [Where should EE code go?](ee_features.md#separation-of-ee-code) +1. If I am introducing a new expectation for existing data, I have confirmed that existing data meets this expectation or I have made this expectation optional rather than required. + +##### Performance, reliability, and availability + +1. I am confident that this MR does not harm performance, or I have asked a reviewer to help assess the performance impact. ([Merge request performance guidelines](merge_request_performance_guidelines.md)) +1. I have added [information for database reviewers in the MR description](database_review.md#required), or I have decided that it is unnecessary. + - [Does this MR have database-related changes?](database_review.md) +1. I have considered the availability and reliability risks of this change. +1. I have considered the scalability risk based on future predicted growth. +1. I have considered the performance, reliability, and availability impacts of this change on large customers who may have significantly more data than the average customer. + +##### Documentation + +1. I have included changelog trailers, or I have decided that they are not needed. + - [Does this MR need a changelog?](changelog.md#what-warrants-a-changelog-entry) +1. I have added/updated documentation or decided that documentation changes are unnecessary for this MR. + - [Is documentation required?](https://about.gitlab.com/handbook/engineering/ux/technical-writing/workflow/#when-documentation-is-required) + +##### Security + +1. I have confirmed that if this MR contains changes to processing or storing of credentials or tokens, authorization, and authentication methods, or other items described in [the security review guidelines](https://about.gitlab.com/handbook/engineering/security/#when-to-request-a-security-review), I have added the `~security` label and I have `@`-mentioned `@gitlab-com/gl-security/appsec`. +1. I have reviewed the documentation regarding [internal application security reviews](https://about.gitlab.com/handbook/engineering/security/#internal-application-security-reviews) for **when** and **how** to request a security review and requested a security review if this is warranted for this change. + +##### Deployment + +1. I have considered using a feature flag for this change because the change may be high risk. +1. If I am using a feature flag, I plan to test the change in staging before I test it in production, and I have considered rolling it out to a subset of production customers before rolling it out to all customers. + - [When to use a feature flag](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/#when-to-use-feature-flags) +1. I have informed the Infrastructure department of a default setting or new setting change per [definition of done](contributing/merge_request_workflow.md#definition-of-done), or decided that this is unnecessary. ### The responsibility of the merge request author The responsibility to find the best solution and implement it lies with the merge request author. The author or [directly responsible individual](https://about.gitlab.com/handbook/people-group/directly-responsible-individuals/) -will stay assigned to the merge request as the assignee throughout +(DRI) stays assigned to the merge request as the assignee throughout the code review lifecycle. If you are unable to set yourself as an assignee, ask a [reviewer](https://about.gitlab.com/handbook/engineering/workflow/code-review/#reviewer) to do this for you. Before requesting a review from a maintainer to approve and merge, they @@ -169,7 +217,7 @@ database specialists to get input on the data model or specific queries, or to any other developer to get an in-depth review of the solution. If an author is unsure if a merge request needs a [domain expert's](#domain-experts) opinion, -that indicates it does. Without it it's unlikely they have the required level of confidence in their +then that indicates it does. Without it, it's unlikely they have the required level of confidence in their solution. Before the review, the author is requested to submit comments on the merge @@ -249,7 +297,7 @@ without duly verifying them. Note that certain Merge Requests may target a stable branch. These are rare events. These types of Merge Requests cannot be merged by the Maintainer. -Instead these should be sent to the [Release Manager](https://about.gitlab.com/community/release-managers/). +Instead, these should be sent to the [Release Manager](https://about.gitlab.com/community/release-managers/). After merging, a maintainer should stay as the reviewer listed on the merge request. @@ -305,8 +353,8 @@ first time. codebase. Thorough descriptions help all reviewers understand your request and test effectively. - If you know your change depends on another being merged first, note it in the - description and set an [merge request dependency](../user/project/merge_requests/merge_request_dependencies.md). -- Be grateful for the reviewer's suggestions. (`Good call. I'll make that change.`) + description and set a [merge request dependency](../user/project/merge_requests/merge_request_dependencies.md). +- Be grateful for the reviewer's suggestions. ("Good call. I'll make that change.") - Don't take it personally. The review is of the code, not of you. - Explain why the code exists. ("It's like that because of these reasons. Would it be more clear if I rename this class/file/method/variable?") @@ -425,20 +473,20 @@ WARNING: - Start a new merge request pipeline with the `Run pipeline` button in the merge request's "Pipelines" tab, and enable "Merge When Pipeline Succeeds" (MWPS). Note that: - - If **[main is broken](https://about.gitlab.com/handbook/engineering/workflow/#broken-master), + - If **[the default branch is broken](https://about.gitlab.com/handbook/engineering/workflow/#broken-master), do not merge the merge request** except for [very specific cases](https://about.gitlab.com/handbook/engineering/workflow/#criteria-for-merging-during-broken-master). For other cases, follow these [handbook instructions](https://about.gitlab.com/handbook/engineering/workflow/#merging-during-broken-master). - If the latest pipeline was created before the merge request was approved, start a new pipeline to ensure that full RSpec suite has been run. You may skip this step only if the merge request does not contain any backend change. - If the **latest [Pipeline for Merged Results](../ci/pipelines/pipelines_for_merged_results.md)** finished less than 2 hours ago, you - might merge without starting a new pipeline as the merge request is close + may merge without starting a new pipeline as the merge request is close enough to `main`. - When you set the MR to "Merge When Pipeline Succeeds", you should take over subsequent revisions for anything that would be spotted after that. - For merge requests that have had [Squash and merge](../user/project/merge_requests/squash_and_merge.md#squash-and-merge) set, - the squashed commit’s default commit message is taken from the merge request title. - You're encouraged to [select a commit with a more informative commit message](../user/project/merge_requests/squash_and_merge.md#overview) before merging. + the squashed commit's default commit message is taken from the merge request title. + You're encouraged to [select a commit with a more informative commit message](../user/project/merge_requests/squash_and_merge.md) before merging. Thanks to **Pipeline for Merged Results**, authors no longer have to rebase their branch as frequently anymore (only when there are conflicts) because the Merge @@ -526,7 +574,7 @@ author. GitLab is used in a lot of places. Many users use our [Omnibus packages](https://about.gitlab.com/install/), but some use -the [Docker images](https://docs.gitlab.com/omnibus/docker/), some are +the [Docker images](../install/docker.md), some are [installed from source](../install/installation.md), and there are other installation methods available. GitLab.com itself is a large Enterprise Edition instance. This has some implications: @@ -566,7 +614,7 @@ Enterprise Edition instance. This has some implications: 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.html#adding-a-new-setting-to-gitlab-yml). + [added to Omnibus](https://docs.gitlab.com/omnibus/settings/gitlab.yml#adding-a-new-setting-to-gitlabyml). 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.md). @@ -613,7 +661,7 @@ A merge request may benefit from being considered a customer critical priority b Properties of customer critical merge requests: -- The [VP of Development](https://about.gitlab.com/job-families/engineering/development/management/vp) ([@clefelhocz1](https://gitlab.com/clefelhocz1)) is the DRI for deciding if a merge request qualifies as customer critical. +- The [VP of Development](https://about.gitlab.com/job-families/engineering/development/management/vp/) ([@clefelhocz1](https://gitlab.com/clefelhocz1)) is the DRI for deciding if a merge request qualifies as customer critical. - The DRI applies the `customer-critical-merge-request` label to the merge request. - It is required that the reviewer(s) and maintainer(s) involved with a customer critical merge request are engaged as soon as this decision is made. - It is required to prioritize work for those involved on a customer critical merge request so that they have the time available necessary to focus on it. @@ -650,7 +698,3 @@ A good example of collaboration on an MR touching multiple parts of the codebase ### Credits Largely based on the [`thoughtbot` code review guide](https://github.com/thoughtbot/guides/tree/master/code-review). - ---- - -[Return to Development documentation](index.md) diff --git a/doc/development/contributing/community_roles.md b/doc/development/contributing/community_roles.md index 3804aa7f8a8..37c3c24a7d1 100644 --- a/doc/development/contributing/community_roles.md +++ b/doc/development/contributing/community_roles.md @@ -16,7 +16,3 @@ GitLab community members and their privileges/responsibilities. | Contributor | Can make contributions to all GitLab public projects | Have a GitLab.com account | [List of current reviewers/maintainers](https://about.gitlab.com/handbook/engineering/projects/#gitlab-ce). - ---- - -[Return to Contributing documentation](index.md) diff --git a/doc/development/contributing/design.md b/doc/development/contributing/design.md index c1dd5ff4c0b..9e8375fcbdd 100644 --- a/doc/development/contributing/design.md +++ b/doc/development/contributing/design.md @@ -11,32 +11,28 @@ For guidance on UX implementation at GitLab, please refer to our [Design System] The UX team uses labels to manage their workflow. -The ~"UX" label on an issue is a signal to the UX team that it will need UX attention. +The `~UX` label on an issue is a signal to the UX team that it will need UX attention. To better understand the priority by which UX tackles issues, see the [UX section](https://about.gitlab.com/handbook/engineering/ux/) of the handbook. -Once an issue has been worked on and is ready for development, a UXer removes the ~"UX" label and applies the ~"UX ready" label to that issue. +Once an issue has been worked on and is ready for development, a UXer removes the `~UX` label and applies the `~"UX ready"` label to that issue. -There is a special type label called ~"product discovery" intended for UX, -PM, FE, and BE. It represents a discovery issue to discuss the problem and +There is a special type label called `~"product discovery"` intended for UX (user experience), +PM (product manager), FE (frontend), and BE (backend). It represents a discovery issue to discuss the problem and potential solutions. The final output for this issue could be a doc of requirements, a design artifact, or even a prototype. The solution will be developed in a subsequent milestone. -~"product discovery" issues are like any other issue and should contain a milestone label, ~"Deliverable" or ~"Stretch", when scheduled in the current milestone. +`~"product discovery"` issues are like any other issue and should contain a milestone label, `~Deliverable` or `~Stretch`, when scheduled in the current milestone. The initial issue should be about the problem we are solving. If a separate [product discovery issue](https://about.gitlab.com/handbook/engineering/ux/ux-department-workflow/#how-we-use-labels) is needed for additional research and design work, it will be created by a PM or UX person. -Assign the ~UX, ~"product discovery" and ~"Deliverable" labels, add a milestone and +Assign the `~UX`, `~"product discovery"` and `~Deliverable` labels, add a milestone and use a title that makes it clear that the scheduled issue is product discovery (for example, `Product discovery for XYZ`). In order to complete a product discovery issue in a release, you must complete the following: -1. UXer removes the ~UX label, adds the ~"UX ready" label. +1. UXer removes the `~UX` label, adds the `~"UX ready"` label. 1. Modify the issue description in the product discovery issue to contain the final design. If it makes sense, the original information indicating the need for the design can be moved to a lower "Original Information" section. 1. Copy the design to the description of the delivery issue for which the product discovery issue was created. Do not simply refer to the product discovery issue as a separate source of truth. 1. In some cases, a product discovery issue also identifies future enhancements that will not go into the issue that originated the product discovery issue. For these items, create new issues containing the designs to ensure they are not lost. Put the issues in the backlog if they are agreed upon as good ideas. Otherwise leave them for triage. - ---- - -[Return to Contributing documentation](index.md) diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index 1dfe560d68d..29f6eb57160 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -15,9 +15,7 @@ feature proposal. Show your support with an award emoji and/or join the discussion. 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 parenthesis is there to help you with what to include. Omit it -when submitting the actual issue. You can copy-paste it and then edit as you -see fit. +The text in the comments (`<!-- ... -->`) is there to help you with what to include. ## Issue triaging @@ -30,12 +28,12 @@ The most important thing is making sure valid issues receive feedback from the development team. Therefore the priority is mentioning developers that can help on those issues. Please select someone with relevant experience from the [GitLab team](https://about.gitlab.com/company/team/). -If there is nobody mentioned with that expertise look in the commit history for +If there is nobody mentioned with that expertise, look in the commit history for the affected files to find someone. We also use [GitLab Triage](https://gitlab.com/gitlab-org/gitlab-triage) to automate some triaging policies. This is currently set up as a scheduled pipeline -(`https://gitlab.com/gitlab-org/quality/triage-ops/pipeline_schedules/10512/editpipeline_schedules/10512/edit`, +(`https://gitlab.com/gitlab-org/quality/triage-ops/-/pipeline_schedules/10512/edit`, must have at least the Developer role in the project) running on [quality/triage-ops](https://gitlab.com/gitlab-org/quality/triage-ops) project. @@ -132,9 +130,9 @@ their color is `#A8D695`. <https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/stages.yml>, with `_` replaced with a space. -For instance, the "Continuous Integration" group is represented by the -~"group::continuous integration" label in the `gitlab-org` group since its key -under `stages.manage.groups` is `continuous_integration`. +For instance, the "Pipeline Execution" group is represented by the +~"group::pipeline execution" label in the `gitlab-org` group since its key +under `stages.manage.groups` is `pipeline_execution`. The current group labels can be found by [searching the labels list for `group::`](https://gitlab.com/groups/gitlab-org/-/labels?search=group::). @@ -146,17 +144,6 @@ You can find the groups listed in the [Product Stages, Groups, and Categories](h We use the term group to map down product requirements from our product stages. As a team needs some way to collect the work their members are planning to be assigned to, we use the `~group::` labels to do so. -Normally there is a 1:1 relationship between Stage labels and Group labels. In -the spirit of "Everyone can contribute", any issue can be picked up by any group, -depending on current priorities. When picking up an issue belonging to a different -group, it should be relabeled. For example, if an issue labeled `~"devops::create"` -and `~"group::knowledge"` is picked up by someone in the Access group of the Plan stage, -the issue should be relabeled as `~"group::access"` while keeping the original -`~"devops::create"` unchanged. - -We also use stage and group labels to help measure our [merge request rates](https://about.gitlab.com/handbook/engineering/metrics/#merge-request-rate). -Please read [Stage and Group labels](https://about.gitlab.com/handbook/engineering/metrics/#stage-and-group-labels) for more information on how the labels are used in this context. - ### Category labels From the handbook's @@ -384,7 +371,7 @@ below will make it easy to manage this, without unnecessary overhead. 1. If you don't agree with a set weight, discuss with other developers until consensus is reached about the weight 1. Issue weights are an abstract measurement of complexity of the issue. Do not - relate issue weight directly to time. This is called [anchoring](https://en.wikipedia.org/wiki/Anchoring) + relate issue weight directly to time. This is called [anchoring](https://en.wikipedia.org/wiki/Anchoring_(cognitive_bias)) and something you want to avoid. 1. Something that has a weight of 1 (or no weight) is really small and simple. Something that is 9 is rewriting a large fundamental part of GitLab, @@ -476,7 +463,3 @@ should be of the same quality as those created [in the usual manner](#technical-and-ux-debt) - in particular, the issue title **must not** begin with `Follow-up`! The creating maintainer should also expect to be involved in some capacity when work begins on the follow-up issue. - ---- - -[Return to Contributing documentation](index.md) diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index 534150e4d37..25561764bd6 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -223,11 +223,19 @@ the contribution acceptance criteria below: ## Definition of done -If you contribute to GitLab please know that changes involve more than just +If you contribute to GitLab, please know that changes involve more than just code. We use the following [definition of done](https://www.agilealliance.org/glossary/definition-of-done). -Your contribution is not *done* until you have made sure it meets all of these +To reach the definition of done, the merge request must create no regressions and meet all these criteria: + +- Verified as working in production on GitLab.com. +- Verified as working for self-managed instances. + +If a regression occurs, we prefer you revert the change. We break the definition of done into two phases: [MR Merge](#mr-merge) and [Production use](#production-use). +Your contribution is *incomplete* until you have made sure it meets all of these requirements. +### MR Merge + 1. Clear description explaining the relevancy of the contribution. 1. Working and clean code that is commented where needed. 1. [Unit, integration, and system tests](../testing_guide/index.md) that all pass @@ -238,17 +246,30 @@ requirements. 1. [Secure coding guidelines](https://gitlab.com/gitlab-com/gl-security/security-guidelines) have been followed. 1. [Documented](../documentation/index.md) in the `/doc` directory. 1. [Changelog entry added](../changelog.md), if necessary. -1. Reviewed by relevant reviewers and all concerns are addressed for Availability, Regressions, Security. Documentation reviews should take place as soon as possible, but they should not block a merge request. -1. Merged by a project maintainer. +1. Reviewed by relevant reviewers, and all concerns are addressed for Availability, Regressions, and Security. Documentation reviews should take place as soon as possible, but they should not block a merge request. +1. The [MR acceptance checklist](../code_review.md#acceptance-checklist) has been checked as confirmed in the MR. 1. Create an issue in the [infrastructure issue tracker](https://gitlab.com/gitlab-com/gl-infra/infrastructure/-/issues) to inform the Infrastructure department when your contribution is changing default settings or introduces a new setting, if relevant. -1. Confirmed to be working in the [Canary stage](https://about.gitlab.com/handbook/engineering/#canary-testing) with no new [Sentry](https://about.gitlab.com/handbook/engineering/#sentry) errors or on GitLab.com once the contribution is deployed. -1. Added to the [release post](https://about.gitlab.com/handbook/marketing/blog/release-posts/), - if relevant. -1. Added to [the website](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/features.yml), if relevant. 1. [Black-box tests/end-to-end tests](../testing_guide/testing_levels.md#black-box-tests-at-the-system-level-aka-end-to-end-tests) added if required. Please contact [the quality team](https://about.gitlab.com/handbook/engineering/quality/#teams) with any questions. +1. The change is tested in a review app where possible and if appropriate. 1. The new feature does not degrade the user experience of the product. +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. An agreed-upon rollout plan. +1. Merged by a project maintainer. + +### Production use + +1. Confirmed to be working in staging before implementing the change in production, where possible. +1. Confirmed to be working in the production with no new [Sentry](https://about.gitlab.com/handbook/engineering/#sentry) errors after the contribution is deployed. +1. Confirmed that the rollout plan has been completed. +1. If there is a performance risk in the change, I have analyzed the performance of the system before and after the change. +1. *If the merge request uses feature flags, per-project or per-group enablement, and a staged rollout:* + - Confirmed to be working on GitLab projects. + - Confirmed to be working at each stage for all projects added. +1. Added to the [release post](https://about.gitlab.com/handbook/marketing/blog/release-posts/), + if relevant. +1. Added to [the website](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/features.yml), if relevant. Contributions do not require approval from the [Product team](https://about.gitlab.com/handbook/product/product-processes/#gitlab-pms-arent-the-arbiters-of-community-contributions). diff --git a/doc/development/contributing/style_guides.md b/doc/development/contributing/style_guides.md index 1b339b7f252..754e6c7aec6 100644 --- a/doc/development/contributing/style_guides.md +++ b/doc/development/contributing/style_guides.md @@ -177,11 +177,10 @@ This ensures that our list isn't mistakenly removed by another auto generation o the `.rubocop_todo.yml`. This also allows us greater visibility into the exceptions which are currently being resolved. -One way to generate the initial list is to run the `todo` auto generation, -with `exclude limit` set to a high number. +One way to generate the initial list is to run the Rake task `rubocop:todo:generate`: ```shell -bundle exec rubocop --auto-gen-config --auto-gen-only-exclude --exclude-limit=100000 +bundle exec rake rubocop:todo:generate ``` You can then move the list from the freshly generated `.rubocop_todo.yml` for the Cop being actively @@ -242,7 +241,3 @@ See the dedicated [Python Development Guidelines](../python_guide/index.md). ## Misc Code should be written in [US English](https://en.wikipedia.org/wiki/American_English). - ---- - -[Return to Contributing documentation](index.md) 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 f83dc35b4a6..d74f826cc14 100644 --- a/doc/development/database/add_foreign_key_to_existing_column.md +++ b/doc/development/database/add_foreign_key_to_existing_column.md @@ -4,11 +4,17 @@ group: Database info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Adding foreign key constraint to an existing column +# Add a foreign key constraint to an existing column -Foreign keys help ensure consistency between related database tables. The current database review process **always** encourages you to add [foreign keys](../foreign_keys.md) when creating tables that reference records from other tables. +Foreign keys ensure consistency between related database tables. The current database review process **always** encourages you to add [foreign keys](../foreign_keys.md) when creating tables that reference records from other tables. -Starting with Rails version 4, Rails includes migration helpers to add foreign key constraints to database tables. Before Rails 4, the only way for ensuring some level of consistency was the [`dependent`](https://guides.rubyonrails.org/association_basics.html#options-for-belongs-to-dependent) option within the association definition. Ensuring data consistency on the application level could fail in some unfortunate cases, so we might end up with inconsistent data in the table. This is mostly affecting older tables, where we simply didn't have the framework support to ensure consistency on the database level. These data inconsistencies can easily cause unexpected application behavior or bugs. +Starting with Rails version 4, Rails includes migration helpers to add foreign key constraints +to database tables. Before Rails 4, the only way for ensuring some level of consistency was the +[`dependent`](https://guides.rubyonrails.org/association_basics.html#options-for-belongs-to-dependent) +option in the association definition. Ensuring data consistency on the application level could fail +in some unfortunate cases, so we might end up with inconsistent data in the table. This mostly affects +older tables, where we didn't have the framework support to ensure consistency on the database level. +These data inconsistencies can cause unexpected application behavior or bugs. Adding a foreign key to an existing database column requires database structure changes and potential data changes. In case the table is in use, we should always assume that there is inconsistent data. @@ -45,7 +51,7 @@ class Email < ActiveRecord::Base end ``` -Problem: when the user is removed, the email records related to the removed user will stay in the `emails` table: +Problem: when the user is removed, the email records related to the removed user stays in the `emails` table: ```ruby user = User.find(1) @@ -66,9 +72,7 @@ In the example above, you'd be still able to update records in the `emails` tabl Migration file for adding `NOT VALID` foreign key: ```ruby -class AddNotValidForeignKeyToEmailsUser < ActiveRecord::Migration[5.2] - include Gitlab::Database::MigrationHelpers - +class AddNotValidForeignKeyToEmailsUser < Gitlab::Database::Migration[1.0] def up # safe to use: it requires short lock on the table since we don't validate the foreign key add_foreign_key :emails, :users, on_delete: :cascade, validate: false @@ -85,16 +89,16 @@ Avoid using the `add_foreign_key` constraint more than once per migration file, #### Data migration to fix existing records -The approach here depends on the data volume and the cleanup strategy. If we can easily find "invalid" records by doing a simple database query and the record count is not that high, then the data migration can be executed within a Rails migration. +The approach here depends on the data volume and the cleanup strategy. If we can find "invalid" +records by doing a database query and the record count is not high, then the data migration can +be executed in a Rails migration. In case the data volume is higher (>1000 records), it's better to create a background migration. If unsure, please contact the database team for advice. -Example for cleaning up records in the `emails` table within a database migration: +Example for cleaning up records in the `emails` table in a database migration: ```ruby -class RemoveRecordsWithoutUserFromEmailsTable < ActiveRecord::Migration[5.2] - include Gitlab::Database::MigrationHelpers - +class RemoveRecordsWithoutUserFromEmailsTable < Gitlab::Database::Migration[1.0] disable_ddl_transaction! class Email < ActiveRecord::Base @@ -116,7 +120,7 @@ end ### Validate the foreign key -Validating the foreign key will scan the whole table and make sure that each relation is correct. +Validating the foreign key scans the whole table and makes sure that each relation is correct. NOTE: When using [background migrations](../background_migrations.md), foreign key validation should happen in the next GitLab release. @@ -126,9 +130,7 @@ Migration file for validating the foreign key: ```ruby # frozen_string_literal: true -class ValidateForeignKeyOnEmailUsers < ActiveRecord::Migration[5.2] - include Gitlab::Database::MigrationHelpers - +class ValidateForeignKeyOnEmailUsers < Gitlab::Database::Migration[1.0] def up validate_foreign_key :emails, :user_id end diff --git a/doc/development/database/constraint_naming_convention.md b/doc/development/database/constraint_naming_convention.md index 3faef8aee09..a22ddc1551c 100644 --- a/doc/development/database/constraint_naming_convention.md +++ b/doc/development/database/constraint_naming_convention.md @@ -6,7 +6,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Constraints naming conventions -The most common option is to let Rails pick the name for database constraints and indexes or let PostgreSQL use the defaults (when applicable). However, when needing to define custom names in Rails or working in Go applications where no ORM is used, it is important to follow strict naming conventions to improve consistency and discoverability. +The most common option is to let Rails pick the name for database constraints and indexes or let +PostgreSQL use the defaults (when applicable). However, when defining custom names in Rails, or +working in Go applications where no ORM is used, it is important to follow strict naming conventions +to improve consistency and discoverability. The table below describes the naming conventions for custom PostgreSQL constraints. The intent is not to retroactively change names in existing databases but rather ensure consistency of future changes. diff --git a/doc/development/database/database_reviewer_guidelines.md b/doc/development/database/database_reviewer_guidelines.md index 7a9c08d9d49..59653c6dde3 100644 --- a/doc/development/database/database_reviewer_guidelines.md +++ b/doc/development/database/database_reviewer_guidelines.md @@ -19,7 +19,7 @@ Database reviewers are domain experts who have substantial experience with datab A database review is required whenever an application update [touches the database](../database_review.md#general-process). The database reviewer is tasked with reviewing the database specific updates and -making sure that any queries or modifications will perform without issues +making sure that any queries or modifications perform without issues at the scale of GitLab.com. For more information on the database review process, check the [database review guidelines](../database_review.md). @@ -72,7 +72,7 @@ topics and use cases. The most frequently required during database reviewing are - [Avoiding downtime in migrations](../avoiding_downtime_in_migrations.md). - [SQL guidelines](../sql.md) for working with SQL queries. -## How to apply for becoming a database maintainer +## How to apply to become a database maintainer Once a database reviewer feels confident on switching to a database maintainer, they can update their [team profile](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/data/team.yml) diff --git a/doc/development/database/efficient_in_operator_queries.md b/doc/development/database/efficient_in_operator_queries.md new file mode 100644 index 00000000000..bc72bce30bf --- /dev/null +++ b/doc/development/database/efficient_in_operator_queries.md @@ -0,0 +1,949 @@ +--- +stage: Enablement +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Efficient `IN` operator queries + +This document describes a technique for building efficient ordered database queries with the `IN` +SQL operator and the usage of a GitLab utility module to help apply the technique. + +NOTE: +The described technique makes heavy use of +[keyset pagination](pagination_guidelines.md#keyset-pagination). +It's advised to get familiar with the topic first. + +## Motivation + +In GitLab, many domain objects like `Issue` live under nested hierarchies of projects and groups. +To fetch nested database records for domain objects at the group-level, +we often perform queries with the `IN` SQL operator. +We are usually interested in ordering the records by some attributes +and limiting the number of records using `ORDER BY` and `LIMIT` clauses for performance. +Pagination may be used to fetch subsequent records. + +Example tasks requiring querying nested domain objects from the group level: + +- Show first 20 issues by creation date or due date from the group `gitlab-org`. +- Show first 20 merge_requests by merged at date from the group `gitlab-com`. + +Unfortunately, ordered group-level queries typically perform badly +as their executions require heavy I/O, memory, and computations. +Let's do an in-depth examination of executing one such query. + +### Performance problems with `IN` queries + +Consider the task of fetching the twenty oldest created issues +from the group `gitlab-org` with the following query: + +```sql +SELECT "issues".* +FROM "issues" +WHERE "issues"."project_id" IN + (SELECT "projects"."id" + FROM "projects" + WHERE "projects"."namespace_id" IN + (SELECT traversal_ids[array_length(traversal_ids, 1)] AS id + FROM "namespaces" + WHERE (traversal_ids @> ('{9970}')))) +ORDER BY "issues"."created_at" ASC, + "issues"."id" ASC +LIMIT 20 +``` + +NOTE: +For pagination, ordering by the `created_at` column is not enough, +we must add the `id` column as a +[tie-breaker](pagination_performance_guidelines.md#tie-breaker-column). + +The execution of the query can be largely broken down into three steps: + +1. The database accesses both `namespaces` and `projects` tables + to find all projects from all groups in the group hierarchy. +1. The database retrieves `issues` records for each project causing heavy disk I/O. + Ideally, an appropriate index configuration should optimize this process. +1. The database sorts the `issues` rows in memory by `created_at` and returns `LIMIT 20` rows to + the end-user. For large groups, this final step requires both large memory and CPU resources. + +<details> +<summary>Expand this sentence to see the execution plan for this DB query.</summary> +<pre><code> + Limit (cost=90170.07..90170.12 rows=20 width=1329) (actual time=967.597..967.607 rows=20 loops=1) + Buffers: shared hit=239127 read=3060 + I/O Timings: read=336.879 + -> Sort (cost=90170.07..90224.02 rows=21578 width=1329) (actual time=967.596..967.603 rows=20 loops=1) + Sort Key: issues.created_at, issues.id + Sort Method: top-N heapsort Memory: 74kB + Buffers: shared hit=239127 read=3060 + I/O Timings: read=336.879 + -> Nested Loop (cost=1305.66..89595.89 rows=21578 width=1329) (actual time=4.709..797.659 rows=241534 loops=1) + Buffers: shared hit=239121 read=3060 + I/O Timings: read=336.879 + -> HashAggregate (cost=1305.10..1360.22 rows=5512 width=4) (actual time=4.657..5.370 rows=1528 loops=1) + Group Key: projects.id + Buffers: shared hit=2597 + -> Nested Loop (cost=576.76..1291.32 rows=5512 width=4) (actual time=2.427..4.244 rows=1528 loops=1) + Buffers: shared hit=2597 + -> HashAggregate (cost=576.32..579.06 rows=274 width=25) (actual time=2.406..2.447 rows=265 loops=1) + Group Key: namespaces.traversal_ids[array_length(namespaces.traversal_ids, 1)] + Buffers: shared hit=334 + -> Bitmap Heap Scan on namespaces (cost=141.62..575.63 rows=274 width=25) (actual time=1.933..2.330 rows=265 loops=1) + Recheck Cond: (traversal_ids @> '{9970}'::integer[]) + Heap Blocks: exact=243 + Buffers: shared hit=334 + -> Bitmap Index Scan on index_namespaces_on_traversal_ids (cost=0.00..141.55 rows=274 width=0) (actual time=1.897..1.898 rows=265 loops=1) + Index Cond: (traversal_ids @> '{9970}'::integer[]) + Buffers: shared hit=91 + -> Index Only Scan using index_projects_on_namespace_id_and_id on projects (cost=0.44..2.40 rows=20 width=8) (actual time=0.004..0.006 rows=6 loops=265) + Index Cond: (namespace_id = (namespaces.traversal_ids)[array_length(namespaces.traversal_ids, 1)]) + Heap Fetches: 51 + Buffers: shared hit=2263 + -> Index Scan using index_issues_on_project_id_and_iid on issues (cost=0.57..10.57 rows=544 width=1329) (actual time=0.114..0.484 rows=158 loops=1528) + Index Cond: (project_id = projects.id) + Buffers: shared hit=236524 read=3060 + I/O Timings: read=336.879 + Planning Time: 7.750 ms + Execution Time: 967.973 ms +(36 rows) +</code></pre> +</details> + +The performance of the query depends on the number of rows in the database. +On average, we can say the following: + +- Number of groups in the group-hierarchy: less than 1 000 +- Number of projects: less than 5 000 +- Number of issues: less than 100 000 + +From the list, it's apparent that the number of `issues` records has +the largest impact on the performance. +As per normal usage, we can say that the number of issue records grows +at a faster rate than the `namespaces` and the `projects` records. + +This problem affects most of our group-level features where records are listed +in a specific order, such as group-level issues, merge requests pages, and APIs. +For very large groups the database queries can easily time out, causing HTTP 500 errors. + +## Optimizing ordered `IN` queries + +In the talk +["How to teach an elephant to dance rock'n'roll"](https://www.youtube.com/watch?v=Ha38lcjVyhQ), +Maxim Boguk demonstrated a technique to optimize a special class of ordered `IN` queries, +such as our ordered group-level queries. + +A typical ordered `IN` query may look like this: + +```sql +SELECT t.* FROM t +WHERE t.fkey IN (value_set) +ORDER BY t.pkey +LIMIT N; +``` + +Here's the key insight used in the technique: we need at most `|value_set| + N` record lookups, +rather than retrieving all records satisfying the condition `t.fkey IN value_set` (`|value_set|` +is the number of values in `value_set`). + +We adopted and generalized the technique for use in GitLab by implementing utilities in the +`Gitlab::Pagination::Keyset::InOperatorOptimization` class to facilitate building efficient `IN` +queries. + +### Requirements + +The technique is not a drop-in replacement for the existing group-level queries using `IN` operator. +The technique can only optimize `IN` queries that satisfy the following requirements: + +- `LIMIT` is present, which usually means that the query is paginated + (offset or keyset pagination). +- The column used with the `IN` query and the columns in the `ORDER BY` + clause are covered with a database index. The columns in the index must be + in the following order: `column_for_the_in_query`, `order by column 1`, and + `order by column 2`. +- The columns in the `ORDER BY` clause are distinct + (the combination of the columns uniquely identifies one particular column in the table). + +WARNING: +This technique will not improve the performance of the `COUNT(*)` queries. + +## The `InOperatorOptimization` module + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67352) in GitLab 14.3. + +The `Gitlab::Pagination::Keyset::InOperatorOptimization` module implements utilities for applying a generalized version of +the efficient `IN` query technique described in the previous section. + +To build optimized, ordered `IN` queries that meet [the requirements](#requirements), +use the utility class `QueryBuilder` from the module. + +NOTE: +The generic keyset pagination module introduced in the merge request +[51481](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51481) +plays a fundamental role in the generalized implementation of the technique +in `Gitlab::Pagination::Keyset::InOperatorOptimization`. + +### Basic usage of `QueryBuilder` + +To illustrate a basic usage, we will build a query that +fetches 20 issues with the oldest `created_at` from the group `gitlab-org`. + +The following ActiveRecord query would produce a query similar to +[the unoptimized query](#performance-problems-with-in-queries) that we examined earlier: + +```ruby +scope = Issue + .where(project_id: Group.find(9970).all_projects.select(:id)) # `gitlab-org` group and its subgroups + .order(:created_at, :id) + .limit(20) +``` + +Instead, use the query builder `InOperatorOptimization::QueryBuilder` to produce an optimized +version: + +```ruby +scope = Issue.order(:created_at, :id) +array_scope = Group.find(9970).all_projects.select(:id) +array_mapping_scope = -> (id_expression) { Issue.where(Issue.arel_table[:project_id].eq(id_expression)) } +finder_query = -> (created_at_expression, id_expression) { Issue.where(Issue.arel_table[:id].eq(id_expression)) } + +Gitlab::Pagination::Keyset::InOperatorOptimization::QueryBuilder.new( + scope: scope, + array_scope: array_scope, + array_mapping_scope: array_mapping_scope, + finder_query: finder_query +).execute.limit(20) +``` + +- `scope` represents the original `ActiveRecord::Relation` object without the `IN` query. The + relation should define an order which must be supported by the + [keyset pagination library](keyset_pagination.md#usage). +- `array_scope` contains the `ActiveRecord::Relation` object, which represents the original + `IN (subquery)`. The select values must contain the columns by which the subquery is "connected" + to the main query: the `id` of the project record. +- `array_mapping_scope` defines a lambda returning an `ActiveRecord::Relation` object. The lambda + matches (`=`) single select values from the `array_scope`. The lambda yields as many + arguments as the select values defined in the `array_scope`. The arguments are Arel SQL expressions. +- `finder_query` loads the actual record row from the database. It must also be a lambda, where + the order by column expressions is available for locating the record. In this example, the + yielded values are `created_at` and `id` SQL expressions. Finding a record is very fast via the + primary key, so we don't use the `created_at` value. + +The following database index on the `issues` table must be present +to make the query execute efficiently: + +```sql +"idx_issues_on_project_id_and_created_at_and_id" btree (project_id, created_at, id) +``` + +<details> +<summary>Expand this sentence to see the SQL query.</summary> +<pre><code> +SELECT "issues".* +FROM + (WITH RECURSIVE "array_cte" AS MATERIALIZED + (SELECT "projects"."id" + FROM "projects" + WHERE "projects"."namespace_id" IN + (SELECT traversal_ids[array_length(traversal_ids, 1)] AS id + FROM "namespaces" + WHERE (traversal_ids @> ('{9970}')))), + "recursive_keyset_cte" AS ( -- initializer row start + (SELECT NULL::issues AS records, + array_cte_id_array, + issues_created_at_array, + issues_id_array, + 0::bigint AS COUNT + FROM + (SELECT ARRAY_AGG("array_cte"."id") AS array_cte_id_array, + ARRAY_AGG("issues"."created_at") AS issues_created_at_array, + ARRAY_AGG("issues"."id") AS issues_id_array + FROM + (SELECT "array_cte"."id" + FROM array_cte) array_cte + LEFT JOIN LATERAL + (SELECT "issues"."created_at", + "issues"."id" + FROM "issues" + WHERE "issues"."project_id" = "array_cte"."id" + ORDER BY "issues"."created_at" ASC, "issues"."id" ASC + LIMIT 1) issues ON TRUE + WHERE "issues"."created_at" IS NOT NULL + AND "issues"."id" IS NOT NULL) array_scope_lateral_query + LIMIT 1) + -- initializer row finished + UNION ALL + (SELECT + -- result row start + (SELECT issues -- record finder query as the first column + FROM "issues" + WHERE "issues"."id" = recursive_keyset_cte.issues_id_array[position] + LIMIT 1), + array_cte_id_array, + recursive_keyset_cte.issues_created_at_array[:position_query.position-1]||next_cursor_values.created_at||recursive_keyset_cte.issues_created_at_array[position_query.position+1:], + recursive_keyset_cte.issues_id_array[:position_query.position-1]||next_cursor_values.id||recursive_keyset_cte.issues_id_array[position_query.position+1:], + recursive_keyset_cte.count + 1 + -- result row finished + FROM recursive_keyset_cte, + LATERAL + -- finding the cursor values of the next record start + (SELECT created_at, + id, + position + FROM UNNEST(issues_created_at_array, issues_id_array) WITH + ORDINALITY AS u(created_at, id, position) + WHERE created_at IS NOT NULL + AND id IS NOT NULL + ORDER BY "created_at" ASC, "id" ASC + LIMIT 1) AS position_query, + -- finding the cursor values of the next record end + -- finding the next cursor values (next_cursor_values_query) start + LATERAL + (SELECT "record"."created_at", + "record"."id" + FROM ( + VALUES (NULL, + NULL)) AS nulls + LEFT JOIN + (SELECT "issues"."created_at", + "issues"."id" + FROM ( + (SELECT "issues"."created_at", + "issues"."id" + FROM "issues" + WHERE "issues"."project_id" = recursive_keyset_cte.array_cte_id_array[position] + AND recursive_keyset_cte.issues_created_at_array[position] IS NULL + AND "issues"."created_at" IS NULL + AND "issues"."id" > recursive_keyset_cte.issues_id_array[position] + ORDER BY "issues"."created_at" ASC, "issues"."id" ASC) + UNION ALL + (SELECT "issues"."created_at", + "issues"."id" + FROM "issues" + WHERE "issues"."project_id" = recursive_keyset_cte.array_cte_id_array[position] + AND recursive_keyset_cte.issues_created_at_array[position] IS NOT NULL + AND "issues"."created_at" IS NULL + ORDER BY "issues"."created_at" ASC, "issues"."id" ASC) + UNION ALL + (SELECT "issues"."created_at", + "issues"."id" + FROM "issues" + WHERE "issues"."project_id" = recursive_keyset_cte.array_cte_id_array[position] + AND recursive_keyset_cte.issues_created_at_array[position] IS NOT NULL + AND "issues"."created_at" > recursive_keyset_cte.issues_created_at_array[position] + ORDER BY "issues"."created_at" ASC, "issues"."id" ASC) + UNION ALL + (SELECT "issues"."created_at", + "issues"."id" + FROM "issues" + WHERE "issues"."project_id" = recursive_keyset_cte.array_cte_id_array[position] + AND recursive_keyset_cte.issues_created_at_array[position] IS NOT NULL + AND "issues"."created_at" = recursive_keyset_cte.issues_created_at_array[position] + AND "issues"."id" > recursive_keyset_cte.issues_id_array[position] + ORDER BY "issues"."created_at" ASC, "issues"."id" ASC)) issues + ORDER BY "issues"."created_at" ASC, "issues"."id" ASC + LIMIT 1) record ON TRUE + LIMIT 1) AS next_cursor_values)) + -- finding the next cursor values (next_cursor_values_query) END +SELECT (records).* + FROM "recursive_keyset_cte" AS "issues" + WHERE (COUNT <> 0)) issues -- filtering out the initializer row +LIMIT 20 +</code></pre> +</details> + +### Using the `IN` query optimization + +#### Adding more filters + +In this example, let's add an extra filter by `milestone_id`. + +Be careful when adding extra filters to the query. If the column is not covered by the same index, +then the query might perform worse than the non-optimized query. The `milestone_id` column in the +`issues` table is currently covered by a different index: + +```sql +"index_issues_on_milestone_id" btree (milestone_id) +``` + +Adding the `miletone_id = X` filter to the `scope` argument or to the optimized scope causes bad performance. + +Example (bad): + +```ruby +Gitlab::Pagination::Keyset::InOperatorOptimization::QueryBuilder.new( + scope: scope, + array_scope: array_scope, + array_mapping_scope: array_mapping_scope, + finder_query: finder_query +).execute + .where(milestone_id: 5) + .limit(20) +``` + +To address this concern, we could define another index: + +```sql +"idx_issues_on_project_id_and_milestone_id_and_created_at_and_id" btree (project_id, milestone_id, created_at, id) +``` + +Adding more indexes to the `issues` table could significantly affect the performance of +the `UPDATE` queries. In this case, it's better to rely on the original query. It means that if we +want to use the optimization for the unfiltered page we need to add extra logic in the application code: + +```ruby +if optimization_possible? # no extra params or params covered with the same index as the ORDER BY clause + run_optimized_query +else + run_normal_in_query +end +``` + +#### Multiple `IN` queries + +Let's assume that we want to extend the group-level queries to include only incident and test case +issue types. + +The original ActiveRecord query would look like this: + +```ruby +scope = Issue + .where(project_id: Group.find(9970).all_projects.select(:id)) # `gitlab-org` group and its subgroups + .where(issue_type: [:incident, :test_case]) # 1, 2 + .order(:created_at, :id) + .limit(20) +``` + +To construct the array scope, we'll need to take the Cartesian product of the `project_id IN` and +the `issue_type IN` queries. `issue_type` is an ActiveRecord enum, so we need to +construct the following table: + +| `project_id` | `issue_type_value` | +| ------------ | ------------------ | +| 2 | 1 | +| 2 | 2 | +| 5 | 1 | +| 5 | 2 | +| 10 | 1 | +| 10 | 2 | +| 9 | 1 | +| 9 | 2 | + +For the `issue_types` query we can construct a value list without querying a table: + +```ruby +value_list = Arel::Nodes::ValuesList.new([[Issue.issue_types[:incident]],[Issue.issue_types[:test_case]]]) +issue_type_values = Arel::Nodes::Grouping.new(value_list).as('issue_type_values (value)').to_sql + +array_scope = Group + .find(9970) + .all_projects + .from("#{Project.table_name}, #{issue_type_values}") + .select(:id, :value) +``` + +Building the `array_mapping_scope` query requires two arguments: `id` and `issue_type_value`: + +```ruby +array_mapping_scope = -> (id_expression, issue_type_value_expression) { Issue.where(Issue.arel_table[:project_id].eq(id_expression)).where(Issue.arel_table[:issue_type].eq(issue_type_value_expression)) } +``` + +The `scope` and the `finder` queries don't change: + +```ruby +scope = Issue.order(:created_at, :id) +finder_query = -> (created_at_expression, id_expression) { Issue.where(Issue.arel_table[:id].eq(id_expression)) } + +Gitlab::Pagination::Keyset::InOperatorOptimization::QueryBuilder.new( + scope: scope, + array_scope: array_scope, + array_mapping_scope: array_mapping_scope, + finder_query: finder_query +).execute.limit(20) +``` + +<details> +<summary>Expand this sentence to see the SQL query.</summary> +<pre><code> +SELECT "issues".* +FROM + (WITH RECURSIVE "array_cte" AS MATERIALIZED + (SELECT "projects"."id", "value" + FROM projects, ( + VALUES (1), (2)) AS issue_type_values (value) + WHERE "projects"."namespace_id" IN + (WITH RECURSIVE "base_and_descendants" AS ( + (SELECT "namespaces".* + FROM "namespaces" + WHERE "namespaces"."type" = 'Group' + AND "namespaces"."id" = 9970) + UNION + (SELECT "namespaces".* + FROM "namespaces", "base_and_descendants" + WHERE "namespaces"."type" = 'Group' + AND "namespaces"."parent_id" = "base_and_descendants"."id")) SELECT "id" + FROM "base_and_descendants" AS "namespaces")), + "recursive_keyset_cte" AS ( + (SELECT NULL::issues AS records, + array_cte_id_array, + array_cte_value_array, + issues_created_at_array, + issues_id_array, + 0::bigint AS COUNT + FROM + (SELECT ARRAY_AGG("array_cte"."id") AS array_cte_id_array, + ARRAY_AGG("array_cte"."value") AS array_cte_value_array, + ARRAY_AGG("issues"."created_at") AS issues_created_at_array, + ARRAY_AGG("issues"."id") AS issues_id_array + FROM + (SELECT "array_cte"."id", + "array_cte"."value" + FROM array_cte) array_cte + LEFT JOIN LATERAL + (SELECT "issues"."created_at", + "issues"."id" + FROM "issues" + WHERE "issues"."project_id" = "array_cte"."id" + AND "issues"."issue_type" = "array_cte"."value" + ORDER BY "issues"."created_at" ASC, "issues"."id" ASC + LIMIT 1) issues ON TRUE + WHERE "issues"."created_at" IS NOT NULL + AND "issues"."id" IS NOT NULL) array_scope_lateral_query + LIMIT 1) + UNION ALL + (SELECT + (SELECT issues + FROM "issues" + WHERE "issues"."id" = recursive_keyset_cte.issues_id_array[POSITION] + LIMIT 1), array_cte_id_array, + array_cte_value_array, + recursive_keyset_cte.issues_created_at_array[:position_query.position-1]||next_cursor_values.created_at||recursive_keyset_cte.issues_created_at_array[position_query.position+1:], recursive_keyset_cte.issues_id_array[:position_query.position-1]||next_cursor_values.id||recursive_keyset_cte.issues_id_array[position_query.position+1:], recursive_keyset_cte.count + 1 + FROM recursive_keyset_cte, + LATERAL + (SELECT created_at, + id, + POSITION + FROM UNNEST(issues_created_at_array, issues_id_array) WITH + ORDINALITY AS u(created_at, id, POSITION) + WHERE created_at IS NOT NULL + AND id IS NOT NULL + ORDER BY "created_at" ASC, "id" ASC + LIMIT 1) AS position_query, + LATERAL + (SELECT "record"."created_at", + "record"."id" + FROM ( + VALUES (NULL, + NULL)) AS nulls + LEFT JOIN + (SELECT "issues"."created_at", + "issues"."id" + FROM ( + (SELECT "issues"."created_at", + "issues"."id" + FROM "issues" + WHERE "issues"."project_id" = recursive_keyset_cte.array_cte_id_array[POSITION] + AND "issues"."issue_type" = recursive_keyset_cte.array_cte_value_array[POSITION] + AND recursive_keyset_cte.issues_created_at_array[POSITION] IS NULL + AND "issues"."created_at" IS NULL + AND "issues"."id" > recursive_keyset_cte.issues_id_array[POSITION] + ORDER BY "issues"."created_at" ASC, "issues"."id" ASC) + UNION ALL + (SELECT "issues"."created_at", + "issues"."id" + FROM "issues" + WHERE "issues"."project_id" = recursive_keyset_cte.array_cte_id_array[POSITION] + AND "issues"."issue_type" = recursive_keyset_cte.array_cte_value_array[POSITION] + AND recursive_keyset_cte.issues_created_at_array[POSITION] IS NOT NULL + AND "issues"."created_at" IS NULL + ORDER BY "issues"."created_at" ASC, "issues"."id" ASC) + UNION ALL + (SELECT "issues"."created_at", + "issues"."id" + FROM "issues" + WHERE "issues"."project_id" = recursive_keyset_cte.array_cte_id_array[POSITION] + AND "issues"."issue_type" = recursive_keyset_cte.array_cte_value_array[POSITION] + AND recursive_keyset_cte.issues_created_at_array[POSITION] IS NOT NULL + AND "issues"."created_at" > recursive_keyset_cte.issues_created_at_array[POSITION] + ORDER BY "issues"."created_at" ASC, "issues"."id" ASC) + UNION ALL + (SELECT "issues"."created_at", + "issues"."id" + FROM "issues" + WHERE "issues"."project_id" = recursive_keyset_cte.array_cte_id_array[POSITION] + AND "issues"."issue_type" = recursive_keyset_cte.array_cte_value_array[POSITION] + AND recursive_keyset_cte.issues_created_at_array[POSITION] IS NOT NULL + AND "issues"."created_at" = recursive_keyset_cte.issues_created_at_array[POSITION] + AND "issues"."id" > recursive_keyset_cte.issues_id_array[POSITION] + ORDER BY "issues"."created_at" ASC, "issues"."id" ASC)) issues + ORDER BY "issues"."created_at" ASC, "issues"."id" ASC + LIMIT 1) record ON TRUE + LIMIT 1) AS next_cursor_values)) SELECT (records).* + FROM "recursive_keyset_cte" AS "issues" + WHERE (COUNT <> 0)) issues +LIMIT 20 +</code> +</pre> +</details> + +NOTE: +To make the query efficient, the following columns need to be covered with an index: `project_id`, `issue_type`, `created_at`, and `id`. + +#### Batch iteration + +Batch iteration over the records is possible via the keyset `Iterator` class. + +```ruby +scope = Issue.order(:created_at, :id) +array_scope = Group.find(9970).all_projects.select(:id) +array_mapping_scope = -> (id_expression) { Issue.where(Issue.arel_table[:project_id].eq(id_expression)) } +finder_query = -> (created_at_expression, id_expression) { Issue.where(Issue.arel_table[:id].eq(id_expression)) } + +opts = { + in_operator_optimization_options: { + array_scope: array_scope, + array_mapping_scope: array_mapping_scope, + finder_query: finder_query + } +} + +Gitlab::Pagination::Keyset::Iterator.new(scope: scope, **opts).each_batch(of: 100) do |records| + puts records.select(:id).map { |r| [r.id] } +end +``` + +#### Keyset pagination + +The optimization works out of the box with GraphQL and the `keyset_paginate` helper method. +Read more about [keyset pagination](keyset_pagination.md). + +```ruby +array_scope = Group.find(9970).all_projects.select(:id) +array_mapping_scope = -> (id_expression) { Issue.where(Issue.arel_table[:project_id].eq(id_expression)) } +finder_query = -> (created_at_expression, id_expression) { Issue.where(Issue.arel_table[:id].eq(id_expression)) } + +opts = { + in_operator_optimization_options: { + array_scope: array_scope, + array_mapping_scope: array_mapping_scope, + finder_query: finder_query + } +} + +issues = Issue + .order(:created_at, :id) + .keyset_paginate(per_page: 20, keyset_order_options: opts) + .records +``` + +#### Offset pagination with Kaminari + +The `ActiveRecord` scope produced by the `InOperatorOptimization` class can be used in +[offset-paginated](pagination_guidelines.md#offset-pagination) +queries. + +```ruby +Gitlab::Pagination::Keyset::InOperatorOptimization::QueryBuilder + .new(...) + .execute + .page(1) + .per(20) + .without_count +``` + +## Generalized `IN` optimization technique + +Let's dive into how `QueryBuilder` builds the optimized query +to fetch the twenty oldest created issues from the group `gitlab-org` +using the generalized `IN` optimization technique. + +### Array CTE + +As the first step, we use a common table expression (CTE) for collecting the `projects.id` values. +This is done by wrapping the incoming `array_scope` ActiveRecord relation parameter with a CTE. + +```sql +WITH array_cte AS MATERIALIZED ( + SELECT "projects"."id" + FROM "projects" + WHERE "projects"."namespace_id" IN + (SELECT traversal_ids[array_length(traversal_ids, 1)] AS id + FROM "namespaces" + WHERE (traversal_ids @> ('{9970}'))) +) +``` + +This query produces the following result set with only one column (`projects.id`): + +| ID | +| --- | +| 9 | +| 2 | +| 5 | +| 10 | + +### Array mapping + +For each project (that is, each record storing a project ID in `array_cte`), +we will fetch the cursor value identifying the first issue respecting the `ORDER BY` clause. + +As an example, let's pick the first record `ID=9` from `array_cte`. +The following query should fetch the cursor value `(created_at, id)` identifying +the first issue record respecting the `ORDER BY` clause for the project with `ID=9`: + +```sql +SELECT "issues"."created_at", "issues"."id" +FROM "issues"."project_id"=9 +ORDER BY "issues"."created_at" ASC, "issues"."id" ASC +LIMIT 1; +``` + +We will use `LATERAL JOIN` to loop over the records in the `array_cte` and find the +cursor value for each project. The query would be built using the `array_mapping_scope` lambda +function. + +```sql +SELECT ARRAY_AGG("array_cte"."id") AS array_cte_id_array, + ARRAY_AGG("issues"."created_at") AS issues_created_at_array, + ARRAY_AGG("issues"."id") AS issues_id_array +FROM ( + SELECT "array_cte"."id" FROM array_cte +) array_cte +LEFT JOIN LATERAL +( + SELECT "issues"."created_at", "issues"."id" + FROM "issues" + WHERE "issues"."project_id" = "array_cte"."id" + ORDER BY "issues"."created_at" ASC, "issues"."id" ASC + LIMIT 1 +) issues ON TRUE +``` + +Since we have an index on `project_id`, `created_at`, and `id`, +index-only scans should quickly locate all the cursor values. + +This is how the query could be translated to Ruby: + +```ruby +created_at_values = [] +id_values = [] +project_ids.map do |project_id| + created_at, id = Issue.select(:created_at, :id).where(project_id: project_id).order(:created_at, :id).limit(1).first # N+1 but it's fast + created_at_values << created_at + id_values << id +end +``` + +This is what the result set would look like: + +| `project_ids` | `created_at_values` | `id_values` | +| ------------- | ------------------- | ----------- | +| 2 | 2020-01-10 | 5 | +| 5 | 2020-01-05 | 4 | +| 10 | 2020-01-15 | 7 | +| 9 | 2020-01-05 | 3 | + +The table shows the cursor values (`created_at, id`) of the first record for each project +respecting the `ORDER BY` clause. + +At this point, we have the initial data. To start collecting the actual records from the database, +we'll use a recursive CTE query where each recursion locates one row until +the `LIMIT` is reached or no more data can be found. + +Here's an outline of the steps we will take in the recursive CTE query +(expressing the steps in SQL is non-trivial but will be explained next): + +1. Sort the initial resultset according to the `ORDER BY` clause. +1. Pick the top cursor to fetch the record, this is our first record. In the example, +this cursor would be (`2020-01-05`, `3`) for `project_id=9`. +1. We can use (`2020-01-05`, `3`) to fetch the next issue respecting the `ORDER BY` clause +`project_id=9` filter. This produces an updated resultset. + + | `project_ids` | `created_at_values` | `id_values` | + | ------------- | ------------------- | ----------- | + | 2 | 2020-01-10 | 5 | + | 5 | 2020-01-05 | 4 | + | 10 | 2020-01-15 | 7 | + | **9** | **2020-01-06** | **6** | + +1. Repeat 1 to 3 with the updated resultset until we have fetched `N=20` records. + +### Initializing the recursive CTE query + +For the initial recursive query, we'll need to produce exactly one row, we call this the +initializer query (`initializer_query`). + +Use `ARRAY_AGG` function to compact the initial result set into a single row +and use the row as the initial value for the recursive CTE query: + +Example initializer row: + +| `records` | `project_ids` | `created_at_values` | `id_values` | `Count` | `Position` | +| -------------- | --------------- | ------------------- | ----------- | ------- | ---------- | +| `NULL::issues` | `[9, 2, 5, 10]` | `[...]` | `[...]` | `0` | `NULL` | + +- The `records` column contains our sorted database records, and the initializer query sets the +first value to `NULL`, which is filtered out later. +- The `count` column tracks the number of records found. We use this column to filter out the +initializer row from the result set. + +### Recursive portion of the CTE query + +The result row is produced with the following steps: + +1. [Order the keyset arrays.](#order-the-keyset-arrays) +1. [Find the next cursor.](#find-the-next-cursor) +1. [Produce a new row.](#produce-a-new-row) + +#### Order the keyset arrays + +Order the keyset arrays according to the original `ORDER BY` clause with `LIMIT 1` using the +`UNNEST [] WITH ORDINALITY` table function. The function locates the "lowest" keyset cursor +values and gives us the array position. These cursor values are used to locate the record. + +NOTE: +At this point, we haven't read anything from the database tables, because we relied on +fast index-only scans. + +| `project_ids` | `created_at_values` | `id_values` | +| ------------- | ------------------- | ----------- | +| 2 | 2020-01-10 | 5 | +| 5 | 2020-01-05 | 4 | +| 10 | 2020-01-15 | 7 | +| 9 | 2020-01-05 | 3 | + +The first row is the 4th one (`position = 4`), because it has the lowest `created_at` and +`id` values. The `UNNEST` function also exposes the position using an extra column (note: +PostgreSQL uses 1-based index). + +Demonstration of the `UNNEST [] WITH ORDINALITY` table function: + +```sql +SELECT position FROM unnest('{2020-01-10, 2020-01-05, 2020-01-15, 2020-01-05}'::timestamp[], '{5, 4, 7, 3}'::int[]) + WITH ORDINALITY AS t(created_at, id, position) ORDER BY created_at ASC, id ASC LIMIT 1; +``` + +Result: + +```sql +position +---------- + 4 +(1 row) +``` + +#### Find the next cursor + +Now, let's find the next cursor values (`next_cursor_values_query`) for the project with `id = 9`. +To do that, we build a keyset pagination SQL query. Find the next row after +`created_at = 2020-01-05` and `id = 3`. Because we order by two database columns, there can be two +cases: + +- There are rows with `created_at = 2020-01-05` and `id > 3`. +- There are rows with `created_at > 2020-01-05`. + +Generating this query is done by the generic keyset pagination library. After the query is done, +we have a temporary table with the next cursor values: + +| `created_at` | ID | +| ------------ | --- | +| 2020-01-06 | 6 | + +#### Produce a new row + +As the final step, we need to produce a new row by manipulating the initializer row +(`data_collector_query` method). Two things happen here: + +- Read the full row from the DB and return it in the `records` columns. (`result_collector_columns` +method) +- Replace the cursor values at the current position with the results from the keyset query. + +Reading the full row from the database is only one index scan by the primary key. We use the +ActiveRecord query passed as the `finder_query`: + +```sql +(SELECT "issues".* FROM issues WHERE id = id_values[position] LIMIT 1) +``` + +By adding parentheses, the result row can be put into the `records` column. + +Replacing the cursor values at `position` can be done via standard PostgreSQL array operators: + +```sql +-- created_at_values column value +created_at_values[:position-1]||next_cursor_values.created_at||created_at_values[position+1:] + +-- id_values column value +id_values[:position-1]||next_cursor_values.id||id_values[position+1:] +``` + +The Ruby equivalent would be the following: + +```ruby +id_values[0..(position - 1)] + [next_cursor_values.id] + id_values[(position + 1)..-1] +``` + +After this, the recursion starts again by finding the next lowest cursor value. + +### Finalizing the query + +For producing the final `issues` rows, we're going to wrap the query with another `SELECT` statement: + +```sql +SELECT "issues".* +FROM ( + SELECT (records).* -- similar to ruby splat operator + FROM recursive_keyset_cte + WHERE recursive_keyset_cte.count <> 0 -- filter out the initializer row +) AS issues +``` + +### Performance comparison + +Assuming that we have the correct database index in place, we can compare the query performance by +looking at the number of database rows accessed by the query. + +- Number of groups: 100 +- Number of projects: 500 +- Number of issues (in the group hierarchy): 50 000 + +Standard `IN` query: + +| Query | Entries read from index | Rows read from the table | Rows sorted in memory | +| ------------------------ | ----------------------- | ------------------------ | --------------------- | +| group hierarchy subquery | 100 | 0 | 0 | +| project lookup query | 500 | 0 | 0 | +| issue lookup query | 50 000 | 20 | 50 000 | + +Optimized `IN` query: + +| Query | Entries read from index | Rows read from the table | Rows sorted in memory | +| ------------------------ | ----------------------- | ------------------------ | --------------------- | +| group hierarchy subquery | 100 | 0 | 0 | +| project lookup query | 500 | 0 | 0 | +| issue lookup query | 519 | 20 | 10 000 | + +The group and project queries are not using sorting, the necessary columns are read from database +indexes. These values are accessed frequently so it's very likely that most of the data will be +in the PostgreSQL's buffer cache. + +The optimized `IN` query will read maximum 519 entries (cursor values) from the index: + +- 500 index-only scans for populating the arrays for each project. The cursor values of the first +record will be here. +- Maximum 19 additional index-only scans for the consecutive records. + +The optimized `IN` query will sort the array (cursor values per project array) 20 times, which +means we'll sort 20 x 500 rows. However, this might be a less memory-intensive task than +sorting 10 000 rows at once. + +Performance comparison for the `gitlab-org` group: + +| Query | Number of 8K Buffers involved | Uncached execution time | Cached execution time | +| -------------------- | ----------------------------- | ----------------------- | --------------------- | +| `IN` query | 240833 | 1.2s | 660ms | +| Optimized `IN` query | 9783 | 450ms | 22ms | + +NOTE: +Before taking measurements, the group lookup query was executed separately in order to make +the group data available in the buffer cache. Since it's a frequently called query, it's going to +hit many shared buffers during the query execution in the production environment. diff --git a/doc/development/database/index.md b/doc/development/database/index.md index b61a71ffb8e..a7b752e14ef 100644 --- a/doc/development/database/index.md +++ b/doc/development/database/index.md @@ -62,6 +62,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w - [Query performance guidelines](../query_performance.md) - [Pagination guidelines](pagination_guidelines.md) - [Pagination performance guidelines](pagination_performance_guidelines.md) +- [Efficient `IN` operator queries](efficient_in_operator_queries.md) ## Case studies diff --git a/doc/development/database/keyset_pagination.md b/doc/development/database/keyset_pagination.md index e30c3cc8832..fd62c36b753 100644 --- a/doc/development/database/keyset_pagination.md +++ b/doc/development/database/keyset_pagination.md @@ -36,7 +36,8 @@ Keyset pagination works without any configuration for simple ActiveRecord querie - Order by one column. - Order by two columns, where the last column is the primary key. -The library can detect nullable and non-distinct columns and based on these, it will add extra ordering using the primary key. This is necessary because keyset pagination expects distinct order by values: +The library detects nullable and non-distinct columns and based on these, adds extra ordering +using the primary key. This is necessary because keyset pagination expects distinct order by values: ```ruby Project.order(:created_at).keyset_paginate.records # ORDER BY created_at, id @@ -79,7 +80,7 @@ cursor = paginator.cursor_for_next_page # encoded column attributes for the next paginator = Project.order(:name).keyset_paginate(cursor: cursor).records # loading the next page ``` -Since keyset pagination does not support page numbers, we are restricted to go to the following pages: +Because keyset pagination does not support page numbers, we are restricted to go to the following pages: - Next page - Previous page @@ -111,7 +112,8 @@ In the HAML file, we can render the records: The performance of the keyset pagination depends on the database index configuration and the number of columns we use in the `ORDER BY` clause. -In case we order by the primary key (`id`), then the generated queries will be efficient since the primary key is covered by a database index. +In case we order by the primary key (`id`), then the generated queries are efficient because +the primary key is covered by a database index. When two or more columns are used in the `ORDER BY` clause, it's advised to check the generated database query and make sure that the correct index configuration is used. More information can be found on the [pagination guideline page](pagination_guidelines.md#index-coverage). @@ -149,7 +151,9 @@ puts paginator2.records.to_a # UNION query ## Complex order configuration -Common `ORDER BY` configurations will be handled by the `keyset_paginate` method automatically so no manual configuration is needed. There are a few edge cases where order object configuration is necessary: +Common `ORDER BY` configurations are handled by the `keyset_paginate` method automatically +so no manual configuration is needed. There are a few edge cases where order object +configuration is necessary: - `NULLS LAST` ordering. - Function-based ordering. @@ -170,12 +174,13 @@ scope.keyset_paginate # raises: Gitlab::Pagination::Keyset::Paginator::Unsupport The `keyset_paginate` method raises an error because the order value on the query is a custom SQL string and not an [`Arel`](https://www.rubydoc.info/gems/arel) AST node. The keyset library cannot automatically infer configuration values from these kinds of queries. -To make keyset pagination work, we need to configure custom order objects, to do so, we need to collect information about the order columns: +To make keyset pagination work, we must configure custom order objects, to do so, we must +collect information about the order columns: -- `relative_position` can have duplicated values since no unique index is present. -- `relative_position` can have null values because we don't have a not null constraint on the column. For this, we need to determine where will we see NULL values, at the beginning of the resultset or the end (`NULLS LAST`). -- Keyset pagination requires distinct order columns, so we'll need to add the primary key (`id`) to make the order distinct. -- Jumping to the last page and paginating backwards actually reverses the `ORDER BY` clause. For this, we'll need to provide the reversed `ORDER BY` clause. +- `relative_position` can have duplicated values because no unique index is present. +- `relative_position` can have null values because we don't have a not null constraint on the column. For this, we must determine where we see NULL values, at the beginning of the result set, or the end (`NULLS LAST`). +- Keyset pagination requires distinct order columns, so we must add the primary key (`id`) to make the order distinct. +- Jumping to the last page and paginating backwards actually reverses the `ORDER BY` clause. For this, we must provide the reversed `ORDER BY` clause. Example: @@ -206,7 +211,8 @@ scope.keyset_paginate.records # works ### Function-based ordering -In the following example, we multiply the `id` by 10 and ordering by that value. Since the `id` column is unique, we need to define only one column: +In the following example, we multiply the `id` by 10 and order by that value. Because the `id` +column is unique, we define only one column: ```ruby order = Gitlab::Pagination::Keyset::Order.build([ @@ -233,7 +239,8 @@ The `add_to_projections` flag tells the paginator to expose the column expressio ### `iid` based ordering -When ordering issues, the database ensures that we'll have distinct `iid` values within a project. Ordering by one column is enough to make the pagination work if the `project_id` filter is present: +When ordering issues, the database ensures that we have distinct `iid` values in a project. +Ordering by one column is enough to make the pagination work if the `project_id` filter is present: ```ruby order = Gitlab::Pagination::Keyset::Order.build([ diff --git a/doc/development/database/multiple_databases.md b/doc/development/database/multiple_databases.md index 71dcc5bb866..0fd9f821fab 100644 --- a/doc/development/database/multiple_databases.md +++ b/doc/development/database/multiple_databases.md @@ -24,24 +24,26 @@ configurations. For example, given a `config/database.yml` like below: ```yaml development: - adapter: postgresql - encoding: unicode - database: gitlabhq_development - host: /path/to/gdk/postgresql - pool: 10 - prepared_statements: false - variables: - statement_timeout: 120s + main: + adapter: postgresql + encoding: unicode + database: gitlabhq_development + host: /path/to/gdk/postgresql + pool: 10 + prepared_statements: false + variables: + statement_timeout: 120s test: &test - adapter: postgresql - encoding: unicode - database: gitlabhq_test - host: /path/to/gdk/postgresql - pool: 10 - prepared_statements: false - variables: - statement_timeout: 120s + main: + adapter: postgresql + encoding: unicode + database: gitlabhq_test + host: /path/to/gdk/postgresql + pool: 10 + prepared_statements: false + variables: + statement_timeout: 120s ``` Edit the `config/database.yml` to look like this: @@ -98,18 +100,45 @@ and their tables must be placed in two directories for now: We aim to keep the schema for both tables the same across both databases. +<!-- +NOTE: The `validate_cross_joins!` method in `spec/support/database/prevent_cross_joins.rb` references + the following heading in the code, so if you make a change to this heading, make sure to update + the corresponding documentation URL used in `spec/support/database/prevent_cross_joins.rb`. +--> + ### Removing joins between `ci_*` and non `ci_*` tables -We are planning on moving all the `ci_*` tables to a separate database so +Queries that join across databases raise an error. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68620) +in GitLab 14.3, for new queries only. Pre-existing queries do not raise an error. + +We are planning on moving all the `ci_*` tables to a separate database, so referencing `ci_*` tables with other tables will not be possible. This means, that using any kind of `JOIN` in SQL queries will not work. We have identified already many such examples that need to be fixed in <https://gitlab.com/groups/gitlab-org/-/epics/6289> . -The following are some real examples that have resulted from this and these -patterns may apply to future cases. +#### Path to removing cross-database joins + +The following steps are the process to remove cross-database joins between +`ci_*` and non `ci_*` tables: + +1. **{check-circle}** Add all failing specs to the [`cross-join-allowlist.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/f5de89daeb468fc45e1e95a76d1b5297aa53da11/spec/support/database/cross-join-allowlist.yml) + file. +1. **{dotted-circle}** Find the code that caused the spec failure and wrap the isolated code + in [`allow_cross_joins_across_databases`](#allowlist-for-existing-cross-joins). + Link to a new issue assigned to the correct team to remove the specs from the + `cross-join-allowlist.yml` file. +1. **{dotted-circle}** Remove the `cross-join-allowlist.yml` file and stop allowing + whole test files. +1. **{dotted-circle}** Fix the problem and remove the `allow_cross_joins_across_databases` call. +1. **{dotted-circle}** Fix all the cross-joins and remove the `allow_cross_joins_across_databases` method. + +#### Suggestions for removing cross-database joins -#### Remove the code +The following sections are some real examples that were identified as joining across databases, +along with possible suggestions on how to fix them. + +##### Remove the code The simplest solution we've seen several times now has been an existing scope that is unused. This is the easiest example to fix. So the first step is to @@ -131,7 +160,7 @@ to evaluate, because `UsageData` is not critical to users and it may be possible to get a similarly useful metric with a simpler approach. Alternatively we may find that nobody is using these metrics, so we can remove them. -#### Use `preload` instead of `includes` +##### Use `preload` instead of `includes` The `includes` and `preload` methods in Rails are both ways to avoid an N+1 query. The `includes` method in Rails uses a heuristic approach to determine @@ -145,7 +174,7 @@ allows you to avoid the join, while still avoiding the N+1 query. You can see a real example of this solution being used in <https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67655>. -#### De-normalize some foreign key to the table +##### De-normalize some foreign key to the table De-normalization refers to adding redundant precomputed (duplicated) data to a table to simplify certain queries or to improve performance. In this @@ -198,7 +227,7 @@ You can see this approach implemented in <https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66963> . This MR also de-normalizes `pipeline_id` to fix a similar query. -#### De-normalize into an extra table +##### De-normalize into an extra table Sometimes the previous de-normalization (adding an extra column) doesn't work for your specific case. This may be due to the fact that your data is not 1:1, or @@ -245,18 +274,88 @@ logic to delete these rows if or whenever necessary in your domain. Finally, this de-normalization and new query also improves performance because it does less joins and needs less filtering. -#### Summary of cross-join removal patterns +##### Use `disable_joins` for `has_one` or `has_many` `through:` relations + +Sometimes a join query is caused by using `has_one ... through:` or `has_many +... through:` across tables that span the different databases. These joins +sometimes can be solved by adding +[`disable_joins:true`](https://edgeguides.rubyonrails.org/active_record_multiple_databases.html#handling-associations-with-joins-across-databases). +This is a Rails feature which we +[backported](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66400). We +also extended the feature to allow a lambda syntax for enabling `disable_joins` +with a feature flag. If you use this feature we encourage using a feature flag +as it mitigates risk if there is some serious performance regression. + +You can see an example where this was used in +<https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66709/diffs>. + +With any change to DB queries it is important to analyze and compare the SQL +before and after the change. `disable_joins` can introduce very poorly performing +code depending on the actual logic of the `has_many` or `has_one` relationship. +The key thing to look for is whether any of the intermediate result sets +used to construct the final result set have an unbounded amount of data loaded. +The best way to tell is by looking at the SQL generated and confirming that +each one is limited in some way. You can tell by either a `LIMIT 1` clause or +by `WHERE` clause that is limiting based on a unique column. Any unbounded +intermediate dataset could lead to loading too many IDs into memory. + +An example where you may see very poor performance is the following +hypothetical code: + +```ruby +class Project + has_many :pipelines + has_many :builds, through: :pipelines +end + +class Pipeline + has_many :builds +end + +class Build + belongs_to :pipeline +end + +def some_action + @builds = Project.find(5).builds.order(created_at: :desc).limit(10) +end +``` + +In the above case `some_action` will generate a query like: + +```sql +select * from builds +inner join pipelines on builds.pipeline_id = pipelines.id +where pipelines.project_id = 5 +order by builds.created_at desc +limit 10 +``` + +However, if you changed the relation to be: + +```ruby +class Project + has_many :pipelines + has_many :builds, through: :pipelines, disable_joins: true +end +``` -A quick checklist for fixing a specific join query would be: +Then you would get the following 2 queries: -1. Is the code even used? If not just remove it -1. If the code is used, then is this feature even used or can we implement the - feature in a simpler way and still meet the requirements. Always prefer the - simplest option. -1. Can we remove the join if we de-normalize the data you are joining to by - adding a new column -1. Can we remove the join by adding a new table in the correct database that - replicates the minimum data needed to do the join +```sql +select id from pipelines where project_id = 5; + +select * from builds where pipeline_id in (...) +order by created_at desc +limit 10; +``` + +Because the first query does not limit by any unique column or +have a `LIMIT` clause, it can load an unlimited number of +pipeline IDs into memory, which are then sent in the following query. +This can lead to very poor performance in the Rails application and the +database. In cases like this, you might need to re-write the +query or look at other patterns described above for removing cross-joins. #### How to validate you have correctly removed a cross-join @@ -291,3 +390,74 @@ end You can see a real example of using this method for fixing a cross-join in <https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67655>. + +#### Allowlist for existing cross-joins + +A cross-join across databases can be explicitly allowed by wrapping the code in the +`::Gitlab::Database.allow_cross_joins_across_databases` helper method. + +This method should only be used: + +- For existing code. +- If the code is required to help migrate away from a cross-join. For example, + in a migration that backfills data for future use to remove a cross-join. + +The `allow_cross_joins_across_databases` helper method can be used as follows: + +```ruby +::Gitlab::Database.allow_cross_joins_across_databases(url: 'https://gitlab.com/gitlab-org/gitlab/-/issues/336590') do + subject.perform(1, 4) +end +``` + +The `url` parameter should point to an issue with a milestone for when we intend +to fix the cross-join. If the cross-join is being used in a migration, we do not +need to fix the code. See <https://gitlab.com/gitlab-org/gitlab/-/issues/340017> +for more details. + +## `config/database.yml` + +GitLab will support running multiple databases in the future, for example to [separate tables for the continuous integration features](https://gitlab.com/groups/gitlab-org/-/epics/6167) from the main database. In order to prepare for this change, we [validate the structure of the configuration](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67877) in `database.yml` to ensure that only known databases are used. + +Previously, the `config/database.yml` would look like this: + +```yaml +production: + adapter: postgresql + encoding: unicode + database: gitlabhq_production + ... +``` + +With the support for many databases the support for this +syntax is deprecated and will be removed in [15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/338182). + +The new `config/database.yml` needs to include a database name +to define a database configuration. Only `main:` and `ci:` database +names are supported today. The `main:` needs to always be a first +entry in a hash. This change applies to decomposed and non-decomposed +change. If an invalidate or deprecated syntax is used the error +or warning will be printed during application start. + +```yaml +# Non-decomposed database +production: + main: + adapter: postgresql + encoding: unicode + database: gitlabhq_production + ... + +# Decomposed database +production: + main: + adapter: postgresql + encoding: unicode + database: gitlabhq_production + ... + ci: + adapter: postgresql + encoding: unicode + database: gitlabhq_production_ci + ... +``` diff --git a/doc/development/database/not_null_constraints.md b/doc/development/database/not_null_constraints.md index 178a207dab5..de070f7e434 100644 --- a/doc/development/database/not_null_constraints.md +++ b/doc/development/database/not_null_constraints.md @@ -25,7 +25,7 @@ For example, consider a migration that creates a table with two `NOT NULL` colum `db/migrate/20200401000001_create_db_guides.rb`: ```ruby -class CreateDbGuides < ActiveRecord::Migration[6.0] +class CreateDbGuides < Gitlab::Database::Migration[1.0] def change create_table :db_guides do |t| t.bigint :stars, default: 0, null: false @@ -44,7 +44,7 @@ For example, consider a migration that adds a new `NOT NULL` column `active` to `db/migrate/20200501000001_add_active_to_db_guides.rb`: ```ruby -class AddExtendedTitleToSprints < ActiveRecord::Migration[6.0] +class AddExtendedTitleToSprints < Gitlab::Database::Migration[1.0] def change add_column :db_guides, :active, :boolean, default: true, null: false end @@ -111,9 +111,7 @@ with `validate: false` in a post-deployment migration, `db/post_migrate/20200501000001_add_not_null_constraint_to_epics_description.rb`: ```ruby -class AddNotNullConstraintToEpicsDescription < ActiveRecord::Migration[6.0] - include Gitlab::Database::MigrationHelpers - +class AddNotNullConstraintToEpicsDescription < Gitlab::Database::Migration[1.0] disable_ddl_transaction! def up @@ -144,9 +142,7 @@ so we are going to add a post-deployment migration for the 13.0 milestone (curre `db/post_migrate/20200501000002_cleanup_epics_with_null_description.rb`: ```ruby -class CleanupEpicsWithNullDescription < ActiveRecord::Migration[6.0] - include Gitlab::Database::MigrationHelpers - +class CleanupEpicsWithNullDescription < Gitlab::Database::Migration[1.0] # With BATCH_SIZE=1000 and epics.count=29500 on GitLab.com # - 30 iterations will be run # - each requires on average ~150ms @@ -184,9 +180,7 @@ migration helper in a final post-deployment migration, `db/post_migrate/20200601000001_validate_not_null_constraint_on_epics_description.rb`: ```ruby -class ValidateNotNullConstraintOnEpicsDescription < ActiveRecord::Migration[6.0] - include Gitlab::Database::MigrationHelpers - +class ValidateNotNullConstraintOnEpicsDescription < Gitlab::Database::Migration[1.0] disable_ddl_transaction! def up diff --git a/doc/development/database/pagination_guidelines.md b/doc/development/database/pagination_guidelines.md index b7209b4ca30..3a772b10a6d 100644 --- a/doc/development/database/pagination_guidelines.md +++ b/doc/development/database/pagination_guidelines.md @@ -302,7 +302,7 @@ LIMIT 20 ##### Tooling -A generic keyset pagination library is available within the GitLab project which can most of the cases easly replace the existing, kaminari based pagination with significant performance improvements when dealing with large datasets. +A generic keyset pagination library is available within the GitLab project which can most of the cases easily replace the existing, kaminari based pagination with significant performance improvements when dealing with large datasets. Example: diff --git a/doc/development/database/rename_database_tables.md b/doc/development/database/rename_database_tables.md index 8ac50d2c0a0..881adf00ad0 100644 --- a/doc/development/database/rename_database_tables.md +++ b/doc/development/database/rename_database_tables.md @@ -60,7 +60,7 @@ Consider the next release as "Release N.M". Execute a standard migration (not a post-migration): ```ruby - include Gitlab::Database::MigrationHelpers + enable_lock_retries! def up rename_table_safely(:issues, :tickets) @@ -96,8 +96,6 @@ At this point, we don't have applications using the old database table name in t 1. Remove the database view through a post-migration: ```ruby - include Gitlab::Database::MigrationHelpers - def up finalize_table_rename(:issues, :tickets) end diff --git a/doc/development/database/strings_and_the_text_data_type.md b/doc/development/database/strings_and_the_text_data_type.md index 688d811b897..a0dda42fdc7 100644 --- a/doc/development/database/strings_and_the_text_data_type.md +++ b/doc/development/database/strings_and_the_text_data_type.md @@ -11,11 +11,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w When adding new columns that will be used to store strings or other textual information: 1. We always use the `text` data type instead of the `string` data type. -1. `text` columns should always have a limit set, either by using the `create_table_with_constraints` helper -when creating a table, or by using the `add_text_limit` when altering an existing table. +1. `text` columns should always have a limit set, either by using the `create_table` with +the `#text ... limit: 100` helper (see below) when creating a table, or by using the `add_text_limit` +when altering an existing table. -The `text` data type can not be defined with a limit, so `create_table_with_constraints` and `add_text_limit` enforce -that by adding a [check constraint](https://www.postgresql.org/docs/11/ddl-constraints.html) on the column. +The standard Rails `text` column type can not be defined with a limit, but we extend `create_table` to +add a `limit: 255` option. Outside of `create_table`, `add_text_limit` can be used to add a [check constraint](https://www.postgresql.org/docs/11/ddl-constraints.html) +to an already existing column. ## Background information @@ -41,36 +43,24 @@ Don't use text columns for `attr_encrypted` attributes. Use a ## Create a new table with text columns When adding a new table, the limits for all text columns should be added in the same migration as -the table creation. +the table creation. We add a `limit:` attribute to Rails' `#text` method, which allows adding a limit +for this column. For example, consider a migration that creates a table with two text columns, `db/migrate/20200401000001_create_db_guides.rb`: ```ruby -class CreateDbGuides < ActiveRecord::Migration[6.0] - include Gitlab::Database::MigrationHelpers - - def up - create_table_with_constraints :db_guides do |t| +class CreateDbGuides < Gitlab::Database::Migration[1.0] + def change + create_table :db_guides do |t| t.bigint :stars, default: 0, null: false - t.text :title - t.text :notes - - t.text_limit :title, 128 - t.text_limit :notes, 1024 + t.text :title, limit: 128 + t.text :notes, limit: 1024 end end - - def down - # No need to drop the constraints, drop_table takes care of everything - drop_table :db_guides - end end ``` -Note that the `create_table_with_constraints` helper uses the `with_lock_retries` helper -internally, so we don't need to manually wrap the method call in the migration. - ## Add a text column to an existing table Adding a column to an existing table requires an exclusive lock for that table. Even though that lock @@ -84,7 +74,7 @@ For example, consider a migration that adds a new text column `extended_title` t `db/migrate/20200501000001_add_extended_title_to_sprints.rb`: ```ruby -class AddExtendedTitleToSprints < ActiveRecord::Migration[6.0] +class AddExtendedTitleToSprints < Gitlab::Database::Migration[1.0] # rubocop:disable Migration/AddLimitToTextColumns # limit is added in 20200501000002_add_text_limit_to_sprints_extended_title @@ -99,8 +89,7 @@ A second migration should follow the first one with a limit added to `extended_t `db/migrate/20200501000002_add_text_limit_to_sprints_extended_title.rb`: ```ruby -class AddTextLimitToSprintsExtendedTitle < ActiveRecord::Migration[6.0] - include Gitlab::Database::MigrationHelpers +class AddTextLimitToSprintsExtendedTitle < Gitlab::Database::Migration[1.0] disable_ddl_transaction! def up @@ -175,9 +164,7 @@ in a post-deployment migration, `db/post_migrate/20200501000001_add_text_limit_migration.rb`: ```ruby -class AddTextLimitMigration < ActiveRecord::Migration[6.0] - include Gitlab::Database::MigrationHelpers - +class AddTextLimitMigration < Gitlab::Database::Migration[1.0] disable_ddl_transaction! def up @@ -208,9 +195,7 @@ to add a background migration for the 13.0 milestone (current), `db/post_migrate/20200501000002_schedule_cap_title_length_on_issues.rb`: ```ruby -class ScheduleCapTitleLengthOnIssues < ActiveRecord::Migration[6.0] - include Gitlab::Database::MigrationHelpers - +class ScheduleCapTitleLengthOnIssues < Gitlab::Database::Migration[1.0] # Info on how many records will be affected on GitLab.com # time each batch needs to run on average, etc ... BATCH_SIZE = 5000 @@ -255,9 +240,7 @@ helper in a final post-deployment migration, `db/post_migrate/20200601000001_validate_text_limit_migration.rb`: ```ruby -class ValidateTextLimitMigration < ActiveRecord::Migration[6.0] - include Gitlab::Database::MigrationHelpers - +class ValidateTextLimitMigration < Gitlab::Database::Migration[1.0] disable_ddl_transaction! def up diff --git a/doc/development/database/table_partitioning.md b/doc/development/database/table_partitioning.md index 207d5a733ce..5319c73aad0 100644 --- a/doc/development/database/table_partitioning.md +++ b/doc/development/database/table_partitioning.md @@ -173,7 +173,7 @@ An example migration of partitioning the `audit_events` table by its `created_at` column would look like: ```ruby -class PartitionAuditEvents < ActiveRecord::Migration[6.0] +class PartitionAuditEvents < Gitlab::Database::Migration[1.0] include Gitlab::Database::PartitioningMigrationHelpers def up @@ -200,7 +200,7 @@ into the partitioned copy. Continuing the above example, the migration would look like: ```ruby -class BackfillPartitionAuditEvents < ActiveRecord::Migration[6.0] +class BackfillPartitionAuditEvents < Gitlab::Database::Migration[1.0] include Gitlab::Database::PartitioningMigrationHelpers def up @@ -233,7 +233,7 @@ failed jobs. Once again, continuing the example, this migration would look like: ```ruby -class CleanupPartitionedAuditEventsBackfill < ActiveRecord::Migration[6.0] +class CleanupPartitionedAuditEventsBackfill < Gitlab::Database::Migration[1.0] include Gitlab::Database::PartitioningMigrationHelpers def up diff --git a/doc/development/database/transaction_guidelines.md b/doc/development/database/transaction_guidelines.md index 1c25496b153..4c586135015 100644 --- a/doc/development/database/transaction_guidelines.md +++ b/doc/development/database/transaction_guidelines.md @@ -12,7 +12,7 @@ For further reference please check PostgreSQL documentation about [transactions] ## Database decomposition and sharding -The [sharding group](https://about.gitlab.com/handbook/engineering/development/enablement/sharding) plans to split the main GitLab database and move some of the database tables to other database servers. +The [sharding group](https://about.gitlab.com/handbook/engineering/development/enablement/sharding/) plans to split the main GitLab database and move some of the database tables to other database servers. The group will start decomposing the `ci_*` related database tables first. To maintain the current application development experience, tooling and static analyzers will be added to the codebase to ensure correct data access and data modification methods. By using the correct form for defining database transactions, we can save significant refactoring work in the future. diff --git a/doc/development/database_debugging.md b/doc/development/database_debugging.md index 67ec1b3c4f1..b1c8508c884 100644 --- a/doc/development/database_debugging.md +++ b/doc/development/database_debugging.md @@ -25,6 +25,12 @@ If you just want to delete everything and start over with an empty DB (approxima bundle exec rake db:reset RAILS_ENV=development ``` +If you want to seed the empty DB with sample data (approximately 4 minutes): + +```shell +bundle exec rake dev:setup +``` + If you just want to delete everything and start over with sample data (approximately 4 minutes). This also does `db:reset` and runs DB-specific migrations: @@ -64,6 +70,36 @@ bundle exec rails db -e development - `SELECT * FROM schema_migrations WHERE version = '20170926203418';`: Check if a migration was run - `DELETE FROM schema_migrations WHERE version = '20170926203418';`: Manually remove a migration +## Access the database with a GUI + +Most GUIs (DataGrid, RubyMine, DBeaver) require a TCP connection to the database, but by default +the database runs on a UNIX socket. To be able to access the database from these tools, some steps +are needed: + +1. On the GDK root directory, run: + + ```shell + gdk config set postgresql.host localhost + ``` + +1. Open your `gdk.yml`, and confirm that it has the following lines: + + ```yaml + postgresql: + host: localhost + ``` + +1. Reconfigure GDK: + + ```shell + gdk reconfigure + ``` + +1. On your database GUI, select `localhost` as host, `5432` as port and `gitlabhq_development` as database. + Alternatively, you can use the connection string `postgresql://localhost:5432/gitlabhq_development`. + +The new connection should be working now. + ## Access the GDK database with Visual Studio Code Use these instructions for exploring the GitLab database while developing with the GDK: diff --git a/doc/development/database_review.md b/doc/development/database_review.md index 2746d9f6582..42bfa656a61 100644 --- a/doc/development/database_review.md +++ b/doc/development/database_review.md @@ -108,7 +108,7 @@ the following preparations into account. - Ensure the down method reverts the changes in `db/structure.sql`. - Update the migration output whenever you modify the migrations during the review process. - Add tests for the migration in `spec/migrations` if necessary. See [Testing Rails migrations at GitLab](testing_guide/testing_migrations_guide.md) for more details. -- When [high-traffic](https://gitlab.com/gitlab-org/gitlab/-/blob/master/rubocop/rubocop-migrations.yml#L3) tables are involved in the migration, use the [`with_lock_retries`](migration_style_guide.md#retry-mechanism-when-acquiring-database-locks) helper method. Review the relevant [examples in our documentation](migration_style_guide.md#examples) for use cases and solutions. +- When [high-traffic](https://gitlab.com/gitlab-org/gitlab/-/blob/master/rubocop/rubocop-migrations.yml#L3) tables are involved in the migration, use the [`enable_lock_retries`](migration_style_guide.md#retry-mechanism-when-acquiring-database-locks) method to enable lock-retries. Review the relevant [examples in our documentation](migration_style_guide.md#usage-with-transactional-migrations) for use cases and solutions. - Ensure RuboCop checks are not disabled unless there's a valid reason to. - When adding an index to a [large table](https://gitlab.com/gitlab-org/gitlab/-/blob/master/rubocop/rubocop-migrations.yml#L3), test its execution using `CREATE INDEX CONCURRENTLY` in the `#database-lab` Slack channel and add the execution time to the MR description: @@ -128,7 +128,9 @@ test its execution using `CREATE INDEX CONCURRENTLY` in the `#database-lab` Slac - Write the raw SQL in the MR description. Preferably formatted nicely with [pgFormatter](https://sqlformat.darold.net) or [paste.depesz.com](https://paste.depesz.com) and using regular quotes + <!-- vale off --> (for example, `"projects"."id"`) and avoiding smart quotes (for example, `“projects”.“id”`). + <!-- vale on --> - In case of queries generated dynamically by using parameters, there should be one raw SQL query for each variation. For example, a finder for issues that may take as a parameter an optional filter on projects, diff --git a/doc/development/deprecation_guidelines/index.md b/doc/development/deprecation_guidelines/index.md index 3543345aa34..f8ee29e6904 100644 --- a/doc/development/deprecation_guidelines/index.md +++ b/doc/development/deprecation_guidelines/index.md @@ -32,6 +32,6 @@ It also should be [deprecated in advance](https://about.gitlab.com/handbook/mark For API removals, see the [GraphQL](../../api/graphql/index.md#deprecation-and-removal-process) and [GitLab API](../../api/index.md#compatibility-guidelines) guidelines. -For configuration removals, see the [Omnibus deprecation policy](https://docs.gitlab.com/omnibus/package-information/deprecation_policy.html). +For configuration removals, see the [Omnibus deprecation policy](../../administration/package_information/deprecation_policy.md). For versioning and upgrade details, see our [Release and Maintenance policy](../../policy/maintenance.md). diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md index b0fa6c3428c..5a4d365ed20 100644 --- a/doc/development/documentation/feature_flags.md +++ b/doc/development/documentation/feature_flags.md @@ -67,10 +67,12 @@ When the state of a flag changes (for example, disabled by default to enabled by Possible version history entries are: ```markdown -> - [Enabled on GitLab.com](issue-link) in GitLab X.X and is ready for production use. -> - [Enabled on GitLab.com](issue-link) in GitLab X.X and is ready for production use. Available to GitLab.com administrators only. -> - [Enabled with <flag name> flag](issue-link) for self-managed GitLab in GitLab X.X and is ready for production use. -> - [Feature flag <flag name> removed](issue-line) in GitLab X.X. +> - [Introduced](issue-link) in GitLab X.X. [Deployed behind the <flag name> flag](../../administration/feature_flags.md), disabled by default. +> - [Enabled on GitLab.com](issue-link) in GitLab X.X. +> - [Enabled on GitLab.com](issue-link) in GitLab X.X. Available to GitLab.com administrators only. +> - [Enabled on self-managed](issue-link) in GitLab X.X. +> - [Feature flag <flag name> removed](issue-link) in GitLab X.X. +> - [Generally available](issue-link) in GitLab X.X. ``` ## Feature flag documentation examples @@ -78,7 +80,7 @@ Possible version history entries are: The following examples show the progression of a feature flag. ```markdown -> Introduced in GitLab 13.7. +> Introduced in GitLab 13.7. [Deployed behind the `forti_token_cloud` flag](../../administration/feature_flags.md), disabled by default. FLAG: On self-managed GitLab, by default this feature is not available. To make it available, @@ -86,11 +88,11 @@ ask an administrator to [enable the `forti_token_cloud` flag](../administration/ The feature is not ready for production use. ``` -If it were to be updated in the future to enable its use in production, you can update the version history: +When the feature is enabled in production, you can update the version history: ```markdown -> - Introduced in GitLab 13.7. -> - [Enabled with `forti_token_cloud` flag](https://gitlab.com/issue/etc) for self-managed GitLab in GitLab X.X and ready for production use. +> - Introduced in GitLab 13.7. [Deployed behind the `forti_token_cloud` flag](../../administration/feature_flags.md), disabled by default. +> - [Enabled on self-managed](https://gitlab.com/issue/etc) GitLab 13.8. FLAG: On self-managed GitLab, by default this feature is available. To hide the feature per user, @@ -100,8 +102,9 @@ ask an administrator to [disable the `forti_token_cloud` flag](../administration And, when the feature is done and fully available to all users: ```markdown -> - Introduced in GitLab 13.7. -> - [Enabled on GitLab.com](https://gitlab.com/issue/etc) in GitLab X.X and is ready for production use. -> - [Enabled with `forti_token_cloud` flag](https://gitlab.com/issue/etc) for self-managed GitLab in GitLab X.X and is ready for production use. -> - [Feature flag `forti_token_cloud`](https://gitlab.com/issue/etc) removed in GitLab X.X. +> - Introduced in GitLab 13.7. [Deployed behind the `forti_token_cloud` flag](../../administration/feature_flags.md), disabled by default. +> - [Enabled on self-managed](https://gitlab.com/issue/etc) GitLab 13.8. +> - [Enabled on GitLab.com](https://gitlab.com/issue/etc) in GitLab 13.9. +> - [Feature flag `forti_token_cloud`](https://gitlab.com/issue/etc) removed in GitLab 14.0. +> - [Generally available](issue-link) in GitLab 14.0. ``` diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 59a1b8c7b99..a597ea512c6 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -131,10 +131,10 @@ The following metadata should be added when a page is moved to another location: - `redirect_to`: The relative path and filename (with an `.md` extension) of the location to which visitors should be redirected for a moved page. - [Learn more](#move-or-rename-a-page). + [Learn more](redirects.md). - `disqus_identifier`: Identifier for Disqus commenting system. Used to keep comments with a page that's been moved to a new URL. - [Learn more](#redirections-for-pages-with-disqus-comments). + [Learn more](redirects.md#redirections-for-pages-with-disqus-comments). ### Comments metadata @@ -156,133 +156,7 @@ Nanoc layout), which is displayed at the top of the page if defined. ## Move or rename a page -Moving or renaming a document is the same as changing its location. Be sure to -assign a technical writer to any merge request that renames or moves a page. -Technical Writers can help with any questions and can review your change. - -When moving or renaming a page, you must redirect browsers to the new page. -This ensures users find the new page, and have the opportunity to update their -bookmarks. - -There are two types of redirects: - -- Redirect codes added into the documentation files themselves, for users who - view the docs in `/help` on self-managed instances. For example, - [`/help` on GitLab.com](https://gitlab.com/help). -- [GitLab Pages redirects](../../user/project/pages/redirects.md), - for users who view the docs on [`docs.gitlab.com`](https://docs.gitlab.com). - -The Technical Writing team manages the [process](https://gitlab.com/gitlab-org/technical-writing/-/blob/main/.gitlab/issue_templates/tw-monthly-tasks.md) -to regularly update the [`redirects.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/content/_data/redirects.yaml) -file. - -To add a redirect: - -1. In the repository (`gitlab`, `gitlab-runner`, `omnibus-gitlab`, or `charts`), - create a new documentation file. Don't delete the old one. The easiest - way is to copy it. For example: - - ```shell - cp doc/user/search/old_file.md doc/api/new_file.md - ``` - -1. Add the redirect code to the old documentation file by running the - following Rake task. The first argument is the path of the old file, - and the second argument is the path of the new file: - - - To redirect to a page in the same project, use relative paths and - the `.md` extension. Both old and new paths start from the same location. - In the following example, both paths are relative to `doc/`: - - ```shell - bundle exec rake "gitlab:docs:redirect[doc/user/search/old_file.md, doc/api/new_file.md]" - ``` - - - To redirect to a page in a different project or site, use the full URL (with `https://`) : - - ```shell - bundle exec rake "gitlab:docs:redirect[doc/user/search/old_file.md, https://example.com]" - ``` - - Alternatively, you can omit the arguments and be asked to enter their values: - - ```shell - bundle exec rake gitlab:docs:redirect - ``` - - If you don't want to use the Rake task, you can use the following template. - However, the file paths must be relative to the `doc` or `docs` directory. - - Replace the value of `redirect_to` with the new file path and `YYYY-MM-DD` - with the date the file should be removed. - - Redirect files that link to docs in internal documentation projects - are removed after three months. Redirect files that link to external sites are - removed after one year: - - ```markdown - --- - redirect_to: '../newpath/to/file/index.md' - remove_date: 'YYYY-MM-DD' - --- - - This document was moved to [another location](../path/to/file/index.md). - - <!-- This redirect file can be deleted after <YYYY-MM-DD>. --> - <!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> - ``` - -1. If the documentation page being moved has any Disqus comments, follow the steps - described in [Redirections for pages with Disqus comments](#redirections-for-pages-with-disqus-comments). -1. Open a merge request with your changes. If a documentation page - you're removing includes images that aren't used - with any other documentation pages, be sure to use your merge request to delete - those images from the repository. -1. Assign the merge request to a technical writer for review and merge. -1. Search for links to the old documentation file. You must find and update all - links that point to the old documentation file: - - - In <https://gitlab.com/gitlab-com/www-gitlab-com>, search for full URLs: - `grep -r "docs.gitlab.com/ee/path/to/file.html" .` - - In <https://gitlab.com/gitlab-org/gitlab-docs/-/tree/master/content/_data>, - search the navigation bar configuration files for the path with `.html`: - `grep -r "path/to/file.html" .` - - In any of the four internal projects, search for links in the docs - and codebase. Search for all variations, including full URL and just the path. - For example, go to the root directory of the `gitlab` project and run: - - ```shell - grep -r "docs.gitlab.com/ee/path/to/file.html" . - grep -r "path/to/file.html" . - grep -r "path/to/file.md" . - grep -r "path/to/file" . - ``` - - You may need to try variations of relative links, such as `../path/to/file` or - `../file` to find every case. - -### Redirections for pages with Disqus comments - -If the documentation page being relocated already has Disqus comments, -we need to preserve the Disqus thread. - -Disqus uses an identifier per page, and for <https://docs.gitlab.com>, the page identifier -is configured to be the page URL. Therefore, when we change the document location, -we need to preserve the old URL as the same Disqus identifier. - -To do that, add to the front matter the variable `disqus_identifier`, -using the old URL as value. For example, let's say we moved the document -available under `https://docs.gitlab.com/my-old-location/README.html` to a new location, -`https://docs.gitlab.com/my-new-location/index.html`. - -Into the **new document** front matter, we add the following information. You must -include the filename in the `disqus_identifier` URL, even if it's `index.html` or `README.html`. - -```yaml ---- -disqus_identifier: 'https://docs.gitlab.com/my-old-location/README.html' ---- -``` +See [redirects](redirects.md). ## Merge requests for GitLab documentation @@ -405,76 +279,7 @@ on how the left-side navigation menu is built and updated. ## Previewing the changes live -NOTE: -To preview your changes to documentation locally, follow this -[development guide](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/README.md#development-when-contributing-to-gitlab-documentation) or [these instructions for GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/gitlab_docs.md). - -The live preview is currently enabled for the following projects: - -- [`gitlab`](https://gitlab.com/gitlab-org/gitlab) -- [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab) -- [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner) - -If your merge request has docs changes, you can use the manual `review-docs-deploy` job -to deploy the docs review app for your merge request. - - - -You must push a branch to those repositories, as it doesn't work for forks. - -The `review-docs-deploy*` job: - -1. Triggers a cross project pipeline and build the docs site with your changes. - -In case the review app URL returns 404, this means that either the site is not -yet deployed, or something went wrong with the remote pipeline. Give it a few -minutes and it should appear online, otherwise you can check the status of the -remote pipeline from the link in the merge request's job output. -If the pipeline failed or got stuck, drop a line in the `#docs` chat channel. - -NOTE: -Someone with no merge rights to the GitLab projects (think of forks from -contributors) cannot run the manual job. In that case, you can -ask someone from the GitLab team who has the permissions to do that for you. - -### Troubleshooting review apps - -In case the review app URL returns 404, follow these steps to debug: - -1. **Did you follow the URL from the merge request widget?** If yes, then check if - the link is the same as the one in the job output. -1. **Did you follow the URL from the job output?** If yes, then it means that - either the site is not yet deployed or something went wrong with the remote - pipeline. Give it a few minutes and it should appear online, otherwise you - can check the status of the remote pipeline from the link in the job output. - If the pipeline failed or got stuck, drop a line in the `#docs` chat channel. - -### Technical aspects - -If you want to know the in-depth details, here's what's really happening: - -1. You manually run the `review-docs-deploy` job in a merge request. -1. The job runs the [`scripts/trigger-build`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/trigger-build) - script with the `docs deploy` flag, which triggers the "Triggered from `gitlab-org/gitlab` 'review-docs-deploy' job" - pipeline trigger in the `gitlab-org/gitlab-docs` project for the `$DOCS_BRANCH` (defaults to `main`). -1. The preview URL is shown both at the job output and in the merge request - widget. You also get the link to the remote pipeline. -1. In the `gitlab-org/gitlab-docs` project, the pipeline is created and it - [skips the test jobs](https://gitlab.com/gitlab-org/gitlab-docs/blob/8d5d5c750c602a835614b02f9db42ead1c4b2f5e/.gitlab-ci.yml#L50-55) - to lower the build time. -1. Once the docs site is built, the HTML files are uploaded as artifacts. -1. A specific runner tied only to the docs project, runs the Review App job - that downloads the artifacts and uses `rsync` to transfer the files over - to a location where NGINX serves them. - -The following GitLab features are used among others: - -- [Manual jobs](../../ci/jobs/job_control.md#create-a-job-that-must-be-run-manually) -- [Multi project pipelines](../../ci/pipelines/multi_project_pipelines.md) -- [Review Apps](../../ci/review_apps/index.md) -- [Artifacts](../../ci/yaml/index.md#artifacts) -- [Specific runner](../../ci/runners/runners_scope.md#prevent-a-specific-runner-from-being-enabled-for-other-projects) -- [Pipelines for merge requests](../../ci/pipelines/merge_request_pipelines.md) +See how you can use review apps to [preview your changes live](review_apps.md). ## Testing diff --git a/doc/development/documentation/redirects.md b/doc/development/documentation/redirects.md new file mode 100644 index 00000000000..eb6878f5870 --- /dev/null +++ b/doc/development/documentation/redirects.md @@ -0,0 +1,155 @@ +--- +stage: none +group: Documentation Guidelines +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +description: Learn how to contribute to GitLab Documentation. +--- + +<!--- + The clean_redirects Rake task in the gitlab-docs repository manually + excludes this file. If the line containing remove_date is moved to a new + document, update the Rake task with the new location. + + https://gitlab.com/gitlab-org/gitlab-docs/-/blob/1979f985708d64558bb487fbe9ed5273729c01b7/Rakefile#L306 +---> + +# Redirects in GitLab documentation + +Moving or renaming a document is the same as changing its location. Be sure +to assign a technical writer to any merge request that renames or moves a page. +Technical Writers can help with any questions and can review your change. + +When moving or renaming a page, you must redirect browsers to the new page. +This ensures users find the new page, and have the opportunity to update their +bookmarks. + +There are two types of redirects: + +- Redirect added into the documentation files themselves, for users who + view the docs in `/help` on self-managed instances. For example, + [`/help` on GitLab.com](https://gitlab.com/help). +- [GitLab Pages redirects](../../user/project/pages/redirects.md), + for users who view the docs on [`docs.gitlab.com`](https://docs.gitlab.com). + + The Technical Writing team manages the [process](https://gitlab.com/gitlab-org/technical-writing/-/blob/main/.gitlab/issue_templates/tw-monthly-tasks.md) + to regularly update and [clean up the redirects](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/raketasks.md#clean-up-redirects). + If you're a contributor, you may add a new redirect, but you don't need to delete + the old ones. This process is automatic and handled by the Technical + Writing team. + +NOTE: +If the old page you're renaming doesn't exist in a stable branch, skip the +following steps and ask a Technical Writer to add the redirect in +[`redirects.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/content/_data/redirects.yaml). +For example, if you add a new page on the 3rd of the month and then rename it before it gets +added in the stable branch on the 18th, the old page will never be part of the internal `/help`. +In that case, you can jump straight to the +[Pages redirect](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/maintenance.md#pages-redirects). + +To add a redirect: + +1. In the repository (`gitlab`, `gitlab-runner`, `omnibus-gitlab`, or `charts`), + create a new documentation file. Don't delete the old one. The easiest + way is to copy it. For example: + + ```shell + cp doc/user/search/old_file.md doc/api/new_file.md + ``` + +1. Add the redirect code to the old documentation file by running the + following Rake task. The first argument is the path of the old file, + and the second argument is the path of the new file: + + - To redirect to a page in the same project, use relative paths and + the `.md` extension. Both old and new paths start from the same location. + In the following example, both paths are relative to `doc/`: + + ```shell + bundle exec rake "gitlab:docs:redirect[doc/user/search/old_file.md, doc/api/new_file.md]" + ``` + + - To redirect to a page in a different project or site, use the full URL (with `https://`) : + + ```shell + bundle exec rake "gitlab:docs:redirect[doc/user/search/old_file.md, https://example.com]" + ``` + + Alternatively, you can omit the arguments and be asked to enter their values: + + ```shell + bundle exec rake gitlab:docs:redirect + ``` + + If you don't want to use the Rake task, you can use the following template. + However, the file paths must be relative to the `doc` or `docs` directory. + + Replace the value of `redirect_to` with the new file path and `YYYY-MM-DD` + with the date the file should be removed. + + Redirect files that link to docs in internal documentation projects + are removed after three months. Redirect files that link to external sites are + removed after one year: + + ```markdown + --- + redirect_to: '../newpath/to/file/index.md' + remove_date: 'YYYY-MM-DD' + --- + + This document was moved to [another location](../path/to/file/index.md). + + <!-- This redirect file can be deleted after <YYYY-MM-DD>. --> + <!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> + ``` + +1. If the documentation page being moved has any Disqus comments, follow the steps + described in [Redirections for pages with Disqus comments](#redirections-for-pages-with-disqus-comments). +1. Open a merge request with your changes. If a documentation page + you're removing includes images that aren't used + with any other documentation pages, be sure to use your merge request to delete + those images from the repository. +1. Assign the merge request to a technical writer for review and merge. +1. Search for links to the old documentation file. You must find and update all + links that point to the old documentation file: + + - In <https://gitlab.com/gitlab-com/www-gitlab-com>, search for full URLs: + `grep -r "docs.gitlab.com/ee/path/to/file.html" .` + - In <https://gitlab.com/gitlab-org/gitlab-docs/-/tree/master/content/_data>, + search the navigation bar configuration files for the path with `.html`: + `grep -r "path/to/file.html" .` + - In any of the four internal projects, search for links in the docs + and codebase. Search for all variations, including full URL and just the path. + For example, go to the root directory of the `gitlab` project and run: + + ```shell + grep -r "docs.gitlab.com/ee/path/to/file.html" . + grep -r "path/to/file.html" . + grep -r "path/to/file.md" . + grep -r "path/to/file" . + ``` + + You may need to try variations of relative links, such as `../path/to/file` or + `../file` to find every case. + +## Redirections for pages with Disqus comments + +If the documentation page being relocated already has Disqus comments, +we need to preserve the Disqus thread. + +Disqus uses an identifier per page, and for <https://docs.gitlab.com>, the page identifier +is configured to be the page URL. Therefore, when we change the document location, +we need to preserve the old URL as the same Disqus identifier. + +To do that, add to the front matter the variable `disqus_identifier`, +using the old URL as value. For example, let's say we moved the document +available under `https://docs.gitlab.com/my-old-location/README.html` to a new location, +`https://docs.gitlab.com/my-new-location/index.html`. + +Into the **new document** front matter, we add the following information. You must +include the filename in the `disqus_identifier` URL, even if it's `index.html` or `README.html`. + +```yaml +--- +disqus_identifier: 'https://docs.gitlab.com/my-old-location/README.html' +--- +``` diff --git a/doc/development/documentation/review_apps.md b/doc/development/documentation/review_apps.md new file mode 100644 index 00000000000..2b8c412f165 --- /dev/null +++ b/doc/development/documentation/review_apps.md @@ -0,0 +1,101 @@ +--- +stage: none +group: Documentation Guidelines +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +description: Learn how documentation review apps work. +--- + +# Documentation review apps + +If you're a GitLab team member and your merge request contains documentation changes, you can use a review app to preview +how they would look if they were deployed to the [GitLab Docs site](https://docs.gitlab.com). + +Review apps are enabled for the following projects: + +- [GitLab](https://gitlab.com/gitlab-org/gitlab) +- [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab) +- [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner) +- [GitLab Charts](https://gitlab.com/gitlab-org/charts/gitlab) + +Alternatively, check the [`gitlab-docs` development guide](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/README.md#development-when-contributing-to-gitlab-documentation) +or [the GDK documentation](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/gitlab_docs.md) +to render and preview the documentation locally. + +## How to trigger a review app + +If a merge request has documentation changes, use the `review-docs-deploy` manual job +to deploy the documentation review app for your merge request. + + + +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. + +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. + +## Technical aspects + +If you want to know the in-depth details, here's what's really happening: + +1. You manually run the `review-docs-deploy` job in a merge request. +1. The job runs the [`scripts/trigger-build`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/trigger-build) + script with the `docs deploy` flag, which triggers the "Triggered from `gitlab-org/gitlab` 'review-docs-deploy' job" + pipeline trigger in the `gitlab-org/gitlab-docs` project for the `$DOCS_BRANCH` (defaults to `main`). +1. The preview URL is shown both at the job output and in the merge request + widget. You also get the link to the remote pipeline. +1. In the `gitlab-org/gitlab-docs` project, the pipeline is created and it + [skips the test jobs](https://gitlab.com/gitlab-org/gitlab-docs/blob/8d5d5c750c602a835614b02f9db42ead1c4b2f5e/.gitlab-ci.yml#L50-55) + to lower the build time. +1. Once the docs site is built, the HTML files are uploaded as artifacts. +1. A specific runner tied only to the docs project, runs the Review App job + that downloads the artifacts and uses `rsync` to transfer the files over + to a location where NGINX serves them. + +The following GitLab features are used among others: + +- [Manual jobs](../../ci/jobs/job_control.md#create-a-job-that-must-be-run-manually) +- [Multi project pipelines](../../ci/pipelines/multi_project_pipelines.md) +- [Review Apps](../../ci/review_apps/index.md) +- [Artifacts](../../ci/yaml/index.md#artifacts) +- [Specific runner](../../ci/runners/runners_scope.md#prevent-a-specific-runner-from-being-enabled-for-other-projects) +- [Pipelines for merge requests](../../ci/pipelines/merge_request_pipelines.md) + +## Troubleshooting review apps + +### Review app returns a 404 error + +If the review app URL returns a 404 error, either the site is not +yet deployed, or something went wrong with the remote pipeline. You can: + +- Wait a few minutes and it should appear online. +- Check the manual job's log and verify the URL. If the URL is different, try the + one from the job log. +- Check the status of the remote pipeline from the link in the merge request's job output. + If the pipeline failed or got stuck, GitLab team members can ask for help in the `#docs` + chat channel. Contributors can ping a technical writer in the merge request. + +### Not enough disk space + +Sometimes the review app server is full and there is no more disk space. Each review +app takes about 570MB of disk space. + +A cron job to remove review apps older than 20 days runs hourly, +but the disk space still occasionally fills up. To manually free up more space, +a GitLab technical writing team member can: + +1. Navigate to the [`gitlab-docs` schedules page](https://gitlab.com/gitlab-org/gitlab-docs/-/pipeline_schedules). +1. Select the play button for the `Remove old review apps from review app server` + schedule. By default, this cleans up review apps older than 14 days. +1. Navigate to the [pipelines page](https://gitlab.com/gitlab-org/gitlab-docs/-/pipelines) + and start the manual job called `clean-pages`. + +If the job says no review apps were found in that period, edit the `CLEAN_REVIEW_APPS_DAYS` +variable in the schedule, and repeat the process above. Gradually decrease the variable +until the free disk space reaches an acceptable amount (for example, 3GB). +Remember to set it to 14 again when you're done. + +There's an issue to [migrate from the DigitalOcean server to GCP buckets](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/735)), +which should solve the disk space problem. diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md index 046de5c6d86..cd69154217c 100644 --- a/doc/development/documentation/site_architecture/index.md +++ b/doc/development/documentation/site_architecture/index.md @@ -33,7 +33,6 @@ from where content is sourced, the `gitlab-docs` project, and the published outp D --> E E -- Build pipeline --> F F[docs.gitlab.com] - G[/ce/] H[/ee/] I[/runner/] J[/omnibus/] @@ -42,7 +41,6 @@ from where content is sourced, the `gitlab-docs` project, and the published outp F --> I F --> J F --> K - H -- symlink --> G ``` GitLab docs content isn't kept in the `gitlab-docs` repository. @@ -54,15 +52,6 @@ product, and all together are pulled to generate the docs website: - [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/-/tree/main/docs) - [GitLab Chart](https://gitlab.com/charts/gitlab/tree/master/doc) -NOTE: -In September 2019, we [moved towards a single codebase](https://gitlab.com/gitlab-org/gitlab/-/issues/2952), -as such the docs for CE and EE are now identical. For historical reasons and -in order not to break any existing links throughout the internet, we still -maintain the CE docs (`https://docs.gitlab.com/ce/`), although it is hidden -from the website, and is now a symlink to the EE docs. When -[Support wildcard redirects](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/500) is resolved, -we can remove this completely. - ## Assets To provide an optimized site structure, design, and a search-engine friendly diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index 4e548179b9e..2cbecc91b20 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -420,6 +420,11 @@ Some contractions, however, should be avoided: | Requests to localhost are not allowed. | Requests to localhost aren't allowed. | | Specified URL cannot be used. | Specified URL can't be used. | +### Acronyms + +If you use an acronym, spell it out on first use on a page. You do not need to spell it out more than once on a page. +When possible, try to avoid acronyms in headings. + ## Text - [Write in Markdown](#markdown). @@ -438,8 +443,21 @@ Some contractions, however, should be avoided: - List item 2 ``` +### Comments + +To embed comments within Markdown, use standard HTML comments that are not rendered +when published. Example: + +```html +<!-- This is a comment that is not rendered --> +``` + ### Emphasis +Use **bold** rather than italic to provide emphasis. GitLab uses a sans-serif font and italic text does not stand out as much as it would in a serif font. For details, see [Butterick's Practical Typography guide on bold or italic](https://practicaltypography.com/bold-or-italic.html). + +You can use italics when you are introducing a term for the first time. Otherwise, use bold. + - Use double asterisks (`**`) to mark a word or text in bold (`**bold**`). - Use underscore (`_`) for text in italics (`_italic_`). - Use greater than (`>`) for blockquotes. @@ -460,6 +478,7 @@ Follow these guidelines for punctuation: | Use serial commas (Oxford commas) before the final **and** or **or** in a list of three or more items. (Tested in [`OxfordComma.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/OxfordComma.yml).) | You can create new issues, merge requests, and milestones. | | Always add a space before and after dashes when using it in a sentence (for replacing a comma, for example). | You should try this - or not. | | When a colon is part of a sentence, always use lowercase after the colon. | Linked issues: a way to create a relationship between issues. | +| Do not use typographer's quotes. Use straight quotes instead. (Tested in [`NonStandardQuotes.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/NonStandardQuotes.yml).) | "It's the questions we can't answer that teach us the most"---Patrick Rothfuss | <!-- vale gitlab.Repetition = YES --> @@ -751,6 +770,7 @@ Valid for Markdown content only, not for front matter entries: For other punctuation rules, refer to the [Pajamas Design System Punctuation section](https://design.gitlab.com/content/punctuation/). +This is overridden by the [documentation-specific punctuation rules](#punctuation). ## Headings @@ -1003,9 +1023,23 @@ document to ensure it links to the most recent version of the file. ## Navigation -When documenting navigation through the user interface, use these terms and styles. +When documenting how to navigate through the GitLab UI: + +- Always use location, then action. + - `From the **Visibility** list,` (location) `select **Public**.` (action) +- Be brief and specific. For example: + - Avoid: `Select **Save** for the changes to take effect.` + - Use instead: `Select **Save**.` +- When selecting from high-level UI elements, use the word **on**. + - Avoid: `From the left sidebar...` or `In the left sidebar...` + - Use instead: `On the left sidebar...` +- If a step must include a reason, start the step with it. + - Avoid: `Select the link in the merge request to view the changes.` + - Use instead: `To view the changes, select the link in the merge request.` +- If a step is optional, start the step with the word `Optional` followed by a period. + - `1. Optional. Enter a name for the dog.` -### What to call the menus +### Names for menus Use these terms when referring to the main GitLab user interface elements: @@ -1017,9 +1051,14 @@ elements: - **Right sidebar**: This is the navigation sidebar on the right of the user interface, specific to the open issue, merge request, or epic. -### How to document the menus +### Names for UI elements -To be consistent, use this format when you write about UI navigation. +UI elements, like button and checkbox names, should be **bold**. +Guidance for each individual UI element is in [the word list](word_list.md). + +### How to write navigation task steps + +To be consistent, use this format when you write navigation steps in a task topic. 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Settings > CI/CD**. @@ -1034,20 +1073,27 @@ Another example: An Admin Area example: ```markdown -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. ``` -This text renders this output: +To select your avatar: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +```markdown +1. On the top bar, in the top right corner, select your avatar. +``` ## Images Images, including screenshots, can help a reader better understand a concept. -However, they can be hard to maintain, and should be used sparingly. +However, they should be used sparingly because: -Before including an image in the documentation, ensure it provides value to the -reader. +- They tend to become out-of-date. +- They are difficult and expensive to localize. +- They cannot be read by screen readers. + +If you do include an image in the documentation, ensure it provides value. +Don't use `lorem ipsum` text. Try to replicate how the feature would be +used in a real-world scenario, and [use realistic text](#fake-user-information). ### Capture the image @@ -1106,7 +1152,7 @@ known tool is [`pngquant`](https://pngquant.org/), which is cross-platform and open source. Install it by visiting the official website and following the instructions for your OS. -GitLab has a [Rake task](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/tasks/pngquant.rake) +GitLab has a [Ruby script](https://gitlab.com/gitlab-org/gitlab/-/blob/master/bin/pngquant) that you can use to automate the process. In the root directory of your local copy of `https://gitlab.com/gitlab-org/gitlab`, run in a terminal: @@ -1114,19 +1160,26 @@ copy of `https://gitlab.com/gitlab-org/gitlab`, run in a terminal: been compressed: ```shell - bundle exec rake pngquant:lint + bin/pngquant lint ``` - Compress all documentation PNG images using `pngquant`: ```shell - bundle exec rake pngquant:compress + bin/pngquant compress + ``` + +- Compress specific files: + + ```shell + bin/pngquant compress doc/user/img/award_emoji_select.png doc/user/img/markdown_logo.png ``` -The only caveat is that the task runs on all images under `doc/`, not only the -ones you might have included in a merge request. In that case, you can run the -compress task and only commit the images that are relevant to your merge -request. +- Compress all PNG files in a specific directory: + + ```shell + bin/pngquant compress doc/user/img + ``` ## Videos @@ -1288,64 +1341,22 @@ For a complete reference on code blocks, see the [Kramdown guide](https://about. > [Introduced](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/384) in GitLab 12.7. You can use icons from the [GitLab SVG library](https://gitlab-org.gitlab.io/gitlab-svgs/) -directly in the documentation. - -This way, you can achieve a consistent look when writing about interacting with -GitLab user interface elements. - -Usage examples: - -- Icon with default size (16px): `**{icon-name}**` +directly in the documentation. For example, `**{tanuki}**` renders as: **{tanuki}**. - Example: `**{tanuki}**` renders as: **{tanuki}**. -- Icon with custom size: `**{icon-name, size}**` +In most cases, you should avoid using the icons in text. +However, you can use an icon when hover text is the only +available way to describe a UI element. For example, **Delete** or **Edit** buttons +often have hover text only. - Available sizes (in pixels): 8, 10, 12, 14, 16, 18, 24, 32, 48, and 72 +When you do use an icon, start with the hover text and follow it with the SVG reference in parentheses. - Example: `**{tanuki, 24}**` renders as: **{tanuki, 24}**. -- Icon with custom size and class: `**{icon-name, size, class-name}**`. +- Avoid: `Select **{pencil}** **Edit**.` This generates as: Select **{pencil}** **Edit**. +- Use instead: `Select **Edit** (**{pencil}**).` This generates as: Select **Edit** (**{pencil}**). - You can access any class available to this element in GitLab documentation CSS. +Do not use words to describe the icon: - Example with `float-right`, a - [Bootstrap utility class](https://getbootstrap.com/docs/4.4/utilities/float/): - `**{tanuki, 32, float-right}**` renders as: **{tanuki, 32, float-right}** - -### When to use icons - -Icons should be used sparingly, and only in ways that aid and do not hinder the -readability of the text. - -For example, this Markdown adds little to the accompanying text: - -```markdown -1. Go to **{home}** **Project information > Details**. -``` - -1. Go to **{home}** **Project information > Details**. - -However, these tables might help the reader connect the text to the user -interface: - -```markdown -| Section | Description | -|:-------------------------|:----------------------------------------------------------------------------------------------------------------------------| -| **{overview}** Overview | View your GitLab Dashboard, and administer projects, users, groups, jobs, runners, and Gitaly servers. | -| **{monitor}** Monitoring | View GitLab system information, and information on background jobs, logs, health checks, requests profiles, and audit events. | -| **{messages}** Messages | Send and manage broadcast messages for your users. | -``` - -| Section | Description | -|:-------------------------|:----------------------------------------------------------------------------------------------------------------------------| -| **{overview}** Overview | View your GitLab Dashboard, and administer projects, users, groups, jobs, runners, and Gitaly servers. | -| **{monitor}** Monitoring | View GitLab system information, and information on background jobs, logs, health checks, requests profiles, and audit events. | -| **{messages}** Messages | Send and manage broadcast messages for your users. | - -Use an icon when you find yourself having to describe an interface element. For -example: - -- Do: Select the Admin Area icon ( **{admin}** ). -- Don't: Select the Admin Area icon (the wrench icon). +- Avoid: `Select **Erase job log** (the trash icon).` +- Use instead: `Select **Erase job log** (**{remove}**).` This generates as: Select **Erase job log** (**{remove}**). ## Alert boxes @@ -1456,27 +1467,9 @@ Follow these styles when you're describing user interface elements in an application: - For elements with a visible label, use that label in bold with matching case. - For example, `the **Cancel** button`. + For example, `Select **Cancel**`. - For elements with a tooltip or hover label, use that label in bold with - matching case. For example, `the **Add status emoji** button`. - -### Verbs for UI elements - -Use these verbs for specific uses with user interface -elements: - -| Recommended | Used for | Replaces | -|:--------------------|:--------------------------------------|:----------------------| -| select | buttons, links, menu items, dropdowns | click, press, hit | -| select or clear | checkboxes | enable, click, press | -| expand | expandable sections | open | -| turn on or turn off | toggles | flip, enable, disable | - -### Other Verbs - -| Recommended | Used for | Replaces | -|:------------|:--------------------------------|:----------------------| -| go to | making a browser go to location | navigate to, open | + matching case. For example, `Select **Add status emoji**`. ## GitLab versions @@ -1504,10 +1497,6 @@ tagged and released set of documentation for your installed version: When a feature is added or updated, you can include its version information either as a **Version history** item or as an inline text reference. -Version text shouldn't include information about the tier in which the feature -is available. This information is provided by the [product badge](#product-tier-badges) -displayed for the page or feature. - #### Version text in the **Version History** If all content in a section is related, add version text after the header for @@ -1523,6 +1512,10 @@ the section. The version information must: - Whenever possible, include a link to the completed issue, merge request, or epic that introduced the feature. An issue is preferred over a merge request, and a merge request is preferred over an epic. +- Do not include information about the tier, unless documenting a tier change + (for example, `Feature X [moved](issue-link) to Premium in GitLab 19.2`). +- Do not link to the pricing page. + The tier is provided by the [product badge](#product-tier-badges) on the heading. ```markdown ## Feature name @@ -1647,37 +1640,24 @@ When names change, it is more complicated to search or grep text that has line b ### Product tier badges -Tier badges are displayed as orange text next to a heading. For example: +Tier badges are displayed as orange text next to a heading. These badges link to the GitLab +pricing page. For example:  You must assign a tier badge: -- To [all H1 topic headings](#product-tier-badges-on-headings). +- To all H1 topic headings. - To topic headings that don't apply to the same tier as the H1. -- To [sections of a topic](#product-tier-badges-on-other-content), - if they apply to a tier other than what applies to the H1. - -#### Product tier badges on headings -To add a tier badge to a heading, add the relevant [tier badge](#available-product-tier-badges) +To add a tier badge to a heading, add the relevant tier badge after the heading text. For example: ```markdown # Heading title **(FREE)** ``` -#### Product tier badges on other content - -In paragraphs, list names, and table cells, an information icon displays when you -add a tier badge. More verbose information displays when a user points to the icon: - -- `**(FREE)**` displays as **(FREE)** -- `**(FREE SELF)**` displays as **(FREE SELF)** -- `**(FREE SAAS)**` displays as **(FREE SAAS)** - -The `**(FREE)**` generates a `span` element to trigger the -badges and tooltips (`<span class="badge-trigger free">`). +Do not add tier badges inline with other text. The single source of truth for a feature should be the heading where the functionality is described. #### Available product tier badges diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index 9e921bb30f0..eafe0e7a1c2 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -17,15 +17,17 @@ For guidance not on this page, we defer to these style guides: <!-- vale off --> <!-- markdownlint-disable --> -## @mention +## `@mention` -Try to avoid. Say "mention" instead, and consider linking to the +Try to avoid **`@mention`**. Say **mention** instead, and consider linking to the [mentions topic](../../../user/project/issues/issue_data_and_actions.md#mentions). -Don't use `code formatting`. +Don't use backticks. ## above -Try to avoid extra words when referring to an example or table in a documentation page, but if required, use **previously** instead. +Try to avoid using **above** when referring to an example or table in a documentation page. If required, use **previous** instead. For example: + +- In the previous example, the dog had fleas. ## admin, admin area @@ -33,55 +35,111 @@ Use **administration**, **administrator**, **administer**, or **Admin Area** ins ## allow, enable -Try to avoid, unless you are talking about security-related features. For example: +Try to avoid **allow** and **enable**, unless you are talking about security-related features. For example: -- Avoid: This feature allows you to create a pipeline. -- Use instead: Use this feature to create a pipeline. +- Do: Use this feature to create a pipeline. +- Do not: This feature allows you to create a pipeline. This phrasing is more active and is from the user perspective, rather than the person who implemented the feature. [View details in the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/allow-allows). ## Alpha -Uppercase. For example: **The XYZ feature is in Alpha.** or **This Alpha release is ready to test.** +Use uppercase for **Alpha**. For example: **The XYZ feature is in Alpha.** or **This Alpha release is ready to test.** You might also want to link to [this section](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha-beta-ga) in the handbook when writing about Alpha features. ## and/or -Instead of **and/or**, use or or rewrite the sentence to spell out both options. +Instead of **and/or**, use **or** or rewrite the sentence to spell out both options. + +## area + +Use [**section**](#section) instead of **area**. The only exception is [the Admin Area](#admin-admin-area). ## below -Try to avoid extra words when referring to an example or table in a documentation page, but if required, use **following** instead. +Try to avoid **below** when referring to an example or table in a documentation page. If required, use **following** instead. For example: + +- In the following example, the dog has fleas. ## Beta -Uppercase. For example: **The XYZ feature is in Beta.** or **This Beta release is ready to test.** +Use uppercase for **Beta**. For example: **The XYZ feature is in Beta.** or **This Beta release is ready to test.** You might also want to link to [this section](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha-beta-ga) in the handbook when writing about Beta features. ## blacklist -Do not use. Another option is **denylist**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml)) +Do not use **blacklist**. Another option is **denylist**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml)) ## board Use lowercase for **boards**, **issue boards**, and **epic boards**. +## box + +Use **text box** to refer to the UI field. Do not use **field** or **box**. For example: + +- In the **Variable name** text box, enter `my text`. + +## button + +Don't use a descriptor with **button**. + +- Do: Select **Run pipelines**. +- Do not: Select the **Run pipelines** button. + +## cannot, can not + +Use **cannot** instead of **can not**. You can also use **can't**. + +See also [contractions](index.md#contractions). + ## checkbox -One word, **checkbox**. Do not use **check box**. +Use one word for **checkbox**. Do not use **check box**. + +You **select** (not **check** or **enable**) and **clear** (not **deselect** or **disable**) checkboxes. +For example: + +- Select the **Protect environment** checkbox. +- Clear the **Protect environment** checkbox. + +If you must refer to the checkbox, you can say it is selected or cleared. For example: + +- Ensure the **Protect environment** checkbox is cleared. +- Ensure the **Protect environment** checkbox is selected. ## CI/CD -Always uppercase. No need to spell out on first use. +CI/CD is always uppercase. No need to spell it out on first use. + +## click + +Do not use **click**. Instead, use **select** with buttons, links, menu items, and lists. +**Select** applies to more devices, while **click** is more specific to a mouse. + +## collapse + +Use **collapse** instead of **close** when you are talking about expanding or collapsing a section in the UI. + +## confirmation dialog + +Use **confirmation dialog** to describe the dialog box that asks you to confirm your action. For example: + +- On the confirmation dialog, select **OK**. ## currently -Do not use 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)) +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)) + +## deploy board + +Use lowercase for **deploy board**. ## Developer @@ -92,26 +150,35 @@ When writing about the Developer role: - Do not use the phrase, **if you are a developer** to mean someone who is assigned the Developer role. Instead, write it out. For example, **if you are assigned the Developer role**. - To describe a situation where the Developer role is the minimum required: - - Avoid: **the Developer role or higher** - - Use instead: **at least the Developer role** + - Avoid: the Developer role or higher + - Use instead: at least the Developer role Do not use **Developer permissions**. A user who is assigned the Developer role has a set of associated permissions. ## disable -See [the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/d/disable-disabled) for guidance. +See [the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/d/disable-disabled) for guidance on **disable**. Use **inactive** or **off** instead. ([Vale](../testing.md#vale) rule: [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml)) +## dropdown list + +Use **dropdown list** to refer to the UI element. Do not use **dropdown** without **list** after it. +Do not use **drop-down** (hyphenated), **dropdown menu**, or other variants. + +For example: + +- From the **Visibility** dropdown list, select **Public**. + ## earlier -Use when talking about version numbers. +Use **earlier** when talking about version numbers. -- Avoid: In GitLab 14.1 and lower. -- Use instead: In GitLab 14.1 and earlier. +- Do: In GitLab 14.1 and earlier. +- Do not: In GitLab 14.1 and lower. ## easily -Do not use. If the user doesn't find the process to be easy, we lose their trust. +Do not use **easily**. If the user doesn't find the process to be easy, we lose their trust. ## e.g. @@ -119,60 +186,75 @@ Do not use Latin abbreviations. Use **for example**, **such as**, **for instance ## email -Do not use **e-mail** with a hyphen. When plural, use **emails** or **email messages**. +Do not use **e-mail** with a hyphen. When plural, use **emails** or **email messages**. ([Vale](../testing.md#vale) rule: [`SubstitutionSuggestions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml)) ## enable -See [the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/e/enable-enables) for guidance. +See [the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/e/enable-enables) for guidance on **enable**. Use **active** or **on** instead. ([Vale](../testing.md#vale) rule: [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml)) +## enter + +Use **enter** instead of **type** when talking about putting values into text boxes. + ## epic -Lowercase. +Use lowercase for **epic**. ## epic board -Lowercase. +Use lowercase for **epic board**. ## etc. -Try to avoid. Be as specific as you can. Do not use **and so on** as a replacement. +Try to avoid **etc.**. Be as specific as you can. Do not use **and so on** as a replacement. -- Avoid: You can update objects, like merge requests, issues, etc. -- Use instead: You can update objects, like merge requests and issues. +- Do: You can update objects, like merge requests and issues. +- Do not: You can update objects, like merge requests, issues, etc. + +## expand + +Use **expand** instead of **open** when you are talking about expanding or collapsing a section in the UI. + +## field + +Use **box** instead of **field** or **text box**. + +- Avoid: In the **Variable name** field, enter `my text`. +- Use instead: In the **Variable name** box, enter `my text`. ## foo -Do not use in product documentation. You can use it in our API and contributor documentation, but try to use a clearer and more meaningful example instead. +Do not use **foo** in product documentation. You can use it in our API and contributor documentation, but try to use a clearer and more meaningful example instead. ## future tense -When possible, use present tense instead. For example, use `after you execute this command, GitLab displays the result` instead of `after you execute this command, GitLab will display the result`. ([Vale](../testing.md#vale) rule: [`FutureTense.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FutureTense.yml)) +When possible, use present tense instead of future tense. For example, use **after you execute this command, GitLab displays the result** instead of **after you execute this command, GitLab will display the result**. ([Vale](../testing.md#vale) rule: [`FutureTense.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FutureTense.yml)) ## Geo -Title case. +Use title case for **Geo**. ## GitLab -Do not make possessive (GitLab's). This guidance follows [GitLab Trademark Guidelines](https://about.gitlab.com/handbook/marketing/corporate-marketing/brand-activation/trademark-guidelines/). +Do not make **GitLab** possessive (GitLab's). This guidance follows [GitLab Trademark Guidelines](https://about.gitlab.com/handbook/marketing/corporate-marketing/brand-activation/trademark-guidelines/). ## GitLab.com -Refers to the GitLab instance managed by GitLab itself. +**GitLab.com** refers to the GitLab instance managed by GitLab itself. ## GitLab SaaS -Refers to the product license that provides access to GitLab.com. Does not refer to the +**GitLab SaaS** refers to the product license that provides access to GitLab.com. It does not refer to the GitLab instance managed by GitLab itself. ## GitLab Runner -Title case. This is the product you install. See also [runners](#runner-runners) and [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/233529). +Use title case for **GitLab Runner**. This is the product you install. See also [runners](#runner-runners) and [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/233529). ## GitLab self-managed -Refers to the product license for GitLab instances managed by customers themselves. +Use **GitLab self-managed** to refer to the product license for GitLab instances managed by customers themselves. ## Guest @@ -183,25 +265,32 @@ When writing about the Guest role: - Do not use the phrase, **if you are a guest** to mean someone who is assigned the Guest role. Instead, write it out. For example, **if you are assigned the Guest role**. - To describe a situation where the Guest role is the minimum required: - - Avoid: **the Guest role or higher** - - Use instead: **at least the Guest role** + - Avoid: the Guest role or higher + - Use instead: at least the Guest role Do not use **Guest permissions**. A user who is assigned the Guest role has a set of associated permissions. ## handy -Do not use. If the user doesn't find the feature or process to be handy, we lose their trust. +Do not use **handy**. If the user doesn't find the feature or process to be handy, we lose their trust. ([Vale](../testing.md#vale) rule: [`Simplicity.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Simplicity.yml)) ## high availability, HA -Do not use. Instead, direct readers to the GitLab [reference architectures](../../../administration/reference_architectures/index.md) for information about configuring GitLab for handling greater amounts of users. +Do not use **high availability** or **HA**. Instead, direct readers to the GitLab [reference architectures](../../../administration/reference_architectures/index.md) for information about configuring GitLab for handling greater amounts of users. ## higher -Do not use when talking about version numbers. +Do not use **higher** when talking about version numbers. -- Avoid: In GitLab 14.1 and higher. -- Use instead: In GitLab 14.1 and later. +- Do: In GitLab 14.1 and later. +- Do not: In GitLab 14.1 and higher. + +## hit + +Don't use **hit** to mean **press**. + +- Avoid: Hit the **ENTER** button. +- Use instead: Press **ENTER**. ## I @@ -213,19 +302,19 @@ Do not use Latin abbreviations. Use **that is** instead. ([Vale](../testing.md#v ## in order to -Do not use. Use **to** instead. ([Vale](../testing.md#vale) rule: [`Wordy.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Wordy.yml)) +Do not use **in order to**. Use **to** instead. ([Vale](../testing.md#vale) rule: [`Wordy.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Wordy.yml)) ## issue -Lowercase. +Use lowercase for **issue**. ## issue board -Lowercase. +Use lowercase for **issue board**. ## issue weights -Lowercase. +Use lowercase for **issue weights**. ## job @@ -235,21 +324,26 @@ If you want to use **CI** with the word **job**, use **CI/CD job** rather than * ## later -Use when talking about version numbers. +Use **later** when talking about version numbers. - Avoid: In GitLab 14.1 and higher. - Use instead: In GitLab 14.1 and later. +## list + +Do not use **list** when referring to a [**dropdown list**](#dropdown-list). +Use the full phrase **dropdown list** instead. + ## log in, log on -Do not use. Use [sign in](#sign-in) instead. If the user interface has **Log in**, you can use it. +Do not use **log in** or **log on**. Use [sign in](#sign-in) instead. If the user interface has **Log in**, you can use it. ## lower -Do not use when talking about version numbers. +Do not use **lower** when talking about version numbers. -- Avoid: In GitLab 14.1 and lower. -- Use instead: In GitLab 14.1 and earlier. +- Do: In GitLab 14.1 and earlier. +- Do not: In GitLab 14.1 and lower. ## Maintainer @@ -260,22 +354,22 @@ When writing about the Maintainer role: - Do not use the phrase, **if you are a maintainer** to mean someone who is assigned the Maintainer role. Instead, write it out. For example, **if you are assigned the Maintainer role**. - To describe a situation where the Maintainer role is the minimum required: - - Avoid: **the Maintainer role or higher** - - Use instead: **at least the Maintainer role** + - Avoid: the Maintainer role or higher + - Use instead: at least the Maintainer role Do not use **Maintainer permissions**. A user who is assigned the Maintainer role has a set of associated permissions. ## mankind -Do not use. Use **people** or **humanity** instead. ([Vale](../testing.md#vale) rule: [`InclusionGender.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionGender.yml)) +Do not use **mankind**. Use **people** or **humanity** instead. ([Vale](../testing.md#vale) rule: [`InclusionGender.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionGender.yml)) ## manpower -Do not use. Use words like **workforce** or **GitLab team members**. ([Vale](../testing.md#vale) rule: [`InclusionGender.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionGender.yml)) +Do not use **manpower**. Use words like **workforce** or **GitLab team members**. ([Vale](../testing.md#vale) rule: [`InclusionGender.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionGender.yml)) ## master -Do not use. Options are **primary** or **main**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml)) +Do not use **master**. Options are **primary** or **main**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml)) ## may, might @@ -287,18 +381,25 @@ Do not use first-person singular. Use **you**, **we**, or **us** instead. ([Vale ## merge requests -Lowercase. If you use **MR** as the acronym, spell it out on first use. +Use lowercase for **merge requests**. If you use **MR** as the acronym, spell it out on first use. ## milestones -Lowercase. +Use lowercase for **milestones**. + +## navigate + +Do not use **navigate**. Use **go** instead. For example: + +- Go to this webpage. +- Open a terminal and go to the `runner` directory. ## need to, should -Try to avoid. If something is required, use **must**. +Try to avoid **needs to**, because it's wordy. Avoid **should** when you can be more specific. If something is required, use **must**. -- Avoid: You need to set the variable. -- Use instead: You must set the variable. Or: Set the variable. +- Do: You must set the variable. Or: Set the variable. +- Do not: You need to set the variable. **Should** is acceptable for recommended actions or items, or in cases where an event may not happen. For example: @@ -310,10 +411,10 @@ happen. For example: ## note that -Do not use. +Do not use **note that** because it's wordy. -- Avoid: Note that you can change the settings. -- Use instead: You can change the settings. +- Do: You can change the settings. +- Do not: Note that you can change the settings. ## Owner @@ -328,15 +429,21 @@ Do not use **Owner permissions**. A user who is assigned the Owner role has a se ## permissions -Do not use roles and permissions interchangeably. Each user is assigned a role. Each role includes a set of permissions. +Do not use **roles** and **permissions** interchangeably. Each user is assigned a role. Each role includes a set of permissions. ## please -Do not use. For details, see the [Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please). +Do not use **please**. For details, see the [Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please). + +## press + +Use **press** when talking about keyboard keys. For example: + +- To stop the command, press <kbd>Control</kbd>+<kbd>C</kbd>. ## profanity -Do not use. Doing so may negatively affect other users and contributors, which is contrary to the GitLab value of [Diversity, Inclusion, and Belonging](https://about.gitlab.com/handbook/values/#diversity-inclusion). +Do not use profanity. Doing so may negatively affect other users and contributors, which is contrary to the GitLab value of [Diversity, Inclusion, and Belonging](https://about.gitlab.com/handbook/values/#diversity-inclusion). ## Reporter @@ -347,30 +454,48 @@ When writing about the Reporter role: - Do not use the phrase, **if you are a reporter** to mean someone who is assigned the Reporter role. Instead, write it out. For example, **if you are assigned the Reporter role**. - To describe a situation where the Reporter role is the minimum required: - - Avoid: **the Reporter role or higher** - - Use instead: **at least the Reporter role** + - Avoid: the Reporter role or higher + - Use instead: at least the Reporter role Do not use **Reporter permissions**. A user who is assigned the Reporter role has a set of associated permissions. ## Repository Mirroring -Title case. +Use title case for **Repository Mirroring**. ## roles -Do not use roles and permissions interchangeably. Each user is assigned a role. Each role includes a set of permissions. +Do not use **roles** and **permissions** interchangeably. Each user is assigned a role. Each role includes a set of permissions. ## runner, runners -Lowercase. These are the agents that run CI/CD jobs. See also [GitLab Runner](#gitlab-runner) and [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/233529). +Use lowercase for **runners**. These are the agents that run CI/CD jobs. See also [GitLab Runner](#gitlab-runner) and [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/233529). ## sanity check -Do not use. Use **check for completeness** instead. ([Vale](../testing.md#vale) rule: [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml)) +Do not use **sanity check**. Use **check for completeness** instead. ([Vale](../testing.md#vale) rule: [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml)) ## scalability -Do not use when talking about increasing GitLab performance for additional users. The words scale or scaling are sometimes acceptable, but references to increasing GitLab performance for additional users should direct readers to the GitLab [reference architectures](../../../administration/reference_architectures/index.md) page. +Do not use **scalability** when talking about increasing GitLab performance for additional users. The words scale or scaling +are sometimes acceptable, but references to increasing GitLab performance for additional users should direct readers +to the GitLab [reference architectures](../../../administration/reference_architectures/index.md) page. + +## section + +Use **section** to describe an area on a page. For example, if a page has lines that separate the UI +into separate areas, refer to these areas as sections. + +We often think of expandable/collapsible areas as **sections**. When you refer to expanding +or collapsing a section, don't include the word **section**. + +- Do: Expand **Auto DevOps**. +- Do not: Expand the **Auto DevOps** section. + +## select + +Use **select** with buttons, links, menu items, and lists. **Select** applies to more devices, +while **click** is more specific to a mouse. ## setup, set up @@ -381,13 +506,13 @@ Use **setup** as a noun, and **set up** as a verb. For example: ## sign in -Use instead of **sign on** or **log on** or **log in**. If the user interface has different words, use those. +Use **sign in** instead of **sign on** or **log on** or **log in**. If the user interface has different words, use those. You can use **single sign-on**. ## simply, simple -Do not use. If the user doesn't find the process to be simple, we lose their trust. +Do not use **simply** or **simple**. If the user doesn't find the process to be simple, we lose their trust. ([Vale](../testing.md#vale) rule: [`Simplicity.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Simplicity.yml)) ## slashes @@ -395,34 +520,38 @@ Instead of **and/or**, use **or** or re-write the sentence. This rule also appli ## slave -Do not use. Another option is **secondary**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml)) +Do not use **slave**. Another option is **secondary**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml)) ## subgroup -Use instead of **sub-group**. +Use **subgroup** (no hyphen) instead of **sub-group**. ([Vale](../testing.md#vale) rule: [`SubstitutionSuggestions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml)) ## that -Do not use when describing a noun. For example: +Do not use **that** when describing a noun. For example: -- Avoid: The file **that** you save... -- Use instead: The file you save... +- Do: The file you save... +- Do not: The file **that** you save... See also [this, these, that, those](#this-these-that-those). ## terminal -Lowercase. For example: +Use lowercase for **terminal**. For example: - Open a terminal. - From a terminal, run the `docker login` command. +## text box + +Use **text box** instead of **field** or **box** when referring to the UI element. + ## there is, there are -Try to avoid. These phrases hide the subject. +Try to avoid **there is** and **there are**. These phrases hide the subject. -- Avoid: There are holes in the bucket. -- Use instead: The bucket has holes. +- Do: The bucket has holes. +- Do not: There are holes in the bucket. ## they @@ -434,37 +563,48 @@ a gender-neutral pronoun. Always follow these words with a noun. For example: -- Avoid: **This** improves performance. -- Use instead: **This setting** improves performance. +- Do: **This setting** improves performance. +- Do not: **This** improves performance. -- Avoid: **These** are the best. -- Use instead: **These pants** are the best. +- Do: **These pants** are the best. +- Do not: **These** are the best. -- Avoid: **That** is the one you are looking for. -- Use instead: **That Jedi** is the one you are looking for. +- Do: **That droid** is the one you are looking for. +- Do not: **That** is the one you are looking for. -- Avoid: **Those** need to be configured. -- Use instead: **Those settings** need to be configured. (Or even better, **Configure those settings.**) +- Do: **Those settings** need to be configured. (Or even better, **Configure those settings.**) +- Do not: **Those** need to be configured. ## to-do item -Use lowercase. ([Vale](../testing.md#vale) rule: [`ToDo.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/ToDo.yml)) +Use lowercase and hyphenate **to-do** item. ([Vale](../testing.md#vale) rule: [`ToDo.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/ToDo.yml)) ## To-Do List -Use title case. ([Vale](../testing.md#vale) rule: [`ToDo.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/ToDo.yml)) +Use title case for **To-Do List**. ([Vale](../testing.md#vale) rule: [`ToDo.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/ToDo.yml)) + +## toggle + +You **turn on** or **turn off** a toggle. For example: + +- Turn on the **blah** toggle. + +## type + +Do not use **type** if you can avoid it. Use **enter** instead. ## useful -Do not use. If the user doesn't find the process to be useful, we lose their trust. +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)) ## utilize -Do not use. Use **use** instead. It's more succinct and easier for non-native English speakers to understand. +Do not use **utilize**. Use **use** instead. It's more succinct and easier for non-native English speakers to understand. +([Vale](../testing.md#vale) rule: [`SubstitutionSuggestions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml)) ## Value Stream Analytics -Title case. +Use title case for **Value Stream Analytics**. ## via @@ -474,14 +614,14 @@ Do not use Latin abbreviations. Use **with**, **through**, or **by using** inste Try to avoid **we** and focus instead on how the user can accomplish something in GitLab. -- Avoid: We created a feature for you to add widgets. -- Instead, use: Use widgets when you have work you want to organize. +- Do: Use widgets when you have work you want to organize. +- Do not: We created a feature for you to add widgets. -One exception: You can use **we recommend** instead of **it is recommended** or **GitLab recommends**. +One exception: You can use **we recommend** instead of **it is recommended** or **GitLab recommends**. ([Vale](../testing.md#vale) rule: [`SubstitutionSuggestions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml)) ## whitelist -Do not use. Another option is **allowlist**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml)) +Do not use **whitelist**. Another option is **allowlist**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml)) <!-- vale on --> <!-- markdownlint-enable --> diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md index 2ade6c1e71d..dfa2f3ed55a 100644 --- a/doc/development/documentation/testing.md +++ b/doc/development/documentation/testing.md @@ -228,7 +228,7 @@ guidelines: In [`ReadingLevel.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/ReadingLevel.yml), we have implemented -[the Flesch-Kincaid grade level test](https://readable.com/blog/the-flesch-reading-ease-and-flesch-kincaid-grade-level/) +[the Flesch-Kincaid grade level test](https://readable.com/readability/flesch-reading-ease-flesch-kincaid-grade-level/) to determine the readability of our documentation. As a general guideline, the lower the score, the more readable the documentation. @@ -319,6 +319,38 @@ To configure Vale in your editor, install one of the following as appropriate: cases, `vale` should work. To find the location, run `which vale` in a terminal. - Vim [ALE plugin](https://github.com/dense-analysis/ale). +- Emacs [Flycheck extension](https://github.com/flycheck/flycheck). + This requires some configuration: + + - `Flycheck` supports `markdownlint-cli` out of the box, but you must point it + to the `.markdownlint.yml` at the base of the project directory. A `.dir-locals.el` + file can accomplish this: + + ```lisp + ;; Place this code in a file called `.dir-locals.el` at the root of the gitlab project. + ((markdown-mode . ((flycheck-markdown-markdownlint-cli-config . ".markdownlint.yml")))) + + ``` + + - A minimal configuration for Flycheck to work with Vale could look like this: + + ```lisp + (flycheck-define-checker vale + "A checker for prose" + :command ("vale" "--output" "line" "--no-wrap" + source) + :standard-input nil + :error-patterns + ((error line-start (file-name) ":" line ":" column ":" (id (one-or-more (not (any ":")))) ":" (message) line-end)) + :modes (markdown-mode org-mode text-mode) + :next-checkers ((t . markdown-markdownlint-cli)) + ) + + (add-to-list 'flycheck-checkers 'vale) + ``` + + In this setup the `markdownlint` checker is set as a "next" checker from the defined `vale` checker. + Enabling this custom Vale checker provides error linting from both Vale and markdownlint. We don't use [Vale Server](https://errata-ai.github.io/vale/#using-vale-with-a-text-editor-or-another-third-party-application). diff --git a/doc/development/elasticsearch.md b/doc/development/elasticsearch.md index 4b87f1c28f1..bba4e1cda23 100644 --- a/doc/development/elasticsearch.md +++ b/doc/development/elasticsearch.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w This area is to maintain a compendium of useful information when working with Elasticsearch. Information on how to enable Elasticsearch and perform the initial indexing is in -the [Elasticsearch integration documentation](../integration/elasticsearch.md#enabling-advanced-search). +the [Elasticsearch integration documentation](../integration/elasticsearch.md#enable-advanced-search). ## Deep Dive @@ -233,6 +233,11 @@ Any data or index cleanup needed to support migration retries should be handled will re-enqueue itself with a delay which is set using the `throttle_delay` option described below. The batching must be handled within the `migrate` method, this setting controls the re-enqueuing only. +- `batch_size` - Sets the number of documents modified during a `batched!` migration run. This size should be set to a value which allows the updates + enough time to finish. This can be tuned in combination with the `throttle_delay` option described below. The batching + must be handled within a custom `migrate` method or by using the [`Elastic::MigrationBackfillHelper`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/workers/concerns/elastic/migration_backfill_helper.rb) + `migrate` method which uses this setting. Default value is 1000 documents. + - `throttle_delay` - Sets the wait time in between batch runs. This time should be set high enough to allow each migration batch enough time to finish. Additionally, the time should be less than 30 minutes since that is how often the [`Elastic::MigrationWorker`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/workers/elastic/migration_worker.rb) diff --git a/doc/development/experiment_guide/experimentation.md b/doc/development/experiment_guide/experimentation.md index ee0f63342f1..b242646c549 100644 --- a/doc/development/experiment_guide/experimentation.md +++ b/doc/development/experiment_guide/experimentation.md @@ -106,7 +106,7 @@ class SomeWorker # Since we cannot access cookies in a worker, we need to bucket models # based on a unique, unchanging attribute instead. - # It is therefore necessery to always provide the same subject. + # It is therefore necessary to always provide the same subject. if Gitlab::Experimentation.in_experiment_group?(:experiment_key, subject: user) # execute experimental code else diff --git a/doc/development/experiment_guide/index.md b/doc/development/experiment_guide/index.md index e4a97091a81..4de272fec20 100644 --- a/doc/development/experiment_guide/index.md +++ b/doc/development/experiment_guide/index.md @@ -8,11 +8,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w Experiments can be conducted by any GitLab team, most often the teams from the [Growth Sub-department](https://about.gitlab.com/handbook/engineering/development/growth/). Experiments are not tied to releases because they primarily target GitLab.com. -Experiments are run as an A/B/n test, and are behind a feature flag to turn the test on or off. Based on the data the experiment generates, the team decides if the experiment had a positive impact and should be made the new default, or rolled back. +Experiments are run as an A/B/n test, and are behind an [experiment feature flag](../feature_flags/#experiment-type) to turn the test on or off. Based on the data the experiment generates, the team decides if the experiment had a positive impact and should be made the new default, or rolled back. -## Experiment tracking issue +## Experiment rollout issue -Each experiment should have an [Experiment tracking](https://gitlab.com/groups/gitlab-org/-/issues?scope=all&state=opened&label_name[]=growth%20experiment&search=%22Experiment+tracking%22) issue to track the experiment from roll-out through to cleanup/removal. The tracking issue is similar to a feature flag rollout issue, and is also used to track the status of an experiment. Immediately after an experiment is deployed, the due date of the issue should be set (this depends on the experiment but can be up to a few weeks in the future). +Each experiment should have an [experiment rollout](https://gitlab.com/groups/gitlab-org/-/boards/1352542) issue to track the experiment from rollout through to cleanup and removal. +The rollout issue is similar to a feature flag rollout issue, and is also used to track the status of an experiment. +When an experiment is deployed, the due date of the issue should be set (this depends on the experiment but can be up to a few weeks in the future). After the deadline, the issue needs to be resolved and either: - It was successful and the experiment becomes the new default. @@ -29,6 +31,10 @@ run) shouldn't impact GitLab availability. To avoid or identify issues, experiments are initially deployed to a small number of users. Regardless, experiments still need tests. +Experiments must have corresponding [frontend or feature tests](../testing_guide/index.md) to ensure they +exist in the application. These tests should help prevent the experiment code from +being removed before the [experiment cleanup process](https://about.gitlab.com/handbook/engineering/development/growth/experimentation/#experiment-cleanup-issue) starts. + If, as a reviewer or maintainer, you find code that would usually fail review but is acceptable for now, mention your concerns with a note that there's no need to change the code. The author can then add a comment to this piece of code @@ -38,22 +44,14 @@ addressed. ## Implementing an experiment -There are currently two options when implementing an experiment. - -One is built into GitLab directly and has been around for a while (this is called -`Exerimentation Module`), and the other is provided by -[`gitlab-experiment`](https://gitlab.com/gitlab-org/gitlab-experiment) and is referred -to as `Gitlab::Experiment` -- GLEX for short. +[`GLEX`](https://gitlab.com/gitlab-org/gitlab-experiment) - or `Gitlab::Experiment`, the `gitlab-experiment` gem - is the preferred option for implementing an experiment in GitLab. -Both approaches use [experiment](../feature_flags/index.md#experiment-type) -feature flags. We recommend using GLEX rather than `Experimentation Module` for new experiments. +For more information, see [Implementing an A/B/n experiment using GLEX](gitlab_experiment.md). -- [Implementing an A/B/n experiment using GLEX](gitlab_experiment.md) -- [Implementing an A/B experiment using `Experimentation Module`](experimentation.md) +There are still some longer running experiments using the [`Exerimentation Module`](experimentation.md). -Historical Context: `Experimentation Module` was built iteratively with the needs that -appeared while implementing Growth sub-department experiments, while GLEX was built -with the findings of the team and an easier to use API. +Both approaches use [experiment](../feature_flags/index.md#experiment-type) feature flags. +`GLEX` is the preferred option for new experiments. ### Add new icons and illustrations for experiments diff --git a/doc/development/fe_guide/accessibility.md b/doc/development/fe_guide/accessibility.md index 0cd7cf58b58..7c870de9a6c 100644 --- a/doc/development/fe_guide/accessibility.md +++ b/doc/development/fe_guide/accessibility.md @@ -334,7 +334,7 @@ Keep in mind that: - When you add `:hover` styles, in most cases you should add `:focus` styles too so that the styling is applied for both mouse **and** keyboard users. - If you remove an interactive element's `outline`, make sure you maintain visual focus state in another way such as with `box-shadow`. -See the [Pajamas Keyboard-only page](https://design.gitlab.com/accessibility-audits/2-keyboard-only/) for more detail. +See the [Pajamas Keyboard-only page](https://design.gitlab.com/accessibility-audits/keyboard-only) for more detail. ## Tabindex @@ -510,7 +510,7 @@ Proper research and testing should be done to ensure compliance with [WCAG](http ### Viewing the browser accessibility tree - [Firefox DevTools guide](https://developer.mozilla.org/en-US/docs/Tools/Accessibility_inspector#accessing_the_accessibility_inspector) -- [Chrome DevTools guide](https://developer.chrome.com/docs/devtools/accessibility/reference#pane) +- [Chrome DevTools guide](https://developer.chrome.com/docs/devtools/accessibility/reference/#pane) ### Browser extensions diff --git a/doc/development/fe_guide/axios.md b/doc/development/fe_guide/axios.md index 2d699b305ce..b42a17d7870 100644 --- a/doc/development/fe_guide/axios.md +++ b/doc/development/fe_guide/axios.md @@ -75,7 +75,7 @@ We have also decided against using [Axios interceptors](https://github.com/axios ### Mock poll requests in tests with Axios -Because polling function requires a header object, we need to always include an object as the third argument: +Because a polling function requires a header object, we need to always include an object as the third argument: ```javascript mock.onGet('/users').reply(200, { foo: 'bar' }, {}); diff --git a/doc/development/fe_guide/content_editor.md b/doc/development/fe_guide/content_editor.md index 6cf4076bf83..956e7d0d56e 100644 --- a/doc/development/fe_guide/content_editor.md +++ b/doc/development/fe_guide/content_editor.md @@ -4,10 +4,10 @@ group: Editor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Content Editor **(FREE)** +# Content Editor development guidelines **(FREE)** The Content Editor is a UI component that provides a WYSIWYG editing -experience for [GitLab Flavored Markdown](../../user/markdown.md) (GFM) in the GitLab application. +experience for [GitLab Flavored Markdown](../../user/markdown.md) in the GitLab application. It also serves as the foundation for implementing Markdown-focused editors that target other engines, like static site generators. @@ -16,103 +16,339 @@ to build the Content Editor. These frameworks provide a level of abstraction on the native [`contenteditable`](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Editable_content) web technology. -## Architecture remarks +## Usage guide -At a high level, the Content Editor: +Follow these instructions to include the Content Editor in a feature. -- Imports arbitrary Markdown. -- Renders it in a HTML editing area. -- Exports it back to Markdown with changes introduced by the user. +1. [Include the Content Editor component](#include-the-content-editor-component). +1. [Set and get Markdown](#set-and-get-markdown). +1. [Listen for changes](#listen-for-changes). -The Content Editor relies on the -[Markdown API endpoint](../../api/markdown.md) to transform Markdown -into HTML. It sends the Markdown input to the REST API and displays the API's -HTML output in the editing area. The editor exports the content back to Markdown -using a client-side library that serializes editable documents into Markdown. +### Include the Content Editor component - +Import the `ContentEditor` Vue component. We recommend using asynchronous named imports to +take advantage of caching, as the ContentEditor is a big dependency. -Check the [Content Editor technical design document](https://docs.google.com/document/d/1fKOiWpdHned4KOLVOOFYVvX1euEjMP5rTntUhpapdBg) -for more information about the design decisions that drive the development of the editor. - -**NOTE**: We also designed the Content Editor to be extensible. We intend to provide -more information about extension development for supporting new types of content in upcoming -milestones. - -## GitLab Flavored Markdown support +```html +<script> +export default { + components: { + ContentEditor: () => + import( + /* webpackChunkName: 'content_editor' */ '~/content_editor/components/content_editor.vue' + ), + }, + // rest of the component definition +} +</script> +``` -The [GitLab Flavored Markdown](../../user/markdown.md) extends -the [CommonMark specification](https://spec.commonmark.org/0.29/) with support for a -variety of content types like diagrams, math expressions, and tables. Supporting -all GitLab Flavored Markdown content types in the Content Editor is a work in progress. For -the status of the ongoing development for CommonMark and GitLab Flavored Markdown support, read: +The Content Editor requires two properties: -- [Basic Markdown formatting extensions](https://gitlab.com/groups/gitlab-org/-/epics/5404) epic. -- [GitLab Flavored Markdown extensions](https://gitlab.com/groups/gitlab-org/-/epics/5438) epic. +- `renderMarkdown` is an asynchronous function that returns the response (String) of invoking the +[Markdown API](../../api/markdown.md). +- `uploadsPath` is a URL that points to a [GitLab upload service](../uploads.md#upload-encodings) + with `multipart/form-data` support. -## Usage +See the [`WikiForm.vue`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/pages/shared/wikis/components/wiki_form.vue#L207) +component for a production example of these two properties. -To include the Content Editor in your feature, import the `createContentEditor` factory -function and the `ContentEditor` Vue component. `createContentEditor` sets up an instance -of [tiptap's Editor class](https://www.tiptap.dev/api/editor/) with all the necessary -extensions to support editing GitLab Flavored Markdown content. It also creates -a Markdown serializer that allows exporting tiptap's document format to Markdown. +### Set and get Markdown -`createContentEditor` requires a `renderMarkdown` parameter invoked -by the editor every time it needs to convert Markdown to HTML. The Content Editor -does not provide a default value for this function yet. +The `ContentEditor` Vue component doesn't implement Vue data binding flow (`v-model`) +because setting and getting Markdown are expensive operations. Data binding would +trigger these operations every time the user interacts with the component. -**NOTE**: The Content Editor is in an early development stage. Usage and development -guidelines are subject to breaking changes in the upcoming months. +Instead, you should obtain an instance of the `ContentEditor` class by listening to the +`initialized` event: ```html <script> -import { GlButton } from '@gitlab/ui'; -import { createContentEditor, ContentEditor } from '~/content_editor'; -import { __ } from '~/locale'; import createFlash from '~/flash'; +import { __ } from '~/locale'; export default { - components: { - ContentEditor, - GlButton, + methods: { + async loadInitialContent(contentEditor) { + this.contentEditor = contentEditor; + + try { + await this.contentEditor.setSerializedContent(this.content); + } catch (e) { + createFlash(__('Could not load initial document')); + } + }, + submitChanges() { + const markdown = this.contentEditor.getSerializedContent(); + }, }, +}; +</script> +<template> + <content-editor + :render-markdown="renderMarkdown" + :uploads-path="pageInfo.uploadsPath" + @initialized="loadInitialContent" + /> +</template> +``` + +### Listen for changes + +You can still react to changes in the Content Editor. Reacting to changes helps +you know if the document is empty or dirty. Use the `@change` event handler for +this purpose. + +```html +<script> +export default { data() { return { - contentEditor: null, - } + empty: false, + }; }, - created() { - this.contentEditor = createContentEditor({ - renderMarkdown: (markdown) => Api.markdown({ text: markdown }), - }); - - try { - await this.contentEditor.setSerializedContent(this.content); - } catch (e) { - createFlash({ - message: __('There was an error loading content in the editor'), error: e - }); + methods: { + handleContentEditorChange({ empty }) { + this.empty = empty; } }, +}; +</script> +<template> + <div> + <content-editor + :render-markdown="renderMarkdown" + :uploads-path="pageInfo.uploadsPath" + @initialized="loadInitialContent" + @change="handleContentEditorChange" + /> + <gl-button :disabled="empty" @click="submitChanges"> + {{ __('Submit changes') }} + </gl-button> + </div> +</template> +``` + +## Implementation guide + +The Content Editor is composed of three main layers: + +- **The editing tools UI**, like the toolbar and the table structure editor. They + display the editor's state and mutate it by dispatching commands. +- **The Tiptap Editor object** manages the editor's state, + and exposes business logic as commands executed by the editing tools UI. +- **The Markdown serializer** transforms a Markdown source string into a ProseMirror + document and vice versa. + +### Editing tools UI + +The editing tools UI are Vue components that display the editor's state and +dispatch [commands](https://www.tiptap.dev/api/commands/#commands) to mutate it. +They are located in the `~/content_editor/components` directory. For example, +the **Bold** toolbar button displays the editor's state by becoming active when +the user selects bold text. This button also dispatches the `toggleBold` command +to format text as bold: + +```mermaid +sequenceDiagram + participant A as Editing tools UI + participant B as Tiptap object + A->>B: queries state/dispatches commands + B--)A: notifies state changes +``` + +#### Node views + +We implement [node views](https://www.tiptap.dev/guide/node-views/vue/#node-views-with-vue) +to provide inline editing tools for some content types, like tables and images. Node views +allow separating the presentation of a content type from its +[model](https://prosemirror.net/docs/guide/#doc.data_structures). Using a Vue component in +the presentation layer enables sophisticated editing experiences in the Content Editor. +Node views are located in `~/content_editor/components/wrappers`. + +#### Dispatch commands + +You can inject the Tiptap Editor object to Vue components to dispatch +commands. + +NOTE: +Do not implement logic that changes the editor's +state in Vue components. Encapsulate this logic in commands, and dispatch +the command from the component's methods. + +```html +<script> +export default { + inject: ['tiptapEditor'], methods: { - async save() { - await Api.updateContent({ - content: this.contentEditor.getSerializedContent(), - }); + execute() { + //Incorrect + const { state, view } = this.tiptapEditor.state; + const { tr, schema } = state; + tr.addMark(state.selection.from, state.selection.to, null, null, schema.mark('bold')); + + // Correct + this.tiptapEditor.chain().toggleBold().focus().run(); + }, + } +}; +</script> +<template> +``` + +#### Query editor's state + +Use the `EditorStateObserver` renderless component to react to changes in the +editor's state, such as when the document or the selection changes. You can listen to +the following events: + +- `docUpdate` +- `selectionUpdate` +- `transaction` +- `focus` +- `blur` +- `error`. + +Learn more about these events in [Tiptap's event guide](https://www.tiptap.dev/api/events/). + +```html +<script> +// Parts of the code has been hidden for efficiency +import EditorStateObserver from './editor_state_observer.vue'; + +export default { + components: { + EditorStateObserver, + }, + data() { + return { + error: null, + }; + }, + methods: { + displayError({ message }) { + this.error = message; + }, + dismissError() { + this.error = null; }, }, }; </script> <template> - <div> - <content-editor :content-editor="contentEditor" /> - <gl-button @click="save()">Save</gl-button> - </div> + <editor-state-observer @error="displayError"> + <gl-alert v-if="error" class="gl-mb-6" variant="danger" @dismiss="dismissError"> + {{ error }} + </gl-alert> + </editor-state-observer> </template> ``` -Call `setSerializedContent` to set initial Markdown in the Editor. This method is -asynchronous because it makes an API request to render the Markdown input. -`getSerializedContent` returns a Markdown string that represents the serialized -version of the editable document. +### The Tiptap editor object + +The Tiptap [Editor](https://www.tiptap.dev/api/editor) class manages +the editor's state and encapsulates all the business logic that powers +the Content Editor. The Content Editor constructs a new instance of this class and +provides all the necessary extensions to support +[GitLab Flavored Markdown](../../user/markdown.md). + +#### Implement new extensions + +Extensions are the building blocks of the Content Editor. You can learn how to implement +new ones by reading [Tiptap's guide](https://www.tiptap.dev/guide/custom-extensions). +We recommend checking the list of built-in [nodes](https://www.tiptap.dev/api/nodes) and +[marks](https://www.tiptap.dev/api/marks) before implementing a new extension +from scratch. + +Store the Content Editor extensions in the `~/content_editor/extensions` directory. +When using a Tiptap's built-in extension, wrap it in a ES6 module inside this directory: + +```javascript +export { Bold as default } from '@tiptap/extension-bold'; +``` + +Use the `extend` method to customize the Extension's behavior: + +```javascript +import { HardBreak } from '@tiptap/extension-hard-break'; + +export default HardBreak.extend({ + addKeyboardShortcuts() { + return { + 'Shift-Enter': () => this.editor.commands.setHardBreak(), + }; + }, +}); +``` + +#### Register extensions + +Register the new extension in `~/content_editor/services/create_content_editor.js`. Import +the extension module and add it to the `builtInContentEditorExtensions` array: + +```javascript +import Emoji from '../extensions/emoji'; + +const builtInContentEditorExtensions = [ + Code, + CodeBlockHighlight, + Document, + Dropcursor, + Emoji, + // Other extensions +``` + +### The Markdown serializer + +The Markdown Serializer transforms a Markdown String to a +[ProseMirror document](https://prosemirror.net/docs/guide/#doc) and vice versa. + +#### Deserialization + +Deserialization is the process of converting Markdown to a ProseMirror document. +We take advantage of ProseMirror's +[HTML parsing and serialization capabilities](https://prosemirror.net/docs/guide/#schema.serialization_and_parsing) +by first rendering the Markdown as HTML using the [Markdown API endpoint](../../api/markdown.md): + +```mermaid +sequenceDiagram + participant A as Content Editor + participant E as Tiptap Object + participant B as Markdown Serializer + participant C as Markdown API + participant D as ProseMirror Parser + A->>B: deserialize(markdown) + B->>C: render(markdown) + C-->>B: html + B->>D: to document(html) + D-->>A: document + A->>E: setContent(document) +``` + +Deserializers live in the extension modules. Read Tiptap's +[parseHTML](https://www.tiptap.dev/guide/custom-extensions#parse-html) and +[addAttributes](https://www.tiptap.dev/guide/custom-extensions#attributes) documentation to +learn how to implement them. Titap's API is a wrapper around ProseMirror's +[schema spec API](https://prosemirror.net/docs/ref/#model.SchemaSpec). + +#### Serialization + +Serialization is the process of converting a ProseMirror document to Markdown. The Content +Editor uses [`prosemirror-markdown`](https://github.com/ProseMirror/prosemirror-markdown) +to serialize documents. We recommend reading the +[MarkdownSerializer](https://github.com/ProseMirror/prosemirror-markdown#class-markdownserializer) +and [MarkdownSerializerState](https://github.com/ProseMirror/prosemirror-markdown#class-markdownserializerstate) +classes documentation before implementing a serializer: + +```mermaid +sequenceDiagram + participant A as Content Editor + participant B as Markdown Serializer + participant C as ProseMirror Markdown + A->>B: serialize(document) + B->>C: serialize(document, serializers) + C-->>A: markdown string +``` + +`prosemirror-markdown` requires implementing a serializer function for each content type supported +by the Content Editor. We implement serializers in `~/content_editor/services/markdown_serializer.js`. diff --git a/doc/development/fe_guide/development_process.md b/doc/development/fe_guide/development_process.md index b85ed4da442..4e50621add4 100644 --- a/doc/development/fe_guide/development_process.md +++ b/doc/development/fe_guide/development_process.md @@ -88,7 +88,7 @@ With the purpose of being [respectful of others' time](https://about.gitlab.com/ GitLab architecture. 1. Add a diagram to the issue and ask a frontend maintainer in the Slack channel `#frontend_maintainers` about it. -  +  1. Don't take more than one week between starting work on a feature and sharing a Merge Request with a reviewer or a maintainer. diff --git a/doc/development/fe_guide/graphql.md b/doc/development/fe_guide/graphql.md index 3b49601f027..0229aa0123a 100644 --- a/doc/development/fe_guide/graphql.md +++ b/doc/development/fe_guide/graphql.md @@ -421,14 +421,16 @@ is still validated. Again, make sure that those overrides are as short-lived as possible by tracking their removal in the appropriate issue. -#### Feature flags in queries +#### Feature-flagged queries -Sometimes it may be helpful to have an entity in the GraphQL query behind a feature flag. -One example is working on a feature where the backend has already been merged but the frontend -has not. In this case, you may consider putting the GraphQL entity behind a feature flag to allow smaller -merge requests to be created and merged. +In cases where the backend is complete and the frontend is being implemented behind a feature flag, +a couple options are available to leverage the feature flag in the GraphQL queries. -To do this we can use the `@include` directive to exclude an entity if the `if` statement passes. +##### The `@include` directive + +The `@include` (or its opposite, `@skip`) can be used to control whether an entity should be +included in the query. If the `@include` directive evaluates to `false`, the entity's resolver is +not hit and the entity is excluded from the response. For example: ```graphql query getAuthorData($authorNameEnabled: Boolean = false) { @@ -456,6 +458,34 @@ export default { }; ``` +Note that, even if the directive evaluates to `false`, the guarded entity is sent to the backend and +matched against the GraphQL schema. So this approach requires that the feature-flagged entity +exists in the schema, even if the feature flag is disabled. When the feature flag is turned off, it +is recommended that the resolver returns `null` at the very least. + +##### Different versions of a query + +There's another approach that involves duplicating the standard query, and it should be avoided. The copy includes the new entities +while the original remains unchanged. It is up to the production code to trigger the right query +based on the feature flag's status. For example: + +```javascript +export default { + apollo: { + user: { + query() { + return this.glFeatures.authorNameEnabled ? NEW_QUERY : ORIGINAL_QUERY, + } + } + }, +}; +``` + +This approach is not recommended as it results in bigger merge requests and requires maintaining +two similar queries for as long as the feature flag exists. This can be used in cases where the new +GraphQL entities are not yet part of the schema, or if they are feature-flagged at the schema level +(`new_entity: :feature_flag`). + ### Manually triggering queries Queries on a component's `apollo` property are made automatically when the component is created. @@ -1310,7 +1340,7 @@ describe('when query times out', () => { expect(getAlert().exists()).toBe(false); expect(getGraph().exists()).toBe(true); - /* fails again, alert retuns but data persists */ + /* fails again, alert returns but data persists */ await advanceApolloTimers(); expect(getAlert().exists()).toBe(true); expect(getGraph().exists()).toBe(true); diff --git a/doc/development/fe_guide/img/content_editor_highlevel_diagram.png b/doc/development/fe_guide/img/content_editor_highlevel_diagram.png Binary files differdeleted file mode 100644 index 73a71cf5843..00000000000 --- a/doc/development/fe_guide/img/content_editor_highlevel_diagram.png +++ /dev/null diff --git a/doc/development/fe_guide/index.md b/doc/development/fe_guide/index.md index 549fa3261b1..a6b49394733 100644 --- a/doc/development/fe_guide/index.md +++ b/doc/development/fe_guide/index.md @@ -22,7 +22,7 @@ Be wary of [the limitations that come with using Hamlit](https://github.com/k0ku We also use [SCSS](https://sass-lang.com) and plain JavaScript with modern ECMAScript standards supported through [Babel](https://babeljs.io/) and ES module support through [webpack](https://webpack.js.org/). -Working with our frontend assets requires Node (v10.13.0 or greater) and Yarn +Working with our frontend assets requires Node (v12.22.1 or greater) and Yarn (v1.10.0 or greater). You can find information on how to install these on our [installation guide](../../install/installation.md#4-node). diff --git a/doc/development/fe_guide/source_editor.md b/doc/development/fe_guide/source_editor.md index fc128c0ecb1..2ff0bacfc3a 100644 --- a/doc/development/fe_guide/source_editor.md +++ b/doc/development/fe_guide/source_editor.md @@ -15,7 +15,7 @@ GitLab features use it, including: - [CI Linter](../../ci/lint.md) - [Snippets](../../user/snippets.md) - [Web Editor](../../user/project/repository/web_editor.md) -- [Security Policies](../../user/application_security/threat_monitoring/index.md) +- [Security Policies](../../user/application_security/policies/index.md) ## How to use Source Editor diff --git a/doc/development/github_importer.md b/doc/development/github_importer.md index 84c10e0c005..57cb74a6159 100644 --- a/doc/development/github_importer.md +++ b/doc/development/github_importer.md @@ -272,3 +272,16 @@ The last log entry reports the number of objects fetched and imported: "import_stage": "Gitlab::GithubImport::Stage::FinishImportWorker" } ``` + +## Errors when importing large projects + +The GitHub importer may encounter errors when importing large projects. For help with this, see the +documentation for the following use cases: + +- [Alternative way to import notes and diff notes](../user/project/import/github.md#alternative-way-to-import-notes-and-diff-notes) +- [Reduce GitHub API request objects per page](../user/project/import/github.md#reduce-github-api-request-objects-per-page) + +## Metrics dashboards + +To assess the GitHub importer health, the [GitHub importer dashboard](https://dashboards.gitlab.net/d/importers-github-importer/importers-github-importer) +provides information about the total number of objects fetched vs. imported over time. diff --git a/doc/development/go_guide/dependencies.md b/doc/development/go_guide/dependencies.md index c5af21d0772..8aa8f286edc 100644 --- a/doc/development/go_guide/dependencies.md +++ b/doc/development/go_guide/dependencies.md @@ -45,7 +45,7 @@ end with a timestamp and the first 12 characters of the commit identifier: If a VCS tag matches one of these patterns, it is ignored. For a complete understanding of Go modules and versioning, see [this series of -blog posts](https://blog.golang.org/using-go-modules) on the official Go +blog posts](https://go.dev/blog/using-go-modules) on the official Go website. ## 'Module' vs 'Package' diff --git a/doc/development/go_guide/index.md b/doc/development/go_guide/index.md index 224d8a0a0f5..0ee73da48db 100644 --- a/doc/development/go_guide/index.md +++ b/doc/development/go_guide/index.md @@ -65,7 +65,7 @@ Remember to run [SAST](../../user/application_security/sast/index.md) and [Dependency Scanning](../../user/application_security/dependency_scanning/index.md) **(ULTIMATE)** on your project (or at least the [`gosec` analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/gosec)), -and to follow our [Security requirements](../code_review.md#security-requirements). +and to follow our [Security requirements](../code_review.md#security). Web servers can take advantages of middlewares like [Secure](https://github.com/unrolled/secure). @@ -196,7 +196,7 @@ library or framework: ### Subtests -Use [subtests](https://blog.golang.org/subtests) whenever possible to improve +Use [subtests](https://go.dev/blog/subtests) whenever possible to improve code readability and test output. ### Better output in tests @@ -319,7 +319,7 @@ A few things to keep in mind when adding context: ### References for working with errors -- [Go 1.13 errors](https://blog.golang.org/go1.13-errors). +- [Go 1.13 errors](https://go.dev/blog/go1.13-errors). - [Programing with errors](https://peter.bourgon.org/blog/2019/09/11/programming-with-errors.html). - [Don't just check errors, handle them diff --git a/doc/development/gotchas.md b/doc/development/gotchas.md index 40598eaff95..fbb6b0219aa 100644 --- a/doc/development/gotchas.md +++ b/doc/development/gotchas.md @@ -203,76 +203,6 @@ in an initializer. - Stack Overflow: [Why you should not write inline JavaScript](https://softwareengineering.stackexchange.com/questions/86589/why-should-i-avoid-inline-scripting) -## Auto loading - -Rails auto-loading on `development` differs from the load policy in the `production` environment. -In development mode, `config.eager_load` is set to `false`, which means classes -are loaded as needed. With the classic Rails autoloader, it is known that this can lead to -[Rails resolving the wrong class](https://guides.rubyonrails.org/v5.2/autoloading_and_reloading_constants.html#when-constants-aren-t-missed-relative-references) -if the class name is ambiguous. This can be fixed by specifying the complete namespace to the class. - -### Error prone example - -```ruby -# app/controllers/application_controller.rb -class ApplicationController < ActionController::Base - ... -end - -# app/controllers/projects/application_controller.rb -class Projects::ApplicationController < ApplicationController - ... - private - - def project - ... - end -end - -# app/controllers/projects/submodule/some_controller.rb -module Projects - module Submodule - class SomeController < ApplicationController - def index - @some_id = project.id - end - end - end -end -``` - -In this case, if for any reason the top level `ApplicationController` -is loaded but `Projects::ApplicationController` is not, `ApplicationController` -would be resolved to `::ApplicationController` and then the `project` method is -undefined, causing an error. - -#### Solution - -```ruby -# app/controllers/projects/submodule/some_controller.rb -module Projects - module Submodule - class SomeController < Projects::ApplicationController - def index - @some_id = project.id - end - end - end -end -``` - -By specifying `Projects::`, we tell Rails exactly what class we are referring -to and we would avoid the issue. - -NOTE: -This problem disappears as soon as we upgrade to Rails 6 and use the Zeitwerk autoloader. - -### Further reading - -- Rails Guides: [Autoloading and Reloading Constants (Classic Mode)](https://guides.rubyonrails.org/autoloading_and_reloading_constants_classic_mode.html) -- Ruby Constant lookup: [Everything you ever wanted to know about constant lookup in Ruby](https://cirw.in/blog/constant-lookup) -- Rails 6 and Zeitwerk autoloader: [Understanding Zeitwerk in Rails 6](https://medium.com/cedarcode/understanding-zeitwerk-in-rails-6-f168a9f09a1f) - ## Storing assets that do not require pre-compiling Assets that need to be served to the user are stored under the `app/assets` directory, which is later pre-compiled and placed in the `public/` directory. diff --git a/doc/development/graphql_guide/graphql_pro.md b/doc/development/graphql_guide/graphql_pro.md index ca20d66dd87..3170f0cfdc2 100644 --- a/doc/development/graphql_guide/graphql_pro.md +++ b/doc/development/graphql_guide/graphql_pro.md @@ -1,6 +1,6 @@ --- -stage: Plan -group: Project Management +stage: Ecosystem +group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/development/graphql_guide/index.md b/doc/development/graphql_guide/index.md index b8d4b53992e..cc97e41df05 100644 --- a/doc/development/graphql_guide/index.md +++ b/doc/development/graphql_guide/index.md @@ -1,6 +1,6 @@ --- -stage: Plan -group: Project Management +stage: Ecosystem +group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/development/graphql_guide/pagination.md b/doc/development/graphql_guide/pagination.md index 5fd2179ea9b..a37c47f1b11 100644 --- a/doc/development/graphql_guide/pagination.md +++ b/doc/development/graphql_guide/pagination.md @@ -1,6 +1,6 @@ --- -stage: Plan -group: Project Management +stage: Ecosystem +group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/development/i18n/externalization.md b/doc/development/i18n/externalization.md index 53825f0904a..52a7f839286 100644 --- a/doc/development/i18n/externalization.md +++ b/doc/development/i18n/externalization.md @@ -137,7 +137,7 @@ The `~/locale` module exports the following key functions for externalization: - `s__()` (namespaced double underscore parenthesis) - `__()` Mark content for translation (note the double underscore). - `s__()` Mark namespaced content for translation -- `n__()` Mark pluralized content for translation +- `n__()` Mark pluralized content for translation ```javascript import { __, s__, n__ } from '~/locale'; @@ -171,6 +171,45 @@ If you need to translate strings in the Vue component's JavaScript, you can impo To test Vue translations, learn about [manually testing translations from the UI](#manually-test-translations-from-the-ui). +### Test files + +Test expectations against externalized contents should not be hard coded, +because we may need to run the tests with non-default locale, and tests with +hard coded contents will fail. + +This means any expectations against externalized contents should call the +same externalizing method to match the translation. + +Bad: + +```ruby +click_button 'Submit review' + +expect(rendered).to have_content('Thank you for your feedback!') +``` + +Good: + +```ruby +click_button _('Submit review') + +expect(rendered).to have_content(_('Thank you for your feedback!')) +``` + +This includes JavaScript tests: + +Bad: + +```javascript +expect(findUpdateIgnoreStatusButton().text()).toBe('Ignore'); +``` + +Good: + +```javascript +expect(findUpdateIgnoreStatusButton().text()).toBe(__('Ignore')); +``` + #### Recommendations If strings are reused throughout a component, it can be useful to define these strings as variables. We recommend defining an `i18n` property on the component's `$options` object. If there is a mixture of many-use and single-use strings in the component, consider using this approach to create a local [Single Source of Truth](https://about.gitlab.com/handbook/values/#single-source-of-truth) for externalized strings. @@ -751,6 +790,28 @@ translate correctly if you extract individual words from the sentence. When in doubt, try to follow the best practices described in this [Mozilla Developer documentation](https://developer.mozilla.org/en-US/docs/Mozilla/Localization/Localization_content_best_practices#Splitting). +### Always pass string literals to the translation helpers + +The `bin/rake gettext:regenerate` script parses the codebase and extracts all the strings from the +[translation helpers](#preparing-a-page-for-translation) ready to be translated. + +The script cannot resolve the strings if they are passed as variables or function calls. Therefore, +make sure to always pass string literals to the helpers. + +```javascript +// Good +__('Some label'); +s__('Namespace', 'Label'); +s__('Namespace|Label'); +n__('%d apple', '%d apples', appleCount); + +// Bad +__(LABEL); +s__(getLabel()); +s__(NAMESPACE, LABEL); +n__(LABEL_SINGULAR, LABEL_PLURAL, appleCount); +``` + ## Updating the PO files with the new content Now that the new content is marked for translation, run this command to update the diff --git a/doc/development/i18n/proofreader.md b/doc/development/i18n/proofreader.md index 462c3fde7d6..76ab00eebfb 100644 --- a/doc/development/i18n/proofreader.md +++ b/doc/development/i18n/proofreader.md @@ -43,6 +43,7 @@ are very appreciative of the work done by translators and proofreaders! - Jan Urbanec - [GitLab](https://gitlab.com/TatranskyMedved), [Crowdin](https://crowdin.com/profile/Tatranskymedved) - Danish - Saederup92 - [GitLab](https://gitlab.com/Saederup92), [Crowdin](https://crowdin.com/profile/Saederup92) + - scootergrisen - [GitLab](https://gitlab.com/scootergrisen), [Crowdin](https://crowdin.com/profile/scootergrisen) - Dutch - Emily Hendle - [GitLab](https://gitlab.com/pundachan), [Crowdin](https://crowdin.com/profile/pandachan) - Esperanto @@ -98,7 +99,8 @@ are very appreciative of the work done by translators and proofreaders! - André Gama - [GitLab](https://gitlab.com/andregamma), [Crowdin](https://crowdin.com/profile/ToeOficial) - Eduardo Addad de Oliveira - [GitLab](https://gitlab.com/eduardoaddad), [Crowdin](https://crowdin.com/profile/eduardoaddad) - Romanian - - Proofreaders needed. + - Mircea Pop - [GitLab](https://gitlab.com/eeex), [Crowdin](https://crowdin.com/profile/eex) + - Rareș Pița - [GitLab](https://gitlab.com/dlphin), [Crowdin](https://crowdin.com/profile/dlphin) - Russian - Nikita Grylov - [GitLab](https://gitlab.com/nixel2007), [Crowdin](https://crowdin.com/profile/nixel2007) - Alexy Lustin - [GitLab](https://gitlab.com/allustin), [Crowdin](https://crowdin.com/profile/lustin) @@ -117,6 +119,7 @@ are very appreciative of the work done by translators and proofreaders! - Turkish - Ali Demirtaş - [GitLab](https://gitlab.com/alidemirtas), [Crowdin](https://crowdin.com/profile/alidemirtas) - Rıfat Ünalmış (Rifat Unalmis) - [GitLab](https://gitlab.com/runalmis), [Crowdin](https://crowdin.com/profile/runalmis) + - İsmail Arılık - [GitLab](https://gitlab.com/ismailarilik), [Crowdin](https://crowdin.com/profile/ismailarilik) - Ukrainian - Volodymyr Sobotovych - [GitLab](https://gitlab.com/wheleph), [Crowdin](https://crowdin.com/profile/wheleph) - Andrew Vityuk - [GitLab](https://gitlab.com/3_1_3_u), [Crowdin](https://crowdin.com/profile/andruwa13) diff --git a/doc/development/img/elasticsearch_architecture.svg b/doc/development/img/elasticsearch_architecture.svg index 2f38f9b04ee..516214c8b8e 100644 --- a/doc/development/img/elasticsearch_architecture.svg +++ b/doc/development/img/elasticsearch_architecture.svg @@ -1 +1 @@ -<svg version="1.2" width="210mm" height="297mm" viewBox="0 0 21000 29700" preserveAspectRatio="xMidYMid" fill-rule="evenodd" stroke-width="28.222" stroke-linejoin="round" xmlns="http://www.w3.org/2000/svg"><defs class="ClipPathGroup"><clipPath id="a" clipPathUnits="userSpaceOnUse"><path d="M0 0h21000v29700H0z"/></clipPath></defs><g class="SlideGroup"><g class="Slide" clip-path="url(#a)"><g class="Page"><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M1975 5575h3051v1651H1975z"/><path fill="#FFF" d="M3500 7200H2000V5600h3000v1600H3500z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M3500 7200H2000V5600h3000v1600H3500z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="2778" y="6311"><tspan>Snippet</tspan></tspan><tspan class="TextPosition" x="2099" y="6785"><tspan>(ActiveRecord)</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M1475 3975h4051v3551H1475z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M3500 7500H1500V4000h4000v3500H3500z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="1788" y="5048"><tspan>ApplicationSearch</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.ConnectorShape"><path class="BoundingBox" fill="none" d="M5975 4675h8051v701H5975z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M6000 5350h4000v-650h4000"/></g><g class="com.sun.star.drawing.ConnectorShape"><path class="BoundingBox" fill="none" d="M5975 5325h8051v1101H5975z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M6000 5350h4000v1050h4000"/></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M1075 2875h4951v4951H1075z"/><path fill="none" stroke="#F33" stroke-width="50" d="M3550 7800H1100V2900h4900v4900H3550z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="700"><tspan class="TextPosition" x="1946" y="3514"><tspan fill="#C9211E">SnippetsSearch</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M1975 12175h3051v1651H1975z"/><path fill="#FFF" d="M3500 13800H2000v-1600h3000v1600H3500z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M3500 13800H2000v-1600h3000v1600H3500z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="2778" y="12911"><tspan>Snippet</tspan></tspan><tspan class="TextPosition" x="2099" y="13385"><tspan>(ActiveRecord)</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M1075 10775h4951v3251H1075z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M3550 14000H1100v-3200h4900v3200H3550z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="2511" y="11461"><tspan>Application</tspan></tspan><tspan class="TextPosition" x="1933" y="11935"><tspan>VersionedSearch</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.ConnectorShape"><path class="BoundingBox" fill="none" d="M3525 13975h4501v7451H3525z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M3550 14000v7400h4450"/></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M14008 14075h4985v851h-4985z"/><path fill="none" stroke="#999" stroke-width="50" d="M16500 14900h-2467v-800h4934v800h-2467z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="14720" y="14648"><tspan fill="gray">ClassMethodProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M13375 13075h6251v2151h-6251z"/><path fill="none" stroke="#F33" stroke-width="50" d="M16500 15200h-3100v-2100h6200v2100h-3100z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="700"><tspan class="TextPosition" x="13799" y="13731"><tspan fill="#C9211E">V12p1::SnippetClassProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M7975 14575h3051v1851H7975z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M9500 16400H8000v-1800h3000v1800H9500z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="8277" y="15411"><tspan>MultiVersion-</tspan></tspan><tspan class="TextPosition" x="8429" y="15885"><tspan>ClassProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M14008 16875h4985v851h-4985z"/><path fill="none" stroke="#999" stroke-width="50" d="M16500 17700h-2467v-800h4934v800h-2467z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="14720" y="17448"><tspan fill="gray">ClassMethodProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M13375 15875h6251v2151h-6251z"/><path fill="none" stroke="#F33" stroke-width="50" d="M16500 18000h-3100v-2100h6200v2100h-3100z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="700"><tspan class="TextPosition" x="13799" y="16531"><tspan fill="#C9211E">V12p2::SnippetClassProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.ConnectorShape"><path class="BoundingBox" fill="none" d="M10975 14125h2451v1401h-2451z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M11000 15500h1463v-1350h937"/></g><g class="com.sun.star.drawing.ConnectorShape"><path class="BoundingBox" fill="none" d="M10975 15475h2451v1501h-2451z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M11000 15500h1463v1450h937"/></g><g class="com.sun.star.drawing.ConnectorShape"><path class="BoundingBox" fill="none" d="M3525 13975h4501v1551H3525z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M3550 14000v1500h4450"/></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M14008 19975h4985v851h-4985z"/><path fill="none" stroke="#999" stroke-width="50" d="M16500 20800h-2467v-800h4934v800h-2467z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="14445" y="20548"><tspan fill="gray">InstanceMethodProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M13375 18975h6251v2151h-6251z"/><path fill="none" stroke="#F33" stroke-width="50" d="M16500 21100h-3100v-2100h6200v2100h-3100z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="700"><tspan class="TextPosition" x="13505" y="19631"><tspan fill="#C9211E">V12p1::SnippetInstanceProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M7975 20275h3051v2251H7975z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M9500 22500H8000v-2200h3000v2200H9500z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="8277" y="21311"><tspan>MultiVersion-</tspan></tspan><tspan class="TextPosition" x="8154" y="21785"><tspan>InstanceProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M14008 22775h4985v851h-4985z"/><path fill="none" stroke="#999" stroke-width="50" d="M16500 23600h-2467v-800h4934v800h-2467z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="14445" y="23348"><tspan fill="gray">InstanceMethodProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M13375 21775h6251v2151h-6251z"/><path fill="none" stroke="#F33" stroke-width="50" d="M16500 23900h-3100v-2100h6200v2100h-3100z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="700"><tspan class="TextPosition" x="13505" y="22431"><tspan fill="#C9211E">V12p2::SnippetInstanceProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.ConnectorShape"><path class="BoundingBox" fill="none" d="M10975 20025h2451v1401h-2451z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M11000 21400h1463v-1350h937"/></g><g class="com.sun.star.drawing.ConnectorShape"><path class="BoundingBox" fill="none" d="M10975 21375h2451v1501h-2451z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M11000 21400h1463v1450h937"/></g><g class="com.sun.star.drawing.TextShape"><path class="BoundingBox" fill="none" d="M900 1600h10697v879H900z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="564" font-weight="400"><tspan class="TextPosition" x="1150" y="2233"><tspan>Standard elasticsearch-rails setup</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.TextShape"><path class="BoundingBox" fill="none" d="M900 9300h7683v879H900z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="564" font-weight="400"><tspan class="TextPosition" x="1150" y="9933"><tspan>GitLab multi-indices setup</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.TextShape"><path class="BoundingBox" fill="none" d="M3400 21300h4821v1197H3400z"/><text class="TextShape"><tspan class="TextParagraph" font-size="388" font-weight="400"><tspan class="TextPosition" x="4250" y="21840"><tspan fill="gray">(instance method)</tspan></tspan><tspan class="TextPosition" x="3651" y="22264"><tspan font-family="Courier" font-size="423">__elasticsearch__</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.TextShape"><path class="BoundingBox" fill="none" d="M3380 15400h4821v1197H3380z"/><text class="TextShape"><tspan class="TextParagraph" font-size="388" font-weight="400"><tspan class="TextPosition" x="4512" y="15940"><tspan fill="gray">(class method)</tspan></tspan><tspan class="TextPosition" x="3631" y="16364"><tspan font-family="Courier" font-size="423">__elasticsearch__</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.TextShape"><path class="BoundingBox" fill="none" d="M9000 3500h4821v1197H9000z"/><text class="TextShape"><tspan class="TextParagraph" font-size="388" font-weight="400"><tspan class="TextPosition" x="10132" y="4040"><tspan fill="gray">(class method)</tspan></tspan><tspan class="TextPosition" x="9251" y="4464"><tspan font-family="Courier" font-size="423">__elasticsearch__</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.TextShape"><path class="BoundingBox" fill="none" d="M9000 6400h4821v1197H9000z"/><text class="TextShape"><tspan class="TextParagraph" font-size="388" font-weight="400"><tspan class="TextPosition" x="9850" y="6940"><tspan fill="gray">(instance method)</tspan></tspan><tspan class="TextPosition" x="9251" y="7364"><tspan font-family="Courier" font-size="423">__elasticsearch__</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M1975 25175h2051v851H1975z"/><path fill="none" stroke="#999" stroke-width="50" d="M3000 26000H2000v-800h2000v800H3000z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="2634" y="25748"><tspan fill="gray">Foo</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.TextShape"><path class="BoundingBox" fill="none" d="M4400 25200h7101v726H4400z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="4650" y="25710"><tspan>elasticsearch-rails’ internal class</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.TextShape"><path class="BoundingBox" fill="none" d="M4400 26400h8601v1200H4400z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="4650" y="26910"><tspan>where model-specific logic is</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M1975 26275h2051v851H1975z"/><path fill="none" stroke="#F33" stroke-width="50" d="M3000 27100H2000v-800h2000v800H3000z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="700"><tspan class="TextPosition" x="2613" y="26848"><tspan fill="#C9211E">Foo</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.TextShape"><path class="BoundingBox" fill="none" d="M4900 17289h5901v2312H4900z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="370" font-weight="400"><tspan class="TextPosition" x="7236" y="17748"><tspan fill="gray">Write operations like </tspan></tspan><tspan class="TextPosition" x="5323" y="18159"><tspan fill="gray">indexing/updating are forwarded </tspan></tspan><tspan class="TextPosition" x="8024" y="18570"><tspan fill="gray">to all instances.</tspan></tspan></tspan><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="370" font-weight="400"><tspan class="TextPosition" x="5501" y="18981"><tspan fill="gray">Read operations are forwarded </tspan></tspan><tspan class="TextPosition" x="7126" y="19392"><tspan fill="gray">to specified instance.</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.ConnectorShape"><path class="BoundingBox" fill="none" d="M10785 15769h1422v2691h-1422z"/><path fill="none" stroke="#999" stroke-width="30" d="M10800 18444c1429 0 934-1618 1119-2337"/><path fill="#999" d="M12206 15769l-460 293 267 217 193-510z"/></g><g class="com.sun.star.drawing.ConnectorShape"><path class="BoundingBox" fill="none" d="M10785 18429h1528v2862h-1528z"/><path fill="none" stroke="#999" stroke-width="30" d="M10800 18444c1509 0 970 1782 1200 2526"/><path fill="#999" d="M12312 21290l-227-496-252 235 479 261z"/></g><g class="com.sun.star.drawing.TextShape"><path class="BoundingBox" fill="none" d="M1800 24000h7101v807H1800z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="494" font-weight="700"><tspan class="TextPosition" x="2050" y="24574"><tspan>Legend</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M13975 4275h5085v851h-5085z"/><path fill="none" stroke="#999" stroke-width="50" d="M16517 5100h-2517v-800h5034v800h-2517z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="14737" y="4848"><tspan fill="gray">ClassMethodProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M13975 5975h5085v851h-5085z"/><path fill="none" stroke="#999" stroke-width="50" d="M16517 6800h-2517v-800h5034v800h-2517z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="14462" y="6548"><tspan fill="gray">InstanceMethodProxy</tspan></tspan></tspan></text></g></g></g></g></svg>
\ No newline at end of file +<svg version="1.2" width="210mm" height="297mm" viewBox="0 0 21000 29700" preserveAspectRatio="xMidYMid" fill-rule="evenodd" stroke-width="28.222" stroke-linejoin="round" xmlns="http://www.w3.org/2000/svg"><defs class="ClipPathGroup"><clipPath id="a" clipPathUnits="userSpaceOnUse"><path d="M0 0h21000v29700H0z"/></clipPath></defs><g class="SlideGroup"><g class="Slide" clip-path="url(#a)"><g class="Page"><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M1975 5575h3051v1651H1975z"/><path fill="#FFF" d="M3500 7200H2000V5600h3000v1600H3500z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M3500 7200H2000V5600h3000v1600H3500z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="2778" y="6311"><tspan>Snippet</tspan></tspan><tspan class="TextPosition" x="2099" y="6785"><tspan>(ActiveRecord)</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M1475 3975h4051v3551H1475z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M3500 7500H1500V4000h4000v3500H3500z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="1788" y="5048"><tspan>ApplicationSearch</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.ConnectorShape"><path class="BoundingBox" fill="none" d="M5975 4675h8051v701H5975z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M6000 5350h4000v-650h4000"/></g><g class="com.sun.star.drawing.ConnectorShape"><path class="BoundingBox" fill="none" d="M5975 5325h8051v1101H5975z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M6000 5350h4000v1050h4000"/></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M1075 2875h4951v4951H1075z"/><path fill="none" stroke="#F33" stroke-width="50" d="M3550 7800H1100V2900h4900v4900H3550z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="700"><tspan class="TextPosition" x="1946" y="3514"><tspan fill="#C9211E">SnippetsSearch</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M1975 12175h3051v1651H1975z"/><path fill="#FFF" d="M3500 13800H2000v-1600h3000v1600H3500z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M3500 13800H2000v-1600h3000v1600H3500z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="2778" y="12911"><tspan>Snippet</tspan></tspan><tspan class="TextPosition" x="2099" y="13385"><tspan>(ActiveRecord)</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M1075 10775h4951v3251H1075z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M3550 14000H1100v-3200h4900v3200H3550z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="2511" y="11461"><tspan>Application</tspan></tspan><tspan class="TextPosition" x="1933" y="11935"><tspan>VersionedSearch</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.ConnectorShape"><path class="BoundingBox" fill="none" d="M3525 13975h4501v7451H3525z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M3550 14000v7400h4450"/></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M14008 14075h4985v851h-4985z"/><path fill="none" stroke="#999" stroke-width="50" d="M16500 14900h-2467v-800h4934v800h-2467z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="14720" y="14648"><tspan fill="gray">ClassMethodProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M13375 13075h6251v2151h-6251z"/><path fill="none" stroke="#F33" stroke-width="50" d="M16500 15200h-3100v-2100h6200v2100h-3100z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="700"><tspan class="TextPosition" x="13799" y="13731"><tspan fill="#C9211E">V12p1::SnippetClassProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M7975 14575h3051v1851H7975z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M9500 16400H8000v-1800h3000v1800H9500z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="8277" y="15411"><tspan>MultiVersion-</tspan></tspan><tspan class="TextPosition" x="8429" y="15885"><tspan>ClassProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M14008 16875h4985v851h-4985z"/><path fill="none" stroke="#999" stroke-width="50" d="M16500 17700h-2467v-800h4934v800h-2467z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="14720" y="17448"><tspan fill="gray">ClassMethodProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M13375 15875h6251v2151h-6251z"/><path fill="none" stroke="#F33" stroke-width="50" d="M16500 18000h-3100v-2100h6200v2100h-3100z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="700"><tspan class="TextPosition" x="13799" y="16531"><tspan fill="#C9211E">V12p2::SnippetClassProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.ConnectorShape"><path class="BoundingBox" fill="none" d="M10975 14125h2451v1401h-2451z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M11000 15500h1463v-1350h937"/></g><g class="com.sun.star.drawing.ConnectorShape"><path class="BoundingBox" fill="none" d="M10975 15475h2451v1501h-2451z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M11000 15500h1463v1450h937"/></g><g class="com.sun.star.drawing.ConnectorShape"><path class="BoundingBox" fill="none" d="M3525 13975h4501v1551H3525z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M3550 14000v1500h4450"/></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M14008 19975h4985v851h-4985z"/><path fill="none" stroke="#999" stroke-width="50" d="M16500 20800h-2467v-800h4934v800h-2467z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="14445" y="20548"><tspan fill="gray">InstanceMethodProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M13375 18975h6251v2151h-6251z"/><path fill="none" stroke="#F33" stroke-width="50" d="M16500 21100h-3100v-2100h6200v2100h-3100z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="700"><tspan class="TextPosition" x="13505" y="19631"><tspan fill="#C9211E">V12p1::SnippetInstanceProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M7975 20275h3051v2251H7975z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M9500 22500H8000v-2200h3000v2200H9500z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="8277" y="21311"><tspan>MultiVersion-</tspan></tspan><tspan class="TextPosition" x="8154" y="21785"><tspan>InstanceProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M14008 22775h4985v851h-4985z"/><path fill="none" stroke="#999" stroke-width="50" d="M16500 23600h-2467v-800h4934v800h-2467z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="14445" y="23348"><tspan fill="gray">InstanceMethodProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M13375 21775h6251v2151h-6251z"/><path fill="none" stroke="#F33" stroke-width="50" d="M16500 23900h-3100v-2100h6200v2100h-3100z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="700"><tspan class="TextPosition" x="13505" y="22431"><tspan fill="#C9211E">V12p2::SnippetInstanceProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.ConnectorShape"><path class="BoundingBox" fill="none" d="M10975 20025h2451v1401h-2451z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M11000 21400h1463v-1350h937"/></g><g class="com.sun.star.drawing.ConnectorShape"><path class="BoundingBox" fill="none" d="M10975 21375h2451v1501h-2451z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M11000 21400h1463v1450h937"/></g><g class="com.sun.star.drawing.TextShape"><path class="BoundingBox" fill="none" d="M900 1600h10697v879H900z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="564" font-weight="400"><tspan class="TextPosition" x="1150" y="2233"><tspan>Standard elasticsearch-rails setup</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.TextShape"><path class="BoundingBox" fill="none" d="M900 9300h7683v879H900z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="564" font-weight="400"><tspan class="TextPosition" x="1150" y="9933"><tspan>GitLab multi-indices setup</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.TextShape"><path class="BoundingBox" fill="none" d="M3400 21300h4821v1197H3400z"/><text class="TextShape"><tspan class="TextParagraph" font-size="388" font-weight="400"><tspan class="TextPosition" x="4250" y="21840"><tspan fill="gray">(instance method)</tspan></tspan><tspan class="TextPosition" x="3651" y="22264"><tspan font-family="Courier" font-size="423">__elasticsearch__</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.TextShape"><path class="BoundingBox" fill="none" d="M3380 15400h4821v1197H3380z"/><text class="TextShape"><tspan class="TextParagraph" font-size="388" font-weight="400"><tspan class="TextPosition" x="4512" y="15940"><tspan fill="gray">(class method)</tspan></tspan><tspan class="TextPosition" x="3631" y="16364"><tspan font-family="Courier" font-size="423">__elasticsearch__</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.TextShape"><path class="BoundingBox" fill="none" d="M9000 3500h4821v1197H9000z"/><text class="TextShape"><tspan class="TextParagraph" font-size="388" font-weight="400"><tspan class="TextPosition" x="10132" y="4040"><tspan fill="gray">(class method)</tspan></tspan><tspan class="TextPosition" x="9251" y="4464"><tspan font-family="Courier" font-size="423">__elasticsearch__</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.TextShape"><path class="BoundingBox" fill="none" d="M9000 6400h4821v1197H9000z"/><text class="TextShape"><tspan class="TextParagraph" font-size="388" font-weight="400"><tspan class="TextPosition" x="9850" y="6940"><tspan fill="gray">(instance method)</tspan></tspan><tspan class="TextPosition" x="9251" y="7364"><tspan font-family="Courier" font-size="423">__elasticsearch__</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M1975 25175h2051v851H1975z"/><path fill="none" stroke="#999" stroke-width="50" d="M3000 26000H2000v-800h2000v800H3000z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="2634" y="25748"><tspan fill="gray">Foo</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.TextShape"><path class="BoundingBox" fill="none" d="M4400 25200h7101v726H4400z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="4650" y="25710"><tspan>elasticsearch-rails' internal class</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.TextShape"><path class="BoundingBox" fill="none" d="M4400 26400h8601v1200H4400z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="4650" y="26910"><tspan>where model-specific logic is</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M1975 26275h2051v851H1975z"/><path fill="none" stroke="#F33" stroke-width="50" d="M3000 27100H2000v-800h2000v800H3000z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="700"><tspan class="TextPosition" x="2613" y="26848"><tspan fill="#C9211E">Foo</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.TextShape"><path class="BoundingBox" fill="none" d="M4900 17289h5901v2312H4900z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="370" font-weight="400"><tspan class="TextPosition" x="7236" y="17748"><tspan fill="gray">Write operations like </tspan></tspan><tspan class="TextPosition" x="5323" y="18159"><tspan fill="gray">indexing/updating are forwarded </tspan></tspan><tspan class="TextPosition" x="8024" y="18570"><tspan fill="gray">to all instances.</tspan></tspan></tspan><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="370" font-weight="400"><tspan class="TextPosition" x="5501" y="18981"><tspan fill="gray">Read operations are forwarded </tspan></tspan><tspan class="TextPosition" x="7126" y="19392"><tspan fill="gray">to specified instance.</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.ConnectorShape"><path class="BoundingBox" fill="none" d="M10785 15769h1422v2691h-1422z"/><path fill="none" stroke="#999" stroke-width="30" d="M10800 18444c1429 0 934-1618 1119-2337"/><path fill="#999" d="M12206 15769l-460 293 267 217 193-510z"/></g><g class="com.sun.star.drawing.ConnectorShape"><path class="BoundingBox" fill="none" d="M10785 18429h1528v2862h-1528z"/><path fill="none" stroke="#999" stroke-width="30" d="M10800 18444c1509 0 970 1782 1200 2526"/><path fill="#999" d="M12312 21290l-227-496-252 235 479 261z"/></g><g class="com.sun.star.drawing.TextShape"><path class="BoundingBox" fill="none" d="M1800 24000h7101v807H1800z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="494" font-weight="700"><tspan class="TextPosition" x="2050" y="24574"><tspan>Legend</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M13975 4275h5085v851h-5085z"/><path fill="none" stroke="#999" stroke-width="50" d="M16517 5100h-2517v-800h5034v800h-2517z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="14737" y="4848"><tspan fill="gray">ClassMethodProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M13975 5975h5085v851h-5085z"/><path fill="none" stroke="#999" stroke-width="50" d="M16517 6800h-2517v-800h5034v800h-2517z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="14462" y="6548"><tspan fill="gray">InstanceMethodProxy</tspan></tspan></tspan></text></g></g></g></g></svg>
\ No newline at end of file diff --git a/doc/development/import_project.md b/doc/development/import_project.md index 69e5873cd87..d021126c8eb 100644 --- a/doc/development/import_project.md +++ b/doc/development/import_project.md @@ -195,7 +195,7 @@ You can use this snippet: `https://gitlab.com/gitlab-org/gitlab/snippets/1924954 You can execute the script from the `gdk/gitlab` directory like this: ```shell -bundle exec rails r /path_to_sript/script.rb project_name /path_to_extracted_project request_store_enabled +bundle exec rails r /path_to_script/script.rb project_name /path_to_extracted_project request_store_enabled ``` ## Troubleshooting diff --git a/doc/development/integrations/jenkins.md b/doc/development/integrations/jenkins.md index a1ad259319d..3987c6658c3 100644 --- a/doc/development/integrations/jenkins.md +++ b/doc/development/integrations/jenkins.md @@ -24,8 +24,8 @@ brew services start jenkins GitLab does not allow requests to localhost or the local network by default. When running Jenkins on your local machine, you need to enable local access. 1. Log into your GitLab instance as an administrator. -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Network**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Network**. 1. Expand **Outbound requests** and check the following checkboxes: - **Allow requests to the local network from web hooks and services** diff --git a/doc/development/integrations/jira_connect.md b/doc/development/integrations/jira_connect.md index 9772f7504cf..ca3dc3660ee 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. Click **Upload**. - If the install was successful, you should see the **GitLab for Jira** app under **Manage apps**. + If the install was successful, you should see the **GitLab.com for Jira Cloud** app under **Manage apps**. You can also click **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 42a57e7f4fb..d37ce29e353 100644 --- a/doc/development/integrations/secure.md +++ b/doc/development/integrations/secure.md @@ -444,6 +444,10 @@ the system saves only the first 20 of them. Note that vulnerabilities in the [Pi Security](../../user/application_security/security_dashboard/#pipeline-security) tab do not enforce this limit and all identifiers present in the report artifact are displayed. +### Details + +The `details` field is an object that supports many different content elements that are displayed when viewing vulnerability information. An example of the various data elements can be seen in the [security-reports repository](https://gitlab.com/gitlab-examples/security/security-reports/-/tree/master/samples/details-example). + ### Location The `location` indicates where the vulnerability has been detected. @@ -454,10 +458,6 @@ which is used to track vulnerabilities as new commits are pushed to the repository. The attributes used to generate the location fingerprint also depend on the type of scanning. -### Details - -The `details` field is an object that supports many different content elements that are displayed when viewing vulnerability information. An example of the various data elements can be seen in the [security-reports repository](https://gitlab.com/gitlab-examples/security/security-reports/-/tree/master/samples/details-example). - #### Dependency Scanning The `location` of a Dependency Scanning vulnerability is composed of a `dependency` and a `file`. diff --git a/doc/development/internal_api.md b/doc/development/internal_api.md index c7fc4bed38c..660d8c60ba8 100644 --- a/doc/development/internal_api.md +++ b/doc/development/internal_api.md @@ -501,6 +501,56 @@ curl --request POST --header "Gitlab-Kas-Api-Request: <JWT token>" \ "http://localhost:3000/api/v4/internal/kubernetes/modules/cilium_alert" ``` +### Create Starboard vulnerability + +Called from the GitLab Kubernetes Agent Server (`kas`) to create a security vulnerability +from a Starboard vulnerability report. This request is idempotent. Multiple requests with the same data +create a single vulnerability. + +| Attribute | Type | Required | Description | +|:----------------|:-------|:---------|:------------| +| `vulnerability` | Hash | yes | Vulnerability data matching the security report schema [`vulnerability` field](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/src/security-report-format.json). | +| `scanner` | Hash | yes | Scanner data matching the security report schema [`scanner` field](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/src/security-report-format.json). | + +```plaintext +PUT internal/kubernetes/modules/starboard_vulnerability +``` + +Example Request: + +```shell +curl --request PUT --header "Gitlab-Kas-Api-Request: <JWT token>" \ + --header "Authorization: Bearer <agent token>" --header "Content-Type: application/json" \ + --url "http://localhost:3000/api/v4/internal/kubernetes/modules/starboard_vulnerability" \ + --data '{ + "vulnerability": { + "name": "CVE-123-4567 in libc", + "severity": "high", + "confidence": "unknown", + "location": { + "kubernetes_resource": { + "namespace": "production", + "kind": "deployment", + "name": "nginx", + "container": "nginx" + } + }, + "identifiers": [ + { + "type": "cve", + "name": "CVE-123-4567", + "value": "CVE-123-4567" + } + ] + }, + "scanner": { + "id": "starboard_trivy", + "name": "Trivy (via Starboard Operator)", + "vendor": "GitLab" + } +}' +``` + ## Subscriptions The subscriptions endpoint is used by [CustomersDot](https://gitlab.com/gitlab-org/customers-gitlab-com) (`customers.gitlab.com`) @@ -675,7 +725,7 @@ Example request: ```shell curl --request POST \ - --url http://localhost:3000/api/v4/namespaces/123/minutes \ + --url "http://localhost:3000/api/v4/namespaces/123/minutes" \ --header 'Content-Type: application/json' \ --header 'PRIVATE-TOKEN: <admin access token>' \ --data '{ @@ -719,7 +769,7 @@ Example request: ```shell curl --request PATCH \ - --url http://localhost:3000/api/v4/namespaces/123/minutes/move/321 \ + --url "http://localhost:3000/api/v4/namespaces/123/minutes/move/321" \ --header 'PRIVATE-TOKEN: <admin access token>' ``` diff --git a/doc/development/issue_types.md b/doc/development/issue_types.md index d02ff590352..31fa50e1d97 100644 --- a/doc/development/issue_types.md +++ b/doc/development/issue_types.md @@ -4,7 +4,10 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Issue Types +# Issue Types (DEPRECATED) + +WARNING: +We are deprecating Issue Types as of GitLab 14.2 in favor of [Work Items and Work Item Types](work_items.md). Sometimes when a new resource type is added it's not clear if it should be only an "extension" of Issue (Issue Type) or if it should be a new first-class resource type diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index bbaa6527e84..ce564551fbf 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -70,7 +70,7 @@ graph LR H -->|Yes| E[Regular migration] H -->|No| I[Post-deploy migration<br/>+ feature flag] - + D -->|Yes| F[Post-deploy migration] D -->|No| G[Background migration] ``` @@ -217,6 +217,40 @@ In case you need to insert, update, or delete a significant amount of data, you: - Must disable the single transaction with `disable_ddl_transaction!`. - Should consider doing it in a [Background Migration](background_migrations.md). +## Migration helpers and versioning + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339115) in GitLab 14.3. + +Various helper methods are available for many common patterns in database migrations. Those +helpers can be found in `Gitlab::Database::MigrationHelpers` and related modules. + +In order to allow changing a helper's behavior over time, we implement a versioning scheme +for migration helpers. This allows us to maintain the behavior of a helper for already +existing migrations but change the behavior for any new migrations. + +For that purpose, all database migrations should inherit from `Gitlab::Database::Migration`, +which is a "versioned" class. For new migrations, the latest version should be used (which +can be looked up in `Gitlab::Database::Migration::MIGRATION_CLASSES`) to use the latest version +of migration helpers. + +In this example, we use version 1.0 of the migration class: + +```ruby +class TestMigration < Gitlab::Database::Migration[1.0] + def change + end +end +``` + +Do not include `Gitlab::Database::MigrationHelpers` directly into a +migration. Instead, use the latest version of `Gitlab::Database::Migration`, which exposes the latest +version of migration helpers automatically. + +Migration helpers and versioning were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68986) +in GitLab 14.3. +For merge requests targeting previous stable branches, use the old format and still inherit from +`ActiveRecord::Migration[6.1]` instead of `Gitlab::Database::Migration[1.0]`. + ## Retry mechanism when acquiring database locks When changing the database schema, we use helper methods to invoke DDL (Data Definition @@ -247,87 +281,91 @@ This problem could cause failed application upgrade processes and even applicati stability issues, since the table may be inaccessible for a short period of time. To increase the reliability and stability of database migrations, the GitLab codebase -offers a helper method to retry the operations with different `lock_timeout` settings -and wait time between the attempts. Multiple smaller attempts to acquire the necessary +offers a method to retry the operations with different `lock_timeout` settings +and wait time between the attempts. Multiple shorter attempts to acquire the necessary lock allow the database to process other statements. -### Examples +There are two distinct ways to use lock retries: + +1. Inside a transactional migration: use `enable_lock_retries!`. +1. Inside a non-transactional migration: use `with_lock_retries`. + +If possible, enable lock-retries for any migration that touches a [high-traffic table](#high-traffic-tables). + +### Usage with transactional migrations + +Regular migrations execute the full migration in a transaction. We can enable the +lock-retry methodology by calling `enable_lock_retries!` at the migration level. + +This leads to the lock timeout being controlled for this migration. Also, it can lead to retrying the full +migration if the lock could not be granted within the timeout. + +Note that, while this is currently an opt-in setting, we prefer to use lock-retries for all migrations and +plan to make this the default going forward. + +Occasionally a migration may need to acquire multiple locks on different objects. +To prevent catalog bloat, ask for all those locks explicitly before performing any DDL. +A better strategy is to split the migration, so that we only need to acquire one lock at the time. **Removing a column:** ```ruby -include Gitlab::Database::MigrationHelpers +enable_lock_retries! def up - with_lock_retries do - remove_column :users, :full_name - end + remove_column :users, :full_name end def down - with_lock_retries do - add_column :users, :full_name, :string - end + add_column :users, :full_name, :string end ``` **Multiple changes on the same table:** -The helper `with_lock_retries` wraps all operations into a single transaction. When you have the lock, +With the lock-retry methodology enabled, all operations wrap into a single transaction. When you have the lock, you should do as much as possible inside the transaction rather than trying to get another lock later. Be careful about running long database statements within the block. The acquired locks are kept until the transaction (block) finishes and depending on the lock type, it might block other database operations. ```ruby -include Gitlab::Database::MigrationHelpers +enable_lock_retries! def up - with_lock_retries do - add_column :users, :full_name, :string - add_column :users, :bio, :string - end + add_column :users, :full_name, :string + add_column :users, :bio, :string end def down - with_lock_retries do - remove_column :users, :full_name - remove_column :users, :bio - end + remove_column :users, :full_name + remove_column :users, :bio end ``` **Removing a foreign key:** ```ruby -include Gitlab::Database::MigrationHelpers +enable_lock_retries! def up - with_lock_retries do - remove_foreign_key :issues, :projects - end + remove_foreign_key :issues, :projects end def down - with_lock_retries do - add_foreign_key :issues, :projects - end + add_foreign_key :issues, :projects end ``` **Changing default value for a column:** ```ruby -include Gitlab::Database::MigrationHelpers +enable_lock_retries! def up - with_lock_retries do - change_column_default :merge_requests, :lock_version, from: nil, to: 0 - end + change_column_default :merge_requests, :lock_version, from: nil, to: 0 end def down - with_lock_retries do - change_column_default :merge_requests, :lock_version, from: 0, to: nil - end + change_column_default :merge_requests, :lock_version, from: 0, to: nil end ``` @@ -336,25 +374,23 @@ end We can wrap the `create_table` method with `with_lock_retries`: ```ruby +enable_lock_retries! + def up - with_lock_retries do - create_table :issues do |t| - t.references :project, index: true, null: false, foreign_key: { on_delete: :cascade } - t.string :title, limit: 255 - end + create_table :issues do |t| + t.references :project, index: true, null: false, foreign_key: { on_delete: :cascade } + t.string :title, limit: 255 end end def down - with_lock_retries do - drop_table :issues - end + drop_table :issues end ``` **Creating a new table when we have two foreign keys:** -Only one foreign key should be created per migration. This is because [the addition of a foreign key constraint requires a `SHARE ROW EXCLUSIVE` lock on the referenced table](https://www.postgresql.org/docs/12/sql-createtable.html#:~:text=The%20addition%20of%20a%20foreign%20key%20constraint%20requires%20a%20SHARE%20ROW%20EXCLUSIVE%20lock%20on%20the%20referenced%20table), and locking multiple tables in the same transaction should be avoided. +Only one foreign key should be created per transaction. This is because [the addition of a foreign key constraint requires a `SHARE ROW EXCLUSIVE` lock on the referenced table](https://www.postgresql.org/docs/12/sql-createtable.html#:~:text=The%20addition%20of%20a%20foreign%20key%20constraint%20requires%20a%20SHARE%20ROW%20EXCLUSIVE%20lock%20on%20the%20referenced%20table), and locking multiple tables in the same transaction should be avoided. For this, we need three migrations: @@ -387,8 +423,6 @@ We can use the `add_concurrent_foreign_key` method in this case, as this helper has the lock retries built into it. ```ruby -include Gitlab::Database::MigrationHelpers - disable_ddl_transaction! def up @@ -405,8 +439,6 @@ end Adding foreign key to `users`: ```ruby -include Gitlab::Database::MigrationHelpers - disable_ddl_transaction! def up @@ -420,16 +452,20 @@ def down end ``` -**Usage with `disable_ddl_transaction!`** +### Usage with non-transactional migrations (`disable_ddl_transaction!`) -Generally the `with_lock_retries` helper should work with `disable_ddl_transaction!`. A custom RuboCop rule ensures that only allowed methods can be placed within the lock retries block. +Only when we disable transactional migrations using `disable_ddl_transaction!`, we can use +the `with_lock_retries` helper to guard an individual sequence of steps. It opens a transaction +to execute the given block. + +A custom RuboCop rule ensures that only allowed methods can be placed within the lock retries block. ```ruby disable_ddl_transaction! def up with_lock_retries do - add_column :users, :name, :text + add_column :users, :name, :text unless column_exists?(:users, :name) end add_text_limit :users, :name, 255 # Includes constraint validation (full table scan) @@ -450,7 +486,8 @@ end ### When to use the helper method -The `with_lock_retries` helper method can be used when you normally use +You can **only** use the `with_lock_retries` helper method when the execution is not already inside +an open transaction (using Postgres subtransactions is discouraged). It can be used with standard Rails migration helper methods. Calling more than one migration helper is not a problem if they're executed on the same table. @@ -498,11 +535,11 @@ by calling the method `disable_ddl_transaction!` in the body of your migration class like so: ```ruby -class MyMigration < ActiveRecord::Migration[6.0] - include Gitlab::Database::MigrationHelpers +class MyMigration < Gitlab::Database::Migration[1.0] disable_ddl_transaction! INDEX_NAME = 'index_name' + def up remove_concurrent_index :table_name, :column_name, name: INDEX_NAME end @@ -549,7 +586,7 @@ by calling the method `disable_ddl_transaction!` in the body of your migration class like so: ```ruby -class MyMigration < ActiveRecord::Migration[6.0] +class MyMigration < Gitlab::Database::Migration[1.0] include Gitlab::Database::MigrationHelpers disable_ddl_transaction! @@ -594,7 +631,7 @@ The easiest way to test for existence of an index by name is to use the be used with a name option. For example: ```ruby -class MyMigration < ActiveRecord::Migration[6.0] +class MyMigration < Gitlab::Database::Migration[1.0] include Gitlab::Database::MigrationHelpers INDEX_NAME = 'index_name' @@ -631,7 +668,7 @@ Here's an example where we add a new column with a foreign key constraint. Note it includes `index: true` to create an index for it. ```ruby -class Migration < ActiveRecord::Migration[6.0] +class Migration < Gitlab::Database::Migration[1.0] def change add_reference :model, :other_model, index: true, foreign_key: { on_delete: :cascade } @@ -677,7 +714,7 @@ expensive and disruptive operation for larger tables, but in reality it's not. Take the following migration as an example: ```ruby -class DefaultRequestAccessGroups < ActiveRecord::Migration[5.2] +class DefaultRequestAccessGroups < Gitlab::Database::Migration[1.0] def change change_column_default(:namespaces, :request_access_enabled, from: false, to: true) end @@ -884,7 +921,7 @@ The Rails 5 natively supports `JSONB` (binary JSON) column type. Example migration adding this column: ```ruby -class AddOptionsToBuildMetadata < ActiveRecord::Migration[5.0] +class AddOptionsToBuildMetadata < Gitlab::Database::Migration[1.0] def change add_column :ci_builds_metadata, :config_options, :jsonb end @@ -916,7 +953,7 @@ Do not store `attr_encrypted` attributes as `:text` in the database; use efficient: ```ruby -class AddSecretToSomething < ActiveRecord::Migration[5.0] +class AddSecretToSomething < Gitlab::Database::Migration[1.0] def change add_column :something, :encrypted_secret, :binary add_column :something, :encrypted_secret_iv, :binary @@ -974,7 +1011,7 @@ If you need more complex logic, you can define and use models local to a migration. For example: ```ruby -class MyMigration < ActiveRecord::Migration[6.0] +class MyMigration < Gitlab::Database::Migration[1.0] class Project < ActiveRecord::Base self.table_name = 'projects' end @@ -1073,7 +1110,7 @@ in a previous migration. It is important not to leave out the `User.reset_column_information` command, in order to ensure that the old schema is dropped from the cache and ActiveRecord loads the updated schema information. ```ruby -class AddAndSeedMyColumn < ActiveRecord::Migration[6.0] +class AddAndSeedMyColumn < Gitlab::Database::Migration[1.0] class User < ActiveRecord::Base self.table_name = 'users' end diff --git a/doc/development/multi_version_compatibility.md b/doc/development/multi_version_compatibility.md index 3314b5e7ddc..f834f4f4ee3 100644 --- a/doc/development/multi_version_compatibility.md +++ b/doc/development/multi_version_compatibility.md @@ -124,7 +124,7 @@ GitLab.com, the feature can be enabled in ChatOps and validated on GitLab.com. **However, it is not necessarily safe to enable the feature by default.** If the feature flag is removed, or the default is flipped to enabled, in the same release -where the code was merged, then customers performing [zero-downtime updates](https://docs.gitlab.com/omnibus/update/#zero-downtime-updates) +where the code was merged, then customers performing [zero-downtime updates](../update/zero_downtime.md) will end up running the new frontend code against the previous release's API. If you're not sure whether it's safe to enable all the changes at once, then one @@ -201,7 +201,7 @@ gantt section Database Schema A :done, schemaA, 00:00 , 1h Schema B :crit, schemaB, after migr, 58m - Schema C. : schmeaC, after postmigr, 1h + Schema C. : schemaC, after postmigr, 1h section Machine A Version N :done, mavn, 00:00 , 75m diff --git a/doc/development/packages.md b/doc/development/packages.md index 94882cefc30..869a1755d8f 100644 --- a/doc/development/packages.md +++ b/doc/development/packages.md @@ -133,7 +133,7 @@ During this phase, the idea is to collect as much information as possible about - **Authentication**: What authentication mechanisms are available (OAuth, Basic Authorization, other). Keep in mind that GitLab users often want to use their [Personal Access Tokens](../user/profile/personal_access_tokens.md). - Although not needed for the MVC first iteration, the [CI/CD job tokens](../api/index.md#gitlab-cicd-job-token) + Although not needed for the MVC first iteration, the [CI/CD job tokens](../ci/jobs/ci_job_token.md) have to be supported at some point in the future. - **Requests**: Which requests are needed to have a working MVC. Ideally, produce a list of all the requests needed for the MVC (including required actions). Further diff --git a/doc/development/pipelines.md b/doc/development/pipelines.md index 820299a426b..dd45091a31b 100644 --- a/doc/development/pipelines.md +++ b/doc/development/pipelines.md @@ -64,7 +64,7 @@ graph LR click 1-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8100542&udv=0" 1-2["docs-lint markdown (1.5 minutes)"]; click 1-2 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=10224335&udv=0" - 1-3["docs-lint links (6 minutes)"]; + 1-3["docs-lint links (5 minutes)"]; click 1-3 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356757&udv=0" 1-4["ui-docs-links lint (2.5 minutes)"]; click 1-4 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=10823717&udv=1020379" @@ -104,7 +104,7 @@ graph RL; 1-18["kubesec-sast"]; 1-19["nodejs-scan-sast"]; 1-20["secrets-sast"]; - 1-21["static-analysis (30 minutes)"]; + 1-21["static-analysis (14 minutes)"]; click 1-21 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914471&udv=0" class 1-3 criticalPath; @@ -123,7 +123,7 @@ graph RL; 2_1-1 & 2_1-2 & 2_1-3 & 2_1-4 --> 1-6; end - 2_2-2["rspec frontend_fixture/rspec-ee frontend_fixture (11 minutes)"]; + 2_2-2["rspec frontend_fixture/rspec-ee frontend_fixture (7 minutes)"]; class 2_2-2 criticalPath; click 2_2-2 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=7910143&udv=0" 2_2-4["memory-on-boot (3.5 minutes)"]; @@ -152,16 +152,14 @@ graph RL; click 2_5-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations" end - 3_1-1["jest (16 minutes)"]; + 3_1-1["jest (14.5 minutes)"]; class 3_1-1 criticalPath; click 3_1-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914204&udv=0" - 3_1-2["karma (2 minutes)"]; - click 3_1-3 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914200&udv=0" subgraph "Needs `rspec frontend_fixture/rspec-ee frontend_fixture`"; - 3_1-1 & 3_1-2 --> 2_2-2; + 3_1-1 --> 2_2-2; end - 3_2-1["rspec:coverage (5.3 minutes)"]; + 3_2-1["rspec:coverage (4 minutes)"]; subgraph "Depends on `rspec` jobs"; 3_2-1 -.->|"(don't use needs because of limitations)"| 2_5-1; click 3_2-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=7248745&udv=0" @@ -208,7 +206,7 @@ graph RL; 1-18["kubesec-sast"]; 1-19["nodejs-scan-sast"]; 1-20["secrets-sast"]; - 1-21["static-analysis (30 minutes)"]; + 1-21["static-analysis (14 minutes)"]; click 1-21 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914471&udv=0" class 1-3 criticalPath; @@ -228,7 +226,7 @@ graph RL; 2_1-1 & 2_1-2 & 2_1-3 & 2_1-4 --> 1-6; end - 2_2-2["rspec frontend_fixture/rspec-ee frontend_fixture (11 minutes)"]; + 2_2-2["rspec frontend_fixture/rspec-ee frontend_fixture (7 minutes)"]; class 2_2-2 criticalPath; click 2_2-2 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=7910143&udv=0" 2_2-4["memory-on-boot (3.5 minutes)"]; @@ -265,16 +263,14 @@ graph RL; click 2_6-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914314&udv=0" end - 3_1-1["jest (16 minutes)"]; + 3_1-1["jest (14.5 minutes)"]; class 3_1-1 criticalPath; click 3_1-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914204&udv=0" - 3_1-2["karma (2 minutes)"]; - click 3_1-3 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914200&udv=0" subgraph "Needs `rspec frontend_fixture/rspec-ee frontend_fixture`"; - 3_1-1 & 3_1-2 --> 2_2-2; + 3_1-1 --> 2_2-2; end - 3_2-1["rspec:coverage (5.3 minutes)"]; + 3_2-1["rspec:coverage (4 minutes)"]; subgraph "Depends on `rspec` jobs"; 3_2-1 -.->|"(don't use needs because of limitations)"| 2_5-1; click 3_2-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=7248745&udv=0" @@ -287,7 +283,7 @@ graph RL; click 4_1-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=7910777&udv=0" end - 3_3-1["review-deploy (10.5 minutes)"]; + 3_3-1["review-deploy (9 minutes)"]; subgraph "Played by `review-build-cng`"; 3_3-1 --> 2_6-1; class 3_3-1 criticalPath; @@ -336,7 +332,7 @@ graph RL; 1-18["kubesec-sast"]; 1-19["nodejs-scan-sast"]; 1-20["secrets-sast"]; - 1-21["static-analysis (30 minutes)"]; + 1-21["static-analysis (14 minutes)"]; click 1-21 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914471&udv=0" class 1-5 criticalPath; @@ -354,7 +350,7 @@ graph RL; class 2_3-1 criticalPath; end - 2_4-1["package-and-qa (140 minutes)"]; + 2_4-1["package-and-qa (113 minutes)"]; subgraph "Needs `build-qa-image` & `build-assets-image`"; 2_4-1 --> 1-2 & 2_3-1; class 2_4-1 criticalPath; @@ -434,10 +430,27 @@ In the `detect-tests` job, we use this mapping to identify the minimal tests nee After a merge request has been approved, the pipeline would contain the full RSpec tests. This will ensure that all tests have been run before a merge request is merged. +### Jest minimal jobs + +Before a merge request is approved, the pipeline will run a minimal set of Jest tests that are related to the merge request changes. +This is to reduce the pipeline cost and shorten the job duration. + +To identify the minimal set of tests needed, we pass a list of all the changed files into `jest` using the [`--findRelatedTests`](https://jestjs.io/docs/cli#--findrelatedtests-spaceseparatedlistofsourcefiles) option. +In this mode, `jest` would resolve all the dependencies of related to the changed files, which include test files that have these files in the dependency chain. + +After a merge request has been approved, the pipeline would contain the full Jest tests. This will ensure that all tests +have been run before a merge request is merged. + +In addition, there are a few circumstances where we would always run the full Jest tests: + +- when `package.json`, `yarn.lock`, `jest` config changes +- when vendored JavaScript is changed +- when `.graphql` files are changed + ### 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](https://docs.gitlab.com/omnibus/package-information/postgresql_versions.html), +[Omnibus defaults to PG12 for new installs and upgrades](../administration/package_information/postgresql_versions.md), Our test suite is currently running against PG11, since GitLab.com still runs on PG11. We do run our test suite against PG11 on nightly scheduled pipelines as well as upon specific @@ -454,7 +467,7 @@ database library changes in MRs and `main` pipelines (with the `rspec db-library #### Long-term plan -We follow the [PostgreSQL versions shipped with Omnibus GitLab](https://docs.gitlab.com/omnibus/package-information/postgresql_versions.html): +We follow the [PostgreSQL versions shipped with Omnibus GitLab](../administration/package_information/postgresql_versions.md): | PostgreSQL version | 13.11 (April 2021) | 13.12 (May 2021) | 14.0 (June 2021?) | | -------------------| ---------------------- | ---------------------- | ---------------------- | @@ -627,7 +640,6 @@ that is deployed in stage `review`. the `qa` stage's jobs (for example, Review App performance report). - `pages`: This stage includes a job that deploys the various reports as GitLab Pages (for example, [`coverage-ruby`](https://gitlab-org.gitlab.io/gitlab/coverage-ruby/), - [`coverage-javascript`](https://gitlab-org.gitlab.io/gitlab/coverage-javascript/), and `webpack-report` (found at `https://gitlab-org.gitlab.io/gitlab/webpack-report/`, but there is [an issue with the deployment](https://gitlab.com/gitlab-org/gitlab/-/issues/233458)). - `notify`: This stage includes jobs that notify various failures to Slack. diff --git a/doc/development/prometheus_metrics.md b/doc/development/prometheus_metrics.md index 66e980978bf..da6ba14cdd8 100644 --- a/doc/development/prometheus_metrics.md +++ b/doc/development/prometheus_metrics.md @@ -36,9 +36,7 @@ After you add or change an existing common metric, you must [re-run the import s Or, you can create a database migration: ```ruby -class ImportCommonMetrics < ActiveRecord::Migration[4.2] - include Gitlab::Database::MigrationHelpers - +class ImportCommonMetrics < Gitlab::Database::Migration[1.0] def up ::Gitlab::DatabaseImporters::CommonMetrics::Importer.new.execute end diff --git a/doc/development/query_recorder.md b/doc/development/query_recorder.md index 8759bd09538..424c089f88e 100644 --- a/doc/development/query_recorder.md +++ b/doc/development/query_recorder.md @@ -18,9 +18,9 @@ This style of test works by counting the number of SQL queries executed by Activ ```ruby it "avoids N+1 database queries" do - control_count = ActiveRecord::QueryRecorder.new { visit_some_page }.count + control = ActiveRecord::QueryRecorder.new { visit_some_page } create_list(:issue, 5) - expect { visit_some_page }.not_to exceed_query_limit(control_count) + expect { visit_some_page }.not_to exceed_query_limit(control) end ``` @@ -37,9 +37,9 @@ You should pass the `skip_cached` variable to `QueryRecorder` and use the `excee ```ruby it "avoids N+1 database queries", :use_sql_query_cache do - control_count = ActiveRecord::QueryRecorder.new(skip_cached: false) { visit_some_page }.count + control = ActiveRecord::QueryRecorder.new(skip_cached: false) { visit_some_page } create_list(:issue, 5) - expect { visit_some_page }.not_to exceed_all_query_limit(control_count) + expect { visit_some_page }.not_to exceed_all_query_limit(control) end ``` diff --git a/doc/development/rake_tasks.md b/doc/development/rake_tasks.md index 6b2b941a0c1..5c8e2d5fc55 100644 --- a/doc/development/rake_tasks.md +++ b/doc/development/rake_tasks.md @@ -128,7 +128,6 @@ In order to run the test you can use the following commands: - `bin/rake spec:unit` to run only the unit tests - `bin/rake spec:integration` to run only the integration tests - `bin/rake spec:system` to run only the system tests -- `bin/rake karma` to run the Karma test suite `bin/rake spec` takes significant time to pass. Instead of running the full test suite locally, you can save a lot of time by running @@ -189,6 +188,17 @@ Alternatively you can use the following on each spec run, bundle exec spring rspec some_spec.rb ``` +## Generate initial RuboCop TODO list + +One way to generate the initial list is to run the Rake task `rubocop:todo:generate`: + +```shell +bundle exec rake rubocop:todo:generate +``` + +See [Resolving RuboCop exceptions](contributing/style_guides.md#resolving-rubocop-exceptions) +on how to proceed from here. + ## Compile Frontend Assets You shouldn't ever need to compile frontend assets manually in development, but diff --git a/doc/development/secure_coding_guidelines.md b/doc/development/secure_coding_guidelines.md index fc60c1d7d7f..0f13b8ecae9 100644 --- a/doc/development/secure_coding_guidelines.md +++ b/doc/development/secure_coding_guidelines.md @@ -295,6 +295,8 @@ The injected client-side code is executed on the victim's browser in the context Much of the impact is contingent upon the function of the application and the capabilities of the victim's session. For further impact possibilities, please check out [the beef project](https://beefproject.com/). +For a demonstration of the impact on GitLab with a realistic attack scenario, see [this video on the GitLab Unfiltered channel](https://www.youtube.com/watch?v=t4PzHNycoKo) (internal, it requires being logged in with the GitLab Unfiltered account). + ### When to consider? When user submitted data is included in responses to end users, which is just about anywhere. diff --git a/doc/development/service_ping/implement.md b/doc/development/service_ping/implement.md index 629128af0c6..d86b06a6965 100644 --- a/doc/development/service_ping/implement.md +++ b/doc/development/service_ping/implement.md @@ -4,20 +4,680 @@ group: Product Intelligence info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Develop and test Service Ping +# Implement Service Ping -To add a new metric and test Service Ping: +Service Ping consists of two kinds of data: +- **Counters**: Track how often a certain event happened over time, such as how many CI/CD pipelines have run. + They are monotonic and always trend up. +- **Observations**: Facts collected from one or more GitLab instances and can carry arbitrary data. + There are no general guidelines for how to collect those, due to the individual nature of that data. + +To implement a new metric in Service Ping, follow these steps: + +1. [Implement the required counter](#types-of-counters) 1. [Name and place the metric](#name-and-place-the-metric) 1. [Test counters manually using your Rails console](#test-counters-manually-using-your-rails-console) 1. [Generate the SQL query](#generate-the-sql-query) 1. [Optimize queries with `#database-lab`](#optimize-queries-with-database-lab) -1. [Add the metric definition](#add-the-metric-definition) +1. [Add the metric definition to the Metrics Dictionary](#add-the-metric-definition) 1. [Add the metric to the Versions Application](#add-the-metric-to-the-versions-application) 1. [Create a merge request](#create-a-merge-request) 1. [Verify your metric](#verify-your-metric) 1. [Set up and test Service Ping locally](#set-up-and-test-service-ping-locally) +## Instrumentation classes + +We recommend you use [instrumentation classes](metrics_instrumentation.md) in `usage_data.rb` where possible. + +For example, we have the following instrumentation class: +`lib/gitlab/usage/metrics/instrumentations/count_boards_metric.rb`. + +You should add it to `usage_data.rb` as follows: + +```ruby +boards: add_metric('CountBoardsMetric', time_frame: 'all'), +``` + +## Types of counters + +There are several types of counters in `usage_data.rb`: + +- **[Batch counters](#batch-counters)**: Used for counts and sums. +- **[Redis counters](#redis-counters):** Used for in-memory counts. +- **[Alternative counters](#alternative-counters):** Used for settings and configurations. + +NOTE: +Only use the provided counter methods. Each counter method contains a built-in fail-safe mechanism that isolates each counter to avoid breaking the entire Service Ping process. + +### Batch counters + +For large tables, PostgreSQL can take a long time to count rows due to MVCC [(Multi-version Concurrency Control)](https://en.wikipedia.org/wiki/Multiversion_concurrency_control). Batch counting is a counting method where a single large query is broken into multiple smaller queries. For example, instead of a single query querying 1,000,000 records, with batch counting, you can execute 100 queries of 10,000 records each. Batch counting is useful for avoiding database timeouts as each batch query is significantly shorter than one single long running query. + +For GitLab.com, there are extremely large tables with 15 second query timeouts, so we use batch counting to avoid encountering timeouts. Here are the sizes of some GitLab.com tables: + +| Table | Row counts in millions | +|------------------------------|------------------------| +| `merge_request_diff_commits` | 2280 | +| `ci_build_trace_sections` | 1764 | +| `merge_request_diff_files` | 1082 | +| `events` | 514 | + +Batch counting requires indexes on columns to calculate max, min, and range queries. In some cases, +you must add a specialized index on the columns involved in a counter. + +#### Ordinary batch counters + +Simple count of a given `ActiveRecord_Relation`, does a non-distinct batch count, smartly reduces `batch_size`, and handles errors. +Handles the `ActiveRecord::StatementInvalid` error. + +Method: + +```ruby +count(relation, column = nil, batch: true, start: nil, finish: nil) +``` + +Arguments: + +- `relation` the ActiveRecord_Relation to perform the count +- `column` the column to perform the count on, by default is the primary key +- `batch`: default `true` to use batch counting +- `start`: custom start of the batch counting to avoid complex min calculations +- `end`: custom end of the batch counting to avoid complex min calculations + +Examples: + +```ruby +count(User.active) +count(::Clusters::Cluster.aws_installed.enabled, :cluster_id) +count(::Clusters::Cluster.aws_installed.enabled, :cluster_id, start: ::Clusters::Cluster.minimum(:id), finish: ::Clusters::Cluster.maximum(:id)) +``` + +#### Distinct batch counters + +Distinct count of a given `ActiveRecord_Relation` on given column, a distinct batch count, smartly reduces `batch_size`, and handles errors. +Handles the `ActiveRecord::StatementInvalid` error. + +Method: + +```ruby +distinct_count(relation, column = nil, batch: true, batch_size: nil, start: nil, finish: nil) +``` + +Arguments: + +- `relation`: the ActiveRecord_Relation to perform the count +- `column`: the column to perform the distinct count, by default is the primary key +- `batch`: default `true` to use batch counting +- `batch_size`: if none set it uses default value 10000 from `Gitlab::Database::BatchCounter` +- `start`: custom start of the batch counting to avoid complex min calculations +- `end`: custom end of the batch counting to avoid complex min calculations + +WARNING: +Counting over non-unique columns can lead to performance issues. For more information, see the [iterating tables in batches](../iterating_tables_in_batches.md) guide. + +Examples: + +```ruby +distinct_count(::Project, :creator_id) +distinct_count(::Note.with_suggestions.where(time_period), :author_id, start: ::User.minimum(:id), finish: ::User.maximum(:id)) +distinct_count(::Clusters::Applications::CertManager.where(time_period).available.joins(:cluster), 'clusters.user_id') +``` + +#### Sum batch operation + +Sum the values of a given ActiveRecord_Relation on given column and handles errors. +Handles the `ActiveRecord::StatementInvalid` error + +Method: + +```ruby +sum(relation, column, batch_size: nil, start: nil, finish: nil) +``` + +Arguments: + +- `relation`: the ActiveRecord_Relation to perform the operation +- `column`: the column to sum on +- `batch_size`: if none set it uses default value 1000 from `Gitlab::Database::BatchCounter` +- `start`: custom start of the batch counting to avoid complex min calculations +- `end`: custom end of the batch counting to avoid complex min calculations + +Examples: + +```ruby +sum(JiraImportState.finished, :imported_issues_count) +``` + +#### Grouping and batch operations + +The `count`, `distinct_count`, and `sum` batch counters can accept an `ActiveRecord::Relation` +object, which groups by a specified column. With a grouped relation, the methods do batch counting, +handle errors, and returns a hash table of key-value pairs. + +Examples: + +```ruby +count(Namespace.group(:type)) +# returns => {nil=>179, "Group"=>54} + +distinct_count(Project.group(:visibility_level), :creator_id) +# returns => {0=>1, 10=>1, 20=>11} + +sum(Issue.group(:state_id), :weight)) +# returns => {1=>3542, 2=>6820} +``` + +#### Add operation + +Sum the values given as parameters. Handles the `StandardError`. +Returns `-1` if any of the arguments are `-1`. + +Method: + +```ruby +add(*args) +``` + +Examples: + +```ruby +project_imports = distinct_count(::Project.where.not(import_type: nil), :creator_id) +bulk_imports = distinct_count(::BulkImport, :user_id) + + add(project_imports, bulk_imports) +``` + +#### Estimated batch counters + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/48233) in GitLab 13.7. + +Estimated batch counter functionality handles `ActiveRecord::StatementInvalid` errors +when used through the provided `estimate_batch_distinct_count` method. +Errors return a value of `-1`. + +WARNING: +This functionality estimates a distinct count of a specific ActiveRecord_Relation in a given column, +which uses the [HyperLogLog](http://algo.inria.fr/flajolet/Publications/FlFuGaMe07.pdf) algorithm. +As the HyperLogLog algorithm is probabilistic, the **results always include error**. +The highest encountered error rate is 4.9%. + +When correctly used, the `estimate_batch_distinct_count` method enables efficient counting over +columns that contain non-unique values, which can not be assured by other counters. + +##### estimate_batch_distinct_count method + +Method: + +```ruby +estimate_batch_distinct_count(relation, column = nil, batch_size: nil, start: nil, finish: nil) +``` + +The [method](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/utils/usage_data.rb#L63) +includes the following arguments: + +- `relation`: The ActiveRecord_Relation to perform the count. +- `column`: The column to perform the distinct count. The default is the primary key. +- `batch_size`: From `Gitlab::Database::PostgresHll::BatchDistinctCounter::DEFAULT_BATCH_SIZE`. Default value: 10,000. +- `start`: The custom start of the batch count, to avoid complex minimum calculations. +- `finish`: The custom end of the batch count to avoid complex maximum calculations. + +The method includes the following prerequisites: + +- The supplied `relation` must include the primary key defined as the numeric column. + For example: `id bigint NOT NULL`. +- The `estimate_batch_distinct_count` can handle a joined relation. To use its ability to + count non-unique columns, the joined relation **must not** have a one-to-many relationship, + such as `has_many :boards`. +- Both `start` and `finish` arguments should always represent primary key relationship values, + even if the estimated count refers to another column, for example: + + ```ruby + estimate_batch_distinct_count(::Note, :author_id, start: ::Note.minimum(:id), finish: ::Note.maximum(:id)) + ``` + +Examples: + +1. Simple execution of estimated batch counter, with only relation provided, + returned value represents estimated number of unique values in `id` column + (which is the primary key) of `Project` relation: + + ```ruby + estimate_batch_distinct_count(::Project) + ``` + +1. Execution of estimated batch counter, where provided relation has applied + additional filter (`.where(time_period)`), number of unique values estimated + in custom column (`:author_id`), and parameters: `start` and `finish` together + apply boundaries that defines range of provided relation to analyze: + + ```ruby + estimate_batch_distinct_count(::Note.with_suggestions.where(time_period), :author_id, start: ::Note.minimum(:id), finish: ::Note.maximum(:id)) + ``` + +1. Execution of estimated batch counter with joined relation (`joins(:cluster)`), + for a custom column (`'clusters.user_id'`): + + ```ruby + estimate_batch_distinct_count(::Clusters::Applications::CertManager.where(time_period).available.joins(:cluster), 'clusters.user_id') + ``` + +When instrumenting metric with usage of estimated batch counter please add +`_estimated` suffix to its name, for example: + +```ruby + "counts": { + "ci_builds_estimated": estimate_batch_distinct_count(Ci::Build), + ... +``` + +### Redis counters + +Handles `::Redis::CommandError` and `Gitlab::UsageDataCounters::BaseCounter::UnknownEvent`. +Returns -1 when a block is sent or hash with all values and -1 when a `counter(Gitlab::UsageDataCounters)` is sent. +The different behavior is due to 2 different implementations of the Redis counter. + +Method: + +```ruby +redis_usage_data(counter, &block) +``` + +Arguments: + +- `counter`: a counter from `Gitlab::UsageDataCounters`, that has `fallback_totals` method implemented +- or a `block`: which is evaluated + +#### Ordinary Redis counters + +Examples of implementation: + +- Using Redis methods [`INCR`](https://redis.io/commands/incr), [`GET`](https://redis.io/commands/get), and [`Gitlab::UsageDataCounters::WikiPageCounter`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/wiki_page_counter.rb) +- Using Redis methods [`HINCRBY`](https://redis.io/commands/hincrby), [`HGETALL`](https://redis.io/commands/hgetall), and [`Gitlab::UsageCounters::PodLogs`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_counters/pod_logs.rb) + +##### UsageData API tracking + +<!-- There's nearly identical content in `##### Adding new events`. If you fix errors here, you may need to fix the same errors in the other location. --> + +1. Track event using `UsageData` API + + Increment event count using ordinary Redis counter, for given event name. + + Tracking events using the `UsageData` API requires the `usage_data_api` feature flag to be enabled, which is enabled by default. + + API requests are protected by checking for a valid CSRF token. + + To be able to increment the values, the related feature `usage_data_<event_name>` should be enabled. + + ```plaintext + POST /usage_data/increment_counter + ``` + + | Attribute | Type | Required | Description | + | :-------- | :--- | :------- | :---------- | + | `event` | string | yes | The event name it should be tracked | + + Response: + + - `200` if event was tracked + - `400 Bad request` if event parameter is missing + - `401 Unauthorized` if user is not authenticated + - `403 Forbidden` for invalid CSRF token provided + +1. Track events using JavaScript/Vue API helper which calls the API above + + Note that `usage_data_api` and `usage_data_#{event_name}` should be enabled to be able to track events + + ```javascript + import api from '~/api'; + + api.trackRedisCounterEvent('my_already_defined_event_name'), + ``` + +#### Redis HLL counters + +WARNING: +HyperLogLog (HLL) is a probabilistic algorithm and its **results always includes some small error**. According to [Redis documentation](https://redis.io/commands/pfcount), data from +used HLL implementation is "approximated with a standard error of 0.81%". + +With `Gitlab::UsageDataCounters::HLLRedisCounter` we have available data structures used to count unique values. + +Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd) and [PFCOUNT](https://redis.io/commands/pfcount). + +##### Add new events + +1. Define events in [`known_events`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events/). + + Example event: + + ```yaml + - name: users_creating_epics + category: epics_usage + redis_slot: users + aggregation: weekly + feature_flag: track_epics_activity + ``` + + Keys: + + - `name`: unique event name. + + Name format for Redis HLL events `<name>_<redis_slot>`. + + [See Metric name](metrics_dictionary.md#metric-name) for a complete guide on metric naming suggestion. + + Consider including in the event's name the Redis slot to be able to count totals for a specific category. + + Example names: `users_creating_epics`, `users_triggering_security_scans`. + + - `category`: event category. Used for getting total counts for events in a category, for easier + access to a group of events. + - `redis_slot`: optional Redis slot. Default value: event name. Only event data that is stored in the same slot + can be aggregated. Ensure keys are in the same slot. For example: + `users_creating_epics` with `redis_slot: 'users'` builds Redis key + `{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`: optional `default_enabled: :yaml`. 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. + +1. Use one of the following methods to track the event: + + - In the controller using the `RedisTracking` module and the following format: + + ```ruby + track_redis_hll_event(*controller_actions, name:, if: nil, &block) + ``` + + Arguments: + + - `controller_actions`: the controller actions to track. + - `name`: the event name. + - `if`: optional custom conditions. Uses the same format as Rails callbacks. + - `&block`: optional block that computes and returns the `custom_id` that we want to track. This overrides the `visitor_id`. + + Example: + + ```ruby + # controller + class ProjectsController < Projects::ApplicationController + include RedisTracking + + skip_before_action :authenticate_user!, only: :show + track_redis_hll_event :index, :show, name: 'users_visiting_projects' + + def index + render html: 'index' + end + + def new + render html: 'new' + end + + def show + render html: 'show' + end + end + ``` + + - In the API using the `increment_unique_values(event_name, values)` helper method. + + Arguments: + + - `event_name`: the event name. + - `values`: the values counted. Can be one value or an array of values. + + Example: + + ```ruby + get ':id/registry/repositories' do + repositories = ContainerRepositoriesFinder.new( + user: current_user, subject: user_group + ).execute + + increment_unique_values('users_listing_repositories', current_user.id) + + present paginate(repositories), with: Entities::ContainerRegistry::Repository, tags: params[:tags], tags_count: params[:tags_count] + end + ``` + + - Using `track_usage_event(event_name, values)` in services and GraphQL. + + Increment unique values count using Redis HLL, for a given event name. + + Examples: + + - [Track usage event for an incident in a service](https://gitlab.com/gitlab-org/gitlab/-/blob/v13.8.3-ee/app/services/issues/update_service.rb#L66) + - [Track usage event for an incident in GraphQL](https://gitlab.com/gitlab-org/gitlab/-/blob/v13.8.3-ee/app/graphql/mutations/alert_management/update_alert_status.rb#L16) + + ```ruby + track_usage_event(:incident_management_incident_created, current_user.id) + ``` + + - Using the `UsageData` API. + <!-- There's nearly identical content in `##### UsageData API Tracking`. If you find / fix errors here, you may need to fix errors in that section too. --> + + Increment unique users count using Redis HLL, for a given event name. + + To track events using the `UsageData` API, ensure the `usage_data_api` feature flag + is set to `default_enabled: true`. Enabled by default in GitLab 13.7 and later. + + API requests are protected by checking for a valid CSRF token. + + ```plaintext + POST /usage_data/increment_unique_users + ``` + + | Attribute | Type | Required | Description | + | :-------- | :--- | :------- | :---------- | + | `event` | string | yes | The event name to track | + + Response: + + - `200` if the event was tracked, or if tracking failed for any reason. + - `400 Bad request` if an event parameter is missing. + - `401 Unauthorized` if the user is not authenticated. + - `403 Forbidden` if an invalid CSRF token is provided. + + - Using the JavaScript/Vue API helper, which calls the `UsageData` API. + + To track events using the `UsageData` API, ensure the `usage_data_api` feature flag + is set to `default_enabled: true`. Enabled by default in GitLab 13.7 and later. + + Example for an existing event already defined in [known events](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events/): + + ```javascript + import api from '~/api'; + + api.trackRedisHllUserEvent('my_already_defined_event_name'), + ``` + +1. Get event data using `Gitlab::UsageDataCounters::HLLRedisCounter.unique_events(event_names:, start_date:, end_date:, context: '')`. + + Arguments: + + - `event_names`: the list of event names. + - `start_date`: start date of the period for which we want to get event data. + - `end_date`: end date of the period for which we want to get event data. + - `context`: context of the event. Allowed values are `default`, `free`, `bronze`, `silver`, `gold`, `starter`, `premium`, `ultimate`. + +1. Testing tracking and getting unique events + +Trigger events in rails console by using `track_event` method + + ```ruby + Gitlab::UsageDataCounters::HLLRedisCounter.track_event('users_viewing_compliance_audit_events', values: 1) + Gitlab::UsageDataCounters::HLLRedisCounter.track_event('users_viewing_compliance_audit_events', values: [2, 3]) + ``` + +Next, get the unique events for the current week. + + ```ruby + # Get unique events for metric for current_week + Gitlab::UsageDataCounters::HLLRedisCounter.unique_events(event_names: 'users_viewing_compliance_audit_events', + start_date: Date.current.beginning_of_week, end_date: Date.current.next_week) + ``` + +##### Recommendations + +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 + +##### Enable or disable Redis HLL tracking + +Events are tracked behind optional [feature flags](../feature_flags/index.md) due to concerns for Redis performance and scalability. + +For a full list of events and corresponding feature flags see, [known_events](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events/) files. + +To enable or disable tracking for specific event in <https://gitlab.com> or <https://about.staging.gitlab.com>, run commands such as the following to +[enable or disable the corresponding feature](../feature_flags/index.md). + +```shell +/chatops run feature set <feature_name> true +/chatops run feature set <feature_name> false +``` + +We can also disable tracking completely by using the global flag: + +```shell +/chatops run feature set redis_hll_tracking true +/chatops run feature set redis_hll_tracking false +``` + +##### Known events are added automatically in Service Data payload + +All events added in [`known_events/common.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events/common.yml) are automatically added to Service Data generation under the `redis_hll_counters` key. This column is stored in [version-app as a JSON](https://gitlab.com/gitlab-services/version-gitlab-com/-/blob/master/db/schema.rb#L209). +For each event we add metrics for the weekly and monthly time frames, and totals for each where applicable: + +- `#{event_name}_weekly`: Data for 7 days for daily [aggregation](#add-new-events) events and data for the last complete week for weekly [aggregation](#add-new-events) events. +- `#{event_name}_monthly`: Data for 28 days for daily [aggregation](#add-new-events) events and data for the last 4 complete weeks for weekly [aggregation](#add-new-events) events. + +Redis HLL implementation calculates automatic total metrics, if there are more than one metric for the same category, aggregation, and Redis slot. + +- `#{category}_total_unique_counts_weekly`: Total unique counts for events in the same category for the last 7 days or the last complete week, if events are in the same Redis slot and we have more than one metric. +- `#{category}_total_unique_counts_monthly`: Total unique counts for events in same category for the last 28 days or the last 4 complete weeks, if events are in the same Redis slot and we have more than one metric. + +Example of `redis_hll_counters` data: + +```ruby +{:redis_hll_counters=> + {"compliance"=> + {"users_viewing_compliance_dashboard_weekly"=>0, + "users_viewing_compliance_dashboard_monthly"=>0, + "users_viewing_compliance_audit_events_weekly"=>0, + "users_viewing_audit_events_monthly"=>0, + "compliance_total_unique_counts_weekly"=>0, + "compliance_total_unique_counts_monthly"=>0}, + "analytics"=> + {"users_viewing_analytics_group_devops_adoption_weekly"=>0, + "users_viewing_analytics_group_devops_adoption_monthly"=>0, + "analytics_total_unique_counts_weekly"=>0, + "analytics_total_unique_counts_monthly"=>0}, + "ide_edit"=> + {"users_editing_by_web_ide_weekly"=>0, + "users_editing_by_web_ide_monthly"=>0, + "users_editing_by_sfe_weekly"=>0, + "users_editing_by_sfe_monthly"=>0, + "ide_edit_total_unique_counts_weekly"=>0, + "ide_edit_total_unique_counts_monthly"=>0} + } +``` + +Example: + +```ruby +# Redis Counters +redis_usage_data(Gitlab::UsageDataCounters::WikiPageCounter) +redis_usage_data { ::Gitlab::UsageCounters::PodLogs.usage_totals[:total] } + +# Define events in common.yml https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events/common.yml + +# Tracking events +Gitlab::UsageDataCounters::HLLRedisCounter.track_event('users_expanding_vulnerabilities', values: visitor_id) + +# Get unique events for metric +redis_usage_data { Gitlab::UsageDataCounters::HLLRedisCounter.unique_events(event_names: 'users_expanding_vulnerabilities', start_date: 28.days.ago, end_date: Date.current) } +``` + +### Alternative counters + +Handles `StandardError` and fallbacks into -1 this way not all measures fail if we encounter one exception. +Mainly used for settings and configurations. + +Method: + +```ruby +alt_usage_data(value = nil, fallback: -1, &block) +``` + +Arguments: + +- `value`: a simple static value in which case the value is simply returned. +- or a `block`: which is evaluated +- `fallback: -1`: the common value used for any metrics that are failing. + +Example: + +```ruby +alt_usage_data { Gitlab::VERSION } +alt_usage_data { Gitlab::CurrentSettings.uuid } +alt_usage_data(999) +``` + +### Add counters to build new metrics + +When adding the results of two counters, use the `add` Service Data method that +handles fallback values and exceptions. It also generates a valid [SQL export](index.md#export-service-ping-sql-queries-and-definitions). + +Example: + +```ruby +add(User.active, User.bot) +``` + +### Prometheus queries + +In those cases where operational metrics should be part of Service Ping, a database or Redis query is unlikely +to provide useful data. Instead, Prometheus might be more appropriate, because most GitLab architectural +components publish metrics to it that can be queried back, aggregated, and included as Service Data. + +NOTE: +Prometheus as a data source for Service Ping is only available for single-node Omnibus installations +that are running the [bundled Prometheus](../../administration/monitoring/prometheus/index.md) instance. + +To query Prometheus for metrics, a helper method is available to `yield` a fully configured +`PrometheusClient`, given it is available as per the note above: + +```ruby +with_prometheus_client do |client| + response = client.query('<your query>') + ... +end +``` + +Refer to [the `PrometheusClient` definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/prometheus_client.rb) +for how to use its API to query for data. + +### Fallback values for Service Ping + +We return fallback values in these cases: + +| Case | Value | +|-----------------------------|-------| +| Deprecated Metric | -1000 | +| Timeouts, general failures | -1 | +| Standard errors in counters | -2 | + ## Name and place the metric Add the metric in one of the top-level keys: @@ -159,7 +819,7 @@ To set up Service Ping locally, you must: ## Test Prometheus-based Service Ping -If the data submitted includes metrics [queried from Prometheus](index.md#prometheus-queries) +If the data submitted includes metrics [queried from Prometheus](#prometheus-queries) you want to inspect and verify, you must: - Ensure that a Prometheus server is running locally. @@ -208,3 +868,197 @@ However, it has the following limitations: with any of the other running services. That is not how node metrics are reported in a production setup, where `node_exporter` always runs as a process alongside other GitLab components on any given node. For Service Ping, none of the node data would therefore appear to be associated to any of the services running, because they all appear to be running on different hosts. To alleviate this problem, the `node_exporter` in GCK was arbitrarily "assigned" to the `web` service, meaning only for this service `node_*` metrics appears in Service Ping. + +## Aggregated metrics + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45979) in GitLab 13.6. + +WARNING: +This feature is intended solely for internal GitLab use. + +To add data for aggregated metrics to the Service Ping payload, add a corresponding definition to: + +- [`config/metrics/aggregates/*.yaml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/aggregates/) for metrics available in the Community Edition. +- [`ee/config/metrics/aggregates/*.yaml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/aggregates/) for metrics available in the Enterprise Edition. + +Each aggregate definition includes following parts: + +- `name`: Unique name under which the aggregate metric is added to the Service Ping payload. +- `operator`: Operator that defines how the aggregated metric data is counted. Available operators are: + - `OR`: Removes duplicates and counts all entries that triggered any of listed events. + - `AND`: Removes duplicates and counts all elements that were observed triggering all of following events. +- `time_frame`: One or more valid time frames. Use these to limit the data included in aggregated metric to events within a specific date-range. Valid time frames are: + - `7d`: Last seven days of data. + - `28d`: Last twenty eight days of data. + - `all`: All historical data, only available for `database` sourced aggregated metrics. +- `source`: Data source used to collect all events data included in aggregated metric. Valid data sources are: + - [`database`](#database-sourced-aggregated-metrics) + - [`redis`](#redis-sourced-aggregated-metrics) +- `events`: list of events names to aggregate into metric. All events in this list must + relay on the same data source. Additional data source requirements are described in the + [Database sourced aggregated metrics](#database-sourced-aggregated-metrics) and + [Redis sourced aggregated metrics](#redis-sourced-aggregated-metrics) sections. +- `feature_flag`: Name of [development feature flag](../feature_flags/index.md#development-type) + that is checked before metrics aggregation is performed. Corresponding feature flag + should have `default_enabled` attribute set to `false`. The `feature_flag` attribute + is optional and can be omitted. When `feature_flag` is missing, no feature flag is checked. + +Example aggregated metric entries: + +```yaml +- name: example_metrics_union + operator: OR + events: + - 'users_expanding_secure_security_report' + - 'users_expanding_testing_code_quality_report' + - 'users_expanding_testing_accessibility_report' + source: redis + time_frame: + - 7d + - 28d +- name: example_metrics_intersection + operator: AND + source: database + time_frame: + - 28d + - all + events: + - 'dependency_scanning_pipeline_all_time' + - 'container_scanning_pipeline_all_time' + feature_flag: example_aggregated_metric +``` + +Aggregated metrics collected in `7d` and `28d` time frames are added into Service Ping payload under the `aggregated_metrics` sub-key in the `counts_weekly` and `counts_monthly` top level keys. + +```ruby +{ + :counts_monthly => { + :deployments => 1003, + :successful_deployments => 78, + :failed_deployments => 275, + :packages => 155, + :personal_snippets => 2106, + :project_snippets => 407, + :promoted_issues => 719, + :aggregated_metrics => { + :example_metrics_union => 7, + :example_metrics_intersection => 2 + }, + :snippets => 2513 + } +} +``` + +Aggregated metrics for `all` time frame are present in the `count` top level key, with the `aggregate_` prefix added to their name. + +For example: + +`example_metrics_intersection` + +Becomes: + +`counts.aggregate_example_metrics_intersection` + +```ruby +{ + :counts => { + :deployments => 11003, + :successful_deployments => 178, + :failed_deployments => 1275, + :aggregate_example_metrics_intersection => 12 + } +} +``` + +### Redis sourced aggregated metrics + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45979) in GitLab 13.6. + +To declare the aggregate of events collected with [Redis HLL Counters](#redis-hll-counters), +you must fulfill the following requirements: + +1. All events listed at `events` attribute must come from + [`known_events/*.yml`](#known-events-are-added-automatically-in-service-data-payload) files. +1. All events listed at `events` attribute must have the same `redis_slot` attribute. +1. All events listed at `events` attribute must have the same `aggregation` attribute. +1. `time_frame` does not include `all` value, which is unavailable for Redis sourced aggregated metrics. + +### Database sourced aggregated metrics + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52784) in GitLab 13.9. +> - It's [deployed behind a feature flag](../../user/feature_flags.md), disabled by default. +> - It's enabled on GitLab.com. + +To declare an aggregate of metrics based on events collected from database, follow +these steps: + +1. [Persist the metrics for aggregation](#persist-metrics-for-aggregation). +1. [Add new aggregated metric definition](#add-new-aggregated-metric-definition). + +#### Persist metrics for aggregation + +Only metrics calculated with [Estimated Batch Counters](#estimated-batch-counters) +can be persisted for database sourced aggregated metrics. To persist a metric, +inject a Ruby block into the +[estimate_batch_distinct_count](#estimate_batch_distinct_count-method) method. +This block should invoke the +`Gitlab::Usage::Metrics::Aggregates::Sources::PostgresHll.save_aggregated_metrics` +[method](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage/metrics/aggregates/sources/postgres_hll.rb#L21), +which stores `estimate_batch_distinct_count` results for future use in aggregated metrics. + +The `Gitlab::Usage::Metrics::Aggregates::Sources::PostgresHll.save_aggregated_metrics` +method accepts the following arguments: + +- `metric_name`: The name of metric to use for aggregations. Should be the same + as the key under which the metric is added into Service Ping. +- `recorded_at_timestamp`: The timestamp representing the moment when a given + Service Ping payload was collected. You should use the convenience method `recorded_at` + to fill `recorded_at_timestamp` argument, like this: `recorded_at_timestamp: recorded_at` +- `time_period`: The time period used to build the `relation` argument passed into + `estimate_batch_distinct_count`. To collect the metric with all available historical + data, set a `nil` value as time period: `time_period: nil`. +- `data`: HyperLogLog buckets structure representing unique entries in `relation`. + The `estimate_batch_distinct_count` method always passes the correct argument + into the block, so `data` argument must always have a value equal to block argument, + like this: `data: result` + +Example metrics persistence: + +```ruby +class UsageData + def count_secure_pipelines(time_period) + ... + relation = ::Security::Scan.latest_successful_by_build.by_scan_types(scan_type).where(security_scans: time_period) + + pipelines_with_secure_jobs['dependency_scanning_pipeline'] = estimate_batch_distinct_count(relation, :commit_id, batch_size: 1000, start: start_id, finish: finish_id) do |result| + ::Gitlab::Usage::Metrics::Aggregates::Sources::PostgresHll + .save_aggregated_metrics(metric_name: 'dependency_scanning_pipeline', recorded_at_timestamp: recorded_at, time_period: time_period, data: result) + end + end +end +``` + +#### Add new aggregated metric definition + +After all metrics are persisted, you can add an aggregated metric definition at +[`aggregated_metrics/`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/aggregates/). + +To declare the aggregate of metrics collected with [Estimated Batch Counters](#estimated-batch-counters), +you must fulfill the following requirements: + +- Metrics names listed in the `events:` attribute, have to use the same names you passed in the `metric_name` argument while persisting metrics in previous step. +- Every metric listed in the `events:` attribute, has to be persisted for **every** selected `time_frame:` value. + +Example definition: + +```yaml +- name: example_metrics_intersection_database_sourced + operator: AND + source: database + events: + - 'dependency_scanning_pipeline' + - 'container_scanning_pipeline' + time_frame: + - 28d + - all +``` diff --git a/doc/development/service_ping/index.md b/doc/development/service_ping/index.md index 816743a3e97..0a94fa2ff6c 100644 --- a/doc/development/service_ping/index.md +++ b/doc/development/service_ping/index.md @@ -66,7 +66,7 @@ We use the following terminology to describe the Service Ping components: > Introduced in GitLab 14.1. -Starting with GitLab version 14.1, free self-managed users running [GitLab EE](../ee_features.md) can receive paid features by registering with GitLab and sending us activity data via [Service Ping](#what-is-service-ping). +Starting with GitLab version 14.1, free self-managed users running [GitLab EE](../ee_features.md) can receive paid features by registering with GitLab and sending us activity data via [Service Ping](#what-is-service-ping). Features introduced here do not remove the feature from its paid tier. Users can continue to access the features in a paid tier without sharing usage data. The paid feature available in this offering is [Email from GitLab](../../tools/email.md). Administrators can use this [Premium](https://about.gitlab.com/pricing/premium/) feature to streamline @@ -85,7 +85,7 @@ Registration is not yet required for participation, but will be added in a futur You can view the exact JSON payload sent to GitLab Inc. in the Admin Area. To view the payload: 1. Sign in as a user with the [Administrator](../../user/permissions.md) role. -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Metrics and profiling**. 1. Expand the **Usage statistics** section. 1. Select **Preview payload**. @@ -107,7 +107,7 @@ configuration file. To disable Service Ping in the GitLab UI: 1. Sign in as a user with the [Administrator](../../user/permissions.md) role. -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Metrics and profiling**. 1. Expand the **Usage statistics** section. 1. Clear the **Enable service ping** checkbox. @@ -222,844 +222,7 @@ We also collect metrics specific to [Geo](../../administration/geo/index.md) sec ## Implementing Service Ping -Service Ping consists of two kinds of data, counters and observations. Counters track how often a certain event -happened over time, such as how many CI pipelines have run. They are monotonic and always trend up. -Observations are facts collected from one or more GitLab instances and can carry arbitrary data. There are no -general guidelines around how to collect those, due to the individual nature of that data. - -### Types of counters - -There are several types of counters in `usage_data.rb`: - -- **Ordinary Batch Counters:** Simple count of a given ActiveRecord_Relation -- **Distinct Batch Counters:** Distinct count of a given ActiveRecord_Relation in a given column -- **Sum Batch Counters:** Sum the values of a given ActiveRecord_Relation in a given column -- **Alternative Counters:** Used for settings and configurations -- **Redis Counters:** Used for in-memory counts. - -NOTE: -Only use the provided counter methods. Each counter method contains a built-in fail-safe mechanism that isolates each counter to avoid breaking the entire Service Ping process. - -### Instrumentation classes - -We recommend you use [instrumentation classes](metrics_instrumentation.md) in `usage_data.rb` where possible. - -For example, we have the following instrumentation class: -`lib/gitlab/usage/metrics/instrumentations/count_boards_metric.rb`. - -You should add it to `usage_data.rb` as follows: - -```ruby -boards: add_metric('CountBoardsMetric', time_frame: 'all'), -``` - -### Batch counting - -For large tables, PostgreSQL can take a long time to count rows due to MVCC [(Multi-version Concurrency Control)](https://en.wikipedia.org/wiki/Multiversion_concurrency_control). Batch counting is a counting method where a single large query is broken into multiple smaller queries. For example, instead of a single query querying 1,000,000 records, with batch counting, you can execute 100 queries of 10,000 records each. Batch counting is useful for avoiding database timeouts as each batch query is significantly shorter than one single long running query. - -For GitLab.com, there are extremely large tables with 15 second query timeouts, so we use batch counting to avoid encountering timeouts. Here are the sizes of some GitLab.com tables: - -| Table | Row counts in millions | -|------------------------------|------------------------| -| `merge_request_diff_commits` | 2280 | -| `ci_build_trace_sections` | 1764 | -| `merge_request_diff_files` | 1082 | -| `events` | 514 | - -The following operation methods are available: - -- [Ordinary batch counters](#ordinary-batch-counters) -- [Distinct batch counters](#distinct-batch-counters) -- [Sum batch operation](#sum-batch-operation) -- [Add operation](#add-operation) -- [Estimated batch counters](#estimated-batch-counters) - -Batch counting requires indexes on columns to calculate max, min, and range queries. In some cases, -you may need to add a specialized index on the columns involved in a counter. - -### Ordinary batch counters - -Handles `ActiveRecord::StatementInvalid` error - -Simple count of a given `ActiveRecord_Relation`, does a non-distinct batch count, smartly reduces `batch_size`, and handles errors. - -Method: `count(relation, column = nil, batch: true, start: nil, finish: nil)` - -Arguments: - -- `relation` the ActiveRecord_Relation to perform the count -- `column` the column to perform the count on, by default is the primary key -- `batch`: default `true` to use batch counting -- `start`: custom start of the batch counting to avoid complex min calculations -- `end`: custom end of the batch counting to avoid complex min calculations - -Examples: - -```ruby -count(User.active) -count(::Clusters::Cluster.aws_installed.enabled, :cluster_id) -count(::Clusters::Cluster.aws_installed.enabled, :cluster_id, start: ::Clusters::Cluster.minimum(:id), finish: ::Clusters::Cluster.maximum(:id)) -``` - -### Distinct batch counters - -Handles `ActiveRecord::StatementInvalid` error - -Distinct count of a given `ActiveRecord_Relation` on given column, a distinct batch count, smartly reduces `batch_size`, and handles errors. - -Method: `distinct_count(relation, column = nil, batch: true, batch_size: nil, start: nil, finish: nil)` - -Arguments: - -- `relation` the ActiveRecord_Relation to perform the count -- `column` the column to perform the distinct count, by default is the primary key -- `batch`: default `true` to use batch counting -- `batch_size`: if none set it uses default value 10000 from `Gitlab::Database::BatchCounter` -- `start`: custom start of the batch counting to avoid complex min calculations -- `end`: custom end of the batch counting to avoid complex min calculations - -WARNING: -Counting over non-unique columns can lead to performance issues. For more information, see the [iterating tables in batches](../iterating_tables_in_batches.md) guide. - -Examples: - -```ruby -distinct_count(::Project, :creator_id) -distinct_count(::Note.with_suggestions.where(time_period), :author_id, start: ::User.minimum(:id), finish: ::User.maximum(:id)) -distinct_count(::Clusters::Applications::CertManager.where(time_period).available.joins(:cluster), 'clusters.user_id') -``` - -### Sum batch operation - -Handles `ActiveRecord::StatementInvalid` error - -Sum the values of a given ActiveRecord_Relation on given column and handles errors. - -Method: `sum(relation, column, batch_size: nil, start: nil, finish: nil)` - -Arguments: - -- `relation` the ActiveRecord_Relation to perform the operation -- `column` the column to sum on -- `batch_size`: if none set it uses default value 1000 from `Gitlab::Database::BatchCounter` -- `start`: custom start of the batch counting to avoid complex min calculations -- `end`: custom end of the batch counting to avoid complex min calculations - -Examples: - -```ruby -sum(JiraImportState.finished, :imported_issues_count) -``` - -### Grouping and batch operations - -The `count`, `distinct_count`, and `sum` batch counters can accept an `ActiveRecord::Relation` -object, which groups by a specified column. With a grouped relation, the methods do batch counting, -handle errors, and returns a hash table of key-value pairs. - -Examples: - -```ruby -count(Namespace.group(:type)) -# returns => {nil=>179, "Group"=>54} - -distinct_count(Project.group(:visibility_level), :creator_id) -# returns => {0=>1, 10=>1, 20=>11} - -sum(Issue.group(:state_id), :weight)) -# returns => {1=>3542, 2=>6820} -``` - -### Add operation - -Handles `StandardError`. - -Returns `-1` if any of the arguments are `-1`. - -Sum the values given as parameters. - -Method: `add(*args)` - -Examples: - -```ruby -project_imports = distinct_count(::Project.where.not(import_type: nil), :creator_id) -bulk_imports = distinct_count(::BulkImport, :user_id) - - add(project_imports, bulk_imports) -``` - -### Estimated batch counters - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/48233) in GitLab 13.7. - -Estimated batch counter functionality handles `ActiveRecord::StatementInvalid` errors -when used through the provided `estimate_batch_distinct_count` method. -Errors return a value of `-1`. - -WARNING: -This functionality estimates a distinct count of a specific ActiveRecord_Relation in a given column, -which uses the [HyperLogLog](http://algo.inria.fr/flajolet/Publications/FlFuGaMe07.pdf) algorithm. -As the HyperLogLog algorithm is probabilistic, the **results always include error**. -The highest encountered error rate is 4.9%. - -When correctly used, the `estimate_batch_distinct_count` method enables efficient counting over -columns that contain non-unique values, which can not be assured by other counters. - -#### estimate_batch_distinct_count method - -Method: `estimate_batch_distinct_count(relation, column = nil, batch_size: nil, start: nil, finish: nil)` - -The [method](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/utils/usage_data.rb#L63) -includes the following arguments: - -- `relation`: The ActiveRecord_Relation to perform the count. -- `column`: The column to perform the distinct count. The default is the primary key. -- `batch_size`: From `Gitlab::Database::PostgresHll::BatchDistinctCounter::DEFAULT_BATCH_SIZE`. Default value: 10,000. -- `start`: The custom start of the batch count, to avoid complex minimum calculations. -- `finish`: The custom end of the batch count to avoid complex maximum calculations. - -The method includes the following prerequisites: - -1. The supplied `relation` must include the primary key defined as the numeric column. - For example: `id bigint NOT NULL`. -1. The `estimate_batch_distinct_count` can handle a joined relation. To use its ability to - count non-unique columns, the joined relation **must not** have a one-to-many relationship, - such as `has_many :boards`. -1. Both `start` and `finish` arguments should always represent primary key relationship values, - even if the estimated count refers to another column, for example: - - ```ruby - estimate_batch_distinct_count(::Note, :author_id, start: ::Note.minimum(:id), finish: ::Note.maximum(:id)) - ``` - -Examples: - -1. Simple execution of estimated batch counter, with only relation provided, - returned value represents estimated number of unique values in `id` column - (which is the primary key) of `Project` relation: - - ```ruby - estimate_batch_distinct_count(::Project) - ``` - -1. Execution of estimated batch counter, where provided relation has applied - additional filter (`.where(time_period)`), number of unique values estimated - in custom column (`:author_id`), and parameters: `start` and `finish` together - apply boundaries that defines range of provided relation to analyze: - - ```ruby - estimate_batch_distinct_count(::Note.with_suggestions.where(time_period), :author_id, start: ::Note.minimum(:id), finish: ::Note.maximum(:id)) - ``` - -1. Execution of estimated batch counter with joined relation (`joins(:cluster)`), - for a custom column (`'clusters.user_id'`): - - ```ruby - estimate_batch_distinct_count(::Clusters::Applications::CertManager.where(time_period).available.joins(:cluster), 'clusters.user_id') - ``` - -When instrumenting metric with usage of estimated batch counter please add -`_estimated` suffix to its name, for example: - -```ruby - "counts": { - "ci_builds_estimated": estimate_batch_distinct_count(Ci::Build), - ... -``` - -### Redis counters - -Handles `::Redis::CommandError` and `Gitlab::UsageDataCounters::BaseCounter::UnknownEvent` -returns -1 when a block is sent or hash with all values -1 when a `counter(Gitlab::UsageDataCounters)` is sent -different behavior due to 2 different implementations of Redis counter - -Method: `redis_usage_data(counter, &block)` - -Arguments: - -- `counter`: a counter from `Gitlab::UsageDataCounters`, that has `fallback_totals` method implemented -- or a `block`: which is evaluated - -#### Ordinary Redis counters - -Examples of implementation: - -- Using Redis methods [`INCR`](https://redis.io/commands/incr), [`GET`](https://redis.io/commands/get), and [`Gitlab::UsageDataCounters::WikiPageCounter`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/wiki_page_counter.rb) -- Using Redis methods [`HINCRBY`](https://redis.io/commands/hincrby), [`HGETALL`](https://redis.io/commands/hgetall), and [`Gitlab::UsageCounters::PodLogs`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_counters/pod_logs.rb) - -##### UsageData API tracking - -<!-- There's nearly identical content in `##### Adding new events`. If you fix errors here, you may need to fix the same errors in the other location. --> - -1. Track event using `UsageData` API - - Increment event count using ordinary Redis counter, for given event name. - - Tracking events using the `UsageData` API requires the `usage_data_api` feature flag to be enabled, which is enabled by default. - - API requests are protected by checking for a valid CSRF token. - - To be able to increment the values, the related feature `usage_data_<event_name>` should be enabled. - - ```plaintext - POST /usage_data/increment_counter - ``` - - | Attribute | Type | Required | Description | - | :-------- | :--- | :------- | :---------- | - | `event` | string | yes | The event name it should be tracked | - - Response: - - - `200` if event was tracked - - `400 Bad request` if event parameter is missing - - `401 Unauthorized` if user is not authenticated - - `403 Forbidden` for invalid CSRF token provided - -1. Track events using JavaScript/Vue API helper which calls the API above - - Note that `usage_data_api` and `usage_data_#{event_name}` should be enabled to be able to track events - - ```javascript - import api from '~/api'; - - api.trackRedisCounterEvent('my_already_defined_event_name'), - ``` - -#### Redis HLL counters - -WARNING: -HyperLogLog (HLL) is a probabilistic algorithm and its **results always includes some small error**. According to [Redis documentation](https://redis.io/commands/pfcount), data from -used HLL implementation is "approximated with a standard error of 0.81%". - -With `Gitlab::UsageDataCounters::HLLRedisCounter` we have available data structures used to count unique values. - -Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd) and [PFCOUNT](https://redis.io/commands/pfcount). - -##### Add new events - -1. Define events in [`known_events`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events/). - - Example event: - - ```yaml - - name: users_creating_epics - category: epics_usage - redis_slot: users - aggregation: weekly - feature_flag: track_epics_activity - ``` - - Keys: - - - `name`: unique event name. - - Name format for Redis HLL events `<name>_<redis_slot>`. - - [See Metric name](metrics_dictionary.md#metric-name) for a complete guide on metric naming suggestion. - - Consider including in the event's name the Redis slot to be able to count totals for a specific category. - - Example names: `users_creating_epics`, `users_triggering_security_scans`. - - - `category`: event category. Used for getting total counts for events in a category, for easier - access to a group of events. - - `redis_slot`: optional Redis slot. Default value: event name. Only event data that is stored in the same slot - can be aggregated. Ensure keys are in the same slot. For example: - `users_creating_epics` with `redis_slot: 'users'` builds Redis key - `{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`: optional `default_enabled: :yaml`. 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. - -1. Use one of the following methods to track the event: - - - In the controller using the `RedisTracking` module and the following format: - - ```ruby - track_redis_hll_event(*controller_actions, name:, if: nil, &block) - ``` - - Arguments: - - - `controller_actions`: the controller actions to track. - - `name`: the event name. - - `if`: optional custom conditions. Uses the same format as Rails callbacks. - - `&block`: optional block that computes and returns the `custom_id` that we want to track. This overrides the `visitor_id`. - - Example: - - ```ruby - # controller - class ProjectsController < Projects::ApplicationController - include RedisTracking - - skip_before_action :authenticate_user!, only: :show - track_redis_hll_event :index, :show, name: 'users_visiting_projects' - - def index - render html: 'index' - end - - def new - render html: 'new' - end - - def show - render html: 'show' - end - end - ``` - - - In the API using the `increment_unique_values(event_name, values)` helper method. - - Arguments: - - - `event_name`: the event name. - - `values`: the values counted. Can be one value or an array of values. - - Example: - - ```ruby - get ':id/registry/repositories' do - repositories = ContainerRepositoriesFinder.new( - user: current_user, subject: user_group - ).execute - - increment_unique_values('users_listing_repositories', current_user.id) - - present paginate(repositories), with: Entities::ContainerRegistry::Repository, tags: params[:tags], tags_count: params[:tags_count] - end - ``` - - - Using `track_usage_event(event_name, values)` in services and GraphQL. - - Increment unique values count using Redis HLL, for a given event name. - - Examples: - - - [Track usage event for an incident in a service](https://gitlab.com/gitlab-org/gitlab/-/blob/v13.8.3-ee/app/services/issues/update_service.rb#L66) - - [Track usage event for an incident in GraphQL](https://gitlab.com/gitlab-org/gitlab/-/blob/v13.8.3-ee/app/graphql/mutations/alert_management/update_alert_status.rb#L16) - - ```ruby - track_usage_event(:incident_management_incident_created, current_user.id) - ``` - - - Using the `UsageData` API. - <!-- There's nearly identical content in `##### UsageData API Tracking`. If you find / fix errors here, you may need to fix errors in that section too. --> - - Increment unique users count using Redis HLL, for a given event name. - - To track events using the `UsageData` API, ensure the `usage_data_api` feature flag - is set to `default_enabled: true`. Enabled by default in GitLab 13.7 and later. - - API requests are protected by checking for a valid CSRF token. - - ```plaintext - POST /usage_data/increment_unique_users - ``` - - | Attribute | Type | Required | Description | - | :-------- | :--- | :------- | :---------- | - | `event` | string | yes | The event name to track | - - Response: - - - `200` if the event was tracked, or if tracking failed for any reason. - - `400 Bad request` if an event parameter is missing. - - `401 Unauthorized` if the user is not authenticated. - - `403 Forbidden` if an invalid CSRF token is provided. - - - Using the JavaScript/Vue API helper, which calls the `UsageData` API. - - To track events using the `UsageData` API, ensure the `usage_data_api` feature flag - is set to `default_enabled: true`. Enabled by default in GitLab 13.7 and later. - - Example for an existing event already defined in [known events](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events/): - - ```javascript - import api from '~/api'; - - api.trackRedisHllUserEvent('my_already_defined_event_name'), - ``` - -1. Get event data using `Gitlab::UsageDataCounters::HLLRedisCounter.unique_events(event_names:, start_date:, end_date:, context: '')`. - - Arguments: - - - `event_names`: the list of event names. - - `start_date`: start date of the period for which we want to get event data. - - `end_date`: end date of the period for which we want to get event data. - - `context`: context of the event. Allowed values are `default`, `free`, `bronze`, `silver`, `gold`, `starter`, `premium`, `ultimate`. - -1. Testing tracking and getting unique events - -Trigger events in rails console by using `track_event` method - - ```ruby - Gitlab::UsageDataCounters::HLLRedisCounter.track_event('users_viewing_compliance_audit_events', values: 1) - Gitlab::UsageDataCounters::HLLRedisCounter.track_event('users_viewing_compliance_audit_events', values: [2, 3]) - ``` - -Next, get the unique events for the current week. - - ```ruby - # Get unique events for metric for current_week - Gitlab::UsageDataCounters::HLLRedisCounter.unique_events(event_names: 'users_viewing_compliance_audit_events', - start_date: Date.current.beginning_of_week, end_date: Date.current.next_week) - ``` - -##### Recommendations - -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 - -##### Enable or disable Redis HLL tracking - -Events are tracked behind optional [feature flags](../feature_flags/index.md) due to concerns for Redis performance and scalability. - -For a full list of events and corresponding feature flags see, [known_events](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events/) files. - -To enable or disable tracking for specific event in <https://gitlab.com> or <https://about.staging.gitlab.com>, run commands such as the following to -[enable or disable the corresponding feature](../feature_flags/index.md). - -```shell -/chatops run feature set <feature_name> true -/chatops run feature set <feature_name> false -``` - -We can also disable tracking completely by using the global flag: - -```shell -/chatops run feature set redis_hll_tracking true -/chatops run feature set redis_hll_tracking false -``` - -##### Known events are added automatically in Service Data payload - -All events added in [`known_events/common.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events/common.yml) are automatically added to Service Data generation under the `redis_hll_counters` key. This column is stored in [version-app as a JSON](https://gitlab.com/gitlab-services/version-gitlab-com/-/blob/master/db/schema.rb#L209). -For each event we add metrics for the weekly and monthly time frames, and totals for each where applicable: - -- `#{event_name}_weekly`: Data for 7 days for daily [aggregation](#add-new-events) events and data for the last complete week for weekly [aggregation](#add-new-events) events. -- `#{event_name}_monthly`: Data for 28 days for daily [aggregation](#add-new-events) events and data for the last 4 complete weeks for weekly [aggregation](#add-new-events) events. - -Redis HLL implementation calculates automatic total metrics, if there are more than one metric for the same category, aggregation, and Redis slot. - -- `#{category}_total_unique_counts_weekly`: Total unique counts for events in the same category for the last 7 days or the last complete week, if events are in the same Redis slot and we have more than one metric. -- `#{category}_total_unique_counts_monthly`: Total unique counts for events in same category for the last 28 days or the last 4 complete weeks, if events are in the same Redis slot and we have more than one metric. - -Example of `redis_hll_counters` data: - -```ruby -{:redis_hll_counters=> - {"compliance"=> - {"users_viewing_compliance_dashboard_weekly"=>0, - "users_viewing_compliance_dashboard_monthly"=>0, - "users_viewing_compliance_audit_events_weekly"=>0, - "users_viewing_audit_events_monthly"=>0, - "compliance_total_unique_counts_weekly"=>0, - "compliance_total_unique_counts_monthly"=>0}, - "analytics"=> - {"users_viewing_analytics_group_devops_adoption_weekly"=>0, - "users_viewing_analytics_group_devops_adoption_monthly"=>0, - "analytics_total_unique_counts_weekly"=>0, - "analytics_total_unique_counts_monthly"=>0}, - "ide_edit"=> - {"users_editing_by_web_ide_weekly"=>0, - "users_editing_by_web_ide_monthly"=>0, - "users_editing_by_sfe_weekly"=>0, - "users_editing_by_sfe_monthly"=>0, - "ide_edit_total_unique_counts_weekly"=>0, - "ide_edit_total_unique_counts_monthly"=>0} - } -``` - -Example: - -```ruby -# Redis Counters -redis_usage_data(Gitlab::UsageDataCounters::WikiPageCounter) -redis_usage_data { ::Gitlab::UsageCounters::PodLogs.usage_totals[:total] } - -# Define events in common.yml https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events/common.yml - -# Tracking events -Gitlab::UsageDataCounters::HLLRedisCounter.track_event('users_expanding_vulnerabilities', values: visitor_id) - -# Get unique events for metric -redis_usage_data { Gitlab::UsageDataCounters::HLLRedisCounter.unique_events(event_names: 'users_expanding_vulnerabilities', start_date: 28.days.ago, end_date: Date.current) } -``` - -### Alternative counters - -Handles `StandardError` and fallbacks into -1 this way not all measures fail if we encounter one exception. -Mainly used for settings and configurations. - -Method: `alt_usage_data(value = nil, fallback: -1, &block)` - -Arguments: - -- `value`: a simple static value in which case the value is simply returned. -- or a `block`: which is evaluated -- `fallback: -1`: the common value used for any metrics that are failing. - -Example: - -```ruby -alt_usage_data { Gitlab::VERSION } -alt_usage_data { Gitlab::CurrentSettings.uuid } -alt_usage_data(999) -``` - -### Add counters to build new metrics - -When adding the results of two counters, use the `add` Service Data method that -handles fallback values and exceptions. It also generates a valid [SQL export](#export-service-ping-sql-queries-and-definitions). - -Example: - -```ruby -add(User.active, User.bot) -``` - -### Prometheus queries - -In those cases where operational metrics should be part of Service Ping, a database or Redis query is unlikely -to provide useful data. Instead, Prometheus might be more appropriate, because most GitLab architectural -components publish metrics to it that can be queried back, aggregated, and included as Service Data. - -NOTE: -Prometheus as a data source for Service Ping is only available for single-node Omnibus installations -that are running the [bundled Prometheus](../../administration/monitoring/prometheus/index.md) instance. - -To query Prometheus for metrics, a helper method is available to `yield` a fully configured -`PrometheusClient`, given it is available as per the note above: - -```ruby -with_prometheus_client do |client| - response = client.query('<your query>') - ... -end -``` - -Refer to [the `PrometheusClient` definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/prometheus_client.rb) -for how to use its API to query for data. - -### Fallback values for Service Ping - -We return fallback values in these cases: - -| Case | Value | -|-----------------------------|-------| -| Deprecated Metric | -1000 | -| Timeouts, general failures | -1 | -| Standard errors in counters | -2 | - -## Aggregated metrics - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45979) in GitLab 13.6. - -WARNING: -This feature is intended solely for internal GitLab use. - -To add data for aggregated metrics to the Service Ping payload, add a corresponding definition to: - -- [`config/metrics/aggregates/*.yaml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/aggregates/) for metrics available in the Community Edition. -- [`ee/config/metrics/aggregates/*.yaml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/aggregates/) for metrics available in the Enterprise Edition. - -Each aggregate definition includes following parts: - -- `name`: Unique name under which the aggregate metric is added to the Service Ping payload. -- `operator`: Operator that defines how the aggregated metric data is counted. Available operators are: - - `OR`: Removes duplicates and counts all entries that triggered any of listed events. - - `AND`: Removes duplicates and counts all elements that were observed triggering all of following events. -- `time_frame`: One or more valid time frames. Use these to limit the data included in aggregated metric to events within a specific date-range. Valid time frames are: - - `7d`: Last seven days of data. - - `28d`: Last twenty eight days of data. - - `all`: All historical data, only available for `database` sourced aggregated metrics. -- `source`: Data source used to collect all events data included in aggregated metric. Valid data sources are: - - [`database`](#database-sourced-aggregated-metrics) - - [`redis`](#redis-sourced-aggregated-metrics) -- `events`: list of events names to aggregate into metric. All events in this list must - relay on the same data source. Additional data source requirements are described in the - [Database sourced aggregated metrics](#database-sourced-aggregated-metrics) and - [Redis sourced aggregated metrics](#redis-sourced-aggregated-metrics) sections. -- `feature_flag`: Name of [development feature flag](../feature_flags/index.md#development-type) - that is checked before metrics aggregation is performed. Corresponding feature flag - should have `default_enabled` attribute set to `false`. The `feature_flag` attribute - is optional and can be omitted. When `feature_flag` is missing, no feature flag is checked. - -Example aggregated metric entries: - -```yaml -- name: example_metrics_union - operator: OR - events: - - 'users_expanding_secure_security_report' - - 'users_expanding_testing_code_quality_report' - - 'users_expanding_testing_accessibility_report' - source: redis - time_frame: - - 7d - - 28d -- name: example_metrics_intersection - operator: AND - source: database - time_frame: - - 28d - - all - events: - - 'dependency_scanning_pipeline_all_time' - - 'container_scanning_pipeline_all_time' - feature_flag: example_aggregated_metric -``` - -Aggregated metrics collected in `7d` and `28d` time frames are added into Service Ping payload under the `aggregated_metrics` sub-key in the `counts_weekly` and `counts_monthly` top level keys. - -```ruby -{ - :counts_monthly => { - :deployments => 1003, - :successful_deployments => 78, - :failed_deployments => 275, - :packages => 155, - :personal_snippets => 2106, - :project_snippets => 407, - :promoted_issues => 719, - :aggregated_metrics => { - :example_metrics_union => 7, - :example_metrics_intersection => 2 - }, - :snippets => 2513 - } -} -``` - -Aggregated metrics for `all` time frame are present in the `count` top level key, with the `aggregate_` prefix added to their name. - -For example: - -`example_metrics_intersection` - -Becomes: - -`counts.aggregate_example_metrics_intersection` - -```ruby -{ - :counts => { - :deployments => 11003, - :successful_deployments => 178, - :failed_deployments => 1275, - :aggregate_example_metrics_intersection => 12 - } -} -``` - -### Redis sourced aggregated metrics - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45979) in GitLab 13.6. - -To declare the aggregate of events collected with [Redis HLL Counters](#redis-hll-counters), -you must fulfill the following requirements: - -1. All events listed at `events` attribute must come from - [`known_events/*.yml`](#known-events-are-added-automatically-in-service-data-payload) files. -1. All events listed at `events` attribute must have the same `redis_slot` attribute. -1. All events listed at `events` attribute must have the same `aggregation` attribute. -1. `time_frame` does not include `all` value, which is unavailable for Redis sourced aggregated metrics. - -### Database sourced aggregated metrics - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52784) in GitLab 13.9. -> - It's [deployed behind a feature flag](../../user/feature_flags.md), disabled by default. -> - It's enabled on GitLab.com. - -To declare an aggregate of metrics based on events collected from database, follow -these steps: - -1. [Persist the metrics for aggregation](#persist-metrics-for-aggregation). -1. [Add new aggregated metric definition](#add-new-aggregated-metric-definition). - -#### Persist metrics for aggregation - -Only metrics calculated with [Estimated Batch Counters](#estimated-batch-counters) -can be persisted for database sourced aggregated metrics. To persist a metric, -inject a Ruby block into the -[estimate_batch_distinct_count](#estimate_batch_distinct_count-method) method. -This block should invoke the -`Gitlab::Usage::Metrics::Aggregates::Sources::PostgresHll.save_aggregated_metrics` -[method](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage/metrics/aggregates/sources/postgres_hll.rb#L21), -which stores `estimate_batch_distinct_count` results for future use in aggregated metrics. - -The `Gitlab::Usage::Metrics::Aggregates::Sources::PostgresHll.save_aggregated_metrics` -method accepts the following arguments: - -- `metric_name`: The name of metric to use for aggregations. Should be the same - as the key under which the metric is added into Service Ping. -- `recorded_at_timestamp`: The timestamp representing the moment when a given - Service Ping payload was collected. You should use the convenience method `recorded_at` - to fill `recorded_at_timestamp` argument, like this: `recorded_at_timestamp: recorded_at` -- `time_period`: The time period used to build the `relation` argument passed into - `estimate_batch_distinct_count`. To collect the metric with all available historical - data, set a `nil` value as time period: `time_period: nil`. -- `data`: HyperLogLog buckets structure representing unique entries in `relation`. - The `estimate_batch_distinct_count` method always passes the correct argument - into the block, so `data` argument must always have a value equal to block argument, - like this: `data: result` - -Example metrics persistence: - -```ruby -class UsageData - def count_secure_pipelines(time_period) - ... - relation = ::Security::Scan.latest_successful_by_build.by_scan_types(scan_type).where(security_scans: time_period) - - pipelines_with_secure_jobs['dependency_scanning_pipeline'] = estimate_batch_distinct_count(relation, :commit_id, batch_size: 1000, start: start_id, finish: finish_id) do |result| - ::Gitlab::Usage::Metrics::Aggregates::Sources::PostgresHll - .save_aggregated_metrics(metric_name: 'dependency_scanning_pipeline', recorded_at_timestamp: recorded_at, time_period: time_period, data: result) - end - end -end -``` - -#### Add new aggregated metric definition - -After all metrics are persisted, you can add an aggregated metric definition at -[`aggregated_metrics/`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/aggregates/). - -To declare the aggregate of metrics collected with [Estimated Batch Counters](#estimated-batch-counters), -you must fulfill the following requirements: - -- Metrics names listed in the `events:` attribute, have to use the same names you passed in the `metric_name` argument while persisting metrics in previous step. -- Every metric listed in the `events:` attribute, has to be persisted for **every** selected `time_frame:` value. - -Example definition: - -```yaml -- name: example_metrics_intersection_database_sourced - operator: AND - source: database - events: - - 'dependency_scanning_pipeline' - - 'container_scanning_pipeline' - time_frame: - - 28d - - all -``` +See the [implement Service Ping](implement.md) guide. ## Example Service Ping payload @@ -1331,7 +494,7 @@ checking the configuration file of your GitLab instance: - Using the Admin Area: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Metrics and profiling**. 1. Expand **Usage Statistics**. 1. Are you able to check or uncheck the checkbox to disable Service Ping? @@ -1388,7 +551,7 @@ To work around this bug, you have two options: sudo gitlab-ctl reconfigure ``` - 1. In GitLab, on the top bar, select **Menu >** **{admin}** **Admin**. + 1. In GitLab, on the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Metrics and profiling**. 1. Expand **Usage Statistics**. 1. Clear the **Enable service ping** checkbox. diff --git a/doc/development/service_ping/metrics_dictionary.md b/doc/development/service_ping/metrics_dictionary.md index b3c5f078a4a..8dc2d2255d1 100644 --- a/doc/development/service_ping/metrics_dictionary.md +++ b/doc/development/service_ping/metrics_dictionary.md @@ -22,6 +22,9 @@ All metrics are stored in YAML files: - [`config/metrics`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/config/metrics) +WARNING: +Only metrics with a metric definition YAML are added to the Service Ping JSON payload. + Each metric is defined in a separate YAML file consisting of a number of fields: | Field | Required | Additional information | @@ -34,14 +37,14 @@ Each metric is defined in a separate YAML file consisting of a number of fields: | `product_group` | yes | The [group](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/stages.yml) that owns the metric. | | `product_category` | no | The [product category](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/categories.yml) for the metric. | | `value_type` | yes | `string`; one of [`string`, `number`, `boolean`, `object`](https://json-schema.org/understanding-json-schema/reference/type.html). | -| `status` | yes | `string`; [status](#metric-statuses) of the metric, may be set to `data_available`, `implemented`, `not_used`, `deprecated`, `removed`, `broken`. | +| `status` | yes | `string`; [status](#metric-statuses) of the metric, may be set to `active`, `deprecated`, `removed`, `broken`. | | `time_frame` | yes | `string`; may be set to a value like `7d`, `28d`, `all`, `none`. | | `data_source` | yes | `string`; may be set to a value like `database`, `redis`, `redis_hll`, `prometheus`, `system`. | | `data_category` | yes | `string`; [categories](#data-category) of the metric, may be set to `operational`, `optional`, `subscription`, `standard`. The default value is `optional`.| | `instrumentation_class` | no | `string`; [the class that implements the metric](metrics_instrumentation.md). | | `distribution` | yes | `array`; may be set to one of `ce, ee` or `ee`. The [distribution](https://about.gitlab.com/handbook/marketing/strategic-marketing/tiers/#definitions) where the tracked feature is available. | | `performance_indicator_type` | no | `array`; may be set to one of [`gmau`, `smau`, `paid_gmau`, or `umau`](https://about.gitlab.com/handbook/business-technology/data-team/data-catalog/xmau-analysis/). | -| `tier` | yes | `array`; may contain one or a combination of `free`, `premium` or `ultimate`. The [tier]( https://about.gitlab.com/handbook/marketing/strategic-marketing/tiers/) where the tracked feature is available. | +| `tier` | yes | `array`; may contain one or a combination of `free`, `premium` or `ultimate`. The [tier]( https://about.gitlab.com/handbook/marketing/strategic-marketing/tiers/) where the tracked feature is available. This should be verbose and contain all tiers where a metric is available. | | `milestone` | no | The milestone when the metric is introduced. | | `milestone_removed` | no | The milestone when the metric is removed. | | `introduced_by_url` | no | The URL to the Merge Request that introduced the metric. | @@ -53,11 +56,8 @@ Each metric is defined in a separate YAML file consisting of a number of fields: Metric definitions can have one of the following statuses: -- `data_available`: Metric data is available and used in a Sisense dashboard. -- `implemented`: Metric is implemented but data is not yet available. This is a temporary - status for newly added metrics awaiting inclusion in a new release. +- `active`: Metric is used and reports data. - `broken`: Metric reports broken data (for example, -1 fallback), or does not report data at all. A metric marked as `broken` must also have the `repair_issue_url` attribute. -- `not_used`: Metric is not used in any dashboard. - `deprecated`: Metric is deprecated and possibly planned to be removed. - `removed`: Metric was removed, but it may appear in Service Ping payloads sent from instances running on older versions of GitLab. @@ -177,7 +177,7 @@ product_section: growth product_stage: growth product_group: group::product intelligence value_type: string -status: data_available +status: active milestone: 9.1 introduced_by_url: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1521 time_frame: none @@ -217,11 +217,11 @@ create ee/config/metrics/counts_7d/issues.yml ## Metrics added dynamic to Service Ping payload -The [Redis HLL metrics](index.md#known-events-are-added-automatically-in-service-data-payload) are added automatically to Service Ping payload. +The [Redis HLL metrics](implement.md#known-events-are-added-automatically-in-service-data-payload) are added automatically to Service Ping payload. A YAML metric definition is required for each metric. A dedicated generator is provided to create metric definitions for Redis HLL events. -The generator takes `category` and `event` arguments, as the root key will be `redis_hll_counters`, and creates two metric definitions for weekly and monthly timeframes: +The generator takes `category` and `event` arguments, as the root key is `redis_hll_counters`, and creates two metric definitions for weekly and monthly time frames: ```shell bundle exec rails generate gitlab:usage_metric_definition:redis_hll issues i_closed diff --git a/doc/development/service_ping/metrics_instrumentation.md b/doc/development/service_ping/metrics_instrumentation.md index 8ad1ae9cce2..6fdbd1eea31 100644 --- a/doc/development/service_ping/metrics_instrumentation.md +++ b/doc/development/service_ping/metrics_instrumentation.md @@ -115,13 +115,13 @@ There is support for: - [Redis HLL metrics](#redis-hyperloglog-metrics). - [Generic metrics](#generic-metrics), which are metrics based on settings or configurations. -Currently, there is no support for: +There is no support for: - `add`, `sum`, `histogram` for database metrics. You can [track the progress to support these](https://gitlab.com/groups/gitlab-org/-/epics/6118). -## Creating a new metric instrumentation class +## Create a new metric instrumentation class To create a stub instrumentation for a Service Ping metric, you can use a dedicated [generator](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/generators/gitlab/usage_metric_generator.rb): diff --git a/doc/development/service_ping/metrics_lifecycle.md b/doc/development/service_ping/metrics_lifecycle.md index 68c5ddecc1f..c0446aece8b 100644 --- a/doc/development/service_ping/metrics_lifecycle.md +++ b/doc/development/service_ping/metrics_lifecycle.md @@ -10,7 +10,7 @@ The following guidelines explain the steps to follow at each stage of a metric's ## Add a new metric -Please follow the [Implementing Service Ping](index.md#implementing-service-ping) guide. +Follow the [Implement Service Ping](implement.md) guide. ## Change an existing metric @@ -39,7 +39,7 @@ For GitLab 12.6, the metric was changed to filter out archived projects: } ``` -In this scenario all instances running up to GitLab 12.5 continue to report `example_metric`, +In this scenario, all instances running up to GitLab 12.5 continue to report `example_metric`, including all archived projects, while all instances running GitLab 12.6 and higher filters out such projects. As Service Ping data is collected from all reporting instances, the resulting dataset includes mixed data, which distorts any following business analysis. diff --git a/doc/development/service_ping/review_guidelines.md b/doc/development/service_ping/review_guidelines.md index f961fd376bd..048b705636f 100644 --- a/doc/development/service_ping/review_guidelines.md +++ b/doc/development/service_ping/review_guidelines.md @@ -59,7 +59,7 @@ are regular backend changes. metrics that are based on Database. - For tracking using Redis HLL (HyperLogLog): - Check the Redis slot. - - Check if a [feature flag is needed](index.md#recommendations). + - Check if a [feature flag is needed](implement.md#recommendations). - For a metric's YAML definition: - Check the metric's `description`. - Check the metric's `key_path`. diff --git a/doc/development/sidekiq_style_guide.md b/doc/development/sidekiq_style_guide.md index c1733a974e4..04b7e2f5c45 100644 --- a/doc/development/sidekiq_style_guide.md +++ b/doc/development/sidekiq_style_guide.md @@ -713,7 +713,7 @@ default weight, which is 1. ## Worker context -> - [Introduced](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/9) in GitLab 12.8. +> [Introduced](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/9) in GitLab 12.8. To have some more information about workers in the logs, we add [metadata to the jobs in the form of an @@ -1002,9 +1002,7 @@ When renaming queues, use the `sidekiq_queue_migrate` helper migration method in a **post-deployment migration**: ```ruby -class MigrateTheRenamedSidekiqQueue < ActiveRecord::Migration[5.0] - include Gitlab::Database::MigrationHelpers - +class MigrateTheRenamedSidekiqQueue < Gitlab::Database::Migration[1.0] def up sidekiq_queue_migrate 'old_queue_name', to: 'new_queue_name' end diff --git a/doc/development/single_table_inheritance.md b/doc/development/single_table_inheritance.md index aa4fe540b0d..eb406b02a91 100644 --- a/doc/development/single_table_inheritance.md +++ b/doc/development/single_table_inheritance.md @@ -31,7 +31,7 @@ could result in loading unexpected code or associations which may cause unintend side effects or failures during upgrades. ```ruby -class SomeMigration < ActiveRecord::Migration[6.0] +class SomeMigration < Gitlab::Database::Migration[1.0] class Services < ActiveRecord::Base self.table_name = 'services' self.inheritance_column = :_type_disabled @@ -47,7 +47,7 @@ This ensures that the migration loads the columns for the migration in isolation and the helper disables STI by default. ```ruby -class EnqueueSomeBackgroundMigration < ActiveRecord::Migration[6.0] +class EnqueueSomeBackgroundMigration < Gitlab::Database::Migration[1.0] disable_ddl_transaction! def up diff --git a/doc/development/snowplow/index.md b/doc/development/snowplow/index.md index 527b4292b23..e8b7d871b77 100644 --- a/doc/development/snowplow/index.md +++ b/doc/development/snowplow/index.md @@ -53,7 +53,7 @@ Snowplow tracking is enabled on GitLab.com, and we use it for most of our tracki To enable Snowplow tracking on a self-managed instance: -1. On the top bar, select **Menu >** **{admin}** **Admin**, then select **Settings > General**. +1. On the top bar, select **Menu > Admin**, then select **Settings > General**. Alternatively, go to `admin/application_settings/general` in your browser. 1. Expand **Snowplow**. @@ -101,7 +101,7 @@ sequenceDiagram ## Structured event taxonomy -When adding new click events, we should add them in a way that's internally consistent. If we don't, it is very painful to perform analysis across features since each feature captures events differently. +When adding new click events, we should add them in a way that's internally consistent. If we don't, it is difficult to perform analysis across features because each feature captures events differently. The current method provides several attributes that are sent on each click event. Please try to follow these guidelines when specifying events to capture: @@ -109,9 +109,9 @@ The current method provides several attributes that are sent on each click event | --------- | ------- | -------- | ----------- | | category | text | true | The page or backend area of the application. Unless infeasible, please use the Rails page attribute by default in the frontend, and namespace + class name on the backend. | | action | text | true | The action the user is taking, or aspect that's being instrumented. The first word should always describe the action or aspect: clicks should be `click`, activations should be `activate`, creations should be `create`, etc. Use underscores to describe what was acted on; for example, activating a form field would be `activate_form_input`. An interface action like clicking on a dropdown would be `click_dropdown`, while a behavior like creating a project record from the backend would be `create_project` | -| label | text | false | The specific element, or object that's being acted on. This is either the label of the element (e.g. a tab labeled 'Create from template' may be `create_from_template`) or a unique identifier if no text is available (e.g. closing the Groups dropdown in the top navigation bar might be `groups_dropdown_close`), or it could be the name or title attribute of a record being created. | +| label | text | false | The specific element or object to act on. This can be one of the following: the label of the element (for example, a tab labeled 'Create from template' for `create_from_template`), a unique identifier if no text is available (for example, `groups_dropdown_close` for closing the Groups dropdown in the top bar), or the name or title attribute of a record being created. | | property | text | false | Any additional property of the element, or object being acted on. | -| value | decimal | false | Describes a numeric value or something directly related to the event. This could be the value of an input (e.g. `10` when clicking `internal` visibility). | +| value | decimal | false | Describes a numeric value or something directly related to the event. This could be the value of an input. For example, `10` when clicking `internal` visibility. | ### Examples @@ -156,7 +156,7 @@ LIMIT 20 Snowplow JS adds many [web-specific parameters](https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/snowplow-tracker-protocol/#Web-specific_parameters) to all web events by default. -## Implementing Snowplow JS (Frontend) tracking +## Implement Snowplow JS (Frontend) tracking GitLab provides `Tracking`, an interface that wraps the [Snowplow JavaScript Tracker](https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/javascript-trackers/) for tracking custom events. The simplest way to use it is to add `data-` attributes to clickable elements and dropdowns. There is also a Vue mixin (exposing a `track` method), and the static method `Tracking.event`. Each of these requires at minimum a `category` and an `action`. You can provide additional [Structured event taxonomy](#structured-event-taxonomy) properties along with an `extra` object that accepts key-value pairs. @@ -174,7 +174,7 @@ GitLab provides `Tracking`, an interface that wraps the [Snowplow JavaScript Tra ### Tracking with data attributes -When working within HAML (or Vue templates) we can add `data-track-*` attributes to elements of interest. All elements that have a `data-track-action` attribute automatically have event tracking bound on clicks. You can provide extra data as a valid JSON string using `data-track-extra`. +When working in HAML (or Vue templates) we can add `data-track-*` attributes to elements of interest. All elements that have a `data-track-action` attribute automatically have event tracking bound on clicks. You can provide extra data as a valid JSON string using `data-track-extra`. Below is an example of `data-track-*` attributes assigned to a button: @@ -191,7 +191,7 @@ Below is an example of `data-track-*` attributes assigned to a button: /> ``` -Event listeners are bound at the document level to handle click events on or within elements with these data attributes. This allows them to be properly handled on re-rendering and changes to the DOM. Note that because of the way these events are bound, click events should not be stopped from propagating up the DOM tree. If for any reason click events are being stopped from propagating, you need to implement your own listeners and follow the instructions in [Tracking within Vue components](#tracking-within-vue-components) or [Tracking in raw JavaScript](#tracking-in-raw-javascript). +Event listeners are bound at the document level to handle click events on or within elements with these data attributes. This allows them to be properly handled on re-rendering and changes to the DOM. Note that because of the way these events are bound, click events should not be stopped from propagating up the DOM tree. If click events are being stopped from propagating, you must implement your own listeners and follow the instructions in [Tracking within Vue components](#tracking-within-vue-components) or [Tracking in raw JavaScript](#tracking-in-raw-javascript). Below is a list of supported `data-track-*` attributes: @@ -237,7 +237,7 @@ import Tracking from '~/tracking'; const trackingMixin = Tracking.mixin({ label: 'right_sidebar' }); ``` -You can provide default options that are passed along whenever an event is tracked from within your component. For instance, if all events within a component should be tracked with a given `label`, you can provide one at this time. Available defaults are `category`, `label`, `property`, and `value`. If no category is specified, `document.body.dataset.page` is used as the default. +You can provide default options that are passed along whenever an event is tracked from within your component. For example, if all events in a component should be tracked with a given `label`, you can provide one at this time. Available defaults are `category`, `label`, `property`, and `value`. If no category is specified, `document.body.dataset.page` is used as the default. You can then use the mixin normally in your component with the `mixin` Vue declaration. The mixin also provides the ability to specify tracking options in `data` or `computed`. These override any defaults and allow the values to be dynamic from props, or based on state. @@ -256,7 +256,7 @@ export default { }; ``` -The mixin provides a `track` method that can be called within the template, +The mixin provides a `track` method that can be called from within the template, or from component methods. An example of the whole implementation might look like this: ```javascript @@ -302,7 +302,7 @@ export default { ``` The event data can be provided directly in the `track` function as well. -This object will merge with any previously provided options. +This object merges with any previously provided options. ```javascript this.track('click_button', { @@ -404,7 +404,7 @@ describe('MyTracking', () => { ### Form tracking -You can enable Snowplow automatic [form tracking](https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/javascript-trackers/javascript-tracker/javascript-tracker-v2/tracking-specific-events/#form-tracking) by calling `Tracking.enableFormTracking` (after the DOM is ready) and providing a `config` object that includes at least one of the following elements: +Enable Snowplow automatic [form tracking](https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/javascript-trackers/javascript-tracker/javascript-tracker-v2/tracking-specific-events/#form-tracking) by calling `Tracking.enableFormTracking` (after the DOM is ready) and providing a `config` object that includes at least one of the following elements: - `forms`: determines which forms are tracked, and are identified by the CSS class name. - `fields`: determines which fields inside the tracked forms are tracked, and are identified by the field `name`. @@ -442,7 +442,7 @@ describe('MyFormTracking', () => { }); ``` -## Implementing Snowplow Ruby (Backend) tracking +## Implement Snowplow Ruby (Backend) tracking GitLab provides `Gitlab::Tracking`, an interface that wraps the [Snowplow Ruby Tracker](https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/ruby-tracker/) for tracking custom events. @@ -483,11 +483,11 @@ https://docs.gitlab.com/ee/development/testing_guide/best_practices.html#test-sn ### Performance -We use the [AsyncEmitter](https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/ruby-tracker//emitters/#the-asyncemitter-class) when tracking events, which allows for instrumentation calls to be run in a background thread. This is still an active area of development. +We use the [AsyncEmitter](https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/ruby-tracker/emitters/#the-asyncemitter-class) when tracking events, which allows for instrumentation calls to be run in a background thread. This is still an active area of development. -## Developing and testing Snowplow +## Develop and test Snowplow -There are several tools for developing and testing Snowplow Event +There are several tools for developing and testing a Snowplow event. | Testing Tool | Frontend Tracking | Backend Tracking | Local Development Environment | Production Environment | Production Environment | |----------------------------------------------|--------------------|---------------------|-------------------------------|------------------------|------------------------| @@ -510,7 +510,7 @@ To test frontend events in development: #### Snowplow Analytics Debugger Chrome Extension -Snowplow Analytics Debugger is a browser extension for testing frontend events. This works on production, staging and local development environments. +Snowplow Analytics Debugger is a browser extension for testing frontend events. This works on production, staging, and local development environments. 1. Install the [Snowplow Analytics Debugger](https://chrome.google.com/webstore/detail/snowplow-analytics-debugg/jbnlcgeengmijcghameodeaenefieedm) Chrome browser extension. 1. Open Chrome DevTools to the Snowplow Analytics Debugger tab. @@ -528,7 +528,7 @@ Snowplow Inspector Chrome Extension is a browser extension for testing frontend Snowplow Micro is a very small version of a full Snowplow data collection pipeline: small enough that it can be launched by a test suite. Events can be recorded into Snowplow Micro just as they can a full Snowplow pipeline. Micro then exposes an API that can be queried. -Snowplow Micro is a Docker-based solution for testing frontend and backend events in a local development environment. You need to modify GDK using the instructions below to set this up. +Snowplow Micro is a Docker-based solution for testing frontend and backend events in a local development environment. You must modify GDK using the instructions below to set this up. - Read [Introducing Snowplow Micro](https://snowplowanalytics.com/blog/2019/07/17/introducing-snowplow-micro/) - Look at the [Snowplow Micro repository](https://github.com/snowplow-incubator/snowplow-micro) @@ -544,10 +544,15 @@ Snowplow Micro is a Docker-based solution for testing frontend and backend event ./snowplow-micro.sh ``` -1. Update your instance's settings to enable Snowplow events and point to the Snowplow Micro collector: +1. Use GDK to start the PostgreSQL terminal and connect to the `gitlabhq_development` database: ```shell gdk psql -d gitlabhq_development + ``` + +1. Update your instance's settings to enable Snowplow events and point to the Snowplow Micro collector: + + ```shell update application_settings set snowplow_collector_hostname='localhost:9090', snowplow_enabled=true, snowplow_cookie_domain='.gitlab.com'; ``` @@ -568,14 +573,14 @@ Snowplow Micro is a Docker-based solution for testing frontend and backend event formTracking: false, ``` -1. Update `snowplow_options` in `lib/gitlab/tracking.rb` to add `protocol` and `port`: +1. Update `options` in `lib/gitlab/tracking.rb` to add `protocol` and `port`: ```diff diff --git a/lib/gitlab/tracking.rb b/lib/gitlab/tracking.rb index 618e359211b..e9084623c43 100644 --- a/lib/gitlab/tracking.rb +++ b/lib/gitlab/tracking.rb - @@ -41,7 +41,9 @@ def snowplow_options(group) + @@ -41,7 +41,9 @@ def options(group) cookie_domain: Gitlab::CurrentSettings.snowplow_cookie_domain, app_id: Gitlab::CurrentSettings.snowplow_app_id, form_tracking: additional_features, @@ -609,7 +614,7 @@ Snowplow Micro is a Docker-based solution for testing frontend and backend event 1. Restart GDK: ```shell - `gdk restart` + gdk restart ``` 1. Send a test Snowplow event from the Rails console: diff --git a/doc/development/snowplow/review_guidelines.md b/doc/development/snowplow/review_guidelines.md index 285fbc3b44b..8edcbf06a0e 100644 --- a/doc/development/snowplow/review_guidelines.md +++ b/doc/development/snowplow/review_guidelines.md @@ -26,7 +26,7 @@ events or touches Snowplow related files. #### The merge request **author** should - For frontend events, when relevant, add a screenshot of the event in - the [testing tool](../snowplow/index.md#developing-and-testing-snowplow) used. + the [testing tool](../snowplow/index.md#develop-and-test-snowplow) used. - For backend events, when relevant, add the output of the [Snowplow Micro](index.md#snowplow-mini) good events `GET http://localhost:9090/micro/good` (it might be a good idea @@ -39,5 +39,5 @@ events or touches Snowplow related files. - Check the [usage recommendations](../snowplow/index.md#usage-recommendations). - Check that the [Event Dictionary](event_dictionary_guide.md) is up-to-date. - If needed, check that the events are firing locally using one of the -[testing tools](../snowplow/index.md#developing-and-testing-snowplow) available. +[testing tools](../snowplow/index.md#develop-and-test-snowplow) available. - Approve the MR, and relabel the MR with `~"product intelligence::approved"`. diff --git a/doc/development/sql.md b/doc/development/sql.md index 40ee19c0b9e..3483305c113 100644 --- a/doc/development/sql.md +++ b/doc/development/sql.md @@ -102,7 +102,7 @@ transaction. Transactions for migrations can be disabled using the following pattern: ```ruby -class MigrationName < ActiveRecord::Migration[4.2] +class MigrationName < Gitlab::Database::Migration[1.0] disable_ddl_transaction! end ``` @@ -110,7 +110,7 @@ end For example: ```ruby -class AddUsersLowerUsernameEmailIndexes < ActiveRecord::Migration[4.2] +class AddUsersLowerUsernameEmailIndexes < Gitlab::Database::Migration[1.0] disable_ddl_transaction! def up diff --git a/doc/development/stage_group_dashboards.md b/doc/development/stage_group_dashboards.md index 61a98ece892..7c518e9b6ca 100644 --- a/doc/development/stage_group_dashboards.md +++ b/doc/development/stage_group_dashboards.md @@ -56,7 +56,7 @@ component can have 2 indicators: [Git](https://gitlab.com/gitlab-com/runbooks/-/blob/f22f40b2c2eab37d85e23ccac45e658b2c914445/metrics-catalog/services/git.jsonnet#L216), and [Web](https://gitlab.com/gitlab-com/runbooks/-/blob/f22f40b2c2eab37d85e23ccac45e658b2c914445/metrics-catalog/services/web.jsonnet#L154) - services, that threshold is **1 second**. + services, that threshold is **5 seconds**. For Sidekiq job execution, the threshold depends on the [job urgency](sidekiq_style_guide.md#job-urgency). It is diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md index ba7312b760f..79664490368 100644 --- a/doc/development/testing_guide/best_practices.md +++ b/doc/development/testing_guide/best_practices.md @@ -54,7 +54,7 @@ When using spring and guard together, use `SPRING=1 bundle exec guard` instead t > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47767) in GitLab 13.7. -We've enabled [deprecation warnings](https://ruby-doc.org/core-2.7.2/Warning.html) +We've enabled [deprecation warnings](https://ruby-doc.org/core-2.7.4/Warning.html) by default when running specs. Making these warnings more visible to developers helps upgrading to newer Ruby versions. @@ -367,26 +367,34 @@ If needed, you can scope interactions within a specific area of the page by usin As you will likely be scoping to an element such as a `div`, which typically does not have a label, you may use a `data-testid` selector in this case. +##### Externalized contents + +Test expectations against externalized contents should call the same +externalizing method to match the translation. For example, you should use the `_` +method in Ruby and `__` method in JavaScript. + +See [Internationalization for GitLab - Test files](../i18n/externalization.md#test-files) for details. + ##### Actions Where possible, use more specific [actions](https://rubydoc.info/github/teamcapybara/capybara/master/Capybara/Node/Actions), such as the ones below. ```ruby # good -click_button 'Submit review' +click_button _('Submit review') -click_link 'UI testing docs' +click_link _('UI testing docs') -fill_in 'Search projects', with: 'gitlab' # fill in text input with text +fill_in _('Search projects'), with: 'gitlab' # fill in text input with text -select 'Last updated', from: 'Sort by' # select an option from a select input +select _('Last updated'), from: 'Sort by' # select an option from a select input -check 'Checkbox label' -uncheck 'Checkbox label' +check _('Checkbox label') +uncheck _('Checkbox label') -choose 'Radio input label' +choose _('Radio input label') -attach_file('Attach a file', '/path/to/file.png') +attach_file(_('Attach a file'), '/path/to/file.png') # bad - interactive elements must have accessible names, so # we should be able to use one of the specific actions above @@ -403,17 +411,17 @@ Where possible, use more specific [finders](https://rubydoc.info/github/teamcapy ```ruby # good -find_button 'Submit review' -find_button 'Submit review', disabled: true +find_button _('Submit review') +find_button _('Submit review'), disabled: true -find_link 'UI testing docs' -find_link 'UI testing docs', href: docs_url +find_link _('UI testing docs') +find_link _('UI testing docs'), href: docs_url -find_field 'Search projects' -find_field 'Search projects', with: 'gitlab' # find the input field with text -find_field 'Search projects', disabled: true -find_field 'Checkbox label', checked: true -find_field 'Checkbox label', unchecked: true +find_field _('Search projects') +find_field _('Search projects'), with: 'gitlab' # find the input field with text +find_field _('Search projects'), disabled: true +find_field _('Checkbox label'), checked: true +find_field _('Checkbox label'), unchecked: true # acceptable when finding a element that is not a button, link, or field find('[data-testid="element"]') @@ -425,31 +433,31 @@ Where possible, use more specific [matchers](https://rubydoc.info/github/teamcap ```ruby # good -expect(page).to have_button 'Submit review' -expect(page).to have_button 'Submit review', disabled: true -expect(page).to have_button 'Notifications', class: 'is-checked' # assert the "Notifications" GlToggle is checked +expect(page).to have_button _('Submit review') +expect(page).to have_button _('Submit review'), disabled: true +expect(page).to have_button _('Notifications'), class: 'is-checked' # assert the "Notifications" GlToggle is checked -expect(page).to have_link 'UI testing docs' -expect(page).to have_link 'UI testing docs', href: docs_url # assert the link has an href +expect(page).to have_link _('UI testing docs') +expect(page).to have_link _('UI testing docs'), href: docs_url # assert the link has an href -expect(page).to have_field 'Search projects' -expect(page).to have_field 'Search projects', disabled: true -expect(page).to have_field 'Search projects', with: 'gitlab' # assert the input field has text +expect(page).to have_field _('Search projects') +expect(page).to have_field _('Search projects'), disabled: true +expect(page).to have_field _('Search projects'), with: 'gitlab' # assert the input field has text -expect(page).to have_checked_field 'Checkbox label' -expect(page).to have_unchecked_field 'Radio input label' +expect(page).to have_checked_field _('Checkbox label') +expect(page).to have_unchecked_field _('Radio input label') -expect(page).to have_select 'Sort by' -expect(page).to have_select 'Sort by', selected: 'Last updated' # assert the option is selected -expect(page).to have_select 'Sort by', options: ['Last updated', 'Created date', 'Due date'] # assert an exact list of options -expect(page).to have_select 'Sort by', with_options: ['Created date', 'Due date'] # assert a partial list of options +expect(page).to have_select _('Sort by') +expect(page).to have_select _('Sort by'), selected: 'Last updated' # assert the option is selected +expect(page).to have_select _('Sort by'), options: ['Last updated', 'Created date', 'Due date'] # assert an exact list of options +expect(page).to have_select _('Sort by'), with_options: ['Created date', 'Due date'] # assert a partial list of options -expect(page).to have_text 'Some paragraph text.' -expect(page).to have_text 'Some paragraph text.', exact: true # assert exact match +expect(page).to have_text _('Some paragraph text.') +expect(page).to have_text _('Some paragraph text.'), exact: true # assert exact match expect(page).to have_current_path 'gitlab/gitlab-test/-/issues' -expect(page).to have_title 'Not Found' +expect(page).to have_title _('Not Found') # acceptable when a more specific matcher above is not possible expect(page).to have_css 'h2', text: 'Issue title' @@ -653,6 +661,12 @@ let_it_be_with_refind(:project) { create(:project) } let_it_be(:project, refind: true) { create(:project) } ``` +Note that `let_it_be` cannot be used with factories that has stubs, such as `allow`. +The reason is that `let_it_be` happens in a `before(:all)` block, and RSpec does not +allow stubs in `before(:all)`. +See this [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/340487) for more details. +To resolve, use `let`, or change the factory to not use stubs. + ### Time-sensitive tests [`ActiveSupport::Testing::TimeHelpers`](https://api.rubyonrails.org/v6.0.3.1/classes/ActiveSupport/Testing/TimeHelpers.html) @@ -1197,6 +1211,8 @@ GitLab uses [factory_bot](https://github.com/thoughtbot/factory_bot) as a test f - Factories don't have to be limited to `ActiveRecord` objects. [See example](https://gitlab.com/gitlab-org/gitlab-foss/commit/0b8cefd3b2385a21cfed779bd659978c0402766d). - Factories and their traits should produce valid objects that are [verified by specs](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/factories_spec.rb). +- Avoid the use of [`skip_callback`](https://api.rubyonrails.org/classes/ActiveSupport/Callbacks/ClassMethods.html#method-i-skip_callback) in factories. + See [issue #247865](https://gitlab.com/gitlab-org/gitlab/-/issues/247865) for details. ### Fixtures diff --git a/doc/development/testing_guide/end_to_end/beginners_guide.md b/doc/development/testing_guide/end_to_end/beginners_guide.md index e0f0e9e7089..7370cc5771b 100644 --- a/doc/development/testing_guide/end_to_end/beginners_guide.md +++ b/doc/development/testing_guide/end_to_end/beginners_guide.md @@ -349,8 +349,8 @@ GITLAB_PASSWORD=<GDK root password> bundle exec bin/qa Test::Instance::All http: Where `<test_file>` is: -- `qa/specs/features/browser_ui/1_manage/login/login_spec.rb` when running the Login example. -- `qa/specs/features/browser_ui/2_plan/issues/issue_spec.rb` when running the Issue example. +- `qa/specs/features/browser_ui/1_manage/login/log_in_spec.rb` when running the Login example. +- `qa/specs/features/browser_ui/2_plan/issues/create_issue_spec.rb` when running the Issue example. ## End-to-end test merge request template diff --git a/doc/development/testing_guide/end_to_end/best_practices.md b/doc/development/testing_guide/end_to_end/best_practices.md index 74c02d19d0a..a3caa8bf2b3 100644 --- a/doc/development/testing_guide/end_to_end/best_practices.md +++ b/doc/development/testing_guide/end_to_end/best_practices.md @@ -8,27 +8,33 @@ info: To determine the technical writer assigned to the Stage/Group associated w This is a tailored extension of the Best Practices [found in the testing guide](../best_practices.md). -## Link a test to its test-case issue +## Class and module naming -Every test should have a corresponding issue in the [Quality Test Cases project](https://gitlab.com/gitlab-org/quality/testcases/). -It's recommended that you reuse the issue created to plan the test. If one does not already exist you -can create the issue yourself. Alternatively, you can run the test in a pipeline that has reporting -enabled and the test-case issue reporter will automatically create a new issue. +The QA framework uses [Zeitwerk](https://github.com/fxn/zeitwerk) for class and module autoloading. The default Zeitwerk [inflector](https://github.com/fxn/zeitwerk#zeitwerkinflector) simply converts snake_cased file names to PascalCased module or class names. It is advised to stick to this pattern to avoid manual maintenance of inflections. -Whether you create a new test-case issue or one is created automatically, you will need to manually add -a `testcase` RSpec metadata tag. In most cases, a single test will be associated with a single test-case -issue ([see below for exceptions](#exceptions)). +In case custom inflection logic is needed, custom inflectors are added in the [qa.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/qa/qa.rb) file in the `loader.inflector.inflect` method invocation. + +## Link a test to its test case + +Every test should have a corresponding test case as well as a results issue in the [Quality Test Cases project](https://gitlab.com/gitlab-org/quality/testcases/). +It's recommended that you reuse the issue created to plan the test as the results issue. If a test case or results issue does not already exist you +can create them yourself. Alternatively, you can run the test in a pipeline that has reporting +enabled and the test-case reporter will automatically create a new test case and/or results issue and link the results issue to it's corresponding test case. + +Whether you create a new test case or one is created automatically, you will need to manually add +a `testcase` RSpec metadata tag. In most cases, a single test will be associated with a single test case + ([see below for exceptions](#exceptions)). For example: ```ruby RSpec.describe 'Stage' do describe 'General description of the feature under test' do - it 'test name', testcase: 'https://gitlab.com/gitlab-org/quality/testcases/-/issues/:issue_id' do + it 'test name', testcase: 'https://gitlab.com/gitlab-org/quality/testcases/-/quality/test_cases/:test_case_id' do ... end - it 'another test', testcase: 'https://gitlab.com/gitlab-org/quality/testcases/-/issues/:another_issue_id' do + it 'another test', testcase: 'https://gitlab.com/gitlab-org/quality/testcases/-/quality/test_cases/:another_test_case_id' do ... end end @@ -38,10 +44,10 @@ end ### Exceptions Most tests are defined by a single line of a `spec` file, which is why those tests can be linked to a -single test-case issue via the `testcase` tag. +single test case via the `testcase` tag. -However, some tests don't have a one-to-one relationship between a line of a `spec` file and a test-case -issue. This is because some tests are defined in a way that means a single line is associated with +However, some tests don't have a one-to-one relationship between a line of a `spec` file and a test case. +This is because some tests are defined in a way that means a single line is associated with multiple tests, including: - Parallelized tests. @@ -49,13 +55,13 @@ multiple tests, including: - Tests in shared examples that include more than one example. In those and similar cases we can't assign a single `testcase` tag and so we rely on the test-case -reporter to programmatically determine the correct test-case issue based on the name and description of -the test. In such cases, the test-case reporter will automatically create a test-case issue the first time -the test runs, if no issue exists already. +reporter to programmatically determine the correct test case based on the name and description of +the test. In such cases, the test-case reporter will automatically create a test case and/or results issue +the first time the test runs, if none exist already. -In such a case, if you create the issue yourself or want to reuse an existing issue, +In such a case, if you create the test case or results issue yourself or want to reuse an existing issue, you must use this [end-to-end test issue template](https://gitlab.com/gitlab-org/quality/testcases/-/blob/master/.gitlab/issue_templates/End-to-end%20Test.md) -to format the issue description. +to format the issue description. (Note you must copy/paste this for test cases as templates aren't currently available.) To illustrate, there are two tests in the shared examples in [`qa/specs/features/ee/browser_ui/3_create/repository/restrict_push_protected_branch_spec.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/47b17db82c38ab704a23b5ba5d296ea0c6a732c8/qa/qa/specs/features/ee/browser_ui/3_create/repository/restrict_push_protected_branch_spec.rb): @@ -84,9 +90,9 @@ RSpec.describe 'Create' do end ``` -There would be two associated test-case issues, one for each shared example, with the following content: +There would be two associated test cases, one for each shared example, with the following content: -[Test 1](https://gitlab.com/gitlab-org/quality/testcases/-/issues/600): +[Test 1 Test Case](https://gitlab.com/gitlab-org/quality/testcases/-/quality/test_cases/1491): ````markdown ```markdown @@ -105,10 +111,66 @@ pushes and merges ./qa/specs/features/ee/browser_ui/3_create/repository/restrict_push_protected_branch_spec.rb +### DO NOT EDIT BELOW THIS LINE + +Active and historical test results: + +https://gitlab.com/gitlab-org/quality/testcases/-/issues/600 + +``` +```` + +[Test 1 Results Issue](https://gitlab.com/gitlab-org/quality/testcases/-/issues/600): + +````markdown +```markdown +Title: browser_ui/3_create/repository/restrict_push_protected_branch_spec.rb | Create Restricted +protected branch push and merge when only one user is allowed to merge and push to a protected +branch behaves like only user with access pushes and merges selecte... + +Description: +### Full description + +Create Restricted protected branch push and merge when only one user is allowed to merge and push +to a protected branch behaves like only user with access pushes and merges selected developer user +pushes and merges + +### File path + +./qa/specs/features/ee/browser_ui/3_create/repository/restrict_push_protected_branch_spec.rb + +``` +```` + +[Test 2 Test Case](https://gitlab.com/gitlab-org/quality/testcases/-/quality/test_cases/602): + +````markdown +```markdown +Title: browser_ui/3_create/repository/restrict_push_protected_branch_spec.rb | Create Restricted +protected branch push and merge when only one user is allowed to merge and push to a protected +branch behaves like only user with access pushes and merges unselec... + +Description: +### Full description + +Create Restricted protected branch push and merge when only one user is allowed to merge and push +to a protected branch behaves like only user with access pushes and merges unselected maintainer +user fails to push + +### File path + +./qa/specs/features/ee/browser_ui/3_create/repository/restrict_push_protected_branch_spec.rb + +### DO NOT EDIT BELOW THIS LINE + +Active and historical test results: + +https://gitlab.com/gitlab-org/quality/testcases/-/issues/602 + ``` ```` -[Test 2](https://gitlab.com/gitlab-org/quality/testcases/-/issues/602): +[Test 2 Results Issue](https://gitlab.com/gitlab-org/quality/testcases/-/issues/602): ````markdown ```markdown @@ -342,7 +404,7 @@ end When something requires waiting to be matched, use `eventually_` matchers with clear wait duration definition. -`Eventually` matchers use the following naming pattern: `eventually_${rspec_matcher_name}`. They are defined in [eventually_matcher.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/qa/spec/support/matchers/eventually_matcher.rb). +`Eventually` matchers use the following naming pattern: `eventually_${rspec_matcher_name}`. They are defined in [eventually_matcher.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/qa/qa/support/matchers/eventually_matcher.rb). ```ruby expect { async_value }.to eventually_eq(value).within(max_duration: 120, max_attempts: 60, reload_page: page) diff --git a/doc/development/testing_guide/end_to_end/index.md b/doc/development/testing_guide/end_to_end/index.md index f4b01c64385..36c0f5adf00 100644 --- a/doc/development/testing_guide/end_to_end/index.md +++ b/doc/development/testing_guide/end_to_end/index.md @@ -170,6 +170,45 @@ Helm chart](https://gitlab.com/gitlab-org/charts/gitlab/), itself deployed with See [Review Apps](../review_apps.md) for more details about Review Apps. +## Test reports + +### Allure report + +For additional test results visibility, tests that run on pipelines generate +and host [Allure](https://github.com/allure-framework/allure2) test reports. + +The `QA` framework is using the [Allure RSpec](https://github.com/allure-framework/allure-ruby/blob/master/allure-rspec/README.md) +gem to generate source files for the `Allure` test report. An additional job +in the pipeline: + +- Fetches these source files from all test jobs. +- Generates and uploads the report to the `GCS` bucket `gitlab-qa-allure-report` under the project `gitlab-qa-resources`. + +A common CI template for report uploading is stored in +[`allure-report.yml`](https://gitlab.com/gitlab-org/quality/pipeline-common/-/blob/master/ci/allure-report.yml). + +#### Merge requests + +When these tests are executed in the scope of merge requests, the `Allure` report is +uploaded to the `GCS` bucket and comment is added linking to their respective reports. + +#### Scheduled pipelines + +Scheduled pipelines for these tests contain a `generate-allure-report` job under the `Report` stage. They also output +a link to the current test report. + +#### Static report links + +Each type of scheduled pipeline generates a static link for the latest test report according to its stage: + +- [`master`](https://storage.googleapis.com/gitlab-qa-allure-reports/package-and-qa/master/index.html) +- [`staging-full`](https://storage.googleapis.com/gitlab-qa-allure-reports/staging-full/master/index.html) +- [`staging-sanity`](https://storage.googleapis.com/gitlab-qa-allure-reports/staging-sanity/master/index.html) +- [`staging-sanity-no-admin`](https://storage.googleapis.com/gitlab-qa-allure-reports/staging-sanity-no-admin/master/index.html) +- [`canary-sanity`](https://storage.googleapis.com/gitlab-qa-allure-reports/canary-sanity/master/index.html) +- [`production`](https://storage.googleapis.com/gitlab-qa-allure-reports/production/master/index.html) +- [`production-sanity`](https://storage.googleapis.com/gitlab-qa-allure-reports/production-sanity/master/index.html) + ## How do I run the tests? If you are not [testing code in a merge request](#testing-code-in-merge-requests), diff --git a/doc/development/testing_guide/end_to_end/rspec_metadata_tests.md b/doc/development/testing_guide/end_to_end/rspec_metadata_tests.md index 3a016c0e95c..b6e92367f89 100644 --- a/doc/development/testing_guide/end_to_end/rspec_metadata_tests.md +++ b/doc/development/testing_guide/end_to_end/rspec_metadata_tests.md @@ -44,3 +44,4 @@ This is a partial list of the [RSpec metadata](https://relishapp.com/rspec/rspec | `:smtp` | The test requires a GitLab instance to be configured to use an SMTP server. Tests SMTP notification email delivery from GitLab by using MailHog. | | `:testcase` | The link to the test case issue in the [Quality Test Cases project](https://gitlab.com/gitlab-org/quality/testcases/). | | `:transient` | The test tests transient bugs. It is excluded by default. | +| `:issue`, `:issue_${num}` | Optional links to issues which might be related to the spec. Helps keeping track of related issues and can also be used by tools that create test reports. Currently added automatically to `Allure` test report. Multiple tags can be used by adding optional number postfix like `issue_1`, `issue_2` etc. | diff --git a/doc/development/testing_guide/frontend_testing.md b/doc/development/testing_guide/frontend_testing.md index 3af806d8f57..76687db3a3f 100644 --- a/doc/development/testing_guide/frontend_testing.md +++ b/doc/development/testing_guide/frontend_testing.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Frontend testing standards and style guidelines There are two types of test suites encountered while developing frontend code -at GitLab. We use Karma with Jasmine and Jest for JavaScript unit and integration testing, +at GitLab. We use Jest for JavaScript unit and integration testing, and RSpec feature tests with Capybara for e2e (end-to-end) integration testing. Unit and feature tests need to be written for all new features. @@ -28,46 +28,9 @@ If you are looking for a guide on Vue component testing, you can jump right away We use Jest to write frontend unit and integration tests. Jest tests can be found in `/spec/frontend` and `/ee/spec/frontend` in EE. -## Karma test suite - -While GitLab has switched over to [Jest](https://jestjs.io), Karma tests still exist in our -application because some of our specs require a browser and can't be easily migrated to Jest. -Those specs intend to eventually drop Karma in favor of either Jest or RSpec. You can track this migration -in the [related epic](https://gitlab.com/groups/gitlab-org/-/epics/4900). - -[Karma](http://karma-runner.github.io/) is a test runner which uses -[Jasmine](https://jasmine.github.io/) as its test framework. Jest also uses Jasmine as foundation, -that's why it's looking quite similar. - -Karma tests live in `spec/javascripts/` and `/ee/spec/javascripts` in EE. - -`app/assets/javascripts/behaviors/autosize.js` -might have a corresponding `spec/javascripts/behaviors/autosize_spec.js` file. - -Keep in mind that in a CI environment, these tests are run in a headless -browser and you don't have access to certain APIs, such as -[`Notification`](https://developer.mozilla.org/en-US/docs/Web/API/notification), -which have to be stubbed. - -### Differences to Karma - -- Jest runs in a Node.js environment, not in a browser. [An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/26982) for running Jest tests in a browser. -- Because Jest runs in a Node.js environment, it uses [jsdom](https://github.com/jsdom/jsdom) by default. See also its [limitations](#limitations-of-jsdom) below. -- Jest does not have access to Webpack loaders or aliases. - The aliases used by Jest are defined in its [own configuration](https://gitlab.com/gitlab-org/gitlab/-/blob/master/jest.config.js). -- All calls to `setTimeout` and `setInterval` are mocked away. See also [Jest Timer Mocks](https://jestjs.io/docs/timer-mocks). -- `rewire` is not required because Jest supports mocking modules. See also [Manual Mocks](https://jestjs.io/docs/manual-mocks). -- No [context object](https://jasmine.github.io/tutorials/your_first_suite#section-The_%3Ccode%3Ethis%3C/code%3E_keyword) is passed to tests in Jest. - This means sharing `this.something` between `beforeEach()` and `it()` for example does not work. - Instead you should declare shared variables in the context that they are needed (via `const` / `let`). -- The following cause tests to fail in Jest: - - Unmocked requests. - - Unhandled Promise rejections. - - Calls to `console.warn`, including warnings from libraries like Vue. - ### Limitations of jsdom -As mentioned [above](#differences-to-karma), Jest uses jsdom instead of a browser for running tests. +Jest uses jsdom instead of a browser for running tests. This comes with a number of limitations, namely: - [No scrolling support](https://github.com/jsdom/jsdom/blob/15.1.1/lib/jsdom/browser/Window.js#L623-L625) @@ -387,8 +350,7 @@ Sometimes we have to test time-sensitive code. For example, recurring events tha If the application itself is waiting for some time, mock await the waiting. In Jest this is already [done by default](https://gitlab.com/gitlab-org/gitlab/-/blob/a2128edfee799e49a8732bfa235e2c5e14949c68/jest.config.js#L47) -(see also [Jest Timer Mocks](https://jestjs.io/docs/timer-mocks)). In Karma you can use the -[Jasmine mock clock](https://jasmine.github.io/api/2.9/Clock.html). +(see also [Jest Timer Mocks](https://jestjs.io/docs/timer-mocks)). ```javascript const doSomethingLater = () => { @@ -409,20 +371,6 @@ it('does something', () => { }); ``` -**in Karma:** - -```javascript -it('does something', () => { - jasmine.clock().install(); - - doSomethingLater(); - jasmine.clock().tick(4000); - - expect(something).toBe('done'); - jasmine.clock().uninstall(); -}); -``` - ### Mocking the current location in Jest NOTE: @@ -476,8 +424,7 @@ it('passes', () => { Sometimes a test needs to wait for something to happen in the application before it continues. Avoid using [`setTimeout`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout) -because it makes the reason for waiting unclear and if used within Karma with a time larger than zero it slows down our test suite. -Instead use one of the following approaches. +because it makes the reason for waiting unclear. Instead use one of the following approaches. #### Promises and Ajax calls @@ -505,19 +452,6 @@ it('waits for an Ajax call', async () => { }); ``` -**in Karma:** - -```javascript -it('waits for an Ajax call', done => { - askTheServer() - .then(() => { - expect(something).toBe('done'); - }) - .then(done) - .catch(done.fail); -}); -``` - If you are not able to register handlers to the `Promise`, for example because it is executed in a synchronous Vue life cycle hook, take a look at the [waitFor](#wait-until-axios-requests-finish) helpers or you can flush all pending `Promise`s: **in Jest:** @@ -548,22 +482,6 @@ it('renders something', () => { }); ``` -**in Karma:** - -```javascript -it('renders something', done => { - wrapper.setProps({ value: 'new value' }); - - wrapper.vm - .$nextTick() - .then(() => { - expect(wrapper.text()).toBe('new value'); - }) - .then(done) - .catch(done.fail); -}); -``` - #### Events If the application triggers an event that you need to wait for in your test, register an event handler which contains @@ -776,8 +694,6 @@ TBU ### Stubbing and Mocking -Jasmine provides stubbing and mocking capabilities. There are some subtle differences in how to use it within Karma and Jest. - Stubs or spies are often used synonymously. In Jest it's quite easy thanks to the `.spyOn` method. [Official docs](https://jestjs.io/docs/jest-object#jestspyonobject-methodname) The more challenging part are mocks, which can be used for functions or even dependencies. @@ -835,7 +751,6 @@ For running the frontend tests, you need the following commands: - `rake frontend:fixtures` (re-)generates [fixtures](#frontend-test-fixtures). Make sure that fixtures are up-to-date before running tests that require them. - `yarn jest` runs Jest tests. -- `yarn karma` runs Karma tests. ### Live testing and focused testing -- Jest @@ -860,49 +775,36 @@ yarn jest ./path/to/folder/ yarn jest term ``` -### Live testing and focused testing -- Karma +## Frontend test fixtures -Karma allows something similar, but it's way more costly. +Frontend fixtures are files containing responses from backend controllers. These responses can be either HTML +generated from HAML templates or JSON payloads. Frontend tests that rely on these responses are +often using fixtures to validate correct integration with the backend code. -Running Karma with `yarn run karma-start` compiles the JavaScript -assets and runs a server at `http://localhost:9876/` where it automatically -runs the tests on any browser which connects to it. You can enter that URL on -multiple browsers at once to have it run the tests on each in parallel. +### Use fixtures -While Karma is running, any changes you make instantly trigger a recompile -and retest of the **entire test suite**, so you can see instantly if you've broken -a test with your changes. You can use [Jasmine focused](https://jasmine.github.io/2.5/focused_specs.html) or -excluded tests (with `fdescribe` or `xdescribe`) to get Karma to run only the -tests you want while you're working on a specific feature, but make sure to -remove these directives when you commit your code. +Jest uses `spec/frontend/__helpers__/fixtures.js` to import fixtures in tests. -It is also possible to only run Karma on specific folders or files by filtering -the run tests via the argument `--filter-spec` or short `-f`: +The following are examples of tests that work for Jest: -```shell -# Run all files -yarn karma-start -# Run specific spec files -yarn karma-start --filter-spec profile/account/components/update_username_spec.js -# Run specific spec folder -yarn karma-start --filter-spec profile/account/components/ -# Run all specs which path contain vue_shared or vie -yarn karma-start -f vue_shared -f vue_mr_widget -``` +```javascript +it('makes a request', () => { + const responseBody = getJSONFixture('some/fixture.json'); // loads spec/frontend/fixtures/some/fixture.json + axiosMock.onGet(endpoint).reply(200, responseBody); -You can also use glob syntax to match files. Remember to put quotes around the -glob otherwise your shell may split it into multiple arguments: + myButton.click(); -```shell -# Run all specs named `file_spec` within the IDE subdirectory -yarn karma -f 'spec/javascripts/ide/**/file_spec.js' -``` + // ... +}); -## Frontend test fixtures +it('uses some HTML element', () => { + loadFixtures('some/page.html'); // loads spec/frontend/fixtures/some/page.html and adds it to the DOM -Frontend fixtures are files containing responses from backend controllers. These responses can be either HTML -generated from HAML templates or JSON payloads. Frontend tests that rely on these responses are -often using fixtures to validate correct integration with the backend code. + const element = document.getElementById('#my-id'); + + // ... +}); +``` ### Generate fixtures @@ -961,34 +863,6 @@ This will create a new fixture located at You can import the JSON fixture in a Jest test using the `getJSONFixture` method [as described below](#use-fixtures). -### Use fixtures - -Jest and Karma test suites import fixtures in different ways: - -- The Karma test suite are served by [jasmine-jquery](https://github.com/velesin/jasmine-jquery). -- Jest use `spec/frontend/__helpers__/fixtures.js`. - -The following are examples of tests that work for both Karma and Jest: - -```javascript -it('makes a request', () => { - const responseBody = getJSONFixture('some/fixture.json'); // loads spec/frontend/fixtures/some/fixture.json - axiosMock.onGet(endpoint).reply(200, responseBody); - - myButton.click(); - - // ... -}); - -it('uses some HTML element', () => { - loadFixtures('some/page.html'); // loads spec/frontend/fixtures/some/page.html and adds it to the DOM - - const element = document.getElementById('#my-id'); - - // ... -}); -``` - ## Data-driven tests Similar to [RSpec's parameterized tests](best_practices.md#table-based--parameterized-tests), @@ -1139,13 +1013,10 @@ Main information on frontend testing levels can be found in the [Testing Levels Tests relevant for frontend development can be found at the following places: -- `spec/javascripts/`, for Karma tests - `spec/frontend/`, for Jest tests - `spec/features/`, for RSpec tests -RSpec runs complete [feature tests](testing_levels.md#frontend-feature-tests), while the Jest and Karma directories contain [frontend unit tests](testing_levels.md#frontend-unit-tests), [frontend component tests](testing_levels.md#frontend-component-tests), and [frontend integration tests](testing_levels.md#frontend-integration-tests). - -All tests in `spec/javascripts/` are intended to be migrated to `spec/frontend/` (see also [#52483](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/52483)). +RSpec runs complete [feature tests](testing_levels.md#frontend-feature-tests), while the Jest directories contain [frontend unit tests](testing_levels.md#frontend-unit-tests), [frontend component tests](testing_levels.md#frontend-component-tests), and [frontend integration tests](testing_levels.md#frontend-integration-tests). Before May 2018, `features/` also contained feature tests run by Spinach. These tests were removed from the codebase in May 2018 ([#23036](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/23036)). @@ -1161,6 +1032,16 @@ If you introduce new helpers, place them in that directory. We have a helper available to make testing actions easier, as per [official documentation](https://vuex.vuejs.org/guide/testing.html): ```javascript +// prefer using like this, a single object argument so parameters are obvious from reading the test +await testAction({ + action: actions.actionName, + payload: { deleteListId: 1 }, + state: { lists: [1, 2, 3] }, + expectedMutations: [ { type: types.MUTATION} ], + expectedActions: [], +}); + +// old way, don't do this for new tests testAction( actions.actionName, // action { }, // params to be passed to action @@ -1177,8 +1058,6 @@ testAction( ); ``` -Check an example in [`spec/frontend/ide/stores/actions_spec.js`](https://gitlab.com/gitlab-org/gitlab/-/blob/fdc7197609dfa7caeb1d962042a26248e49f27da/spec/frontend/ide/stores/actions_spec.js#L392). - ### Wait until Axios requests finish <!-- vale gitlab.Spelling = NO --> diff --git a/doc/development/testing_guide/index.md b/doc/development/testing_guide/index.md index 889dc45d6e3..015d8a92a4d 100644 --- a/doc/development/testing_guide/index.md +++ b/doc/development/testing_guide/index.md @@ -19,7 +19,7 @@ importance. GitLab is built on top of [Ruby on Rails](https://rubyonrails.org/), and we're using [RSpec](https://github.com/rspec/rspec-rails#feature-specs) for all the backend tests, with [Capybara](https://github.com/teamcapybara/capybara) for end-to-end integration testing. -On the frontend side, we're using [Jest](https://jestjs.io/) and [Karma](http://karma-runner.github.io/)/[Jasmine](https://jasmine.github.io/) for JavaScript unit and +On the frontend side, we're using [Jest](https://jestjs.io/) for JavaScript unit and integration testing. Following are two great articles that everyone should read to understand what @@ -40,7 +40,7 @@ system tests, parameterized tests etc. ## [Frontend testing standards and style guidelines](frontend_testing.md) -Everything you should know about how to write good Frontend tests: Karma, +Everything you should know about how to write good Frontend tests: Jest, testing promises, stubbing etc. ## [Flaky tests](flaky_tests.md) diff --git a/doc/development/testing_guide/review_apps.md b/doc/development/testing_guide/review_apps.md index cf757aad870..72d63fd8194 100644 --- a/doc/development/testing_guide/review_apps.md +++ b/doc/development/testing_guide/review_apps.md @@ -175,7 +175,7 @@ For GitLab Team Members only. If you want to sign in to the review app, review the GitLab handbook information for the [shared 1Password account](https://about.gitlab.com/handbook/security/#1password-for-teams). - The default username is `root`. -- The password can be found in the 1Password secure note named `gitlab-{ce,ee} Review App's root password`. +- The password can be found in the 1Password login item named `GitLab EE Review App`. ### Enable a feature flag for my Review App diff --git a/doc/development/testing_guide/testing_levels.md b/doc/development/testing_guide/testing_levels.md index 3a4a28702c7..29cdfab713e 100644 --- a/doc/development/testing_guide/testing_levels.md +++ b/doc/development/testing_guide/testing_levels.md @@ -31,7 +31,7 @@ records should use stubs/doubles as much as possible. | Code path | Tests path | Testing engine | Notes | | --------- | ---------- | -------------- | ----- | -| `app/assets/javascripts/` | `spec/javascripts/`, `spec/frontend/` | Karma & Jest | More details in the [Frontend Testing guide](frontend_testing.md) section. | +| `app/assets/javascripts/` | `spec/frontend/` | Jest | More details in the [Frontend Testing guide](frontend_testing.md) section. | | `app/finders/` | `spec/finders/` | RSpec | | | `app/graphql/` | `spec/graphql/` | RSpec | | | `app/helpers/` | `spec/helpers/` | RSpec | | @@ -233,7 +233,7 @@ They're useful to test permissions, redirections, what view is rendered etc. | `app/controllers/` | `spec/requests/`, `spec/controllers` | RSpec | Request specs are preferred over legacy controller specs. | | `app/mailers/` | `spec/mailers/` | RSpec | | | `lib/api/` | `spec/requests/api/` | RSpec | | -| `app/assets/javascripts/` | `spec/javascripts/`, `spec/frontend/` | Karma & Jest | [More details below](#frontend-integration-tests) | +| `app/assets/javascripts/` | `spec/frontend/` | Jest | [More details below](#frontend-integration-tests) | ### Frontend integration tests @@ -322,13 +322,6 @@ controller.instance_variable_set(:@user, user) and use methods [deprecated in Rails 5](https://gitlab.com/gitlab-org/gitlab/-/issues/16260). -### About Karma - -Karma is both in the Unit tests and the Integration tests category. Karma provides an environment to -run JavaScript tests, so you can either run unit tests (e.g. test a single -JavaScript method), or integration tests (e.g. test a component that is composed -of multiple components). - ## White-box tests at the system level (formerly known as System / Feature tests) Formal definitions: @@ -551,7 +544,7 @@ and the basic idea is that the cost of a test includes: There are cases where the behavior you are testing is not worth the time spent running the full application, for example, if you are testing styling, animation, edge cases or small actions that don't involve the backend, -you should write an integration test using Jasmine. +you should write an integration test using [Frontend integration tests](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/frontend_integration/README.md). --- diff --git a/doc/development/transient/prevention-patterns.md b/doc/development/transient/prevention-patterns.md index 472b5756805..c517a6bcd54 100644 --- a/doc/development/transient/prevention-patterns.md +++ b/doc/development/transient/prevention-patterns.md @@ -97,7 +97,7 @@ by the server-side endpoint satisfies the API contract. #### Related reading [Debug it!](https://pragprog.com/titles/pbdp/debug-it/) explores techniques to diagnose -and fix non-determinstic bugs and write software that is easier to debug. +and fix non-deterministic bugs and write software that is easier to debug. ## Backend diff --git a/doc/development/understanding_explain_plans.md b/doc/development/understanding_explain_plans.md index c3fefd40171..c3dfeaa6b92 100644 --- a/doc/development/understanding_explain_plans.md +++ b/doc/development/understanding_explain_plans.md @@ -826,4 +826,4 @@ A more extensive guide on understanding query plans can be found in the [presentation](https://public.dalibo.com/exports/conferences/_archives/_2012/201211_explain/understanding_explain.pdf) from [Dalibo.org](https://www.dalibo.com/en/). -Depesz's blog also has a good [section](https://www.depesz.com/tag/unexplainable) dedicated to query plans. +Depesz's blog also has a good [section](https://www.depesz.com/tag/unexplainable/) dedicated to query plans. diff --git a/doc/development/work_items.md b/doc/development/work_items.md new file mode 100644 index 00000000000..d4a1073461a --- /dev/null +++ b/doc/development/work_items.md @@ -0,0 +1,196 @@ +--- +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- +# Work items and work item types + +## Challenges + +Issues have the potential to be a centralized hub for collaboration. +We need to accept the +fact that different issue types require different fields and different context, depending +on what job they are being used to accomplish. For example: + +- A bug needs to list steps to reproduce. +- An incident needs references to stack traces and other contextual information relevant only + to that incident. + +Instead of each object type diverging into a separate model, we can standardize on an underlying +common model that we can customize with the widgets (one or more attributes) it contains. + +Here are some problems with current issues usage and why we are looking into work items: + +- Using labels to show issue types is cumbersome and makes reporting views more complex. +- Issue types are one of the top two use cases of labels, so it makes sense to provide first class + support for them. +- Issues are starting to become cluttered as we add more capabilities to them, and they are not + perfect: + + - There is no consistent pattern for how to surface relationships to other objects. + - There is not a coherent interaction model across different types of issues because we use + labels for this. + - The various implementations of issue types lack flexibility and extensibility. + +- Epics, issues, requirements, and others all have similar but just subtle enough + differences in common interactions that the user needs to hold a complicated mental + model of how they each behave. +- Issues are not extensible enough to support all of the emerging jobs they need to facilitate. +- Codebase maintainability and feature development become bigger challenges as we grow the Issue type + beyond its core role of issue tracking into supporting the different work item types and handling + logic and structure differences. +- New functionality is typically implemented with first class objects that import behavior from issues via + shared concerns. This leads to duplicated effort and ultimately small differences between common interactions. This + leads to inconsistent UX. +- Codebase maintainability and feature development becomes a bigger challenges as we grow issues + beyond its core role of issue tracking into supporting the different types and subtle differences between them. + +## Work item and work item type terms + +Using the terms "issue" or "issuable" to reference the types of collaboration objects +(for example, issue, bug, feature, or epic) often creates confusion. To avoid confusion, we will use the term +work item type (WIT) when referring to the type of a collaboration object. +An instance of a WIT is a work item (WI). For example, `issue#123`, `bug#456`, `requirement#789`. + +### Migration strategy + +WI model will be built on top of the existing `Issue` model and we'll gradually migrate `Issue` +model code to the WI model. + +One way to approach it is: + +```ruby +class WorkItems::WorkItem < ApplicationRecord + self.table_name = 'issues' + + # ... all the current issue.rb code +end + +class Issue < WorkItems::WorkItem + # Do not add code to this class add to WorkItems:WorkItem +end +``` + +We already use the concept of WITs within `issues` table through `issue_type` +column. There are `issue`, `incident`, and `test_case` issue types. To extend this +so that in future we can allow users to define custom WITs, we will move the +`issue_type` to a separate table: `work_item_types`. The migration process of `issue_type` +to `work_item_types` will involve creating the set of WITs for all root-level groups. + +NOTE: +At first, defining a WIT will only be possible at the root-level group, which would then be inherited by sub-groups. +We will investigate the possibility of defining new WITs at sub-group levels at a later iteration. + +### Introducing work_item_types table + +For example, suppose there are three root-level groups with IDs: `11`, `12`, and `13`. Also, +assume the following base types: `issue: 0`, `incident: 1`, `test_case: 2`. + +The respective `work_item_types` records: + +| `group_id` | `base_type` | `title` | +| -------------- | ----------- | --------- | +| 11 | 0 | Issue | +| 11 | 1 | Incident | +| 11 | 2 | Test Case | +| 12 | 0 | Issue | +| 12 | 1 | Incident | +| 12 | 2 | Test Case | +| 13 | 0 | Issue | +| 13 | 1 | Incident | +| 13 | 2 | Test Case | + +What we will do to achieve this: + +1. Add a `work_item_type_id` column to the `issues` table. +1. Ensure we write to both `issues#issue_type` and `issues#work_item_type_id` columns for + new or updated issues. +1. Backfill the `work_item_type_id` column to point to the `work_item_types#id` corresponding + to issue's project root groups. For example: + + ```ruby + issue.project.root_group.work_item_types.where(base_type: issue.issue_type).first.id. + ``` + +1. After `issues#work_item_type_id` is populated, we can switch our queries from + using `issue_type` to using `work_item_type_id`. + +To introduce a new WIT there are two options: + +- Follow the first step of the above process. We will still need to run a migration + that adds a new WIT for all root-level groups to make the WIT available to + all users. Besides a long-running migration, we'll need to + insert several million records to `work_item_types`. This might be unwanted for users + that do not want or need additional WITs in their workflow. +- Create an opt-in flow, so that the record in `work_item_types` for specific root-level group + is created only when a customer opts in. However, this implies a lower discoverability + of the newly introduced work item type. + +### Work item type widgets + +All WITs will share the same pool of predefined widgets and will be customized by +which widgets are active on a specific WIT. Every attribute (column or association) +will become a widget with self-encapsulated functionality regardless of the WIT it belongs to. +Because any WIT can have any widget, we only need to define which widget is active for a +specific WIT. So, after switching the type of a specific work item, we display a different set +of widgets. + +### Widgets metadata + +In order to customize each WIT with corresponding active widgets we will need a data +structure to map each WIT to specific widgets. + +NOTE: +The exact structure of the WITs widgets metadata is still to be defined. + +### Custom work item types + +With the WIT widget metadata and the workflow around mapping WIT to specific +widgets, we will be able to expose custom WITs to the users. Users will be able +to create their own WITs and customize them with widgets from the predefined pool. + +### Custom widgets + +The end goal is to allow users to define custom widgets and use these custom +widgets on any WIT. But this is a much further iteration and requires additional +investigation to determine both data and application architecture to be used. + +## Migrate requirements and epics to work item types + +We'll migrate requirements and epics into work item types, with their own set +of widgets. To achieve that, we'll migrate data to the `issues` table, +and we'll keep current `requirements` and `epics` tables to be used as proxies for old references to ensure +backward compatibility with already existing references. + +### Migrate requirements to work item types + +Currently `Requirement` attributes are a subset of `Issue` attributes, so the migration +consists mainly of: + +- Data migration. +- Keeping backwards compatibility at API levels. +- Ensuring that old references continue to work. + +The migration to a different underlying data structure should be seamless to the end user. + +### Migrate epics to work item types + +`Epic` has some extra functionality that the `Issue` WIT does not currently have. +So, migrating epics to a work item type requires providing feature parity between the current `Epic` object and WITs. + +The main missing features are: + +- Get WIs to the group level. This is dependent on [Consolidate Groups and Projects](https://gitlab.com/gitlab-org/architecture/tasks/-/issues/7) + initiative. +- A hierarchy widget: the ability to structure work items into hierarchies. +- Inherited date widget. + +To avoid disrupting workflows for users who are already using epics, we will introduce a new WIT +called `Feature` that will provide feature parity with epics at the project-level. Having that combined with progress +on [Consolidate Groups and Projects](https://gitlab.com/gitlab-org/architecture/tasks/-/issues/7) front will help us +provide a smooth migration path of epics to WIT with minimal disruption to user workflow. + +## Work item, work item type, and widgets roadmap + +We will move towards work items, work item types, and custom widgets (CW) in an iterative process. +For a rough outline of the work ahead of us, see [epic 6033](https://gitlab.com/groups/gitlab-org/-/epics/6033). diff --git a/doc/downgrade_ee_to_ce/index.md b/doc/downgrade_ee_to_ce/index.md index 00e59c46da1..865d60fed73 100644 --- a/doc/downgrade_ee_to_ce/index.md +++ b/doc/downgrade_ee_to_ce/index.md @@ -6,10 +6,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Downgrading from EE to CE -If you ever decide to downgrade your Enterprise Edition back to the Community -Edition, there are a few steps you need take before installing the CE package -on top of the current EE package, or, if you are in an installation from source, -before you change remotes and fetch the latest CE code. +If you ever decide to downgrade your Enterprise Edition back to the +Community Edition, there are a few steps you need take beforehand. On Omnibus GitLab +installations, these steps are made before installing the CE package on top of +the current EE package. On installations from source, they are done before +you change remotes and fetch the latest CE code. ## Disable Enterprise-only features @@ -17,8 +18,8 @@ First thing to do is to disable the following features. ### Authentication mechanisms -Kerberos and Atlassian Crowd are only available on the Enterprise Edition, so -you should disable these mechanisms before downgrading and you should provide +Kerberos and Atlassian Crowd are only available on the Enterprise Edition. You +should disable these mechanisms before downgrading. Be sure to provide alternative authentication methods to your users. ### Remove Service Integration entries from the database @@ -35,63 +36,63 @@ column if you didn't intend it to be used for storing the inheritance class or o use another column for that information.) ``` -All integrations are created automatically for every project you have, so in order -to avoid getting this error, you need to remove all records with the type set to +All integrations are created automatically for every project you have. +To avoid getting this error, you must remove all records with the type set to `GithubService` from your database: -**Omnibus Installation** +- **Omnibus Installation** -```shell -sudo gitlab-rails runner "Integration.where(type: ['GithubService']).delete_all" -``` + ```shell + sudo gitlab-rails runner "Integration.where(type: ['GithubService']).delete_all" + ``` -**Source Installation** +- **Source Installation** -```shell -bundle exec rails runner "Integration.where(type: ['GithubService']).delete_all" production -``` + ```shell + bundle exec rails runner "Integration.where(type: ['GithubService']).delete_all" production + ``` NOTE: -If you are running `GitLab =< v13.0` you need to also remove `JenkinsDeprecatedService` records -and if you are running `GitLab =< v13.6` you need to also remove `JenkinsService` records. +If you are running `GitLab =< v13.0` you must also remove `JenkinsDeprecatedService` records +and if you are running `GitLab =< v13.6` you must remove `JenkinsService` records. ### Variables environment scopes -If you're using this feature and there are variables sharing the same -key, but they have different scopes in a project, then you might want to -revisit the environment scope setting for those variables. +In GitLab Community Edition, [environment scopes](../user/group/clusters/index.md#environment-scopes) +are completely ignored, so if you are using this feature there may be some +necessary adjustments to your configuration. This is especially true if +configuration variables share the same key, but have different +scopes in a project. In cases like these you could accidentally get a variable +which you're not expecting for a particular environment. Make sure that you have +the right variables in this case. -In CE, environment scopes are completely ignored, therefore you could -accidentally get a variable which you're not expecting for a particular -environment. Make sure that you have the right variables in this case. - -Data is completely preserved, so you could always upgrade back to EE and -restore the behavior if you leave it alone. +Your data is completely preserved in the transition, so you could always upgrade +back to EE and restore the behavior if you leave it alone. ## Downgrade to CE After performing the above mentioned steps, you are now ready to downgrade your GitLab installation to the Community Edition. -**Omnibus Installation** - -To downgrade an Omnibus installation, it is sufficient to install the Community -Edition package on top of the currently installed one. You can do this manually, -by directly [downloading the package](https://packages.gitlab.com/gitlab/gitlab-ce) -you need, or by adding our CE package repository and following the -[CE installation instructions](https://about.gitlab.com/install/?version=ce). - -**Source Installation** - -To downgrade a source installation, you need to replace the current remote of -your GitLab installation with the Community Edition's remote, fetch the latest -changes, and checkout the latest stable branch: - -```shell -git remote set-url origin git@gitlab.com:gitlab-org/gitlab-foss.git -git fetch --all -git checkout 8-x-stable -``` +- **Omnibus Installation** + + To downgrade an Omnibus installation, it is sufficient to install the Community + Edition package on top of the currently installed one. You can do this manually, + by directly [downloading the package](https://packages.gitlab.com/gitlab/gitlab-ce) + you need, or by adding our CE package repository and following the + [CE installation instructions](https://about.gitlab.com/install/?version=ce). + +- **Source Installation** + + To downgrade a source installation, you must replace the current remote of + your GitLab installation with the Community Edition's remote. After that, you + can fetch the latest changes, and checkout the latest stable branch: + + ```shell + git remote set-url origin git@gitlab.com:gitlab-org/gitlab-foss.git + git fetch --all + git checkout 8-x-stable + ``` Remember to follow the correct [update guides](../update/index.md) to make sure all dependencies are up to date. diff --git a/doc/install/aws/eks_clusters_aws.md b/doc/install/aws/eks_clusters_aws.md new file mode 100644 index 00000000000..95f9f81f601 --- /dev/null +++ b/doc/install/aws/eks_clusters_aws.md @@ -0,0 +1,53 @@ +--- +type: reference, concepts +stage: Enablement +group: Alliances +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# EKS cluster provisioning best practices **(FREE SELF)** + +GitLab can be used to provision an EKS cluster into AWS, however, it necessarily focuses on a basic EKS configuration. Using the AWS tools can help with advanced cluster configuration, automation, and maintenance. + +This documentation is not for clusters for deployment of GitLab itself, but instead clusters purpose built for: + +- EKS Clusters for GitLab Runners +- Application Deployment Clusters for GitLab review apps +- Application Deployment Cluster for production applications + +Information on deploying GitLab onto EKS can be found in [Provisioning GitLab Cloud Native Hybrid on AWS EKS](gitlab_hybrid_on_aws.md). + +## Use AWS EKS quick start or `eksctl` + +Using the EKS Quick Start or `eksctl` enables the following when building an EKS Cluster: + +- It can be part of CloudFormation IaC or [CLI (`eksctl`)](https://eksctl.io/) automation +- You have various cluster configuration options: + - Selection of operating system: Amazon Linux 2, Windows, Bottlerocket + - Selection of Hardware Architecture: x86, ARM, GPU + - Selection of Fargate backend +- It can deploy high value-add items to the cluster, including: + - A bastion host to keep the cluster endpoint private and possible perform performance testing. + - Prometheus and Grafana for monitoring. +- EKS Autoscaler for automatic K8s Node scaling. +- 2 or 3 Availability Zones (AZ) spread for balance between High Availability (HA) and cost control. +- Ability to specify spot compute. + +Read more about Amazon EKS architecture quick start guide: + +- [Landing page](https://aws.amazon.com/quickstart/architecture/amazon-eks/) +- [Reference guide](https://aws-quickstart.github.io/quickstart-amazon-eks/) +- [Reference guide deployment steps](https://aws-quickstart.github.io/quickstart-amazon-eks/#_deployment_steps) +- [Reference guide parameter reference](https://aws-quickstart.github.io/quickstart-amazon-eks/#_parameter_reference) + +## Inject GitLab configuration for integrating clusters + +Read more how to [configure an App Deployment cluster](../../user/project/clusters/add_existing_cluster.md) and extract information from it to integrate it into GitLab. + +## Provision GitLab Runners using Helm charts + +Read how to [use the GitLab Runner Helm Chart](https://docs.gitlab.com/runner/install/kubernetes.html) to deploy a runner into a cluster. + +## Runner Cache + +Since the EKS Quick Start provides for EFS provisioning, the best approach is to use EFS for runner caching. Eventually we will publish information on using an S3 bucket for runner caching here. diff --git a/doc/install/aws/gitlab_hybrid_on_aws.md b/doc/install/aws/gitlab_hybrid_on_aws.md new file mode 100644 index 00000000000..9f53f333463 --- /dev/null +++ b/doc/install/aws/gitlab_hybrid_on_aws.md @@ -0,0 +1,362 @@ +--- +type: reference, concepts +stage: Enablement +group: Alliances +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +{::options parse_block_html="true" /} + +# Provision GitLab Cloud Native Hybrid on AWS EKS **(FREE SELF)** + +GitLab "Cloud Native Hybrid" is a hybrid of the cloud native technology Kubernetes (EKS) and EC2. While as much of the GitLab application as possible runs in Kubernetes or on AWS services (PaaS), the GitLab service Gitaly must still be run on Ec2. Gitaly is a layer designed to overcome limitations of the Git binaries in a horizontally scaled architecture. You can read more here about why Gitaly was built and why the limitations of Git mean that it must currently run on instance compute in [Git Characteristics That Make Horizontal Scaling Difficult](https://gitlab.com/gitlab-org/gitaly/-/blob/master/doc/DESIGN.md#git-characteristics-that-make-horizontal-scaling-difficult) + +Amazon provides a managed Kubernetes service offering known as [Amazon Elastic Kubernetes Service (EKS)](https://aws.amazon.com/eks/). + +## Tested AWS Bill of Materials by reference architecture size + +| GitLab Cloud Native Hybrid Ref Arch | GitLab Baseline Perf Test Results Omnibus on Instances | AWS Bill of Materials (BOM) for CNH | AWS Build Performance Testing Results for [CNH](https://gitlab.com/gitlab-com/alliances/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) | CNH Cost Estimate 3 AZs | +| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | +| [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<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 Scale GPT Test Results](https://gitlab.com/gitlab-com/alliances/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 AutoScale GPT Test Results](https://gitlab.com/gitlab-com/alliances/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<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 Scale GPT Test Results](https://gitlab.com/gitlab-com/alliances/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/gitlab-com/alliances/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 | +| [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 Scale GPT Test Results](https://gitlab.com/gitlab-com/alliances/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 AutoScale GPT Test Results](hhttps://gitlab.com/gitlab-com/alliances/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 Scale GPT Test Results](https://gitlab.com/gitlab-com/alliances/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 AutoScale GPT Test Results](https://gitlab.com/gitlab-com/alliances/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) | 10K 1 YR Ec2 Compute Savings + 1 YR RDS & Elasticache RIs | + +## Available Infrastructure as Code for GitLab Cloud Native Hybrid + +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). + +NOTE: +This automation is in **Developer Preview**. GitLab is working with AWS on [these outstanding issues](https://github.com/aws-quickstart/quickstart-eks-gitlab/issues?q=is%3Aissue+is%3Aopen+%5BHL%5D) before it is fully released. + +The [GitLab Environment Toolkit (GET)](https://gitlab.com/gitlab-org/quality/gitlab-environment-toolkit/-/tree/master) 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. +It is helpful to review the [GitLab Environment Toolkit (GET) Issues](https://gitlab.com/gitlab-org/quality/gitlab-environment-toolkit/-/issues) to understand if any of them may affect your provisioning plans. + +| | [AWS Quick Start for GitLab Cloud Native Hybrid on EKS](https://aws-quickstart.github.io/quickstart-eks-gitlab/) | [GitLab Environment Toolkit (GET)](https://gitlab.com/gitlab-org/quality/gitlab-environment-toolkit/-/tree/master) | +| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | +| GitLab Reference Architecture Compliant | Yes | Yes | +| GitLab Performance Tool (GPT) Tested | Yes | Yes | +| Amazon Well Architected Compliant | Yes<br />(via Quick Start program) | Critical portions <br />reviewed by AWS | +| Target Cloud Platforms | AWS | AWS, Google, Azure | +| IaC Languages | CloudFormation (Quick Starts) | Terraform, Ansible | +| Community Contributions and Participation (EcoSystem) | <u>GitLab QSG</u>: Getting Started<br /><u>For QSG Dependencies (e.g. EKS)</u>: Substantial | Getting Started | +| Compatible with AWS Meta-Automation Services (via CloudFormation) | Service Catalog (Direct Import), Control Tower<br />Quick Starts, SaaS Factory | No | +| Results in a Ready-to-Use instance | Yes | Manual Actions or <br />Supplemental IaC Required | +| **<u>Configuration Features</u>** | | | +| Can deploy Omnibus GitLab (non-Kubernetes | No | Yes | +| Complete Internal Encryption | 85%, Targeting 100% | Manual | +| AWS GovCloud Support | Yes | TBD | + +### Streamlined Performance Testing of AWS Quick Start Prepared GitLab Instances + +A set of performance testing instructions have been abbreviated for testing a GitLab instance prepared using the AWS Quick Start for GitLab Cloud Native Hybrid on EKS. They assume zero familiarity with GitLab Performance Tool. They can be accessed here: [Performance Testing an Instance Prepared using AWS Quick Start for GitLab Cloud Native Hybrid on EKS](https://gitlab.com/gitlab-com/alliances/aws/implementation-patterns/gitlab-cloud-native-hybrid-on-eks/-/blob/master/Easy-DIY-Perf-Testing.md). + +### AWS GovCloud Support for AWS Quick Start for GitLab CNH on EKS + +The AWS Quick Start for GitLab Cloud Native Hybrid on EKS has been tested with GovCloud and works with the following restrictions and understandings. + +- GovCloud does not have public Route53 hosted zones, so you must set the following parameters: + + | CloudFormation Quick Start form field | CloudFormation Parameter | Setting | + | --------------------------------------------------- | ------------------------ | ------- | + | **Create Route 53 hosted zone** | CreatedHostedZone | No | + | **Request AWS Certificate Manager SSL certificate** | CreateSslCertificate | No | + +- The Quick Start creates public load balancer IPs, so that you can easily configure your local hosts file to get to the GUI for GitLab when deploying tests. However, you may need to manually alter this if public load balancers are not part of your provisioning plan. We are planning to make non-public load balancers a configuration option issue link: [Short Term: Documentation and/or Automation for private GitLab instance with no internet Ingress](https://github.com/aws-quickstart/quickstart-eks-gitlab/issues/55) +- As of 2021-08-19, AWS GovCloud has Graviton instances for Aurora PostgreSQL available, but does not for ElastiCache Redis. +- It is challenging to get the Quick Start template to load in GovCloud from the Standard Quick Start URL, so the generic ones are provided here: + - [Launch for New VPC in us-gov-east-1](https://us-gov-east-1.console.amazonaws-us-gov.com/cloudformation/home?region=us-gov-east-1#/stacks/quickcreate?templateUrl=https://aws-quickstart.s3.us-east-1.amazonaws.com/quickstart-eks-gitlab/templates/gitlab-entry-new-vpc.template.yaml&stackName=Gitlab-for-EKS-New-VPC) + - [Launch for New VPC in us-gov-west-1](https://us-gov-west-1.console.amazonaws-us-gov.com/cloudformation/home?region=us-gov-west-1#/stacks/quickcreate?templateUrl=https://aws-quickstart.s3.us-east-1.amazonaws.com/quickstart-eks-gitlab/templates/gitlab-entry-new-vpc.template.yaml&stackName=Gitlab-for-EKS-New-VPC) + +## AWS PaaS qualified for all GitLab implementations + +For both Omnibus GitLab or Cloud Native Hybrid implementations, the following GitLab Service roles can be performed by AWS Services (PaaS). Any PaaS solutions that require preconfigured sizing based on the scale of your instance will also be listed in the per-instance size Bill of Materials lists. Those PaaS that do not require specific sizing, are not repeated in the BOM lists (for example, AWS Certification Manager). + +These services have been tested with GitLab. + +Some services, such as log aggregation, outbound email are not specified by GitLab, but where provided are noted. + +| GitLab Services | AWS PaaS (Tested) | Provided by AWS Cloud <br />Native Hybrid Quick Start | +| ------------------------------------------------------------ | ------------------------------ | ------------------------------------------------------------ | +| <u>Tested PaaS Mentioned in Reference Architectures</u> | | | +| **PostgreSQL Database** | Aurora RDS | Yes. | +| **Redis Caching** | Redis Elasticache | Yes. | +| **Gitaly Cluster (Git Repository Storage)**<br />(Including Praefect and PostgreSQL) | ASG and Instances | Yes - ASG and Instances<br />**Note: Gitaly cannot be put into a Kubernetes Cluster.** | +| **All GitLab storages besides Git Repository Storage**<br />(Includes Git-LFS which is S3 Compatible) | AWS S3 | Yes | +| | | | +| <u>Tested PaaS for Supplemental Services</u> | | | +| **Front End Load Balancing** | AWS ELB | Yes | +| **Internal Load Balancing** | AWS ELB | Yes | +| **Outbound Email Services** | AWS Simple Email Service (SES) | Yes | +| **Certificate Authority and Management** | AWS Certificate Manager (ACM) | Yes | +| **DNS** | AWS Route53 (tested) | Yes | +| **GitLab and Infrastructure Log Aggregation** | AWS CloudWatch Logs | Yes (ContainerInsights Agent for EKS) | +| **Infrastructure Performance Metrics** | AWS CloudWatch Metrics | Yes | +| | | | +| <u>Supplemental Services and Configurations (Tested)</u> | | | +| **Prometheus for GitLab** | AWS EKS (Cloud Native Only) | Yes | +| **Grafana for GitLab** | AWS EKS (Cloud Native Only) | Yes | +| **Administrative Access to GitLab Backend** | Bastion Host in VPC | Yes - HA - Preconfigured for Cluster Management. | +| **Encryption (In Transit / At Rest)** | AWS KMS | Yes | +| **Secrets Storage for Provisioning** | AWS Secrets Manager | Yes | +| **Configuration Data for Provisioning** | AWS Parameter Store | Yes | +| **AutoScaling Kubernetes** | EKS AutoScaling Agent | Yes | + +## GitLab Cloud Native Hybrid on AWS + +### 2K Cloud Native Hybrid on EKS + +**2K Cloud Native Hybrid on EKS Bill of Materials (BOM)** + +**GPT Test Results** + +- [3K Full Scale GPT Test Results](https://gitlab.com/gitlab-com/alliances/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) + +- [3K AutoScale GPT Test Results](https://gitlab.com/gitlab-com/alliances/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) + + **Deploy Now** + Deploy Now links leverage the AWS Quick Start automation and only prepopulate the number of instances and instance types for the Quick Start based on the Bill of Meterials below. You must provide appropriate input for all other parameters by following the guidance in the [Quick Start documentation's Deployment steps](https://aws-quickstart.github.io/quickstart-eks-gitlab/#_deployment_steps) section. + +- **Deploy Now: AWS Quick Start for 2 AZs** +- **Deploy Now: AWS Quick Start for 3 AZs** + +NOTE: +On Demand pricing is used in this table for comparisons, but should not be used for budgeting nor purchasing AWS resources for a GitLab production instance. Do not use these tables to calculate actual monthly or yearly price estimates, instead use the AWS Calculator links in the "GitLab on AWS Compute" table above and customize it with your desired savings plan. + +**BOM Total:** = Bill of Materials Total - this is what you use when building this configuration + +**Ref Arch Raw Total:** = The totals if the configuration was built on regular VMs with no PaaS services. Configuring on pure VMs generally requires additional VMs for cluster management activities. + +**Idle Configuration (Scaled-In)** = can be used to scale-in during time of low demand and/or for warm standby Geo instances. Requires configuration, testing and management of EKS autoscaling to meet your internal requirements. + +| Service | Ref Arch Raw (Full Scaled) | AWS BOM | Example Full Scaled Cost<br />(On Demand, US East) | +| ------------------------------------------------------------ | -------------------------- | ------------------------------------------------------------ | -------------------------------------------------- | +| Webservice | 12 vCPU,16 GB | | | +| Sidekiq | 2 vCPU, 8 GB | | | +| Supporting services such as NGINX, Prometheus, etc | 2 vCPU, 8 GB | | | +| **GitLab Ref Arch Raw Total K8s Node Capacity** | 16 vCPU, 32 GB | | | +| One Node for Overhead and Miscellaneous (EKS Cluster AutoScaler, Grafana, Prometheus, etc) | + 8 vCPU, 16GB | | | +| **Grand Total w/ Overheads**<br />Minimum hosts = 3 | 24 vCPU, 48 GB | **c5.2xlarge** <br />(8vcpu/16GB) x 3 nodes<br />24 vCPU, 48 GB | $1.02/hr | +| **Idle Configuration (Scaled-In)** | 16 vCPU, 32 GB | **c5.2xlarge** x 2 | $0.68/hr | + +NOTE: +If EKS node autoscaling is employed, it is likely that your average loading will run lower than this, especially during non-working hours and weekends. + +| Non-Kubernetes Compute | Ref Arch Raw Total | AWS BOM<br />(Directly Usable in AWS Quick Start) | Example Cost<br />US East, 3 AZ | Example Cost<br />US East, 2 AZ | +| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------- | ------------------------------- | ---------------------------------------------------- | +| **Bastion Host (Quick Start)** | 1 HA instance in ASG | **t2.micro** for prod, **m4.2xlarge** for perf. testing | | | +| **PostgreSQL**<br />AWS Aurora RDS Nodes Configuration (GPT tested) | 2vCPU, 7.5 GB<br />Tested with Graviton ARM | **db.r6g.large** x 3 nodes <br />(6vCPU, 48 GB) | 3 nodes x $0.26 = $0.78/hr | 3 nodes x $0.26 = $0.78/hr<br />(Aurora is always 3) | +| **Redis** | 1vCPU, 3.75GB<br />(across 12 nodes for Redis Cache, Redis Queues/Shared State, Sentinel Cache, Sentinel Queues/Shared State) | **cache.m6g.large** x 3 nodes<br />(6vCPU, 19GB) | 3 nodes x $0.15 = $0.45/hr | 2 nodes x $0.15 = $0.30/hr | +| **<u>Gitaly Cluster</u>** [Details](gitlab_sre_for_aws.md#gitaly-sre-considerations) | [Gitaly & Praefect Must Have an Uneven Node Count for HA](gitlab_sre_for_aws.md#gitaly-and-praefect-elections) | | | | +| Gitaly Instances (in ASG) | 12 vCPU, 45GB<br />(across 3 nodes) | **m5.xlarge** x 3 nodes<br />(48 vCPU, 180 GB) | $0.192 x 3 = $0.58/hr | $0.192 x 3 = $0.58/hr | +| | The GitLab Reference architecture for 2K is not Highly Available and therefore has a single Gitaly no Praefect. AWS Quick Starts MUST be HA, so it implements Prafect from the 3K Ref Architecture to meet that requirement | | | | +| Praefect (Instances in ASG with load balancer) | 6 vCPU, 10 GB<br />([across 3 nodes](gitlab_sre_for_aws.md#gitaly-and-praefect-elections)) | **c5.large** x 3 nodes<br />(6 vCPU, 12 GB) | $0.09 x 3 = $0.21/hr | $0.09 x 3 = $0.21/hr | +| Praefect PostgreSQL(1) (AWS RDS) | 6 vCPU, 5.4 GB<br />([across 3 nodes](gitlab_sre_for_aws.md#gitaly-and-praefect-elections)) | N/A Reuses GitLab PostgreSQL | $0 | $0 | +| Internal Load Balancing Node | 2 vCPU, 1.8 GB | AWS ELB | $0.10/hr | $0.10/hr | + +### 3K Cloud Native Hybrid on EKS + +**3K Cloud Native Hybrid on EKS Bill of Materials (BOM)** + +**GPT Test Results** + +- [5K Full Scale GPT Test Results](https://gitlab.com/gitlab-com/alliances/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) +- [5K AutoScale from 25% GPT Test Results](https://gitlab.com/gitlab-com/alliances/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) + +**Deploy Now** + +Deploy Now links leverage the AWS Quick Start automation and only prepopulate the number of instances and instance types for the Quick Start based on the Bill of Meterials below. You must provide appropriate input for all other parameters by following the guidance in the [Quick Start documentation's Deployment steps](https://aws-quickstart.github.io/quickstart-eks-gitlab/#_deployment_steps) section. + +- **[Deploy Now: AWS Quick Start for 2 AZs](https://us-east-2.console.aws.amazon.com/cloudformation/home?region=us-east-2#/stacks/quickcreate?templateUrl=https://aws-quickstart.s3.us-east-1.amazonaws.com/quickstart-eks-gitlab/templates/gitlab-entry-new-vpc.template.yaml&stackName=Gitlab-EKS-3K-Users-2AZs¶m_NumberOfAZs=2¶m_NodeInstanceType=c5.2xlarge¶m_NumberOfNodes=3¶m_MaxNumberOfNodes=3¶m_DBInstanceClass=db.r6g.xlarge¶m_CacheNodes=2¶m_CacheNodeType=cache.m6g.large¶m_GitalyInstanceType=m5.large¶m_NumberOfGitalyReplicas=3¶m_PraefectInstanceType=c5.large¶m_NumberOfPraefectReplicas=3)** +- **[Deploy Now: AWS Quick Start for 3 AZs](https://us-east-2.console.aws.amazon.com/cloudformation/home?region=us-east-2#/stacks/quickcreate?templateUrl=https://aws-quickstart.s3.us-east-1.amazonaws.com/quickstart-eks-gitlab/templates/gitlab-entry-new-vpc.template.yaml&stackName=Gitlab-EKS-3K-Users-3AZs¶m_NumberOfAZs=3¶m_NodeInstanceType=c5.2xlarge¶m_NumberOfNodes=3¶m_MaxNumberOfNodes=3¶m_DBInstanceClass=db.r6g.xlarge¶m_CacheNodes=3¶m_CacheNodeType=cache.m6g.large¶m_GitalyInstanceType=m5.large¶m_NumberOfGitalyReplicas=3¶m_PraefectInstanceType=c5.large¶m_NumberOfPraefectReplicas=3)** + +NOTE: +On Demand pricing is used in this table for comparisons, but should not be used for budgeting nor purchasing AWS resources for a GitLab production instance. Do not use these tables to calculate actual monthly or yearly price estimates, instead use the AWS Calculator links in the "GitLab on AWS Compute" table above and customize it with your desired savings plan. + +**BOM Total:** = Bill of Materials Total - this is what you use when building this configuration + +**Ref Arch Raw Total:** = The totals if the configuration was built on regular VMs with no PaaS services. Configuring on pure VMs generally requires additional VMs for cluster management activities. + + **Idle Configuration (Scaled-In)** = can be used to scale-in during time of low demand and/or for warm standby Geo instances. Requires configuration, testing and management of EKS autoscaling to meet your internal requirements. + +| Service | Ref Arch Raw (Full Scaled) | AWS BOM | Example Full Scaled Cost<br />(On Demand, US East) | +| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | -------------------------------------------------- | +| Webservice | [4 pods](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/examples/ref/3k.yaml#L7) x ([5 vCPU & 6.25 GB](../../administration/reference_architectures/3k_users.md#webservice)) = <br />20 vCPU, 25 GB | | | +| Sidekiq | [8 pods](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/examples/ref/3k.yaml#L24) x ([1 vCPU & 2 GB](../../administration/reference_architectures/3k_users.md#sidekiq)) = <br />8 vCPU, 16 GB | | | +| Supporting services such as NGINX, Prometheus, etc | [2 allocations](../../administration/reference_architectures/3k_users.md#cluster-topology) x ([2 vCPU and 7.5 GB](../../administration/reference_architectures/3k_users.md#cluster-topology)) = <br />4 vCPU, 15 GB | | | +| **GitLab Ref Arch Raw Total K8s Node Capacity** | 32 vCPU, 56 GB | | | +| One Node for Overhead and Miscellaneous (EKS Cluster AutoScaler, Grafana, Prometheus, etc) | + 16 vCPU, 32GB | | | +| **Grand Total w/ Overheads Full Scale**<br />Minimum hosts = 3 | 48 vCPU, 88 GB | **c5.2xlarge** (8vcpu/16GB) x 5 nodes<br />40 vCPU, 80 GB<br />[Full Scale GPT Test Results](https://gitlab.com/gitlab-com/alliances/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) | $1.70/hr | +| **Possible Idle Configuration (Scaled-In 75% - round up)**<br />Pod autoscaling must be also adjusted to enable lower idling configuration. | 24 vCPU, 48 GB | c5.2xlarge x 4 | $1.36/hr | + +Other combinations of node type and quantity can be used to meet the Grand Total. Due to the properties of pods, hosts that are overly small may have significant unused capacity. + +NOTE: +If EKS node autoscaling is employed, it is likely that your average loading will run lower than this, especially during non-working hours and weekends. + +| Non-Kubernetes Compute | Ref Arch Raw Total | AWS BOM<br />(Directly Usable in AWS Quick Start) | Example Cost<br />US East, 3 AZ | Example Cost<br />US East, 2 AZ | +| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------ | +| **Bastion Host (Quick Start)** | 1 HA instance in ASG | **t2.micro** for prod, **m4.2xlarge** for perf. testing | | | +| **PostgreSQL**<br />AWS Aurora RDS Nodes Configuration (GPT tested) | 18vCPU, 36 GB <br />(across 9 nodes for PostgreSQL, PgBouncer, Consul)<br />Tested with Graviton ARM | **db.r6g.xlarge** x 3 nodes <br />(12vCPU, 96 GB) | 3 nodes x $0.52 = $1.56/hr | 3 nodes x $0.52 = $1.56/hr<br />(Aurora is always 3) | +| **Redis** | 6vCPU, 18GB<br />(across 6 nodes for Redis Cache, Sentinel) | **cache.m6g.large** x 3 nodes<br />(6vCPU, 19GB) | 3 nodes x $0.15 = $0.45/hr | 2 nodes x $0.15 = $0.30/hr | +| **<u>Gitaly Cluster</u>** [Details](gitlab_sre_for_aws.md#gitaly-sre-considerations) | | | | | +| Gitaly Instances (in ASG) | 12 vCPU, 45GB<br />([across 3 nodes](gitlab_sre_for_aws.md#gitaly-and-praefect-elections)) | **m5.large** x 3 nodes<br />(12 vCPU, 48 GB) | $0.192 x 3 = $0.58/hr | [Gitaly & Praefect Must Have an Uneven Node Count for HA](gitlab_sre_for_aws.md#gitaly-and-praefect-elections) | +| Praefect (Instances in ASG with load balancer) | 6 vCPU, 5.4 GB<br />([across 3 nodes](gitlab_sre_for_aws.md#gitaly-and-praefect-elections)) | **c5.large** x 3 nodes<br />(6 vCPU, 12 GB) | $0.09 x 3 = $0.21/hr | [Gitaly & Praefect Must Have an Uneven Node Count for HA](gitlab_sre_for_aws.md#gitaly-and-praefect-elections) | +| Praefect PostgreSQL(1) (AWS RDS) | 6 vCPU, 5.4 GB<br />([across 3 nodes](gitlab_sre_for_aws.md#gitaly-and-praefect-elections)) | N/A Reuses GitLab PostgreSQL | $0 | | +| Internal Load Balancing Node | 2 vCPU, 1.8 GB | AWS ELB | $0.10/hr | $0.10/hr | + +### 5K Cloud Native Hybrid on EKS + +**5K Cloud Native Hybrid on EKS Bill of Materials (BOM)** + +**GPT Test Results** + +- [5K Full Scale GPT Test Results](https://gitlab.com/gitlab-com/alliances/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) +- [5K AutoScale from 25% GPT Test Results](https://gitlab.com/gitlab-com/alliances/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) + +**Deploy Now** + +Deploy Now links leverage the AWS Quick Start automation and only prepopulate the number of instances and instance types for the Quick Start based on the Bill of Meterials below. You must provide appropriate input for all other parameters by following the guidance in the [Quick Start documentation's Deployment steps](https://aws-quickstart.github.io/quickstart-eks-gitlab/#_deployment_steps) section. + +- **[Deploy Now: AWS Quick Start for 2 AZs](https://us-east-2.console.aws.amazon.com/cloudformation/home?region=us-east-2#/stacks/quickcreate?templateUrl=https://aws-quickstart.s3.us-east-1.amazonaws.com/quickstart-eks-gitlab/templates/gitlab-entry-new-vpc.template.yaml&stackName=Gitlab-EKS-5K-Users-2AZs¶m_NumberOfAZs=2¶m_NodeInstanceType=c5.2xlarge¶m_NumberOfNodes=5¶m_MaxNumberOfNodes=5¶m_DBInstanceClass=db.r6g.2xlarge¶m_CacheNodes=2¶m_CacheNodeType=cache.m6g.xlarge¶m_GitalyInstanceType=m5.2xlarge¶m_NumberOfGitalyReplicas=2¶m_PraefectInstanceType=c5.large¶m_NumberOfPraefectReplicas=2)** +- **[Deploy Now: AWS Quick Start for 3 AZs](https://us-east-2.console.aws.amazon.com/cloudformation/home?region=us-east-2#/stacks/quickcreate?templateUrl=https://aws-quickstart.s3.us-east-1.amazonaws.com/quickstart-eks-gitlab/templates/gitlab-entry-new-vpc.template.yaml&stackName=Gitlab-EKS-5K-Users-3AZs¶m_NumberOfAZs=3¶m_NodeInstanceType=c5.2xlarge¶m_NumberOfNodes=5¶m_MaxNumberOfNodes=5¶m_DBInstanceClass=db.r6g.2xlarge¶m_CacheNodes=3¶m_CacheNodeType=cache.m6g.xlarge¶m_GitalyInstanceType=m5.2xlarge¶m_NumberOfGitalyReplicas=3¶m_PraefectInstanceType=c5.large¶m_NumberOfPraefectReplicas=3)** + +NOTE: +On Demand pricing is used in this table for comparisons, but should not be used for budgeting nor purchasing AWS resources for a GitLab production instance. Do not use these tables to calculate actual monthly or yearly price estimates, instead use the AWS Calculator links in the "GitLab on AWS Compute" table above and customize it with your desired savings plan. + +**BOM Total:** = Bill of Materials Total - this is what you use when building this configuration + +**Ref Arch Raw Total:** = The totals if the configuration was built on regular VMs with no PaaS services. Configuring on pure VMs generally requires additional VMs for cluster management activities. + +**Idle Configuration (Scaled-In)** = can be used to scale-in during time of low demand and/or for warm standby Geo instances. Requires configuration, testing and management of EKS autoscaling to meet your internal requirements. + +| Service | Ref Arch Raw (Full Scaled) | AWS BOM | Example Full Scaled Cost<br />(On Demand, US East) | +| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | -------------------------------------------------- | +| Webservice | [10 pods](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/examples/ref/5k.yaml#L7) x ([5 vCPU & 6.25GB](../../administration/reference_architectures/5k_users.md#webservice)) = <br />50 vCPU, 62.5 GB | | | +| Sidekiq | [8 pods](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/examples/ref/5k.yaml#L24) x ([1 vCPU & 2 GB](../../administration/reference_architectures/5k_users.md#sidekiq)) = <br />8 vCPU, 16 GB | | | +| Supporting services such as NGINX, Prometheus, etc | [2 allocations](../../administration/reference_architectures/5k_users.md#cluster-topology) x ([2 vCPU and 7.5 GB](../../administration/reference_architectures/5k_users.md#cluster-topology)) = <br />4 vCPU, 15 GB | | | +| **GitLab Ref Arch Raw Total K8s Node Capacity** | 62 vCPU, 96.5 GB | | | +| One Node for Quick Start Overhead and Miscellaneous (EKS Cluster AutoScaler, Grafana, Prometheus, etc) | + 8 vCPU, 16GB | | | +| **Grand Total w/ Overheads Full Scale**<br />Minimum hosts = 3 | 70 vCPU, 112.5 GB | **c5.2xlarge** (8vcpu/16GB) x 9 nodes<br />72 vCPU, 144 GB<br />[Full Scale GPT Test Results](https://gitlab.com/gitlab-com/alliances/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) | $2.38/hr | +| **Possible Idle Configuration (Scaled-In 75% - round up)**<br />Pod autoscaling must be also adjusted to enable lower idling configuration. | 24 vCPU, 48 GB | c5.2xlarge x 7 | $1.85/hr | + +Other combinations of node type and quantity can be used to meet the Grand Total. Due to the cpu and memory requirements of pods, hosts that are overly small may have significant unused capacity. + +NOTE: +If EKS node autoscaling is employed, it is likely that your average loading will run lower than this, especially during non-working hours and weekends. + +| Non-Kubernetes Compute | Ref Arch Raw Total | AWS BOM<br />(Directly Usable in AWS Quick Start) | Example Cost<br />US East, 3 AZ | Example Cost<br />US East, 2 AZ | +| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------ | +| **Bastion Host (Quick Start)** | 1 HA instance in ASG | **t2.micro** for prod, **m4.2xlarge** for perf. testing | | | +| **PostgreSQL**<br />AWS Aurora RDS Nodes Configuration (GPT tested) | 21vCPU, 51 GB <br />(across 9 nodes for PostgreSQL, PgBouncer, Consul)<br />Tested with Graviton ARM | **db.r6g.2xlarge** x 3 nodes <br />(24vCPU, 192 GB) | 3 nodes x $1.04 = $3.12/hr | 3 nodes x $1.04 = $3.12/hr<br />(Aurora is always 3) | +| **Redis** | 9vCPU, 27GB<br />(across 6 nodes for Redis, Sentinel) | **cache.m6g.xlarge** x 3 nodes<br />(12vCPU, 39GB) | 3 nodes x $0.30 = $0.90/hr | 2 nodes x $0.30 = $0.60/hr | +| **<u>Gitaly Cluster</u>** [Details](gitlab_sre_for_aws.md#gitaly-sre-considerations) | | | | | +| Gitaly Instances (in ASG) | 24 vCPU, 90GB<br />([across 3 nodes](gitlab_sre_for_aws.md#gitaly-and-praefect-elections)) | **m5.2xlarge** x 3 nodes<br />(24 vCPU, 96GB) | $0.384 x 3 = $1.15/hr | [Gitaly & Praefect Must Have an Uneven Node Count for HA](gitlab_sre_for_aws.md#gitaly-and-praefect-elections) | +| Praefect (Instances in ASG with load balancer) | 6 vCPU, 5.4 GB<br />([across 3 nodes](gitlab_sre_for_aws.md#gitaly-and-praefect-elections)) | **c5.large** x 3 nodes<br />(6 vCPU, 12 GB) | $0.09 x 3 = $0.21/hr | [Gitaly & Praefect Must Have an Uneven Node Count for HA](gitlab_sre_for_aws.md#gitaly-and-praefect-elections) | +| Praefect PostgreSQL(1) (AWS RDS) | 6 vCPU, 5.4 GB<br />([across 3 nodes](gitlab_sre_for_aws.md#gitaly-and-praefect-elections)) | N/A Reuses GitLab PostgreSQL | $0 | | +| Internal Load Balancing Node | 2 vCPU, 1.8 GB | AWS ELB | $0.10/hr | $0.10/hr | + +### 10K Cloud Native Hybrid on EKS + +**10K Cloud Native Hybrid on EKS Bill of Materials (BOM)** + +**GPT Test Results** + +- [10K Full Scale GPT Test Results](https://gitlab.com/gitlab-com/alliances/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) +- [10K AutoScale GPT Test Results](https://gitlab.com/gitlab-com/alliances/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) + +**Deploy Now** + +Deploy Now links leverage the AWS Quick Start automation and only prepopulate the number of instances and instance types for the Quick Start based on the Bill of Meterials below. You must provide appropriate input for all other parameters by following the guidance in the [Quick Start documentation's Deployment steps](https://aws-quickstart.github.io/quickstart-eks-gitlab/#_deployment_steps) section. + +- **[Deploy Now: AWS Quick Start for 3 AZs](https://us-east-2.console.aws.amazon.com/cloudformation/home?region=us-east-2#/stacks/quickcreate?templateUrl=https://aws-quickstart.s3.us-east-1.amazonaws.com/quickstart-eks-gitlab/templates/gitlab-entry-new-vpc.template.yaml&stackName=Gitlab-EKS-10K-Users-3AZs¶m_NumberOfAZs=3¶m_NodeInstanceType=c5.4xlarge¶m_NumberOfNodes=9¶m_MaxNumberOfNodes=9¶m_DBInstanceClass=db.r6g.2xlarge¶m_CacheNodes=3¶m_CacheNodeType=cache.m6g.2xlarge¶m_GitalyInstanceType=m5.4xlarge¶m_NumberOfGitalyReplicas=3¶m_PraefectInstanceType=c5.large¶m_NumberOfPraefectReplicas=3)** + +NOTE: +On Demand pricing is used in this table for comparisons, but should not be used for budgeting nor purchasing AWS resources for a GitLab production instance. Do not use these tables to calculate actual monthly or yearly price estimates, instead use the AWS Calculator links in the "GitLab on AWS Compute" table above and customize it with your desired savings plan. + +**BOM Total:** = Bill of Materials Total - this is what you use when building this configuration + +**Ref Arch Raw Total:** = The totals if the configuration was built on regular VMs with no PaaS services. Configuring on pure VMs generally requires additional VMs for cluster management activities. + + **Idle Configuration (Scaled-In)** = can be used to scale-in during time of low demand and/or for warm standby Geo instances. Requires configuration, testing and management of EKS autoscaling to meet your internal requirements. + +| Service | Ref Arch Raw (Full Scaled) | AWS BOM<br />(Directly Usable in AWS Quick Start) | Example Full Scaled Cost<br />(On Demand, US East) | +| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | -------------------------------------------------- | +| Webservice | [20 pods](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/examples/ref/10k.yaml#L7) x ([5 vCPU & 6.25 GB](../../administration/reference_architectures/10k_users.md#webservice)) = <br />100 vCPU, 125 GB | | | +| Sidekiq | [14 pods](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/examples/ref/10k.yaml#L24) x ([1 vCPU & 2 GB](../../administration/reference_architectures/10k_users.md#sidekiq))<br />14 vCPU, 28 GB | | | +| Supporting services such as NGINX, Prometheus, etc | [2 allocations](../../administration/reference_architectures/10k_users.md#cluster-topology) x ([2 vCPU and 7.5 GB](../../administration/reference_architectures/10k_users.md#cluster-topology))<br />4 vCPU, 15 GB | | | +| **GitLab Ref Arch Raw Total K8s Node Capacity** | 128 vCPU, 158 GB | | | +| One Node for Overhead and Miscellaneous (EKS Cluster AutoScaler, Grafana, Prometheus, etc) | + 16 vCPU, 32GB | | | +| **Grand Total w/ Overheads Fully Scaled**<br />Minimum hosts = 3 | 142 vCPU, 190 GB | **c5.4xlarge** (16vcpu/32GB) x 9 nodes<br />144 vCPU, 288GB<br /><br />[Full Scale GPT Test Results](https://gitlab.com/gitlab-com/alliances/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) | $6.12/hr | +| **Possible Idle Configuration (Scaled-In 75% - round up)**<br />Pod autoscaling must be also adjusted to enable lower idling configuration. | 40 vCPU, 80 GB | c5.4xlarge x 7<br /><br />[AutoScale GPT Test Results](https://gitlab.com/gitlab-com/alliances/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) | $4.76/hr | + +Other combinations of node type and quantity can be used to meet the Grand Total. Due to the cpu and memory requirements of pods, hosts that are overly small may have significant unused capacity. + +NOTE: +If EKS node autoscaling is employed, it is likely that your average loading will run lower than this, especially during non-working hours and weekends. + +| Non-Kubernetes Compute | Ref Arch Raw Total | AWS BOM | Example Cost<br />US East, 3 AZ | Example Cost<br />US East, 2 AZ | +| ------------------------------------------------------------ | ------------------------------ | ------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| **Bastion Host (Quick Start)** | 1 HA instance in ASG | **t2.micro** for prod, **m4.2xlarge** for perf. testing | | | +| **PostgreSQL**<br />AWS Aurora RDS Nodes Configuration (GPT tested) | 36vCPU, 102 GB <br />(across 9 nodes for PostgreSQL, PgBouncer, Consul) | **db.r6g.2xlarge** x 3 nodes <br />(24vCPU, 192 GB) | 3 nodes x $1.04 = $3.12/hr | 3 nodes x $1.04 = $3.12/hr<br />(Aurora is always 3) | +| **Redis** | 30vCPU, 114GB<br />(across 12 nodes for Redis Cache, Redis Queues/Shared State, Sentinel Cache, Sentinel Queues/Shared State) | **cache.m5.2xlarge** x 3 nodes<br />(24vCPU, 78GB) | 3 nodes x $0.62 = $1.86/hr | 2 nodes x $0.62 = $1.24/hr | +| **<u>Gitaly Cluster</u>** [Details](gitlab_sre_for_aws.md#gitaly-sre-considerations) | | | | | +| Gitaly Instances (in ASG) | 48 vCPU, 180GB<br />([across 3 nodes](gitlab_sre_for_aws.md#gitaly-and-praefect-elections)) | **m5.4xlarge** x 3 nodes<br />(48 vCPU, 180 GB) | $0.77 x 3 = $2.31/hr | [Gitaly & Praefect Must Have an Uneven Node Count for HA](gitlab_sre_for_aws.md#gitaly-and-praefect-elections) | +| Praefect (Instances in ASG with load balancer) | 6 vCPU, 5.4 GB<br />([across 3 nodes](gitlab_sre_for_aws.md#gitaly-and-praefect-elections)) | **c5.large** x 3 nodes<br />(6 vCPU, 12 GB) | $0.09 x 3 = $0.21/hr | [Gitaly & Praefect Must Have an Uneven Node Count for HA](gitlab_sre_for_aws.md#gitaly-and-praefect-elections) | +| Praefect PostgreSQL(1) (AWS RDS) | 6 vCPU, 5.4 GB<br />([across 3 nodes](gitlab_sre_for_aws.md#gitaly-and-praefect-elections)) | N/A Reuses GitLab PostgreSQL | $0 | | +| Internal Load Balancing Node | 2 vCPU, 1.8 GB | AWS ELB | $0.10/hr | $0.10/hr | + +### 50K Cloud Native Hybrid on EKS + +**50K Cloud Native Hybrid on EKS Bill of Materials (BOM)** + +**GPT Test Results** + +- [50K Full Scale GPT Test Results](https://gitlab.com/gitlab-com/alliances/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) +- [50K AutoScale GPT Test Results](https://gitlab.com/gitlab-com/alliances/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) + +**Deploy Now** + +Deploy Now links leverage the AWS Quick Start automation and only prepopulate the number of instances and instance types for the Quick Start based on the Bill of Meterials below. You must provide appropriate input for all other parameters by following the guidance in the [Quick Start documentation's Deployment steps](https://aws-quickstart.github.io/quickstart-eks-gitlab/#_deployment_steps) section. + +- **[Deploy Now: AWS Quick Start for 3 AZs - 1/4 Scale EKS](https://us-east-2.console.aws.amazon.com/cloudformation/home?region=us-east-2#/stacks/quickcreate?templateUrl=https://aws-quickstart.s3.us-east-1.amazonaws.com/quickstart-eks-gitlab/templates/gitlab-entry-new-vpc.template.yaml&stackName=Gitlab-EKS-50K-Users-3AZs¶m_NumberOfAZs=3¶m_NodeInstanceType=c5.4xlarge¶m_NumberOfNodes=7¶m_MaxNumberOfNodes=9¶m_DBInstanceClass=db.r6g.8xlarge¶m_CacheNodes=3¶m_CacheNodeType=cache.m6g.2xlarge¶m_GitalyInstanceType=m5.16xlarge¶m_NumberOfGitalyReplicas=3¶m_PraefectInstanceType=c5.xlarge¶m_NumberOfPraefectReplicas=3)** + +NOTE: +On Demand pricing is used in this table for comparisons, but should not be used for budgeting nor purchasing AWS resources for a GitLab production instance. Do not use these tables to calculate actual monthly or yearly price estimates, instead use the AWS Calculator links in the "GitLab on AWS Compute" table above and customize it with your desired savings plan. + +**BOM Total:** = Bill of Materials Total - this is what you use when building this configuration + +**Ref Arch Raw Total:** = The totals if the configuration was built on regular VMs with no PaaS services. Configuring on pure VMs generally requires additional VMs for cluster management activities. + + **Idle Configuration (Scaled-In)** = can be used to scale-in during time of low demand and/or for warm standby Geo instances. Requires configuration, testing and management of EKS autoscaling to meet your internal requirements. + +| Service | Ref Arch Raw (Full Scaled) | AWS BOM<br />(Directly Usable in AWS Quick Start) | Example Full Scaled Cost<br />(On Demand, US East) | +| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | -------------------------------------------------- | +| Webservice | [80 pods](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/examples/ref/10k.yaml#L7) x ([5 vCPU & 6.25 GB](../../administration/reference_architectures/10k_users.md#webservice)) = <br />400 vCPU, 500 GB | | | +| Sidekiq | [14 pods](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/examples/ref/10k.yaml#L24) x ([1 vCPU & 2 GB](../../administration/reference_architectures/10k_users.md#sidekiq))<br />14 vCPU, 28 GB | | | +| Supporting services such as NGINX, Prometheus, etc | [2 allocations](../../administration/reference_architectures/10k_users.md#cluster-topology) x ([2 vCPU and 7.5 GB](../../administration/reference_architectures/10k_users.md#cluster-topology))<br />4 vCPU, 15 GB | | | +| **GitLab Ref Arch Raw Total K8s Node Capacity** | 428 vCPU, 533 GB | | | +| One Node for Overhead and Miscellaneous (EKS Cluster AutoScaler, Grafana, Prometheus, etc) | + 16 vCPU, 32GB | | | +| **Grand Total w/ Overheads Fully Scaled**<br />Minimum hosts = 3 | 444 vCPU, 565 GB | **c5.4xlarge** (16vcpu/32GB) x 28 nodes<br />448 vCPU, 896GB<br /><br />[Full Scale GPT Test Results](https://gitlab.com/gitlab-com/alliances/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) | $19.04/hr | +| **Possible Idle Configuration (Scaled-In 75% - round up)**<br />Pod autoscaling must be also adjusted to enable lower idling configuration. | 40 vCPU, 80 GB | c5.2xlarge x 10<br /><br />[AutoScale GPT Test Results](https://gitlab.com/gitlab-com/alliances/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) | $6.80/hr | + +Other combinations of node type and quantity can be used to meet the Grand Total. Due to the cpu and memory requirements of pods, hosts that are overly small may have significant unused capacity. + +NOTE: +If EKS node autoscaling is employed, it is likely that your average loading will run lower than this, especially during non-working hours and weekends. + +| Non-Kubernetes Compute | Ref Arch Raw Total | AWS BOM | Example Cost<br />US East, 3 AZ | Example Cost<br />US East, 2 AZ | +| ------------------------------------------------------------ | ------------------------------------------------------------ | --------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------ | +| **Bastion Host (Quick Start)** | 1 HA instance in ASG | **t2.micro** for prod, **m4.2xlarge** for perf. testing | | | +| **PostgreSQL**<br />AWS Aurora RDS Nodes Configuration (GPT tested) | 96vCPU, 360 GB <br />(across 3 nodes) | **db.r6g.8xlarge** x 3 nodes <br />(96vCPU, 768 GB total) | 3 nodes x $4.15 = $12.45/hr | 3 nodes x $4.15 = $12.45/hr<br />(Aurora is always 3) | +| **Redis** | 30vCPU, 114GB<br />(across 12 nodes for Redis Cache, Redis Queues/Shared State, Sentinel Cache, Sentinel Queues/Shared State) | **cache.m6g.2xlarge** x 3 nodes<br />(24vCPU, 78GB total) | 3 nodes x $0.60 = $1.80/hr | 2 nodes x $0.60 = $1.20/hr | +| **<u>Gitaly Cluster</u>** [Details](gitlab_sre_for_aws.md#gitaly-sre-considerations) | | | | | +| Gitaly Instances (in ASG) | 64 vCPU, 240GB x [3 nodes](gitlab_sre_for_aws.md#gitaly-and-praefect-elections) | **m5.16xlarge** x 3 nodes<br />(64 vCPU, 256 GB each) | $3.07 x 3 = $9.21/hr | [Gitaly & Praefect Must Have an Uneven Node Count for HA](gitlab_sre_for_aws.md#gitaly-and-praefect-elections) | +| Praefect (Instances in ASG with load balancer) | 4 vCPU, 3.6 GB x [3 nodes](gitlab_sre_for_aws.md#gitaly-and-praefect-elections) | **c5.xlarge** x 3 nodes<br />(4 vCPU, 8 GB each) | $0.17 x 3 = $0.51/hr | [Gitaly & Praefect Must Have an Uneven Node Count for HA](gitlab_sre_for_aws.md#gitaly-and-praefect-elections) | +| Praefect PostgreSQL(1) (AWS RDS) | 2 vCPU, 1.8 GB x [3 nodes](gitlab_sre_for_aws.md#gitaly-and-praefect-elections) | N/A Reuses GitLab PostgreSQL | $0 | | +| Internal Load Balancing Node | 2 vCPU, 1.8 GB | AWS ELB | $0.10/hr | $0.10/hr | + +## Helpful Resources + +- [Architecting Kubernetes clusters — choosing a worker node size](https://learnk8s.io/kubernetes-node-size) diff --git a/doc/install/aws/gitlab_sre_for_aws.md b/doc/install/aws/gitlab_sre_for_aws.md new file mode 100644 index 00000000000..a2d3a2d0295 --- /dev/null +++ b/doc/install/aws/gitlab_sre_for_aws.md @@ -0,0 +1,59 @@ +--- +stage: Enablement +group: Alliances +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +comments: false +description: Doing SRE for GitLab instances and runners on AWS. +type: index +--- + +# GitLab Site Reliability Engineering for AWS **(FREE SELF)** + +## Known issues list + +Known issues are gathered from within GitLab and from customer reported issues. Customers successfully implement GitLab with a variety of "as a Service" components that GitLab has not specifically been designed for, nor has ongoing testing for. While GitLab does take partner technologies very seriously, the highlighting of known issues here is a convenience for implementers and it does not imply that GitLab has targeted compatibility with, nor carries any type of guarantee of running on the partner technology where the issues occur. Please consult individual issues to understand GitLabs stance and plans on any given known issue. + +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. + +## Gitaly SRE considerations + +Gitaly and Gitaly Cluster have been engineered by GitLab to overcome fundamental challenges with horizontal scaling of the open source Git binaries. Here is indepth technical reading on the topic: + +### Why Gitaly was built + +Below are some links to better understand why Gitaly was built: + +- [Git characteristics that make horizontal scaling difficult](https://gitlab.com/gitlab-org/gitaly/-/blob/master/doc/DESIGN.md#git-characteristics-that-make-horizontal-scaling-difficult) +- [Git architectural characteristics and assumptions](https://gitlab.com/gitlab-org/gitaly/-/blob/master/doc/DESIGN.md#git-architectural-characteristics-and-assumptions) +- [Affects on horizontal compute architecture](https://gitlab.com/gitlab-org/gitaly/-/blob/master/doc/DESIGN.md#affects-on-horizontal-compute-architecture) +- [Evidence to back building a new horizontal layer to scale Git](https://gitlab.com/gitlab-org/gitaly/-/blob/master/doc/DESIGN.md#evidence-to-back-building-a-new-horizontal-layer-to-scale-git) + +### Gitaly and Praefect elections + +As part of Gitaly cluster consistency, Praefect nodes will occasionally need to vote on what data copy is the most accurate. This requires an uneven number of Praefect nodes to avoid stalemates. This means that for HA, Gitaly and Praefect require a minimum of three nodes. + +### Gitaly performance monitoring + +Complete performance metrics should be collected for Gitaly instances for identification of bottlenecks, as they could have to do with disk IO, network IO or memory. + +Gitaly must be implemented on instance compute. + +### Gitaly EBS volume sizing guidelines + +Gitaly storage is expected to be local (not NFS of any type including EFS). +Gitaly servers also need disk space for building and caching Git pack files. + +Background: + +- When not using provisioned EBS IO, EBS volume size determines the IO level, so provisioning volumes that are much larger than needed can be the least expensive way to improve EBS IO. +- Only use nitro instance types due to higher IO and EBS optimization. +- Use Amazon Linux 2 to ensure the best disk and memory optimizations (for example, ENA network adapters and drivers). +- If GitLab backup scripts are used, they need a temporary space location large enough to hold 2 times the current size of the Git File system. If that will be done on Gitaly servers, separate volumes should be used. + +### Gitaly HA in EKS quick start + +The [AWS GitLab Cloud Native Hybrid on EKS Quick Start](gitlab_hybrid_on_aws.md#available-infrastructure-as-code-for-gitlab-cloud-native-hybrid) for GitLab Cloud Native implements Gitaly as a multi-zone, self-healing infrastructure. It has specific code for reestablishing a Gitaly node when one fails, including AZ failure. + +### Gitaly long term management + +Gitaly node disk sizes will need to be monitored and increased to accommodate Git repository growth and Gitaly temporary and caching storage needs. The storage configuration on all nodes should be kept identical. diff --git a/doc/install/aws/index.md b/doc/install/aws/index.md index ca024f685f1..342b6962628 100644 --- a/doc/install/aws/index.md +++ b/doc/install/aws/index.md @@ -1,846 +1,110 @@ --- stage: Enablement -group: Distribution +group: Alliances info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: howto +comments: false +description: Read through the GitLab installation methods. +type: index --- -# Installing GitLab on Amazon Web Services (AWS) **(FREE SELF)** - -This page offers a walkthrough of a common configuration -for GitLab on AWS using the official GitLab Linux package. You should customize it to accommodate your needs. - -NOTE: -For organizations with 1,000 users or less, the recommended AWS installation method is to launch an EC2 single box [Omnibus Installation](https://about.gitlab.com/install/) and implement a snapshot strategy for backing up the data. See the [1,000 user reference architecture](../../administration/reference_architectures/1k_users.md) for more. +# AWS implementation patterns **(FREE SELF)** -## Introduction +GitLab [Reference Architectures](../../administration/reference_architectures/index.md) give qualified and tested guidance on the recommended ways GitLab can be configured to meet the performance requirements of various workloads. Reference Architectures are purpose-designed to be non-implementation specific so they can be extrapolated to as many environments as possible. This generally means they have a highly-granular "machine" to "server role" specification and focus on system elements that impact performance. This is what enables Reference Architectures to be adaptable to the broadest number of supported implementations. -For the most part, we'll make use of Omnibus GitLab in our setup, but we'll also leverage native AWS services. Instead of using the Omnibus bundled PostgreSQL and Redis, we will use AWS RDS and ElastiCache. - -In this guide, we'll go through a multi-node setup where we'll start by -configuring our Virtual Private Cloud and subnets to later integrate -services such as RDS for our database server and ElastiCache as a Redis -cluster to finally manage them within an auto scaling group with custom -scaling policies. +Implementation patterns are built on the foundational information and testing done for Reference Architectures and allow architects and implementers at GitLab, GitLab Customers, and GitLab Partners to build out deployments with less experimentation and a higher degree of confidence that the results will perform as expected. -## Requirements +## Implementation patterns information -In addition to having a basic familiarity with [AWS](https://docs.aws.amazon.com/) and [Amazon EC2](https://docs.aws.amazon.com/ec2/), you will need: +### Install GitLab Cloud Native Hybrid on AWS EKS (HA) -- [An AWS account](https://console.aws.amazon.com/console/home) -- [To create or upload an SSH key](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) - to connect to the instance via SSH -- A domain name for the GitLab instance -- An SSL/TLS certificate to secure your domain. If you do not already own one, you can provision a free public SSL/TLS certificate through [AWS Certificate Manager](https://aws.amazon.com/certificate-manager/)(ACM) for use with the [Elastic Load Balancer](#load-balancer) we'll create. +[Provision GitLab Cloud Native Hybrid on AWS EKS (HA)](gitlab_hybrid_on_aws.md). This document includes instructions, patterns, and automation for installing GitLab Cloud Native Hybrid on AWS EKS. It also includes [Bill of Materials](https://en.wikipedia.org/wiki/Bill_of_materials) listings and links to Infrastructure as Code. GitLab Cloud Native Hybrid is the supported way to put as much of GitLab as possible into Kubernetes. -NOTE: -It can take a few hours to validate a certificate provisioned through ACM. To avoid delays later, request your certificate as soon as possible. +### Install Omnibus GitLab on AWS EC2 (HA) -## Architecture +[Omnibus GitLab on AWS EC2 (HA)](manual_install_aws.md) - instructions for installing GitLab on EC2 instances. Manual instructions from which you may build out a GitLab instance or create your own Infrastructure as Code (IaC). -Below is a diagram of the recommended architecture. +### GitLab Site Reliability Engineering (SRE) for AWS - +[GitLab SRE Considerations for AWS](gitlab_sre_for_aws.md) - important information and known issues for planning, implementing, upgrading and long term management of GitLab instances and runners on AWS. -## AWS costs +### EKS cluster provisioning best practices -GitLab uses the following AWS services, with links to pricing information: +[EKS Cluster Provisioning Patterns](eks_clusters_aws.md) - considerations for setting up EKS cluster for runners and for integrating. -- **EC2**: GitLab is deployed on shared hardware, for which - [on-demand pricing](https://aws.amazon.com/ec2/pricing/on-demand/) applies. - If you want to run GitLab on a dedicated or reserved instance, see the - [EC2 pricing page](https://aws.amazon.com/ec2/pricing/) for information about - its cost. -- **S3**: GitLab uses S3 ([pricing page](https://aws.amazon.com/s3/pricing/)) to - store backups, artifacts, and LFS objects. -- **ELB**: A Classic Load Balancer ([pricing page](https://aws.amazon.com/elasticloadbalancing/pricing/)), - used to route requests to the GitLab instances. -- **RDS**: An Amazon Relational Database Service using PostgreSQL - ([pricing page](https://aws.amazon.com/rds/postgresql/pricing/)). -- **ElastiCache**: An in-memory cache environment ([pricing page](https://aws.amazon.com/elasticache/pricing/)), - used to provide a Redis configuration. +### Scaling HA GitLab Runner on AWS EC2 ASG -## Create an IAM EC2 instance role and profile +The following repository is self-contained in regard to enabling this pattern: [GitLab HA Scaling Runner Vending Machine for AWS EC2 ASG](https://gitlab.com/guided-explorations/aws/gitlab-runner-autoscaling-aws-asg/). The [feature list for this implementation pattern](https://gitlab.com/guided-explorations/aws/gitlab-runner-autoscaling-aws-asg/-/blob/main/FEATURES.md) is good to review to understand the complete value it can deliver. -As we'll be using [Amazon S3 object storage](#amazon-s3-object-storage), our EC2 instances need to have read, write, and list permissions for our S3 buckets. To avoid embedding AWS keys in our GitLab configuration, we'll make use of an [IAM Role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) to allow our GitLab instance with this access. We'll need to create an IAM policy to attach to our IAM role: +## Additional details on implementation patterns -### Create an IAM Policy +GitLab implementation patterns build upon [GitLab Reference Architectures](../../administration/reference_architectures/index.md) in the following ways. -1. Navigate to the IAM dashboard and click on **Policies** in the left menu. -1. Click **Create policy**, select the `JSON` tab, and add a policy. We want to [follow security best practices and grant _least privilege_](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege), giving our role only the permissions needed to perform the required actions. - 1. Assuming you prefix the S3 bucket names with `gl-` as shown in the diagram, add the following policy: +### Cloud platform well architected compliance - ```json - { "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "s3:PutObject", - "s3:GetObject", - "s3:DeleteObject", - "s3:PutObjectAcl" - ], - "Resource": "arn:aws:s3:::gl-*/*" - }, - { - "Effect": "Allow", - "Action": [ - "s3:ListBucket", - "s3:AbortMultipartUpload", - "s3:ListMultipartUploadParts", - "s3:ListBucketMultipartUploads" - ], - "Resource": "arn:aws:s3:::gl-*" - } - ] - } - ``` +Testing-backed architectural qualification is a fundamental concept behind implementation patterns: -1. Click **Review policy**, give your policy a name (we'll use `gl-s3-policy`), and click **Create policy**. +- Implementation patterns maintain GitLab Reference Architecture compliance and provide [GitLab Performance Tool](https://gitlab.com/gitlab-org/quality/performance) (gpt) reports to demonstrate adherence to them. +- Implementation patterns may be qualified by and/or contributed to by the technology vendor. For instance, an implementation pattern for AWS may be officially reviewed by AWS. +- Implementation patterns may specify and test Cloud Platform PaaS services for suitability for GitLab. This testing can be coordinated and help qualify these technologies for Reference Architectures. For instance, qualifying compatibility with and availability of runtime versions of top level PaaS such as those for PostgreSQL and Redis. +- Implementation patterns can provided qualified testing for platform limitations, for example, ensuring Gitaly Cluster can work correctly on specific Cloud Platform availability zone latency and throughput characteristics or qualifying what levels of available platform partner local disk performance is workable for Gitaly server to operate with integrity. -### Create an IAM Role +### Platform partner specificity -1. Still on the IAM dashboard, click on **Roles** in the left menu, and - click **Create role**. -1. Create a new role by selecting **AWS service > EC2**, then click - **Next: Permissions**. -1. In the policy filter, search for the `gl-s3-policy` we created above, select it, and click **Tags**. -1. Add tags if needed and click **Review**. -1. Give the role a name (we'll use `GitLabS3Access`) and click **Create Role**. +Implementation patterns enable platform-specific terminology, best practice architecture, and platform-specific build manifests: -We'll use this role when we [create a launch configuration](#create-a-launch-configuration) later on. +- Implementation patterns are more vendor specific. For instance, advising specific compute instances / VMs / nodes instead of vCPUs or other generalized measures. +- Implementation patterns are oriented to implementing good architecture for the vendor in view. +- Implementation patterns are written to an audience who is familiar with building on the infrastructure that the implementation pattern targets. For example, if the implementation pattern is for GCP, the specific terminology of GCP is used - including using the specific names for PaaS services. +- Implementation patterns can test and qualify if the versions of PaaS available are compatible with GitLab (for example, PostgreSQL, Redis, etc.). -## Configuring the network +### Platform as a Service (PaaS) specification and usage -We'll start by creating a VPC for our GitLab cloud infrastructure, then -we can create subnets to have public and private instances in at least -two [Availability Zones (AZs)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html). Public subnets will require a Route Table keep and an associated -Internet Gateway. +Platform as a Service options are a huge portion of the value provided by Cloud Platforms as they simplify operational complexity and reduce the SRE and security skilling required to operate advanced, highly available technology services. Implementation patterns can be prequalified against the partner PaaS options. -### Creating the Virtual Private Cloud (VPC) +- Implementation patterns help implementers understand what PaaS options are known to work and how to choose between PaaS solutions when a single platform has more than one PaaS option for the same GitLab role (for example, AWS RDS versus AWS Aurora RDS). +- For instance, where reference architectures do not have a specific recommendation on what technology is leveraged for GitLab outbound email services or what the sizing should be - a Reference Implementation may advise using a cloud providers Email as a Service (PaaS) and possibly even with specific settings. -We'll now create a VPC, a virtual networking environment that you'll control: +### Cost optimizing engineering -1. Sign in to [Amazon Web Services](https://console.aws.amazon.com/vpc/home). -1. Select **Your VPCs** from the left menu and then click **Create VPC**. - At the "Name tag" enter `gitlab-vpc` and at the "IPv4 CIDR block" enter - `10.0.0.0/16`. If you don't require dedicated hardware, you can leave - "Tenancy" as default. Click **Yes, Create** when ready. +Cost engineering is a fundamental aspect of Cloud Architecture and frequently the savings capabilities available on a platform exert strong influence on how to build out scaled computing. -  +- Implementation patterns may define GPT tested autoscaling for various aspects of GitLab infrastructure, including minimum idling configurations and scaling speeds. +- Implementation patterns may provide GPT testing for advised configurations that go beyond the scope of reference architectures, for instance GPT tested elastic scaling configurations for Cloud Native Hybrid that enable lower resourcing during periods of lower usage (for example on the weekend). +- Implementation patterns may engineer specifically for the savings models available on a platform provider. An AWS example would be maximizing the occurrence of a specific instance type for taking advantage of reserved instances. +- Implementation patterns may leverage ephemeral compute where appropriate and with appropriate customer guidelines. For instance, a Kubernetes node group dedicated to runners on ephemeral compute (with appropriate GitLab Runner tagging to indicate the compute type). +- Implementation patterns may include vendor specific cost calculators. -1. Select the VPC, click **Actions**, click **Edit DNS resolution**, and enable DNS resolution. Hit **Save** when done. +### Actionability and automatability orientation -### Subnets +Implementation patterns are one step closer to specifics that can be used as a source for build instructions and automation code: -Now, let's create some subnets in different Availability Zones. Make sure -that each subnet is associated to the VPC we just created and -that CIDR blocks don't overlap. This will also -allow us to enable multi AZ for redundancy. +- Implementation patterns enable builders to generate a list of vendor specific resources required to implement GitLab for a given Reference Architecture. +- Implementation patterns enable builders to use manual instructions or to create automation to build out the reference implementation. -We will create private and public subnets to match load balancers and -RDS instances as well: +## Supplementary implementation patterns -1. Select **Subnets** from the left menu. -1. Click **Create subnet**. Give it a descriptive name tag based on the IP, - for example `gitlab-public-10.0.0.0`, select the VPC we created previously, select an availability zone (we'll use `us-west-2a`), - and at the IPv4 CIDR block let's give it a 24 subnet `10.0.0.0/24`: - -  - -1. Follow the same steps to create all subnets: - - | Name tag | Type | Availability Zone | CIDR block | - | ------------------------- | ------- | ----------------- | ------------- | - | `gitlab-public-10.0.0.0` | public | `us-west-2a` | `10.0.0.0/24` | - | `gitlab-private-10.0.1.0` | private | `us-west-2a` | `10.0.1.0/24` | - | `gitlab-public-10.0.2.0` | public | `us-west-2b` | `10.0.2.0/24` | - | `gitlab-private-10.0.3.0` | private | `us-west-2b` | `10.0.3.0/24` | +Implementation patterns may also provide specialized implementations beyond the scope of reference architecture compliance, especially where the cost of enablement can be more appropriately managed. -1. Once all the subnets are created, enable **Auto-assign IPv4** for the two public subnets: - 1. Select each public subnet in turn, click **Actions**, and click **Modify auto-assign IP settings**. Enable the option and save. - -### Internet Gateway - -Now, still on the same dashboard, go to Internet Gateways and -create a new one: +For example: -1. Select **Internet Gateways** from the left menu. -1. Click **Create internet gateway**, give it the name `gitlab-gateway` and - click **Create**. -1. Select it from the table, and then under the **Actions** dropdown choose - "Attach to VPC". - -  - -1. Choose `gitlab-vpc` from the list and hit **Attach**. - -### Create NAT Gateways - -Instances deployed in our private subnets need to connect to the internet for updates, but should not be reachable from the public internet. To achieve this, we'll make use of [NAT Gateways](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html) deployed in each of our public subnets: - -1. Navigate to the VPC dashboard and click on **NAT Gateways** in the left menu bar. -1. Click **Create NAT Gateway** and complete the following: - 1. **Subnet**: Select `gitlab-public-10.0.0.0` from the dropdown. - 1. **Elastic IP Allocation ID**: Enter an existing Elastic IP or click **Allocate Elastic IP address** to allocate a new IP to your NAT gateway. - 1. Add tags if needed. - 1. Click **Create NAT Gateway**. +- Small, self-contained GitLab instances for per-person admin training, perhaps on Kubernetes so that a deployment cluster is self-contained as well. +- GitLab Runner implementation patterns, including using platform-specific PaaS. -Create a second NAT gateway but this time place it in the second public subnet, `gitlab-public-10.0.2.0`. +## Intended audiences and contributors -### Route Tables +The primary audiences for and contributors to this information is the GitLab **Implementation Eco System** which consists of at least: -#### Public Route Table +GitLab Implementation Community: -We need to create a route table for our public subnets to reach the internet via the internet gateway we created in the previous step. +- Customers +- GitLab Channel Partners (Integrators) +- Platform Partners -On the VPC dashboard: +GitLab Internal Implementation Teams: -1. Select **Route Tables** from the left menu. -1. Click **Create Route Table**. -1. At the "Name tag" enter `gitlab-public` and choose `gitlab-vpc` under "VPC". -1. Click **Create**. - -We now need to add our internet gateway as a new target and have -it receive traffic from any destination. - -1. Select **Route Tables** from the left menu and select the `gitlab-public` - route to show the options at the bottom. -1. Select the **Routes** tab, click **Edit routes > Add route** and set `0.0.0.0/0` - as the destination. In the target column, select the `gitlab-gateway` we created previously. - Hit **Save routes** once done. - -Next, we must associate the **public** subnets to the route table: - -1. Select the **Subnet Associations** tab and click **Edit subnet associations**. -1. Check only the public subnets and click **Save**. - -#### Private Route Tables - -We also need to create two private route tables so that instances in each private subnet can reach the internet via the NAT gateway in the corresponding public subnet in the same availability zone. - -1. Follow the same steps as above to create two private route tables. Name them `gitlab-private-a` and `gitlab-private-b` respectively. -1. Next, add a new route to each of the private route tables where the destination is `0.0.0.0/0` and the target is one of the NAT gateways we created earlier. - 1. Add the NAT gateway we created in `gitlab-public-10.0.0.0` as the target for the new route in the `gitlab-private-a` route table. - 1. Similarly, add the NAT gateway in `gitlab-public-10.0.2.0` as the target for the new route in the `gitlab-private-b`. -1. Lastly, associate each private subnet with a private route table. - 1. Associate `gitlab-private-10.0.1.0` with `gitlab-private-a`. - 1. Associate `gitlab-private-10.0.3.0` with `gitlab-private-b`. - -## Load Balancer - -We'll create a load balancer to evenly distribute inbound traffic on ports `80` and `443` across our GitLab application servers. Based the on the [scaling policies](#create-an-auto-scaling-group) we'll create later, instances will be added to or removed from our load balancer as needed. Additionally, the load balance will perform health checks on our instances. - -On the EC2 dashboard, look for Load Balancer in the left navigation bar: - -1. Click the **Create Load Balancer** button. - 1. Choose the **Classic Load Balancer**. - 1. Give it a name (we'll use `gitlab-loadbalancer`) and for the **Create LB Inside** option, select `gitlab-vpc` from the dropdown menu. - 1. In the **Listeners** section, set the following listeners: - - HTTP port 80 for both load balancer and instance protocol and ports - - TCP port 22 for both load balancer and instance protocols and ports - - HTTPS port 443 for load balancer protocol and ports, forwarding to HTTP port 80 on the instance (we will configure GitLab to listen on port 80 [later in the guide](#add-support-for-proxied-ssl)) - 1. In the **Select Subnets** section, select both public subnets from the list so that the load balancer can route traffic to both availability zones. -1. We'll add a security group for our load balancer to act as a firewall to control what traffic is allowed through. Click **Assign Security Groups** and select **Create a new security group**, give it a name - (we'll use `gitlab-loadbalancer-sec-group`) and description, and allow both HTTP and HTTPS traffic - from anywhere (`0.0.0.0/0, ::/0`). Also allow SSH traffic, select a custom source, and add a single trusted IP address or an IP address range in CIDR notation. This will allow users to perform Git actions over SSH. -1. Click **Configure Security Settings** and set the following: - 1. Select an SSL/TLS certificate from ACM or upload a certificate to IAM. - 1. Under **Select a Cipher**, pick a predefined security policy from the dropdown. You can see a breakdown of [Predefined SSL Security Policies for Classic Load Balancers](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-security-policy-table.html) in the AWS docs. Check the GitLab codebase for a list of [supported SSL ciphers and protocols](https://gitlab.com/gitlab-org/gitlab/-/blob/9ee7ad433269b37251e0dd5b5e00a0f00d8126b4/lib/support/nginx/gitlab-ssl#L97-99). -1. Click **Configure Health Check** and set up a health check for your EC2 instances. - 1. For **Ping Protocol**, select HTTP. - 1. For **Ping Port**, enter 80. - 1. For **Ping Path**, enter `/users/sign_in`. (We use `/users/sign_in` as it's a public endpoint that does - not require authentication.) - 1. Keep the default **Advanced Details** or adjust them according to your needs. -1. Click **Add EC2 Instances** - don't add anything as we will create an Auto Scaling Group later to manage instances for us. -1. Click **Add Tags** and add any tags you need. -1. Click **Review and Create**, review all your settings, and click **Create** if you're happy. - -After the Load Balancer is up and running, you can revisit your Security -Groups to refine the access only through the ELB and any other requirements -you might have. - -### Configure DNS for Load Balancer - -On the Route 53 dashboard, click **Hosted zones** in the left navigation bar: - -1. Select an existing hosted zone or, if you do not already have one for your domain, click **Create Hosted Zone**, enter your domain name, and click **Create**. -1. Click **Create Record Set** and provide the following values: - 1. **Name:** Use the domain name (the default value) or enter a subdomain. - 1. **Type:** Select **A - IPv4 address**. - 1. **Alias:** Defaults to **No**. Select **Yes**. - 1. **Alias Target:** Find the **ELB Classic Load Balancers** section and select the classic load balancer we created earlier. - 1. **Routing Policy:** We'll use **Simple** but you can choose a different policy based on your use case. - 1. **Evaluate Target Health:** We'll set this to **No** but you can choose to have the load balancer route traffic based on target health. - 1. Click **Create**. -1. If you registered your domain through Route 53, you're done. If you used a different domain registrar, you need to update your DNS records with your domain registrar. You'll need to: - 1. Click on **Hosted zones** and select the domain you added above. - 1. You'll see a list of `NS` records. From your domain registrar's administrator panel, add each of these as `NS` records to your domain's DNS records. These steps may vary between domain registrars. If you're stuck, Google **"name of your registrar" add DNS records** and you should find a help article specific to your domain registrar. - -The steps for doing this vary depending on which registrar you use and is beyond the scope of this guide. - -## PostgreSQL with RDS - -For our database server we will use Amazon RDS which offers Multi AZ -for redundancy. First we'll create a security group and subnet group, then we'll -create the actual RDS instance. - -### RDS Security Group - -We need a security group for our database that will allow inbound traffic from the instances we'll deploy in our `gitlab-loadbalancer-sec-group` later on: - -1. From the EC2 dashboard, select **Security Groups** from the left menu bar. -1. Click **Create security group**. -1. Give it a name (we'll use `gitlab-rds-sec-group`), a description, and select the `gitlab-vpc` from the **VPC** dropdown. -1. In the **Inbound rules** section, click **Add rule** and set the following: - 1. **Type:** search for and select the **PostgreSQL** rule. - 1. **Source type:** set as "Custom". - 1. **Source:** select the `gitlab-loadbalancer-sec-group` we created earlier. -1. When done, click **Create security group**. - -### RDS Subnet Group - -1. Navigate to the RDS dashboard and select **Subnet Groups** from the left menu. -1. Click on **Create DB Subnet Group**. -1. Under **Subnet group details**, enter a name (we'll use `gitlab-rds-group`), a description, and choose the `gitlab-vpc` from the VPC dropdown. -1. From the **Availability Zones** dropdown, select the Availability Zones that include the subnets you've configured. In our case, we'll add `eu-west-2a` and `eu-west-2b`. -1. From the **Subnets** dropdown, select the two private subnets (`10.0.1.0/24` and `10.0.3.0/24`) as we defined them in the [subnets section](#subnets). -1. Click **Create** when ready. - -### Create the database - -WARNING: -Avoid using burstable instances (t class instances) for the database as this could lead to performance issues due to CPU credits running out during sustained periods of high load. - -Now, it's time to create the database: - -1. Navigate to the RDS dashboard, select **Databases** from the left menu, and click **Create database**. -1. Select **Standard Create** for the database creation method. -1. Select **PostgreSQL** as the database engine and select the minimum PostgreSQL version as defined for your GitLab version in our [database requirements](../../install/requirements.md#postgresql-requirements). -1. Since this is a production server, let's choose **Production** from the **Templates** section. -1. Under **Settings**, set a DB instance identifier, a master username, and a master password. We'll use `gitlab-db-ha`, `gitlab`, and a very secure password respectively. Make a note of these as we'll need them later. -1. For the DB instance size, select **Standard classes** and select an instance size that meets your requirements from the dropdown menu. We'll use a `db.m4.large` instance. -1. Under **Storage**, configure the following: - 1. Select **Provisioned IOPS (SSD)** from the storage type dropdown menu. Provisioned IOPS (SSD) storage is best suited for this use (though you can choose General Purpose (SSD) to reduce the costs). Read more about it at [Storage for Amazon RDS](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_Storage.html). - 1. Allocate storage and set provisioned IOPS. We'll use the minimum values, `100` and `1000`, respectively. - 1. Enable storage autoscaling (optional) and set a maximum storage threshold. -1. Under **Availability & durability**, select **Create a standby instance** to have a standby RDS instance provisioned in a different [Availability Zone](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.MultiAZ.html). -1. Under **Connectivity**, configure the following: - 1. Select the VPC we created earlier (`gitlab-vpc`) from the **Virtual Private Cloud (VPC)** dropdown menu. - 1. Expand the **Additional connectivity configuration** section and select the subnet group (`gitlab-rds-group`) we created earlier. - 1. Set public accessibility to **No**. - 1. Under **VPC security group**, select **Choose existing** and select the `gitlab-rds-sec-group` we create above from the dropdown. - 1. Leave the database port as the default `5432`. -1. For **Database authentication**, select **Password authentication**. -1. Expand the **Additional configuration** section and complete the following: - 1. The initial database name. We'll use `gitlabhq_production`. - 1. Configure your preferred backup settings. - 1. The only other change we'll make here is to disable auto minor version updates under **Maintenance**. - 1. Leave all the other settings as is or tweak according to your needs. - 1. Once you're happy, click **Create database**. - -Now that the database is created, let's move on to setting up Redis with ElastiCache. - -## Redis with ElastiCache - -ElastiCache is an in-memory hosted caching solution. Redis maintains its own -persistence and is used to store session data, temporary cache information, and background job queues for the GitLab application. - -### Create a Redis Security Group - -1. Navigate to the EC2 dashboard. -1. Select **Security Groups** from the left menu. -1. Click **Create security group** and fill in the details. Give it a name (we'll use `gitlab-redis-sec-group`), - add a description, and choose the VPC we created previously -1. In the **Inbound rules** section, click **Add rule** and add a **Custom TCP** rule, set port `6379`, and set the "Custom" source as the `gitlab-loadbalancer-sec-group` we created earlier. -1. When done, click **Create security group**. - -### Redis Subnet Group - -1. Navigate to the ElastiCache dashboard from your AWS console. -1. Go to **Subnet Groups** in the left menu, and create a new subnet group (we'll name ours `gitlab-redis-group`). - Make sure to select our VPC and its [private subnets](#subnets). Click - **Create** when ready. - -  - -### Create the Redis Cluster - -1. Navigate back to the ElastiCache dashboard. -1. Select **Redis** on the left menu and click **Create** to create a new - Redis cluster. Do not enable **Cluster Mode** as it is [not supported](../../administration/redis/replication_and_failover_external.md#requirements). Even without cluster mode on, you still get the - chance to deploy Redis in multiple availability zones. -1. In the settings section: - 1. Give the cluster a name (`gitlab-redis`) and a description. - 1. For the version, select the latest of `5.0` series (e.g., `5.0.6`). - 1. Leave the port as `6379` since this is what we used in our Redis security group above. - 1. Select the node type (at least `cache.t3.medium`, but adjust to your needs) and the number of replicas. -1. In the advanced settings section: - 1. Select the multi-AZ auto-failover option. - 1. Select the subnet group we created previously. - 1. Manually select the preferred availability zones, and under "Replica 2" - choose a different zone than the other two. - -  - -1. In the security settings, edit the security groups and choose the - `gitlab-redis-sec-group` we had previously created. -1. Leave the rest of the settings to their default values or edit to your liking. -1. When done, click **Create**. - -## Setting up Bastion Hosts - -Since our GitLab instances will be in private subnets, we need a way to connect to these instances via SSH to make configuration changes, perform upgrades, etc. One way of doing this is via a [bastion host](https://en.wikipedia.org/wiki/Bastion_host), sometimes also referred to as a jump box. - -NOTE: -If you do not want to maintain bastion hosts, you can set up [AWS Systems Manager Session Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager.html) for access to instances. This is beyond the scope of this document. - -### Create Bastion Host A - -1. Navigate to the EC2 Dashboard and click on **Launch instance**. -1. Select the **Ubuntu Server 18.04 LTS (HVM)** AMI. -1. Choose an instance type. We'll use a `t2.micro` as we'll only use the bastion host to SSH into our other instances. -1. Click **Configure Instance Details**. - 1. Under **Network**, select the `gitlab-vpc` from the dropdown menu. - 1. Under **Subnet**, select the public subnet we created earlier (`gitlab-public-10.0.0.0`). - 1. Double check that under **Auto-assign Public IP** you have **Use subnet setting (Enable)** selected. - 1. Leave everything else as default and click **Add Storage**. -1. For storage, we'll leave everything as default and only add an 8GB root volume. We won't store anything on this instance. -1. Click **Add Tags** and on the next screen click **Add Tag**. - 1. We'll only set `Key: Name` and `Value: Bastion Host A`. -1. Click **Configure Security Group**. - 1. Select **Create a new security group**, enter a **Security group name** (we'll use `bastion-sec-group`), and add a description. - 1. We'll enable SSH access from anywhere (`0.0.0.0/0`). If you want stricter security, specify a single IP address or an IP address range in CIDR notation. - 1. Click **Review and Launch** -1. Review all your settings and, if you're happy, click **Launch**. -1. Acknowledge that you have access to an existing key pair or create a new one. Click **Launch Instance**. - -Confirm that you can SSH into the instance: - -1. On the EC2 Dashboard, click on **Instances** in the left menu. -1. Select **Bastion Host A** from your list of instances. -1. Click **Connect** and follow the connection instructions. -1. If you are able to connect successfully, let's move on to setting up our second bastion host for redundancy. - -### Create Bastion Host B - -1. Create an EC2 instance following the same steps as above with the following changes: - 1. For the **Subnet**, select the second public subnet we created earlier (`gitlab-public-10.0.2.0`). - 1. Under the **Add Tags** section, we'll set `Key: Name` and `Value: Bastion Host B` so that we can easily identify our two instances. - 1. For the security group, select the existing `bastion-sec-group` we created above. - -### Use SSH Agent Forwarding - -EC2 instances running Linux use private key files for SSH authentication. You'll connect to your bastion host using an SSH client and the private key file stored on your client. Since the private key file is not present on the bastion host, you will not be able to connect to your instances in private subnets. - -Storing private key files on your bastion host is a bad idea. To get around this, use SSH agent forwarding on your client. See [Securely Connect to Linux Instances Running in a Private Amazon VPC](https://aws.amazon.com/blogs/security/securely-connect-to-linux-instances-running-in-a-private-amazon-vpc/) for a step-by-step guide on how to use SSH agent forwarding. - -## Install GitLab and create custom AMI - -We will need a preconfigured, custom GitLab AMI to use in our launch configuration later. As a starting point, we will use the official GitLab AMI to create a GitLab instance. Then, we'll add our custom configuration for PostgreSQL, Redis, and Gitaly. If you prefer, instead of using the official GitLab AMI, you can also spin up an EC2 instance of your choosing and [manually install GitLab](https://about.gitlab.com/install/). - -### Install GitLab - -From the EC2 dashboard: - -1. Use the section below titled "[Find official GitLab-created AMI IDs on AWS](#find-official-gitlab-created-ami-ids-on-aws)" to find the correct AMI to launch. -1. After clicking **Launch** on the desired AMI, select an instance type based on your workload. Consult the [hardware requirements](../../install/requirements.md#hardware-requirements) to choose one that fits your needs (at least `c5.xlarge`, which is sufficient to accommodate 100 users). -1. Click **Configure Instance Details**: - 1. In the **Network** dropdown, select `gitlab-vpc`, the VPC we created earlier. - 1. In the **Subnet** dropdown, select `gitlab-private-10.0.1.0` from the list of subnets we created earlier. - 1. Double check that **Auto-assign Public IP** is set to `Use subnet setting (Disable)`. - 1. Click **Add Storage**. - 1. The root volume is 8GiB by default and should be enough given that we won't store any data there. -1. Click **Add Tags** and add any tags you may need. In our case, we'll only set `Key: Name` and `Value: GitLab`. -1. Click **Configure Security Group**. Check **Select an existing security group** and select the `gitlab-loadbalancer-sec-group` we created earlier. -1. Click **Review and launch** followed by **Launch** if you're happy with your settings. -1. Finally, acknowledge that you have access to the selected private key file or create a new one. Click **Launch Instances**. - -### Add custom configuration - -Connect to your GitLab instance via **Bastion Host A** using [SSH Agent Forwarding](#use-ssh-agent-forwarding). Once connected, add the following custom configuration: - -#### Disable Let's Encrypt - -Since we're adding our SSL certificate at the load balancer, we do not need the GitLab built-in support for Let's Encrypt. Let's Encrypt [is enabled by default](https://docs.gitlab.com/omnibus/settings/ssl.html#lets-encrypt-integration) when using an `https` domain in GitLab 10.7 and later, so we need to explicitly disable it: - -1. Open `/etc/gitlab/gitlab.rb` and disable it: - - ```ruby - letsencrypt['enable'] = false - ``` - -1. Save the file and reconfigure for the changes to take effect: - - ```shell - sudo gitlab-ctl reconfigure - ``` - -#### Install the required extensions for PostgreSQL - -From your GitLab instance, connect to the RDS instance to verify access and to install the required `pg_trgm` and `btree_gist` extensions. - -To find the host or endpoint, navigate to **Amazon RDS > Databases** and click on the database you created earlier. Look for the endpoint under the **Connectivity & security** tab. - -Do not to include the colon and port number: - -```shell -sudo /opt/gitlab/embedded/bin/psql -U gitlab -h <rds-endpoint> -d gitlabhq_production -``` - -At the `psql` prompt create the extension and then quit the session: - -```shell -psql (10.9) -Type "help" for help. - -gitlab=# CREATE EXTENSION pg_trgm; -gitlab=# CREATE EXTENSION btree_gist; -gitlab=# \q -``` - -#### Configure GitLab to connect to PostgreSQL and Redis - -1. Edit `/etc/gitlab/gitlab.rb`, find the `external_url 'http://<domain>'` option - and change it to the `https` domain you will be using. - -1. Look for the GitLab database settings and uncomment as necessary. In - our current case we'll specify the database adapter, encoding, host, name, - username, and password: - - ```ruby - # Disable the built-in Postgres - postgresql['enable'] = false - - # Fill in the connection details - gitlab_rails['db_adapter'] = "postgresql" - gitlab_rails['db_encoding'] = "unicode" - gitlab_rails['db_database'] = "gitlabhq_production" - gitlab_rails['db_username'] = "gitlab" - gitlab_rails['db_password'] = "mypassword" - gitlab_rails['db_host'] = "<rds-endpoint>" - ``` - -1. Next, we need to configure the Redis section by adding the host and - uncommenting the port: - - ```ruby - # Disable the built-in Redis - redis['enable'] = false - - # Fill in the connection details - gitlab_rails['redis_host'] = "<redis-endpoint>" - gitlab_rails['redis_port'] = 6379 - ``` - -1. Finally, reconfigure GitLab for the changes to take effect: - - ```shell - sudo gitlab-ctl reconfigure - ``` - -1. You might also find it useful to run a check and a service status to make sure - everything has been setup correctly: - - ```shell - sudo gitlab-rake gitlab:check - sudo gitlab-ctl status - ``` - -#### Set up Gitaly - -WARNING: -In this architecture, having a single Gitaly server creates a single point of failure. Use -[Gitaly Cluster](../../administration/gitaly/praefect.md) to remove this limitation. - -Gitaly is a service that provides high-level RPC access to Git repositories. -It should be enabled and configured on a separate EC2 instance in one of the -[private subnets](#subnets) we configured previously. - -Let's create an EC2 instance where we'll install Gitaly: - -1. From the EC2 dashboard, click **Launch instance**. -1. Choose an AMI. In this example, we'll select the **Ubuntu Server 18.04 LTS (HVM), SSD Volume Type**. -1. Choose an instance type. We'll pick a `c5.xlarge`. -1. Click **Configure Instance Details**. - 1. In the **Network** dropdown, select `gitlab-vpc`, the VPC we created earlier. - 1. In the **Subnet** dropdown, select `gitlab-private-10.0.1.0` from the list of subnets we created earlier. - 1. Double check that **Auto-assign Public IP** is set to `Use subnet setting (Disable)`. - 1. Click **Add Storage**. -1. Increase the Root volume size to `20 GiB` and change the **Volume Type** to `Provisoned IOPS SSD (io1)`. (This is an arbitrary size. Create a volume big enough for your repository storage requirements.) - 1. For **IOPS** set `1000` (20 GiB x 50 IOPS). You can provision up to 50 IOPS per GiB. If you select a larger volume, increase the IOPS accordingly. Workloads where many small files are written in a serialized manner, like `git`, requires performant storage, hence the choice of `Provisoned IOPS SSD (io1)`. -1. Click on **Add Tags** and add your tags. In our case, we'll only set `Key: Name` and `Value: Gitaly`. -1. Click on **Configure Security Group** and let's **Create a new security group**. - 1. Give your security group a name and description. We'll use `gitlab-gitaly-sec-group` for both. - 1. Create a **Custom TCP** rule and add port `8075` to the **Port Range**. For the **Source**, select the `gitlab-loadbalancer-sec-group`. - 1. Also add an inbound rule for SSH from the `bastion-sec-group` so that we can connect using [SSH Agent Forwarding](#use-ssh-agent-forwarding) from the Bastion hosts. -1. Click **Review and launch** followed by **Launch** if you're happy with your settings. -1. Finally, acknowledge that you have access to the selected private key file or create a new one. Click **Launch Instances**. - -NOTE: -Instead of storing configuration _and_ repository data on the root volume, you can also choose to add an additional EBS volume for repository storage. Follow the same guidance as above. See the [Amazon EBS pricing](https://aws.amazon.com/ebs/pricing/). We do not recommend using EFS as it may negatively impact the performance of GitLab. You can review the [relevant documentation](../../administration/nfs.md#avoid-using-cloud-based-file-systems) for more details. - -Now that we have our EC2 instance ready, follow the [documentation to install GitLab and set up Gitaly on its own server](../../administration/gitaly/configure_gitaly.md#run-gitaly-on-its-own-server). Perform the client setup steps from that document on the [GitLab instance we created](#install-gitlab) above. - -#### Add Support for Proxied SSL - -As we are terminating SSL at our [load balancer](#load-balancer), follow the steps at [Supporting proxied SSL](https://docs.gitlab.com/omnibus/settings/nginx.html#supporting-proxied-ssl) to configure this in `/etc/gitlab/gitlab.rb`. - -Remember to run `sudo gitlab-ctl reconfigure` after saving the changes to the `gitlab.rb` file. - -#### Fast lookup of authorized SSH keys - -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. Since we do not have shared storage in our setup, we'll 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. - -If you do not configure fast lookup, Git actions over SSH will result in the following error: - -```shell -Permission denied (publickey). -fatal: Could not read from remote repository. - -Please make sure you have the correct access rights -and the repository exists. -``` - -#### Configure host keys - -Ordinarily we would manually copy the contents (primary and public keys) of `/etc/ssh/` on the primary application server to `/etc/ssh` on all secondary servers. This prevents false man-in-the-middle-attack alerts when accessing servers in your cluster behind a load balancer. - -We'll automate this by creating static host keys as part of our custom AMI. As these host keys are also rotated every time an EC2 instance boots up, "hard coding" them into our custom AMI serves as a handy workaround. - -On your GitLab instance run the following: - -```shell -sudo mkdir /etc/ssh_static -sudo cp -R /etc/ssh/* /etc/ssh_static -``` - -In `/etc/ssh/sshd_config` update the following: - -```shell -# HostKeys for protocol version 2 -HostKey /etc/ssh_static/ssh_host_rsa_key -HostKey /etc/ssh_static/ssh_host_dsa_key -HostKey /etc/ssh_static/ssh_host_ecdsa_key -HostKey /etc/ssh_static/ssh_host_ed25519_key -``` - -#### Amazon S3 object storage - -Since we're not using NFS for shared storage, we will use [Amazon S3](https://aws.amazon.com/s3/) buckets to store backups, artifacts, LFS objects, uploads, merge request diffs, container registry images, and more. Our documentation includes [instructions on how to configure object storage](../../administration/object_storage.md) for each of these data types, and other information about using object storage with GitLab. - -NOTE: -Since we are using the [AWS IAM profile](#create-an-iam-role) we created earlier, be sure to omit the AWS access key and secret access key/value pairs when configuring object storage. Instead, use `'use_iam_profile' => true` in your configuration as shown in the object storage documentation linked above. - -Remember to run `sudo gitlab-ctl reconfigure` after saving the changes to the `gitlab.rb` file. - -NOTE: -One current feature of GitLab that still requires a shared directory (NFS) is -[GitLab Pages](../../user/project/pages/index.md). -There is [work in progress](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/196) -to eliminate the need for NFS to support GitLab Pages. - ---- - -That concludes the configuration changes for our GitLab instance. Next, we'll create a custom AMI based on this instance to use for our launch configuration and auto scaling group. - -### Log in for the first time - -Using the domain name you used when setting up [DNS for the load balancer](#configure-dns-for-load-balancer), you should now be able to visit GitLab in your browser. -If you didn't change the password by any other means, the default password will be the same as the instance ID. To change the default password, login as the `root` user -with the default password and [change it in the user profile](../../user/profile#change-your-password). - -When our [auto scaling group](#create-an-auto-scaling-group) spins up new instances, we'll be able to log in with username `root` and the newly created password. - -### Create custom AMI - -On the EC2 dashboard: - -1. Select the `GitLab` instance we [created earlier](#install-gitlab). -1. Click on **Actions**, scroll down to **Image** and click **Create Image**. -1. Give your image a name and description (we'll use `GitLab-Source` for both). -1. Leave everything else as default and click **Create Image** - -Now we have a custom AMI that we'll use to create our launch configuration the next step. - -## Deploy GitLab inside an auto scaling group - -### Create a launch configuration - -From the EC2 dashboard: - -1. Select **Launch Configurations** from the left menu and click **Create launch configuration**. -1. Select **My AMIs** from the left menu and select the `GitLab` custom AMI we created above. -1. Select an instance type best suited for your needs (at least a `c5.xlarge`) and click **Configure details**. -1. Enter a name for your launch configuration (we'll use `gitlab-ha-launch-config`). -1. **Do not** check **Request Spot Instance**. -1. From the **IAM Role** dropdown, pick the `GitLabAdmin` instance role we [created earlier](#create-an-iam-ec2-instance-role-and-profile). -1. Leave the rest as defaults and click **Add Storage**. -1. The root volume is 8GiB by default and should be enough given that we won't store any data there. Click **Configure Security Group**. -1. Check **Select and existing security group** and select the `gitlab-loadbalancer-sec-group` we created earlier. -1. Click **Review**, review your changes, and click **Create launch configuration**. -1. Acknowledge that you have access to the private key or create a new one. Click **Create launch configuration**. - -### Create an auto scaling group - -1. As soon as the launch configuration is created, you'll see an option to **Create an Auto Scaling group using this launch configuration**. Click that to start creating the auto scaling group. -1. Enter a **Group name** (we'll use `gitlab-auto-scaling-group`). -1. For **Group size**, enter the number of instances you want to start with (we'll enter `2`). -1. Select the `gitlab-vpc` from the **Network** dropdown. -1. Add both the private [subnets we created earlier](#subnets). -1. Expand the **Advanced Details** section and check the **Receive traffic from one or more load balancers** option. -1. From the **Classic Load Balancers** dropdown, select the load balancer we created earlier. -1. For **Health Check Type**, select **ELB**. -1. We'll leave our **Health Check Grace Period** as the default `300` seconds. Click **Configure scaling policies**. -1. Check **Use scaling policies to adjust the capacity of this group**. -1. For this group we'll scale between 2 and 4 instances where one instance will be added if CPU -utilization is greater than 60% and one instance is removed if it falls -to less than 45%. - - - -1. Finally, configure notifications and tags as you see fit, review your changes, and create the -auto scaling group. - -As the auto scaling group is created, you'll see your new instances spinning up in your EC2 dashboard. You'll also see the new instances added to your load balancer. Once the instances pass the heath check, they are ready to start receiving traffic from the load balancer. - -Since our instances are created by the auto scaling group, go back to your instances and terminate the [instance we created manually above](#install-gitlab). We only needed this instance to create our custom AMI. - -## Health check and monitoring with Prometheus - -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) - -GitLab also has various [health check endpoints](../../user/admin_area/monitoring/health_check.md) -that you can ping and get reports. - -## GitLab Runner - -If you want to take advantage of [GitLab CI/CD](../../ci/index.md), you have to -set up at least one [runner](https://docs.gitlab.com/runner/). - -Read more on configuring an -[autoscaling GitLab Runner on AWS](https://docs.gitlab.com/runner/configuration/runner_autoscale_aws/). - -## Backup and restore - -GitLab provides [a tool to back up](../../raketasks/backup_restore.md#back-up-gitlab) -and restore its Git data, database, attachments, LFS objects, and so on. - -Some important things to know: - -- The backup/restore tool **does not** store some configuration files, like secrets; you'll - need to [configure this yourself](../../raketasks/backup_restore.md#storing-configuration-files). -- By default, the backup files are stored locally, but you can - [backup GitLab using S3](../../raketasks/backup_restore.md#using-amazon-s3). -- You can [exclude specific directories form the backup](../../raketasks/backup_restore.md#excluding-specific-directories-from-the-backup). - -### Backing up GitLab - -To back up GitLab: - -1. SSH into your instance. -1. Take a backup: - - ```shell - sudo gitlab-backup create - ``` - -NOTE: -For GitLab 12.1 and earlier, use `gitlab-rake gitlab:backup:create`. - -### Restoring GitLab from a backup - -To restore GitLab, first review the [restore documentation](../../raketasks/backup_restore.md#restore-gitlab), -and primarily the restore prerequisites. Then, follow the steps under the -[Omnibus installations section](../../raketasks/backup_restore.md#restore-for-omnibus-gitlab-installations). - -## Updating GitLab - -GitLab releases a new version every month on the 22nd. Whenever a new version is -released, you can update your GitLab instance: - -1. SSH into your instance -1. Take a backup: - - ```shell - sudo gitlab-backup create - ``` - -NOTE: -For GitLab 12.1 and earlier, use `gitlab-rake gitlab:backup:create`. - -1. Update the repositories and install GitLab: - - ```shell - sudo apt update - sudo apt install gitlab-ee - ``` - -After a few minutes, the new version should be up and running. - -## Find official GitLab-created AMI IDs on AWS - -To find the AMIs generated by GitLab: - -1. Login to AWS Web Console, so that clicking the links below will take you directly to the AMI list. -1. Pick the edition you want: - - - [GitLab Enterprise Edition](https://console.aws.amazon.com/ec2/v2/home?region=us-east-1#Images:visibility=public-images;ownerAlias=782774275127;search=GitLab%20EE;sort=desc:name): If you want to unlock the enterprise features, a license is needed. Recommended for this guide. - - [GitLab Community Edition](https://console.aws.amazon.com/ec2/v2/home?region=us-east-1#Images:visibility=public-images;ownerAlias=782774275127;search=GitLab%20CE;sort=desc:name): The open source version of GitLab. - - [GitLab Premium or Ultimate Marketplace (Prelicensed)](https://console.aws.amazon.com/ec2/v2/home?region=us-east-1#Images:visibility=public-images;source=Marketplace;search=GitLab%20EE;sort=desc:name): 5 user license built into per-minute billing. -1. AMI IDs are unique per region, so once you've loaded one of the above, select the desired target region in the upper right of the console to see the appropriate AMIs. -1. Once the console is loaded, you can add additional search criteria to narrow further. For instance, `13.` to find only 13.x versions. -1. To launch an EC2 Machine with one of the listed AMIs, check the box at the start of the relevant row, and select the "Launch" button near the top of left of the page. - -NOTE: -If you are trying to restore from an older version of GitLab while moving to AWS, find the -[Enterprise and Community Editions Before 11.10.3](https://console.aws.amazon.com/ec2/v2/home?region=us-east-1#Images:visibility=public-images;ownerAlias=855262394183;sort=desc:name). - -## Conclusion - -In this guide, we went mostly through scaling and some redundancy options, -your mileage may vary. - -Keep in mind that all solutions come with a trade-off between -cost/complexity and uptime. The more uptime you want, the more complex the solution. -And the more complex the solution, the more work is involved in setting up and -maintaining it. - -Have a read through these other resources and feel free to -[open an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) -to request additional material: - -- [Scaling GitLab](../../administration/reference_architectures/index.md): - GitLab supports several different types of clustering. -- [Geo replication](../../administration/geo/index.md): - Geo is the solution for widely distributed development teams. -- [Omnibus GitLab](https://docs.gitlab.com/omnibus/) - Everything you need to know - about administering your GitLab instance. -- [Upload a license](../../user/admin_area/license.md): - Activate all GitLab Enterprise Edition functionality with a license. -- [Pricing](https://about.gitlab.com/pricing/): Pricing for the different tiers. - -## Troubleshooting - -### Instances are failing health checks - -If your instances are failing the load balancer's health checks, verify that they are returning a status `200` from the health check endpoint we configured earlier. Any other status, including redirects (e.g. status `302`) will cause the health check to fail. - -You may have to set a password on the `root` user to prevent automatic redirects on the sign-in endpoint before health checks will pass. - -### "The change you requested was rejected (422)" - -If you see this page when trying to set a password via the web interface, make sure `external_url` in `gitlab.rb` matches the domain you are making a request from, and run `sudo gitlab-ctl reconfigure` after making any changes to it. - -### Some job logs are not uploaded to object storage - -When the GitLab deployment is scaled up to more than one node, some job logs may not be uploaded to [object storage](../../administration/object_storage.md) properly. [Incremental logging is required](../../administration/object_storage.md#other-alternatives-to-file-system-storage) for CI to use object storage. - -Enable [incremental logging](../../administration/job_logs.md#enable-or-disable-incremental-logging) if it has not already been enabled. +- Quality / Distribution / Self-Managed +- Alliances +- Training +- Support +- Professional Services +- Public Sector diff --git a/doc/install/aws/manual_install_aws.md b/doc/install/aws/manual_install_aws.md new file mode 100644 index 00000000000..a490cf0eb73 --- /dev/null +++ b/doc/install/aws/manual_install_aws.md @@ -0,0 +1,850 @@ +--- +stage: Enablement +group: Distribution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: howto +--- + +{::options parse_block_html="true" /} + +# Installing GitLab on Amazon Web Services (AWS) (DEPRECATED) **(FREE SELF)** + +This page offers a walkthrough of a common configuration for GitLab on AWS using the official GitLab Linux package. You should customize it to accommodate your needs. + +NOTE: +For organizations with 1,000 users or less, the recommended AWS installation method is to launch an EC2 single box [Omnibus Installation](https://about.gitlab.com/install/) and implement a snapshot strategy for backing up the data. See the [1,000 user reference architecture](../../administration/reference_architectures/1k_users.md) for more. + +NOTE: +The [GitLab Environment Toolkit (GET)](https://gitlab.com/gitlab-org/quality/gitlab-environment-toolkit/-/tree/master) is GitLabs internal effort to create a multi-cloud, multi-GitLab toolkit to provision GitLab. It can be used to deploy Omnibus GitLab on AWS. GET is developed by GitLab developers and is open to community contributions. + +## Introduction + +For the most part, we'll make use of Omnibus GitLab in our setup, but we'll also leverage native AWS services. Instead of using the Omnibus bundled PostgreSQL and Redis, we will use AWS RDS and ElastiCache. + +In this guide, we'll go through a multi-node setup where we'll start by +configuring our Virtual Private Cloud and subnets to later integrate +services such as RDS for our database server and ElastiCache as a Redis +cluster to finally manage them within an auto scaling group with custom +scaling policies. + +## Requirements + +In addition to having a basic familiarity with [AWS](https://docs.aws.amazon.com/) and [Amazon EC2](https://docs.aws.amazon.com/ec2/), you will need: + +- [An AWS account](https://console.aws.amazon.com/console/home) +- [To create or upload an SSH key](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) + to connect to the instance via SSH +- A domain name for the GitLab instance +- An SSL/TLS certificate to secure your domain. If you do not already own one, you can provision a free public SSL/TLS certificate through [AWS Certificate Manager](https://aws.amazon.com/certificate-manager/)(ACM) for use with the [Elastic Load Balancer](#load-balancer) we'll create. + +NOTE: +It can take a few hours to validate a certificate provisioned through ACM. To avoid delays later, request your certificate as soon as possible. + +## Architecture + +Below is a diagram of the recommended architecture. + + + +## AWS costs + +GitLab uses the following AWS services, with links to pricing information: + +- **EC2**: GitLab is deployed on shared hardware, for which + [on-demand pricing](https://aws.amazon.com/ec2/pricing/on-demand/) applies. + If you want to run GitLab on a dedicated or reserved instance, see the + [EC2 pricing page](https://aws.amazon.com/ec2/pricing/) for information about + its cost. +- **S3**: GitLab uses S3 ([pricing page](https://aws.amazon.com/s3/pricing/)) to + store backups, artifacts, and LFS objects. +- **ELB**: A Classic Load Balancer ([pricing page](https://aws.amazon.com/elasticloadbalancing/pricing/)), + used to route requests to the GitLab instances. +- **RDS**: An Amazon Relational Database Service using PostgreSQL + ([pricing page](https://aws.amazon.com/rds/postgresql/pricing/)). +- **ElastiCache**: An in-memory cache environment ([pricing page](https://aws.amazon.com/elasticache/pricing/)), + used to provide a Redis configuration. + +## Create an IAM EC2 instance role and profile + +As we'll be using [Amazon S3 object storage](#amazon-s3-object-storage), our EC2 instances need to have read, write, and list permissions for our S3 buckets. To avoid embedding AWS keys in our GitLab configuration, we'll make use of an [IAM Role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) to allow our GitLab instance with this access. We'll need to create an IAM policy to attach to our IAM role: + +### Create an IAM Policy + +1. Navigate to the IAM dashboard and click on **Policies** in the left menu. +1. Click **Create policy**, select the `JSON` tab, and add a policy. We want to [follow security best practices and grant _least privilege_](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege), giving our role only the permissions needed to perform the required actions. + 1. Assuming you prefix the S3 bucket names with `gl-` as shown in the diagram, add the following policy: + + ```json + { "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "s3:PutObject", + "s3:GetObject", + "s3:DeleteObject", + "s3:PutObjectAcl" + ], + "Resource": "arn:aws:s3:::gl-*/*" + }, + { + "Effect": "Allow", + "Action": [ + "s3:ListBucket", + "s3:AbortMultipartUpload", + "s3:ListMultipartUploadParts", + "s3:ListBucketMultipartUploads" + ], + "Resource": "arn:aws:s3:::gl-*" + } + ] + } + ``` + +1. Click **Review policy**, give your policy a name (we'll use `gl-s3-policy`), and click **Create policy**. + +### Create an IAM Role + +1. Still on the IAM dashboard, click on **Roles** in the left menu, and + click **Create role**. +1. Create a new role by selecting **AWS service > EC2**, then click + **Next: Permissions**. +1. In the policy filter, search for the `gl-s3-policy` we created above, select it, and click **Tags**. +1. Add tags if needed and click **Review**. +1. Give the role a name (we'll use `GitLabS3Access`) and click **Create Role**. + +We'll use this role when we [create a launch configuration](#create-a-launch-configuration) later on. + +## Configuring the network + +We'll start by creating a VPC for our GitLab cloud infrastructure, then +we can create subnets to have public and private instances in at least +two [Availability Zones (AZs)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html). Public subnets will require a Route Table keep and an associated +Internet Gateway. + +### Creating the Virtual Private Cloud (VPC) + +We'll now create a VPC, a virtual networking environment that you'll control: + +1. Sign in to [Amazon Web Services](https://console.aws.amazon.com/vpc/home). +1. Select **Your VPCs** from the left menu and then click **Create VPC**. + At the "Name tag" enter `gitlab-vpc` and at the "IPv4 CIDR block" enter + `10.0.0.0/16`. If you don't require dedicated hardware, you can leave + "Tenancy" as default. Click **Yes, Create** when ready. + +  + +1. Select the VPC, click **Actions**, click **Edit DNS resolution**, and enable DNS resolution. Hit **Save** when done. + +### Subnets + +Now, let's create some subnets in different Availability Zones. Make sure +that each subnet is associated to the VPC we just created and +that CIDR blocks don't overlap. This will also +allow us to enable multi AZ for redundancy. + +We will create private and public subnets to match load balancers and +RDS instances as well: + +1. Select **Subnets** from the left menu. +1. Click **Create subnet**. Give it a descriptive name tag based on the IP, + for example `gitlab-public-10.0.0.0`, select the VPC we created previously, select an availability zone (we'll use `us-west-2a`), + and at the IPv4 CIDR block let's give it a 24 subnet `10.0.0.0/24`: + +  + +1. Follow the same steps to create all subnets: + + | Name tag | Type | Availability Zone | CIDR block | + | ------------------------- | ------- | ----------------- | ------------- | + | `gitlab-public-10.0.0.0` | public | `us-west-2a` | `10.0.0.0/24` | + | `gitlab-private-10.0.1.0` | private | `us-west-2a` | `10.0.1.0/24` | + | `gitlab-public-10.0.2.0` | public | `us-west-2b` | `10.0.2.0/24` | + | `gitlab-private-10.0.3.0` | private | `us-west-2b` | `10.0.3.0/24` | + +1. Once all the subnets are created, enable **Auto-assign IPv4** for the two public subnets: + 1. Select each public subnet in turn, click **Actions**, and click **Modify auto-assign IP settings**. Enable the option and save. + +### Internet Gateway + +Now, still on the same dashboard, go to Internet Gateways and +create a new one: + +1. Select **Internet Gateways** from the left menu. +1. Click **Create internet gateway**, give it the name `gitlab-gateway` and + click **Create**. +1. Select it from the table, and then under the **Actions** dropdown choose + "Attach to VPC". + +  + +1. Choose `gitlab-vpc` from the list and hit **Attach**. + +### Create NAT Gateways + +Instances deployed in our private subnets need to connect to the internet for updates, but should not be reachable from the public internet. To achieve this, we'll make use of [NAT Gateways](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html) deployed in each of our public subnets: + +1. Navigate to the VPC dashboard and click on **NAT Gateways** in the left menu bar. +1. Click **Create NAT Gateway** and complete the following: + 1. **Subnet**: Select `gitlab-public-10.0.0.0` from the dropdown. + 1. **Elastic IP Allocation ID**: Enter an existing Elastic IP or click **Allocate Elastic IP address** to allocate a new IP to your NAT gateway. + 1. Add tags if needed. + 1. Click **Create NAT Gateway**. + +Create a second NAT gateway but this time place it in the second public subnet, `gitlab-public-10.0.2.0`. + +### Route Tables + +#### Public Route Table + +We need to create a route table for our public subnets to reach the internet via the internet gateway we created in the previous step. + +On the VPC dashboard: + +1. Select **Route Tables** from the left menu. +1. Click **Create Route Table**. +1. At the "Name tag" enter `gitlab-public` and choose `gitlab-vpc` under "VPC". +1. Click **Create**. + +We now need to add our internet gateway as a new target and have +it receive traffic from any destination. + +1. Select **Route Tables** from the left menu and select the `gitlab-public` + route to show the options at the bottom. +1. Select the **Routes** tab, click **Edit routes > Add route** and set `0.0.0.0/0` + as the destination. In the target column, select the `gitlab-gateway` we created previously. + Hit **Save routes** once done. + +Next, we must associate the **public** subnets to the route table: + +1. Select the **Subnet Associations** tab and click **Edit subnet associations**. +1. Check only the public subnets and click **Save**. + +#### Private Route Tables + +We also need to create two private route tables so that instances in each private subnet can reach the internet via the NAT gateway in the corresponding public subnet in the same availability zone. + +1. Follow the same steps as above to create two private route tables. Name them `gitlab-private-a` and `gitlab-private-b` respectively. +1. Next, add a new route to each of the private route tables where the destination is `0.0.0.0/0` and the target is one of the NAT gateways we created earlier. + 1. Add the NAT gateway we created in `gitlab-public-10.0.0.0` as the target for the new route in the `gitlab-private-a` route table. + 1. Similarly, add the NAT gateway in `gitlab-public-10.0.2.0` as the target for the new route in the `gitlab-private-b`. +1. Lastly, associate each private subnet with a private route table. + 1. Associate `gitlab-private-10.0.1.0` with `gitlab-private-a`. + 1. Associate `gitlab-private-10.0.3.0` with `gitlab-private-b`. + +## Load Balancer + +We'll create a load balancer to evenly distribute inbound traffic on ports `80` and `443` across our GitLab application servers. Based the on the [scaling policies](#create-an-auto-scaling-group) we'll create later, instances will be added to or removed from our load balancer as needed. Additionally, the load balance will perform health checks on our instances. + +On the EC2 dashboard, look for Load Balancer in the left navigation bar: + +1. Click the **Create Load Balancer** button. + 1. Choose the **Classic Load Balancer**. + 1. Give it a name (we'll use `gitlab-loadbalancer`) and for the **Create LB Inside** option, select `gitlab-vpc` from the dropdown menu. + 1. In the **Listeners** section, set the following listeners: + - HTTP port 80 for both load balancer and instance protocol and ports + - TCP port 22 for both load balancer and instance protocols and ports + - HTTPS port 443 for load balancer protocol and ports, forwarding to HTTP port 80 on the instance (we will configure GitLab to listen on port 80 [later in the guide](#add-support-for-proxied-ssl)) + 1. In the **Select Subnets** section, select both public subnets from the list so that the load balancer can route traffic to both availability zones. +1. We'll add a security group for our load balancer to act as a firewall to control what traffic is allowed through. Click **Assign Security Groups** and select **Create a new security group**, give it a name + (we'll use `gitlab-loadbalancer-sec-group`) and description, and allow both HTTP and HTTPS traffic + from anywhere (`0.0.0.0/0, ::/0`). Also allow SSH traffic, select a custom source, and add a single trusted IP address or an IP address range in CIDR notation. This will allow users to perform Git actions over SSH. +1. Click **Configure Security Settings** and set the following: + 1. Select an SSL/TLS certificate from ACM or upload a certificate to IAM. + 1. Under **Select a Cipher**, pick a predefined security policy from the dropdown. You can see a breakdown of [Predefined SSL Security Policies for Classic Load Balancers](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-security-policy-table.html) in the AWS docs. Check the GitLab codebase for a list of [supported SSL ciphers and protocols](https://gitlab.com/gitlab-org/gitlab/-/blob/9ee7ad433269b37251e0dd5b5e00a0f00d8126b4/lib/support/nginx/gitlab-ssl#L97-99). +1. Click **Configure Health Check** and set up a health check for your EC2 instances. + 1. For **Ping Protocol**, select HTTP. + 1. For **Ping Port**, enter 80. + 1. For **Ping Path**, enter `/users/sign_in`. (We use `/users/sign_in` as it's a public endpoint that does + not require authentication.) + 1. Keep the default **Advanced Details** or adjust them according to your needs. +1. Click **Add EC2 Instances** - don't add anything as we will create an Auto Scaling Group later to manage instances for us. +1. Click **Add Tags** and add any tags you need. +1. Click **Review and Create**, review all your settings, and click **Create** if you're happy. + +After the Load Balancer is up and running, you can revisit your Security +Groups to refine the access only through the ELB and any other requirements +you might have. + +### Configure DNS for Load Balancer + +On the Route 53 dashboard, click **Hosted zones** in the left navigation bar: + +1. Select an existing hosted zone or, if you do not already have one for your domain, click **Create Hosted Zone**, enter your domain name, and click **Create**. +1. Click **Create Record Set** and provide the following values: + 1. **Name:** Use the domain name (the default value) or enter a subdomain. + 1. **Type:** Select **A - IPv4 address**. + 1. **Alias:** Defaults to **No**. Select **Yes**. + 1. **Alias Target:** Find the **ELB Classic Load Balancers** section and select the classic load balancer we created earlier. + 1. **Routing Policy:** We'll use **Simple** but you can choose a different policy based on your use case. + 1. **Evaluate Target Health:** We'll set this to **No** but you can choose to have the load balancer route traffic based on target health. + 1. Click **Create**. +1. If you registered your domain through Route 53, you're done. If you used a different domain registrar, you need to update your DNS records with your domain registrar. You'll need to: + 1. Click on **Hosted zones** and select the domain you added above. + 1. You'll see a list of `NS` records. From your domain registrar's administrator panel, add each of these as `NS` records to your domain's DNS records. These steps may vary between domain registrars. If you're stuck, Google **"name of your registrar" add DNS records** and you should find a help article specific to your domain registrar. + +The steps for doing this vary depending on which registrar you use and is beyond the scope of this guide. + +## PostgreSQL with RDS + +For our database server we will use Amazon RDS which offers Multi AZ +for redundancy. First we'll create a security group and subnet group, then we'll +create the actual RDS instance. + +### RDS Security Group + +We need a security group for our database that will allow inbound traffic from the instances we'll deploy in our `gitlab-loadbalancer-sec-group` later on: + +1. From the EC2 dashboard, select **Security Groups** from the left menu bar. +1. Click **Create security group**. +1. Give it a name (we'll use `gitlab-rds-sec-group`), a description, and select the `gitlab-vpc` from the **VPC** dropdown. +1. In the **Inbound rules** section, click **Add rule** and set the following: + 1. **Type:** search for and select the **PostgreSQL** rule. + 1. **Source type:** set as "Custom". + 1. **Source:** select the `gitlab-loadbalancer-sec-group` we created earlier. +1. When done, click **Create security group**. + +### RDS Subnet Group + +1. Navigate to the RDS dashboard and select **Subnet Groups** from the left menu. +1. Click on **Create DB Subnet Group**. +1. Under **Subnet group details**, enter a name (we'll use `gitlab-rds-group`), a description, and choose the `gitlab-vpc` from the VPC dropdown. +1. From the **Availability Zones** dropdown, select the Availability Zones that include the subnets you've configured. In our case, we'll add `eu-west-2a` and `eu-west-2b`. +1. From the **Subnets** dropdown, select the two private subnets (`10.0.1.0/24` and `10.0.3.0/24`) as we defined them in the [subnets section](#subnets). +1. Click **Create** when ready. + +### Create the database + +WARNING: +Avoid using burstable instances (t class instances) for the database as this could lead to performance issues due to CPU credits running out during sustained periods of high load. + +Now, it's time to create the database: + +1. Navigate to the RDS dashboard, select **Databases** from the left menu, and click **Create database**. +1. Select **Standard Create** for the database creation method. +1. Select **PostgreSQL** as the database engine and select the minimum PostgreSQL version as defined for your GitLab version in our [database requirements](../../install/requirements.md#postgresql-requirements). +1. Since this is a production server, let's choose **Production** from the **Templates** section. +1. Under **Settings**, set a DB instance identifier, a master username, and a master password. We'll use `gitlab-db-ha`, `gitlab`, and a very secure password respectively. Make a note of these as we'll need them later. +1. For the DB instance size, select **Standard classes** and select an instance size that meets your requirements from the dropdown menu. We'll use a `db.m4.large` instance. +1. Under **Storage**, configure the following: + 1. Select **Provisioned IOPS (SSD)** from the storage type dropdown menu. Provisioned IOPS (SSD) storage is best suited for this use (though you can choose General Purpose (SSD) to reduce the costs). Read more about it at [Storage for Amazon RDS](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_Storage.html). + 1. Allocate storage and set provisioned IOPS. We'll use the minimum values, `100` and `1000`, respectively. + 1. Enable storage autoscaling (optional) and set a maximum storage threshold. +1. Under **Availability & durability**, select **Create a standby instance** to have a standby RDS instance provisioned in a different [Availability Zone](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.MultiAZ.html). +1. Under **Connectivity**, configure the following: + 1. Select the VPC we created earlier (`gitlab-vpc`) from the **Virtual Private Cloud (VPC)** dropdown menu. + 1. Expand the **Additional connectivity configuration** section and select the subnet group (`gitlab-rds-group`) we created earlier. + 1. Set public accessibility to **No**. + 1. Under **VPC security group**, select **Choose existing** and select the `gitlab-rds-sec-group` we create above from the dropdown. + 1. Leave the database port as the default `5432`. +1. For **Database authentication**, select **Password authentication**. +1. Expand the **Additional configuration** section and complete the following: + 1. The initial database name. We'll use `gitlabhq_production`. + 1. Configure your preferred backup settings. + 1. The only other change we'll make here is to disable auto minor version updates under **Maintenance**. + 1. Leave all the other settings as is or tweak according to your needs. + 1. Once you're happy, click **Create database**. + +Now that the database is created, let's move on to setting up Redis with ElastiCache. + +## Redis with ElastiCache + +ElastiCache is an in-memory hosted caching solution. Redis maintains its own +persistence and is used to store session data, temporary cache information, and background job queues for the GitLab application. + +### Create a Redis Security Group + +1. Navigate to the EC2 dashboard. +1. Select **Security Groups** from the left menu. +1. Click **Create security group** and fill in the details. Give it a name (we'll use `gitlab-redis-sec-group`), + add a description, and choose the VPC we created previously +1. In the **Inbound rules** section, click **Add rule** and add a **Custom TCP** rule, set port `6379`, and set the "Custom" source as the `gitlab-loadbalancer-sec-group` we created earlier. +1. When done, click **Create security group**. + +### Redis Subnet Group + +1. Navigate to the ElastiCache dashboard from your AWS console. +1. Go to **Subnet Groups** in the left menu, and create a new subnet group (we'll name ours `gitlab-redis-group`). + Make sure to select our VPC and its [private subnets](#subnets). Click + **Create** when ready. + +  + +### Create the Redis Cluster + +1. Navigate back to the ElastiCache dashboard. +1. Select **Redis** on the left menu and click **Create** to create a new + Redis cluster. Do not enable **Cluster Mode** as it is [not supported](../../administration/redis/replication_and_failover_external.md#requirements). Even without cluster mode on, you still get the + chance to deploy Redis in multiple availability zones. +1. In the settings section: + 1. Give the cluster a name (`gitlab-redis`) and a description. + 1. For the version, select the latest of `5.0` series (e.g., `5.0.6`). + 1. Leave the port as `6379` since this is what we used in our Redis security group above. + 1. Select the node type (at least `cache.t3.medium`, but adjust to your needs) and the number of replicas. +1. In the advanced settings section: + 1. Select the multi-AZ auto-failover option. + 1. Select the subnet group we created previously. + 1. Manually select the preferred availability zones, and under "Replica 2" + choose a different zone than the other two. + +  + +1. In the security settings, edit the security groups and choose the + `gitlab-redis-sec-group` we had previously created. +1. Leave the rest of the settings to their default values or edit to your liking. +1. When done, click **Create**. + +## Setting up Bastion Hosts + +Since our GitLab instances will be in private subnets, we need a way to connect to these instances via SSH to make configuration changes, perform upgrades, etc. One way of doing this is via a [bastion host](https://en.wikipedia.org/wiki/Bastion_host), sometimes also referred to as a jump box. + +NOTE: +If you do not want to maintain bastion hosts, you can set up [AWS Systems Manager Session Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager.html) for access to instances. This is beyond the scope of this document. + +### Create Bastion Host A + +1. Navigate to the EC2 Dashboard and click on **Launch instance**. +1. Select the **Ubuntu Server 18.04 LTS (HVM)** AMI. +1. Choose an instance type. We'll use a `t2.micro` as we'll only use the bastion host to SSH into our other instances. +1. Click **Configure Instance Details**. + 1. Under **Network**, select the `gitlab-vpc` from the dropdown menu. + 1. Under **Subnet**, select the public subnet we created earlier (`gitlab-public-10.0.0.0`). + 1. Double check that under **Auto-assign Public IP** you have **Use subnet setting (Enable)** selected. + 1. Leave everything else as default and click **Add Storage**. +1. For storage, we'll leave everything as default and only add an 8GB root volume. We won't store anything on this instance. +1. Click **Add Tags** and on the next screen click **Add Tag**. + 1. We'll only set `Key: Name` and `Value: Bastion Host A`. +1. Click **Configure Security Group**. + 1. Select **Create a new security group**, enter a **Security group name** (we'll use `bastion-sec-group`), and add a description. + 1. We'll enable SSH access from anywhere (`0.0.0.0/0`). If you want stricter security, specify a single IP address or an IP address range in CIDR notation. + 1. Click **Review and Launch** +1. Review all your settings and, if you're happy, click **Launch**. +1. Acknowledge that you have access to an existing key pair or create a new one. Click **Launch Instance**. + +Confirm that you can SSH into the instance: + +1. On the EC2 Dashboard, click on **Instances** in the left menu. +1. Select **Bastion Host A** from your list of instances. +1. Click **Connect** and follow the connection instructions. +1. If you are able to connect successfully, let's move on to setting up our second bastion host for redundancy. + +### Create Bastion Host B + +1. Create an EC2 instance following the same steps as above with the following changes: + 1. For the **Subnet**, select the second public subnet we created earlier (`gitlab-public-10.0.2.0`). + 1. Under the **Add Tags** section, we'll set `Key: Name` and `Value: Bastion Host B` so that we can easily identify our two instances. + 1. For the security group, select the existing `bastion-sec-group` we created above. + +### Use SSH Agent Forwarding + +EC2 instances running Linux use private key files for SSH authentication. You'll connect to your bastion host using an SSH client and the private key file stored on your client. Since the private key file is not present on the bastion host, you will not be able to connect to your instances in private subnets. + +Storing private key files on your bastion host is a bad idea. To get around this, use SSH agent forwarding on your client. See [Securely Connect to Linux Instances Running in a Private Amazon VPC](https://aws.amazon.com/blogs/security/securely-connect-to-linux-instances-running-in-a-private-amazon-vpc/) for a step-by-step guide on how to use SSH agent forwarding. + +## Install GitLab and create custom AMI + +We will need a preconfigured, custom GitLab AMI to use in our launch configuration later. As a starting point, we will use the official GitLab AMI to create a GitLab instance. Then, we'll add our custom configuration for PostgreSQL, Redis, and Gitaly. If you prefer, instead of using the official GitLab AMI, you can also spin up an EC2 instance of your choosing and [manually install GitLab](https://about.gitlab.com/install/). + +### Install GitLab + +From the EC2 dashboard: + +1. Use the section below titled "[Find official GitLab-created AMI IDs on AWS](#find-official-gitlab-created-ami-ids-on-aws)" to find the correct AMI to launch. +1. After clicking **Launch** on the desired AMI, select an instance type based on your workload. Consult the [hardware requirements](../../install/requirements.md#hardware-requirements) to choose one that fits your needs (at least `c5.xlarge`, which is sufficient to accommodate 100 users). +1. Click **Configure Instance Details**: + 1. In the **Network** dropdown, select `gitlab-vpc`, the VPC we created earlier. + 1. In the **Subnet** dropdown, select `gitlab-private-10.0.1.0` from the list of subnets we created earlier. + 1. Double check that **Auto-assign Public IP** is set to `Use subnet setting (Disable)`. + 1. Click **Add Storage**. + 1. The root volume is 8GiB by default and should be enough given that we won't store any data there. +1. Click **Add Tags** and add any tags you may need. In our case, we'll only set `Key: Name` and `Value: GitLab`. +1. Click **Configure Security Group**. Check **Select an existing security group** and select the `gitlab-loadbalancer-sec-group` we created earlier. +1. Click **Review and launch** followed by **Launch** if you're happy with your settings. +1. Finally, acknowledge that you have access to the selected private key file or create a new one. Click **Launch Instances**. + +### Add custom configuration + +Connect to your GitLab instance via **Bastion Host A** using [SSH Agent Forwarding](#use-ssh-agent-forwarding). Once connected, add the following custom configuration: + +#### Disable Let's Encrypt + +Since we're adding our SSL certificate at the load balancer, we do not need the GitLab built-in support for Let's Encrypt. Let's Encrypt [is enabled by default](https://docs.gitlab.com/omnibus/settings/ssl.html#lets-encrypt-integration) when using an `https` domain in GitLab 10.7 and later, so we need to explicitly disable it: + +1. Open `/etc/gitlab/gitlab.rb` and disable it: + + ```ruby + letsencrypt['enable'] = false + ``` + +1. Save the file and reconfigure for the changes to take effect: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +#### Install the required extensions for PostgreSQL + +From your GitLab instance, connect to the RDS instance to verify access and to install the required `pg_trgm` and `btree_gist` extensions. + +To find the host or endpoint, navigate to **Amazon RDS > Databases** and click on the database you created earlier. Look for the endpoint under the **Connectivity & security** tab. + +Do not to include the colon and port number: + +```shell +sudo /opt/gitlab/embedded/bin/psql -U gitlab -h <rds-endpoint> -d gitlabhq_production +``` + +At the `psql` prompt create the extension and then quit the session: + +```shell +psql (10.9) +Type "help" for help. + +gitlab=# CREATE EXTENSION pg_trgm; +gitlab=# CREATE EXTENSION btree_gist; +gitlab=# \q +``` + +#### Configure GitLab to connect to PostgreSQL and Redis + +1. Edit `/etc/gitlab/gitlab.rb`, find the `external_url 'http://<domain>'` option + and change it to the `https` domain you will be using. + +1. Look for the GitLab database settings and uncomment as necessary. In + our current case we'll specify the database adapter, encoding, host, name, + username, and password: + + ```ruby + # Disable the built-in Postgres + postgresql['enable'] = false + + # Fill in the connection details + gitlab_rails['db_adapter'] = "postgresql" + gitlab_rails['db_encoding'] = "unicode" + gitlab_rails['db_database'] = "gitlabhq_production" + gitlab_rails['db_username'] = "gitlab" + gitlab_rails['db_password'] = "mypassword" + gitlab_rails['db_host'] = "<rds-endpoint>" + ``` + +1. Next, we need to configure the Redis section by adding the host and + uncommenting the port: + + ```ruby + # Disable the built-in Redis + redis['enable'] = false + + # Fill in the connection details + gitlab_rails['redis_host'] = "<redis-endpoint>" + gitlab_rails['redis_port'] = 6379 + ``` + +1. Finally, reconfigure GitLab for the changes to take effect: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +1. You might also find it useful to run a check and a service status to make sure + everything has been setup correctly: + + ```shell + sudo gitlab-rake gitlab:check + sudo gitlab-ctl status + ``` + +#### Set up Gitaly + +WARNING: +In this architecture, having a single Gitaly server creates a single point of failure. Use +[Gitaly Cluster](../../administration/gitaly/praefect.md) to remove this limitation. + +Gitaly is a service that provides high-level RPC access to Git repositories. +It should be enabled and configured on a separate EC2 instance in one of the +[private subnets](#subnets) we configured previously. + +Let's create an EC2 instance where we'll install Gitaly: + +1. From the EC2 dashboard, click **Launch instance**. +1. Choose an AMI. In this example, we'll select the **Ubuntu Server 18.04 LTS (HVM), SSD Volume Type**. +1. Choose an instance type. We'll pick a `c5.xlarge`. +1. Click **Configure Instance Details**. + 1. In the **Network** dropdown, select `gitlab-vpc`, the VPC we created earlier. + 1. In the **Subnet** dropdown, select `gitlab-private-10.0.1.0` from the list of subnets we created earlier. + 1. Double check that **Auto-assign Public IP** is set to `Use subnet setting (Disable)`. + 1. Click **Add Storage**. +1. Increase the Root volume size to `20 GiB` and change the **Volume Type** to `Provisoned IOPS SSD (io1)`. (This is an arbitrary size. Create a volume big enough for your repository storage requirements.) + 1. For **IOPS** set `1000` (20 GiB x 50 IOPS). You can provision up to 50 IOPS per GiB. If you select a larger volume, increase the IOPS accordingly. Workloads where many small files are written in a serialized manner, like `git`, requires performant storage, hence the choice of `Provisoned IOPS SSD (io1)`. +1. Click on **Add Tags** and add your tags. In our case, we'll only set `Key: Name` and `Value: Gitaly`. +1. Click on **Configure Security Group** and let's **Create a new security group**. + 1. Give your security group a name and description. We'll use `gitlab-gitaly-sec-group` for both. + 1. Create a **Custom TCP** rule and add port `8075` to the **Port Range**. For the **Source**, select the `gitlab-loadbalancer-sec-group`. + 1. Also add an inbound rule for SSH from the `bastion-sec-group` so that we can connect using [SSH Agent Forwarding](#use-ssh-agent-forwarding) from the Bastion hosts. +1. Click **Review and launch** followed by **Launch** if you're happy with your settings. +1. Finally, acknowledge that you have access to the selected private key file or create a new one. Click **Launch Instances**. + +NOTE: +Instead of storing configuration _and_ repository data on the root volume, you can also choose to add an additional EBS volume for repository storage. Follow the same guidance as above. See the [Amazon EBS pricing](https://aws.amazon.com/ebs/pricing/). We do not recommend using EFS as it may negatively impact the performance of GitLab. You can review the [relevant documentation](../../administration/nfs.md#avoid-using-cloud-based-file-systems) for more details. + +Now that we have our EC2 instance ready, follow the [documentation to install GitLab and set up Gitaly on its own server](../../administration/gitaly/configure_gitaly.md#run-gitaly-on-its-own-server). Perform the client setup steps from that document on the [GitLab instance we created](#install-gitlab) above. + +#### Add Support for Proxied SSL + +As we are terminating SSL at our [load balancer](#load-balancer), follow the steps at [Supporting proxied SSL](https://docs.gitlab.com/omnibus/settings/nginx.html#supporting-proxied-ssl) to configure this in `/etc/gitlab/gitlab.rb`. + +Remember to run `sudo gitlab-ctl reconfigure` after saving the changes to the `gitlab.rb` file. + +#### Fast lookup of authorized SSH keys + +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. Since we do not have shared storage in our setup, we'll 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. + +If you do not configure fast lookup, Git actions over SSH will result in the following error: + +```shell +Permission denied (publickey). +fatal: Could not read from remote repository. + +Please make sure you have the correct access rights +and the repository exists. +``` + +#### Configure host keys + +Ordinarily we would manually copy the contents (primary and public keys) of `/etc/ssh/` on the primary application server to `/etc/ssh` on all secondary servers. This prevents false man-in-the-middle-attack alerts when accessing servers in your cluster behind a load balancer. + +We'll automate this by creating static host keys as part of our custom AMI. As these host keys are also rotated every time an EC2 instance boots up, "hard coding" them into our custom AMI serves as a handy workaround. + +On your GitLab instance run the following: + +```shell +sudo mkdir /etc/ssh_static +sudo cp -R /etc/ssh/* /etc/ssh_static +``` + +In `/etc/ssh/sshd_config` update the following: + +```shell +# HostKeys for protocol version 2 +HostKey /etc/ssh_static/ssh_host_rsa_key +HostKey /etc/ssh_static/ssh_host_dsa_key +HostKey /etc/ssh_static/ssh_host_ecdsa_key +HostKey /etc/ssh_static/ssh_host_ed25519_key +``` + +#### Amazon S3 object storage + +Since we're not using NFS for shared storage, we will use [Amazon S3](https://aws.amazon.com/s3/) buckets to store backups, artifacts, LFS objects, uploads, merge request diffs, container registry images, and more. Our documentation includes [instructions on how to configure object storage](../../administration/object_storage.md) for each of these data types, and other information about using object storage with GitLab. + +NOTE: +Since we are using the [AWS IAM profile](#create-an-iam-role) we created earlier, be sure to omit the AWS access key and secret access key/value pairs when configuring object storage. Instead, use `'use_iam_profile' => true` in your configuration as shown in the object storage documentation linked above. + +Remember to run `sudo gitlab-ctl reconfigure` after saving the changes to the `gitlab.rb` file. + +NOTE: +One current feature of GitLab that still requires a shared directory (NFS) is +[GitLab Pages](../../user/project/pages/index.md). +There is [work in progress](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/196) +to eliminate the need for NFS to support GitLab Pages. + +--- + +That concludes the configuration changes for our GitLab instance. Next, we'll create a custom AMI based on this instance to use for our launch configuration and auto scaling group. + +### Log in for the first time + +Using the domain name you used when setting up [DNS for the load balancer](#configure-dns-for-load-balancer), you should now be able to visit GitLab in your browser. +If you didn't change the password by any other means, the default password will be the same as the instance ID. To change the default password, login as the `root` user +with the default password and [change it in the user profile](../../user/profile#change-your-password). + +When our [auto scaling group](#create-an-auto-scaling-group) spins up new instances, we'll be able to log in with username `root` and the newly created password. + +### Create custom AMI + +On the EC2 dashboard: + +1. Select the `GitLab` instance we [created earlier](#install-gitlab). +1. Click on **Actions**, scroll down to **Image** and click **Create Image**. +1. Give your image a name and description (we'll use `GitLab-Source` for both). +1. Leave everything else as default and click **Create Image** + +Now we have a custom AMI that we'll use to create our launch configuration the next step. + +## Deploy GitLab inside an auto scaling group + +### Create a launch configuration + +From the EC2 dashboard: + +1. Select **Launch Configurations** from the left menu and click **Create launch configuration**. +1. Select **My AMIs** from the left menu and select the `GitLab` custom AMI we created above. +1. Select an instance type best suited for your needs (at least a `c5.xlarge`) and click **Configure details**. +1. Enter a name for your launch configuration (we'll use `gitlab-ha-launch-config`). +1. **Do not** check **Request Spot Instance**. +1. From the **IAM Role** dropdown, pick the `GitLabAdmin` instance role we [created earlier](#create-an-iam-ec2-instance-role-and-profile). +1. Leave the rest as defaults and click **Add Storage**. +1. The root volume is 8GiB by default and should be enough given that we won't store any data there. Click **Configure Security Group**. +1. Check **Select and existing security group** and select the `gitlab-loadbalancer-sec-group` we created earlier. +1. Click **Review**, review your changes, and click **Create launch configuration**. +1. Acknowledge that you have access to the private key or create a new one. Click **Create launch configuration**. + +### Create an auto scaling group + +1. As soon as the launch configuration is created, you'll see an option to **Create an Auto Scaling group using this launch configuration**. Click that to start creating the auto scaling group. +1. Enter a **Group name** (we'll use `gitlab-auto-scaling-group`). +1. For **Group size**, enter the number of instances you want to start with (we'll enter `2`). +1. Select the `gitlab-vpc` from the **Network** dropdown. +1. Add both the private [subnets we created earlier](#subnets). +1. Expand the **Advanced Details** section and check the **Receive traffic from one or more load balancers** option. +1. From the **Classic Load Balancers** dropdown, select the load balancer we created earlier. +1. For **Health Check Type**, select **ELB**. +1. We'll leave our **Health Check Grace Period** as the default `300` seconds. Click **Configure scaling policies**. +1. Check **Use scaling policies to adjust the capacity of this group**. +1. For this group we'll scale between 2 and 4 instances where one instance will be added if CPU +utilization is greater than 60% and one instance is removed if it falls +to less than 45%. + + + +1. Finally, configure notifications and tags as you see fit, review your changes, and create the +auto scaling group. + +As the auto scaling group is created, you'll see your new instances spinning up in your EC2 dashboard. You'll also see the new instances added to your load balancer. Once the instances pass the heath check, they are ready to start receiving traffic from the load balancer. + +Since our instances are created by the auto scaling group, go back to your instances and terminate the [instance we created manually above](#install-gitlab). We only needed this instance to create our custom AMI. + +## Health check and monitoring with Prometheus + +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) + +GitLab also has various [health check endpoints](../../user/admin_area/monitoring/health_check.md) +that you can ping and get reports. + +## GitLab Runner + +If you want to take advantage of [GitLab CI/CD](../../ci/index.md), you have to +set up at least one [runner](https://docs.gitlab.com/runner/). + +Read more on configuring an +[autoscaling GitLab Runner on AWS](https://docs.gitlab.com/runner/configuration/runner_autoscale_aws/). + +## Backup and restore + +GitLab provides [a tool to back up](../../raketasks/backup_restore.md#back-up-gitlab) +and restore its Git data, database, attachments, LFS objects, and so on. + +Some important things to know: + +- The backup/restore tool **does not** store some configuration files, like secrets; you'll + need to [configure this yourself](../../raketasks/backup_restore.md#storing-configuration-files). +- By default, the backup files are stored locally, but you can + [backup GitLab using S3](../../raketasks/backup_restore.md#using-amazon-s3). +- You can [exclude specific directories form the backup](../../raketasks/backup_restore.md#excluding-specific-directories-from-the-backup). + +### Backing up GitLab + +To back up GitLab: + +1. SSH into your instance. +1. Take a backup: + + ```shell + sudo gitlab-backup create + ``` + +NOTE: +For GitLab 12.1 and earlier, use `gitlab-rake gitlab:backup:create`. + +### Restoring GitLab from a backup + +To restore GitLab, first review the [restore documentation](../../raketasks/backup_restore.md#restore-gitlab), +and primarily the restore prerequisites. Then, follow the steps under the +[Omnibus installations section](../../raketasks/backup_restore.md#restore-for-omnibus-gitlab-installations). + +## Updating GitLab + +GitLab releases a new version every month on the 22nd. Whenever a new version is +released, you can update your GitLab instance: + +1. SSH into your instance +1. Take a backup: + + ```shell + sudo gitlab-backup create + ``` + +NOTE: +For GitLab 12.1 and earlier, use `gitlab-rake gitlab:backup:create`. + +1. Update the repositories and install GitLab: + + ```shell + sudo apt update + sudo apt install gitlab-ee + ``` + +After a few minutes, the new version should be up and running. + +## Find official GitLab-created AMI IDs on AWS + +To find the AMIs generated by GitLab: + +1. Login to AWS Web Console, so that clicking the links below will take you directly to the AMI list. +1. Pick the edition you want: + + - [GitLab Enterprise Edition](https://console.aws.amazon.com/ec2/v2/home?region=us-east-1#Images:visibility=public-images;ownerAlias=782774275127;search=GitLab%20EE;sort=desc:name): If you want to unlock the enterprise features, a license is needed. Recommended for this guide. + - [GitLab Community Edition](https://console.aws.amazon.com/ec2/v2/home?region=us-east-1#Images:visibility=public-images;ownerAlias=782774275127;search=GitLab%20CE;sort=desc:name): The open source version of GitLab. + - [GitLab Premium or Ultimate Marketplace (Prelicensed)](https://console.aws.amazon.com/ec2/v2/home?region=us-east-1#Images:visibility=public-images;source=Marketplace;search=GitLab%20EE;sort=desc:name): 5 user license built into per-minute billing. +1. AMI IDs are unique per region, so once you've loaded one of the above, select the desired target region in the upper right of the console to see the appropriate AMIs. +1. Once the console is loaded, you can add additional search criteria to narrow further. For instance, `13.` to find only 13.x versions. +1. To launch an EC2 Machine with one of the listed AMIs, check the box at the start of the relevant row, and select the "Launch" button near the top of left of the page. + +NOTE: +If you are trying to restore from an older version of GitLab while moving to AWS, find the +[Enterprise and Community Editions Before 11.10.3](https://console.aws.amazon.com/ec2/v2/home?region=us-east-1#Images:visibility=public-images;ownerAlias=855262394183;sort=desc:name). + +## Conclusion + +In this guide, we went mostly through scaling and some redundancy options, +your mileage may vary. + +Keep in mind that all solutions come with a trade-off between +cost/complexity and uptime. The more uptime you want, the more complex the solution. +And the more complex the solution, the more work is involved in setting up and +maintaining it. + +Have a read through these other resources and feel free to +[open an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) +to request additional material: + +- [Scaling GitLab](../../administration/reference_architectures/index.md): + GitLab supports several different types of clustering. +- [Geo replication](../../administration/geo/index.md): + Geo is the solution for widely distributed development teams. +- [Omnibus GitLab](https://docs.gitlab.com/omnibus/) - Everything you need to know + about administering your GitLab instance. +- [Upload a license](../../user/admin_area/license.md): + Activate all GitLab Enterprise Edition functionality with a license. +- [Pricing](https://about.gitlab.com/pricing/): Pricing for the different tiers. + +## Troubleshooting + +### Instances are failing health checks + +If your instances are failing the load balancer's health checks, verify that they are returning a status `200` from the health check endpoint we configured earlier. Any other status, including redirects (e.g. status `302`) will cause the health check to fail. + +You may have to set a password on the `root` user to prevent automatic redirects on the sign-in endpoint before health checks will pass. + +### "The change you requested was rejected (422)" + +If you see this page when trying to set a password via the web interface, make sure `external_url` in `gitlab.rb` matches the domain you are making a request from, and run `sudo gitlab-ctl reconfigure` after making any changes to it. + +### Some job logs are not uploaded to object storage + +When the GitLab deployment is scaled up to more than one node, some job logs may not be uploaded to [object storage](../../administration/object_storage.md) properly. [Incremental logging is required](../../administration/object_storage.md#other-alternatives-to-file-system-storage) for CI to use object storage. + +Enable [incremental logging](../../administration/job_logs.md#enable-or-disable-incremental-logging) if it has not already been enabled. diff --git a/doc/install/azure/index.md b/doc/install/azure/index.md index 38d423fbcdf..50cbb9fb3b6 100644 --- a/doc/install/azure/index.md +++ b/doc/install/azure/index.md @@ -248,7 +248,7 @@ in this section whenever you need to update GitLab. To determine the version of GitLab you're currently running: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Dashboard**. 1. Find the version under the **Components** table. diff --git a/doc/install/docker.md b/doc/install/docker.md index 7be97a1f2e6..b611f87938e 100644 --- a/doc/install/docker.md +++ b/doc/install/docker.md @@ -4,7 +4,7 @@ group: Distribution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab Docker images +# 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 @@ -368,7 +368,7 @@ You can then access your GitLab instance at `http://198.51.100.1/` and `https:// ### Expose GitLab on different ports -GitLab will occupy [some ports](https://docs.gitlab.com/omnibus/package-information/defaults.html) +GitLab will occupy [some ports](../administration/package_information/defaults.md) inside the container. If you want to use a different host port than `80` (HTTP) or `443` (HTTPS), @@ -621,7 +621,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 64MB 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: @@ -636,7 +636,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 page, the recommended -solution to fix this problem is to increase the size of shm to at least 256Mb. +solution to fix this problem is to increase the size of shared memory to at least 256MB. 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/installation.md b/doc/install/installation.md index a0587c6ef8a..b524177abc4 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -231,9 +231,9 @@ Download Ruby and compile it: ```shell mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress-bar "https://cache.ruby-lang.org/pub/ruby/2.7/ruby-2.7.2.tar.gz" -echo 'cb9731a17487e0ad84037490a6baf8bfa31a09e8 ruby-2.7.2.tar.gz' | shasum -c - && tar xzf ruby-2.7.2.tar.gz -cd ruby-2.7.2 +curl --remote-name --progress-bar "https://cache.ruby-lang.org/pub/ruby/2.7/ruby-2.7.4.tar.gz" +echo '3043099089608859fc8cce7f9fdccaa1f53a462457e3838ec3b25a7d609fbc5b ruby-2.7.4.tar.gz' | sha256sum -c - && tar xzf ruby-2.7.4.tar.gz +cd ruby-2.7.4 ./configure --disable-install-rdoc --enable-shared make diff --git a/doc/install/next_steps.md b/doc/install/next_steps.md index f271caef493..e25241f0378 100644 --- a/doc/install/next_steps.md +++ b/doc/install/next_steps.md @@ -4,7 +4,7 @@ group: Distribution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Steps after installing GitLab +# Steps after installing GitLab **(FREE SELF)** Here are a few resources you might want to check out after completing the installation. diff --git a/doc/install/requirements.md b/doc/install/requirements.md index ba515de417f..641b092e1e3 100644 --- a/doc/install/requirements.md +++ b/doc/install/requirements.md @@ -36,7 +36,7 @@ For the installation options, see [the main installation page](index.md). Installation of GitLab on these operating systems is possible, but not supported. Please see the [installation from source guide](installation.md) and the [installation guides](https://about.gitlab.com/install/) for more information. -Please see [OS versions that are no longer supported](https://docs.gitlab.com/omnibus/package-information/deprecated_os.html) for Omnibus installs page +Please see [OS versions that are no longer supported](../administration/package_information/deprecated_os.md) for Omnibus installs page for a list of supported and unsupported OS versions as well as the last support GitLab version for that OS. ### Microsoft Windows @@ -60,6 +60,8 @@ Redis version 6.0 or higher is recommended, as this is what ships with The necessary hard drive space largely depends on the size of the repositories you want to store in GitLab but as a *rule of thumb* you should have at least as much free space as all your repositories combined take up. +The Omnibus GitLab package requires about 2.5 GB of storage space for installation. + If you want to be flexible about growing your hard drive space in the future consider mounting it using [logical volume management (LVM)](https://en.wikipedia.org/wiki/Logical_volume_management) so you can add more hard drives when you need them. Apart from a local hard drive you can also mount a volume that supports the network file system (NFS) protocol. This volume might be located on a file server, a network attached storage (NAS) device, a storage area network (SAN) or on an Amazon Web Services (AWS) Elastic Block Store (EBS) volume. @@ -197,7 +199,7 @@ Take for example the following scenarios: ```plaintext The highest number from 2 - And + And [ the lowest number from - number of cores: 2 @@ -212,11 +214,11 @@ Take for example the following scenarios: ```plaintext The highest number from 2 - And + And [ the lowest number from - number of cores: 4 - - memory limit: (4 - 1.5) = 2.5 + - memory limit: (4 - 1.5) = 2.5 ] ``` @@ -227,7 +229,7 @@ Take for example the following scenarios: ```plaintext The highest number from 2 - And + And [ the lowest number from - number of cores: 4 @@ -254,6 +256,12 @@ of [legacy Rugged code](../administration/gitaly/index.md#direct-access-to-git-i higher, due to how [Ruby MRI multi-threading](https://en.wikipedia.org/wiki/Global_interpreter_lock) works. +### Puma per worker maximum memory + +By default, each Puma worker will be limited to 1024 MB of memory. +This setting [can be adjusted](../administration/operations/puma.md#puma-worker-killer) and should be considered +if you need to increase the number of Puma workers. + ## Redis and Sidekiq Redis stores all user sessions and the background task queue. @@ -321,7 +329,7 @@ For the listed web browsers, GitLab supports: NOTE: We don't support running GitLab with JavaScript disabled in the browser and have no plans of supporting that -in the future because we have features such as Issue Boards which require JavaScript extensively. +in the future because we have features such as issue boards which require JavaScript extensively. <!-- ## Troubleshooting diff --git a/doc/integration/akismet.md b/doc/integration/akismet.md index a652025387e..efc293569fe 100644 --- a/doc/integration/akismet.md +++ b/doc/integration/akismet.md @@ -30,8 +30,8 @@ To use Akismet: 1. Sign in or create a new account. 1. Click **Show** to reveal the API key, and copy the API key's value. 1. Sign in to GitLab as an administrator. -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Reporting** (`/admin/application_settings/reporting`). +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Reporting** (`/admin/application_settings/reporting`). 1. Select the **Enable Akismet** checkbox. 1. Fill in the API key from step 3. 1. Save the configuration. diff --git a/doc/integration/auth0.md b/doc/integration/auth0.md index 34ee326d6d5..870da6cdb3d 100644 --- a/doc/integration/auth0.md +++ b/doc/integration/auth0.md @@ -9,8 +9,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w To enable the Auth0 OmniAuth provider, you must create an Auth0 account, and an application. -1. Sign in to the [Auth0 Console](https://auth0.com/auth/login). If you need to - create an account, you can do so at the same link. +1. Sign in to the [Auth0 Console](https://auth0.com/auth/login). You can also + create an account using the same link. 1. Select **New App/API**. diff --git a/doc/integration/azure.md b/doc/integration/azure.md index dceb135ad89..47d80ab9a66 100644 --- a/doc/integration/azure.md +++ b/doc/integration/azure.md @@ -4,17 +4,19 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Microsoft Azure OAuth2 OmniAuth Provider **(FREE)** +# Microsoft Azure OAuth 2.0 OmniAuth Provider **(FREE)** NOTE: Per Microsoft, this provider uses the [older Azure Active Directory v1.0 endpoint](https://docs.microsoft.com/en-us/azure/active-directory/azuread-dev/v1-protocols-oauth-code). Microsoft documentation suggests that you should use the [OpenID Connect protocol to use the v2 endpoints](../administration/auth/oidc.md#microsoft-azure) for new projects. -To use v2 endpoints via OmniAuth, please follow [Microsoft Azure OAuth2 OmniAuth Provider v2 instructions](#microsoft-azure-oauth2-omniauth-provider-v2). +To use v2 endpoints via OmniAuth, please follow [Microsoft Azure OAuth 2.0 OmniAuth Provider v2 instructions](#microsoft-azure-oauth-20-omniauth-provider-v2). -To enable the Microsoft Azure OAuth2 OmniAuth provider, you must register your application with Azure. Azure generates a client ID and secret key for you to use. +To enable the Microsoft Azure OAuth 2.0 OmniAuth provider, you must register +your application with Azure. Azure generates a client ID and secret key for you +to use. -Sign in to the [Azure Portal](https://portal.azure.com), and follow the instructions in -the [Microsoft Quickstart documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app). +Sign in to the [Azure Portal](https://portal.azure.com), and follow the +instructions in the [Microsoft Quickstart documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app). As you go through the Microsoft procedure, keep the following in mind: @@ -23,9 +25,9 @@ As you go through the Microsoft procedure, keep the following in mind: - The redirect URI requires the URL of the Azure OAuth callback of your GitLab installation. For example, `https://gitlab.mycompany.com/users/auth/azure_oauth2/callback`. The type dropdown should be set to **Web**. -- The `client ID` and `client secret` are terms associated with OAuth 2. In some Microsoft documentation, +- The `client ID` and `client secret` are terms associated with OAuth 2.0. In some Microsoft documentation, the terms may be listed as `Application ID` and `Application Secret`. -- If you need to generate a new client secret, follow the Microsoft documentation +- If you have to generate a new client secret, follow the Microsoft documentation for [creating a new application secret](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#create-a-new-application-secret). - Save the client ID and client secret for your new app, as the client secret is only displayed one time. @@ -89,41 +91,46 @@ As you go through the Microsoft procedure, keep the following in mind: - *If you installed from source,* [restart GitLab](../administration/restart_gitlab.md#installations-from-source). -On the sign-in page, you should now see a Microsoft icon below the regular sign-in form. -Click the icon to begin the authentication process. Microsoft then asks you to -sign in and authorize the GitLab application. If successful, you are returned to GitLab and signed in. +On the sign-in page, you should now see a Microsoft icon below the regular +sign-in form. Click the icon to begin the authentication process. Microsoft then +asks you to sign in and authorize the GitLab application. If successful, you are +returned to GitLab and signed in. Read [Enable OmniAuth for an Existing User](omniauth.md#enable-omniauth-for-an-existing-user) for information on how existing GitLab users can connect to their newly-available Azure AD accounts. -## Microsoft Azure OAuth2 OmniAuth Provider v2 +## Microsoft Azure OAuth 2.0 OmniAuth Provider v2 -In order to use v2 endpoints provided by Microsoft Azure Active Directory you must to configure it via Azure OAuth2 OmniAuth Provider v2. +To use v2 endpoints provided by Microsoft Azure Active Directory you must to +configure it via Azure OAuth 2.0 OmniAuth Provider v2. ### Registering an Azure application -To enable the Microsoft Azure OAuth2 OmniAuth provider, you must register your application with Azure. Azure generates a client ID and secret key for you to use. +To enable the Microsoft Azure OAuth 2.0 OmniAuth provider, you must register +your application with Azure. Azure generates a client ID and secret key for you +to use. -Sign in to the [Azure Portal](https://portal.azure.com), and follow the instructions in -the [Microsoft Quickstart documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app). +Sign in to the [Azure Portal](https://portal.azure.com), and follow the +instructions in the [Microsoft Quickstart documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app). As you go through the Microsoft procedure, keep the following in mind: -- If you have multiple instances of Azure Active Directory, you can switch to the desired tenant. +- If you have multiple instances of Azure Active Directory, you can switch to + the desired tenant. - You're setting up a Web application. - The redirect URI requires the URL of the Azure OAuth callback of your GitLab installation. For example, `https://gitlab.example.com/users/auth/azure_activedirectory_v2/callback`. The type dropdown should be set to **Web**. -- The `client ID` and `client secret` are terms associated with OAuth 2. In some Microsoft documentation, +- The `client ID` and `client secret` are terms associated with OAuth 2.0. In some Microsoft documentation, the terms may be listed as `Application ID` and `Application Secret`. -- If you need to generate a new client secret, follow the Microsoft documentation +- If you have to generate a new client secret, follow the Microsoft documentation for [creating a new application secret](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#create-a-new-application-secret). - Save the client ID and client secret for your new app, as the client secret is only displayed one time. ### Adding API permissions (scopes) -Once you have created an application, follow the [Microsoft Quickstart documentation to expose a web API](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-expose-web-apis). Be sure to add the following delegated permissions under the Microsoft Graph API: +After you have created an application, follow the [Microsoft Quickstart documentation to expose a web API](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-expose-web-apis). Be sure to add the following delegated permissions under the Microsoft Graph API: - `email` - `openid` @@ -181,7 +188,8 @@ Once you have created an application, follow the [Microsoft Quickstart documenta The `scope` parameter is optional and can be added to `args`. Default `scope` is: `openid profile email`. -1. Replace `CLIENT ID`, `CLIENT SECRET`, and `TENANT ID` with the values you got above. +1. Replace `CLIENT ID`, `CLIENT SECRET`, and `TENANT ID` with the values you got + above. 1. Save the configuration file. diff --git a/doc/integration/bitbucket.md b/doc/integration/bitbucket.md index 44aca1ca6b1..7a3f4a7710d 100644 --- a/doc/integration/bitbucket.md +++ b/doc/integration/bitbucket.md @@ -10,8 +10,8 @@ NOTE: Starting from GitLab 11.4, OmniAuth is enabled by default. If you're using an earlier version, you must explicitly enable it. -You can set up Bitbucket.org as an OAuth2 provider to use your -Bitbucket.org account credentials to sign in to GitLab, or import your projects from +You can set up Bitbucket.org as an OAuth 2.0 provider to use your Bitbucket.org +account credentials to sign in to GitLab. You can also import your projects from Bitbucket.org. - To use Bitbucket.org as an OmniAuth provider, follow the diff --git a/doc/integration/cas.md b/doc/integration/cas.md index be54c31ec01..60ce728fa55 100644 --- a/doc/integration/cas.md +++ b/doc/integration/cas.md @@ -6,7 +6,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w # CAS OmniAuth Provider **(FREE)** -To enable the CAS OmniAuth provider you must register your application with your CAS instance. This requires the service URL GitLab supplies to CAS. It should be something like: `https://gitlab.example.com:443/users/auth/cas3/callback?url`. By default handling for SLO is enabled, you only need to configure CAS for back-channel logout. +To enable the CAS OmniAuth provider you must register your application with your +CAS instance. This requires the service URL GitLab supplies to CAS. It should be +something like: `https://gitlab.example.com:443/users/auth/cas3/callback?url`. +Handling for Single Logout (SLO) is enabled by default, so you only have to +configure CAS for back-channel logout. 1. On your GitLab server, open the configuration file. diff --git a/doc/integration/datadog.md b/doc/integration/datadog.md index e06cca19e60..687be5adcf7 100644 --- a/doc/integration/datadog.md +++ b/doc/integration/datadog.md @@ -27,8 +27,8 @@ project, group, or instance level: 1. *For project-level or group-level integrations:* In GitLab, go to your project or group. 1. *For instance-level integrations:* 1. Sign in to GitLab as a user with the [Administrator role](../user/permissions.md). - 1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Integrations**. + 1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Integrations**. 1. Scroll to **Add an integration**, and select **Datadog**. 1. Select **Active** to enable the integration. 1. Specify the [**Datadog site**](https://docs.datadoghq.com/getting_started/site/) to send data to. diff --git a/doc/integration/elasticsearch.md b/doc/integration/elasticsearch.md index 20b66411a7e..9514c298885 100644 --- a/doc/integration/elasticsearch.md +++ b/doc/integration/elasticsearch.md @@ -9,9 +9,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w > Moved to GitLab Premium in 13.9. -This document describes how to enable Advanced Search. After -Advanced Search is enabled, you'll have the benefit of fast search response times -and the advantage of the [special searches](../user/search/advanced_search.md). +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). ## Version requirements @@ -26,94 +25,61 @@ and the advantage of the [special searches](../user/search/advanced_search.md). | GitLab Enterprise Edition 9.0 through 11.4 | Elasticsearch 5.1 through 5.5 | | GitLab Enterprise Edition 8.4 through 8.17 | Elasticsearch 2.4 with [Delete By Query Plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/2.4/plugins-delete-by-query.html) installed | -The Elasticsearch Integration is designed to work with supported versions of -Elasticsearch and follows Elasticsearch's [End of Life Policy](https://www.elastic.co/support/eol). +The Elasticsearch Integration works with supported versions of +Elasticsearch and follows Elasticsearch's [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 the actual removal. +before we remove them. ## System requirements -Elasticsearch requires additional resources in excess of those documented in the +Elasticsearch requires additional resources to those documented in the [GitLab system requirements](../install/requirements.md). -The amount of resources (memory, CPU, storage) varies greatly, based on the -amount of data being indexed into the Elasticsearch cluster. According to +Memory, CPU, and storage resource amounts vary depending on the amount of data you index into the Elasticsearch cluster. Heavily used Elasticsearch clusters may require more resources. According to [Elasticsearch official guidelines](https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html#_memory), each node should have: - [Memory](https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html#_memory): 8 GiB (minimum). -- [CPU](https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html#_cpus): Modern processor with multiple cores. -- [Storage](https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html#_disks): Use SSD storage. The total storage size of all Elasticsearch nodes is about 50% of the total size of your Git repositories. It includes one primary and one replica. +- [CPU](https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html#_cpus): Modern processor with multiple cores. GitLab.com has minimal CPU requirements for Elasticsearch. Multiple cores provide extra concurrency, which is more beneficial than faster CPUs. +- [Storage](https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html#_disks): Use SSD storage. The total storage size of all Elasticsearch nodes is about 50% of the total size of your Git repositories. It includes one primary and one replica. The [`estimate_cluster_size`](#gitlab-advanced-search-rake-tasks) Rake task ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221177) in GitLab 13.10) uses total repository size to estimate the Advanced Search storage requirements. -A few notes on CPU and storage: - -- CPU requirements for Elasticsearch tend to be minimal. There are specific - scenarios where this isn't true, but GitLab.com isn't using Elasticsearch in - an exceptionally CPU-heavy way. More cores are more performant than faster - CPUs. Extra concurrency from multiple cores far outweighs a slightly - faster clock speed in Elasticsearch. - -- Storage requirements for Elasticsearch are important, especially for - indexing-heavy clusters. When possible use SSDs, whose speed is far superior - to any spinning media for Elasticsearch. In testing, nodes that use SSD storage - see boosts in both query and indexing performance. - -- We've introduced the [`estimate_cluster_size`](#gitlab-advanced-search-rake-tasks) - Rake task to estimate the Advanced Search storage requirements in advance, which -- The [`estimate_cluster_size`](#gitlab-advanced-search-rake-tasks) Rake task estimates the - Advanced Search storage requirements in advance. The Rake task uses total repository size - for the calculation. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221177) in GitLab 13.10. - -Keep in mind, these are **minimum requirements** for Elasticsearch. -Heavily-used Elasticsearch clusters likely require considerably more -resources. - -## Installing Elasticsearch +## Install Elasticsearch Elasticsearch is *not* included in the Omnibus packages or when you install from -source. You must [install it separately](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/install-elasticsearch.html "Elasticsearch 7.x installation documentation"). -Be sure to select your version. Providing detailed information on installing -Elasticsearch is out of the scope of this document. +source. You must [install it separately](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/install-elasticsearch.html "Elasticsearch 7.x installation documentation") and ensure you select your version. Detailed information on how to install Elasticsearch is out of the scope of this page. -Elasticsearch should be installed on a separate server, whether you install -it yourself or use a cloud hosted offering like Elastic's [Elasticsearch Service](https://www.elastic.co/elasticsearch/service) -(available on AWS, GCP, or Azure) or the [Amazon Elasticsearch](https://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/es-gsg.html) -service. Running Elasticsearch on the same server as GitLab is not recommended -and can cause a degradation in GitLab instance performance. +You can install Elasticsearch yourself, or use a cloud hosted offering such as [Elasticsearch Service](https://www.elastic.co/elasticsearch/service)(available on AWS, GCP, or Azure) or the [Amazon Elasticsearch](https://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/es-gsg.html) +service. +You should install Elasticsearch on a separate server. Running Elasticsearch on the same server as GitLab is not recommended and can cause a degradation in GitLab instance performance. -**For a single node Elasticsearch cluster the functional cluster health status -is yellow** (will never be green) because the primary shard is allocated but -replicas can not be as there is no other node to which Elasticsearch can assign a -replica. +For a single node Elasticsearch cluster, the functional cluster health status is always yellow due to the allocation of the primary shard. Elasticsearch cannot assign replica shards to the same node as primary shards. -After the data is added to the database or repository and [Elasticsearch is -enabled in the Admin Area](#enabling-advanced-search) the search index is -updated automatically. +The search index updates after you: -## Upgrading to a new Elasticsearch major version +- Add data to the database or repository. +- [Enable Elasticsearch](#enable-advanced-search) in the Admin Area. -Since Elasticsearch can read and use indices created in the previous major version, you don't need to change anything in the GitLab configuration when upgrading Elasticsearch. +## Upgrade to a new Elasticsearch major version -The only thing worth noting is that if you have created your current index before GitLab 13.0, you might want to reindex from scratch (which implicitly creates an alias) in order to use some features, for example [Zero downtime reindexing](#zero-downtime-reindexing). Once you do that, you are able to perform zero-downtime reindexing and will benefit from any future features that make use of the alias. +Elasticsearch reads and uses indices created in the previous major version. You are not required to change the GitLab configuration when you upgrade Elasticsearch. -If you are unsure when your current index was created, -you can check whether it was created after GitLab 13.0 by using the -[Elasticsearch cat aliases API](https://www.elastic.co/guide/en/elasticsearch/reference/7.11/cat-alias.html). -If the list of aliases returned contains an entry for `gitlab-production` that points to an index +If your current index was created before GitLab 13.0, you must reindex from scratch to create an alias to use features such as [zero downtime reindexing](#zero-downtime-reindexing). After you reindex, you can perform zero downtime reindexing and also benefit from future features that use the alias. + +To check if your current index was created before GitLab 13.0, use the [Elasticsearch cat aliases API](https://www.elastic.co/guide/en/elasticsearch/reference/7.11/cat-alias.html). +If the returned list of aliases does not contain a `gitlab-production` alias, you must reindex to use features such as zero downtime reindexing. +If the returned list of aliases contains an entry for `gitlab-production` that points to an index named `gitlab-production-<numerical timestamp>`, your index was created after GitLab 13.0. -If the `gitlab-production` alias is missing, you need to reindex from scratch to use -features such as Zero-downtime reindexing. ## Elasticsearch repository indexer -For indexing Git repository data, GitLab uses an [indexer written in Go](https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer). +To index Git repository data, GitLab uses an [indexer written in Go](https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer). -The way you install the Go indexer depends on your version of GitLab: +Depending on your GitLab version, there are different installation procedures for the Go indexer: - For Omnibus GitLab 11.8 or greater, see [Omnibus GitLab](#omnibus-gitlab). - For installations from source or older versions of Omnibus GitLab, [install the indexer from source](#from-source). -- If you are using GitLab Development Kit, see [GDK Elasticsearch how-to](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/elasticsearch.md) +- If you are using GitLab Development Kit, see [GDK Elasticsearch how-to](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/elasticsearch.md). ### Omnibus GitLab @@ -126,7 +92,7 @@ First, we need to install some dependencies, then we build and install the indexer itself. This project relies on [International Components for Unicode](http://site.icu-project.org/) (ICU) for text encoding, -therefore we need to ensure the development packages for your platform are +therefore we must ensure the development packages for your platform are installed before running `make`. #### Debian / Ubuntu @@ -154,7 +120,7 @@ brew install icu4c export PKG_CONFIG_PATH="/usr/local/opt/icu4c/lib/pkgconfig:$PKG_CONFIG_PATH" ``` -### Building and installing +### Build and install To build and install the indexer, run: @@ -166,7 +132,7 @@ sudo -u git -H bundle exec rake gitlab:indexer:install[$indexer_path] RAILS_ENV= cd $indexer_path && sudo make install ``` -The `gitlab-elasticsearch-indexer` will be installed to `/usr/local/bin`. +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. @@ -177,21 +143,21 @@ Example: PREFIX=/usr sudo -E make install ``` -After installation, be sure to [enable Elasticsearch](#enabling-advanced-search). +After installation, be sure to [enable Elasticsearch](#enable-advanced-search). NOTE: If you see an error such as `Permission denied - /home/git/gitlab-elasticsearch-indexer/` while indexing, you may need to set the `production -> elasticsearch -> indexer_path` setting in your `gitlab.yml` file to `/usr/local/bin/gitlab-elasticsearch-indexer`, which is where the binary is installed. -## Enabling Advanced Search +## Enable Advanced Search For GitLab instances with more than 50GB repository data you can follow the instructions for [Indexing large instances](#indexing-large-instances) below. -To enable Advanced Search, you need to have admin access to GitLab: +To enable Advanced Search, you must have admin access to GitLab: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Advanced Search**. NOTE: @@ -206,7 +172,7 @@ To enable Advanced Search, you need to have admin access to GitLab: 1. Select **Index all projects**. 1. Select **Check progress** in the confirmation message to see the status of the background jobs. -1. Personal snippets need to be indexed using another Rake task: +1. Personal snippets must be indexed using another Rake task: ```shell # Omnibus installations @@ -216,7 +182,7 @@ To enable Advanced Search, you need to have admin access to GitLab: bundle exec rake gitlab:elastic:index_snippets RAILS_ENV=production ``` -1. After the indexing has completed, enable **Search with Elasticsearch enabled** and select **Save changes**. +1. After indexing completes, enable **Search with Elasticsearch enabled** and select **Save changes**. NOTE: When your Elasticsearch cluster is down while Elasticsearch is enabled, @@ -237,8 +203,8 @@ The following Elasticsearch settings are available: | `Username` | The `username` of your Elasticsearch instance. | | `Password` | The password of your Elasticsearch instance. | | `Number of Elasticsearch shards` | Elasticsearch indexes are split into multiple shards for performance reasons. In general, you should use at least 5 shards, and indexes 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 will greatly increase total disk space required by the index. | -| `Limit namespaces and projects that can be indexed` | Enabling this will allow you to select namespaces and projects to index. All other namespaces and projects will use database search instead. If you enable this option but do not select any namespaces or projects, none will be indexed. [Read more below](#limiting-namespaces-and-projects). +| `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 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 will be indexed. [Read more below](#limit-namespaces-and-projects). | `Using AWS hosted Elasticsearch with IAM credentials` | Sign your Elasticsearch 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 Elasticsearch Service](https://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/es-ac.html) for details of AWS hosted Elasticsearch domain access policy configuration. | | `AWS Region` | The AWS region in which your Elasticsearch service is located. | | `AWS Access Key` | The AWS access key. | @@ -255,38 +221,38 @@ 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). -### Limiting namespaces and projects +### Limit namespaces and projects -If you select `Limit namespaces and projects that can be indexed`, more options will become available. +If you select `Limit namespaces and projects that can be indexed`, more options become available.  -You can select namespaces and projects to index exclusively. Note that if the namespace is a group it will include +You can select namespaces and projects to index exclusively. Note that 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 will not provide a code or commit scope. This will be possible only in the scope of an indexed namespace. Currently 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. +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 will 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. You can filter the selection dropdown by writing part of the namespace or project name you're interested in.  NOTE: -If no namespaces or projects are selected, no Advanced Search indexing will take place. +If no namespaces or projects are selected, no Advanced Search indexing takes place. WARNING: -If you have already indexed your instance, you will have to regenerate the index in order to delete all existing data -for filtering to work correctly. To do this run the Rake tasks `gitlab:elastic:recreate_index` and -`gitlab:elastic:clear_index_status`. Afterwards, removing a namespace or a project from the list will delete the data +If you have already indexed your instance, you must regenerate the index to delete all existing data +for filtering to work correctly. To do this, run the Rake tasks `gitlab:elastic:recreate_index` and +`gitlab:elastic:clear_index_status`. Afterwards, removing a namespace or a project from the list deletes the data from the Elasticsearch index as expected. -## Enabling custom language analyzers +## Enable custom language analyzers You can improve the language support for Chinese and Japanese languages by utilizing [`smartcn`](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-smartcn.html) and/or [`kuromoji`](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-kuromoji.html) analysis plugins from Elastic. To enable language(s) support: 1. Install the desired plugin(s), please refer to [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/plugins/7.9/installation.html) for plugins installation instructions. The plugin(s) 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 **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Advanced Search**. 1. Locate **Custom analyzers: language support**. 1. Enable plugin(s) support for **Indexing**. @@ -303,11 +269,11 @@ For guidance on what to install, see the following Elasticsearch language plugin | `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.| -## Disabling Advanced Search +## Disable Advanced Search To disable the Elasticsearch integration: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Advanced Search**. 1. Uncheck **Elasticsearch indexing** and **Search with Elasticsearch enabled**. 1. Click **Save changes** for the changes to take effect. @@ -327,7 +293,7 @@ The idea behind this reindexing method is to leverage the [Elasticsearch reindex and Elasticsearch index alias feature to perform the operation. We set up an index alias which connects to a `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. Once the reindexing job is complete, we switch to the new index by connecting 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. ### Trigger the reindex via the Advanced Search administration @@ -339,7 +305,7 @@ index alias to it which becomes the new `primary` index. At the end, we resume t To trigger the reindexing process: 1. Sign in to your GitLab instance as an administrator. -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Advanced Search**. 1. Expand **Elasticsearch zero-downtime reindexing**. 1. Select **Trigger cluster reindexing**. @@ -350,13 +316,13 @@ After this process is completed, the original index is scheduled to be deleted a 14 days. You can cancel this action by pressing the **Cancel** button on the same page you triggered the reindexing process. -While the reindexing is running, you will be able to follow its progress under that same section. +While the reindexing is running, you can follow its progress under that same section. #### Elasticsearch zero-downtime reindexing > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55681) in GitLab 13.12. -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Advanced Search**. 1. Expand **Elasticsearch zero-downtime reindexing**, and you'll find the following options: @@ -404,7 +370,7 @@ Sometimes, you might want to abandon the unfinished reindex job and resume the i bundle exec rake gitlab:elastic:mark_reindex_failed RAILS_ENV=production ``` -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Advanced Search**. 1. Expand **Elasticsearch zero-downtime reindexing**. 1. Clear the **Pause Elasticsearch indexing** checkbox. @@ -486,8 +452,8 @@ version](../update/index.md#upgrading-to-a-new-major-version). Rake tasks are available to: -- [Build and install](#building-and-installing) the indexer. -- Delete indexes when [disabling Elasticsearch](#disabling-advanced-search). +- [Build and install](#build-and-install) the indexer. +- Delete indexes when [disabling Elasticsearch](#disable-advanced-search). - Add GitLab data to an index. The following are some available Rake tasks: @@ -558,7 +524,7 @@ For basic guidance on choosing a cluster configuration you may refer to [Elastic - 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 will generally help 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 **Menu >** **{admin}** **Admin > Dashboard > Statistics** pane (the number of documents to be indexed), divide by 5 million, and add 5. For example: + - Another consideration is the number of documents. To determine the number of shards to use, sum the numbers in the **Menu > Admin > Dashboard > Statistics** pane (the number of documents to be indexed), divide by 5 million, and add 5. For example: - If you have fewer than about 2,000,000 documents, use the default of 5 shards - 10,000,000 documents: `10000000/5000000 + 5` = 7 shards - 100,000,000 documents: `100000000/5000000 + 5` = 25 shards @@ -573,7 +539,7 @@ For basic guidance on choosing a cluster configuration you may refer to [Elastic ### Indexing large instances This section may be helpful in the event that the other -[basic instructions](#enabling-advanced-search) cause problems +[basic instructions](#enable-advanced-search) cause problems due to large volumes of data being indexed. WARNING: @@ -582,7 +548,7 @@ Make sure to prepare for this task by having a [Scalable and Highly Available Setup](../administration/reference_architectures/index.md) or creating [extra Sidekiq processes](../administration/operations/extra_sidekiq_processes.md). -1. [Configure your Elasticsearch host and port](#enabling-advanced-search). +1. [Configure your Elasticsearch host and port](#enable-advanced-search). 1. Create empty indexes: ```shell @@ -603,7 +569,7 @@ Sidekiq processes](../administration/operations/extra_sidekiq_processes.md). bundle exec rake gitlab:elastic:clear_index_status RAILS_ENV=production ``` -1. [Enable **Elasticsearch indexing**](#enabling-advanced-search). +1. [Enable **Elasticsearch indexing**](#enable-advanced-search). 1. Indexing large Git repositories can take a while. To speed up the process, you can [tune for indexing speed](https://www.elastic.co/guide/en/elasticsearch/reference/current/tune-for-indexing-speed.html#tune-for-indexing-speed): - 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. @@ -635,7 +601,7 @@ Sidekiq processes](../administration/operations/extra_sidekiq_processes.md). ``` This enqueues a Sidekiq job for each project that needs to be indexed. - You can view the jobs in **Menu >** **{admin}** **Admin > Monitoring > Background Jobs > Queues Tab** + You can view the jobs in **Menu > Admin > Monitoring > Background Jobs > Queues Tab** and click `elastic_commit_indexer`, or you can query indexing status using a Rake task: ```shell @@ -734,7 +700,7 @@ Sidekiq processes](../administration/operations/extra_sidekiq_processes.md). } }' ``` -1. After the indexing has completed, enable [**Search with Elasticsearch enabled**](#enabling-advanced-search). +1. After the indexing has completed, enable [**Search with Elasticsearch enabled**](#enable-advanced-search). ### Deleted documents @@ -836,7 +802,7 @@ be necessary for you to [reindex](#zero-downtime-reindexing) after updating GitL ### I indexed all the repositories but I can't get any hits for my search term in the UI -Make sure you indexed all the database data [as stated above](#enabling-advanced-search). +Make sure you indexed all the database data [as stated above](#enable-advanced-search). If there aren't any results (hits) in the UI search, check if you are seeing the same results via the rails console (`sudo gitlab-rails console`): @@ -857,7 +823,7 @@ More [complex Elasticsearch API calls](https://www.elastic.co/guide/en/elasticse It is important to understand at which level the problem is manifesting (UI, Rails code, Elasticsearch side) to be able to [troubleshoot further](../administration/troubleshooting/elasticsearch.md#search-results-workflow). NOTE: -The above instructions are not to be used for scenarios that only index a [subset of namespaces](#limiting-namespaces-and-projects). +The above instructions are not to be used for scenarios that only index a [subset of namespaces](#limit-namespaces-and-projects). See [Elasticsearch Index Scopes](#advanced-search-index-scopes) for more information on searching for specific types of data. @@ -906,25 +872,20 @@ Elasticsearch::Transport::Transport::Errors::BadRequest([400] { This is because we changed the index mapping in GitLab 8.12 and the old indexes should be removed and built from scratch again, see details in the [update guide](../update/upgrading_from_source.md). -- Exception `Elasticsearch::Transport::Transport::Errors::BadRequest` +### `Elasticsearch::Transport::Transport::Errors::BadRequest` - If you have this exception (just like in the case above but the actual message is different) please check if you have the correct Elasticsearch version and you met the other [requirements](#system-requirements). - There is also an easy way to check it automatically with `sudo gitlab-rake gitlab:check` command. +If you have this exception (just like in the case above but the actual message is different) please check if you have the correct Elasticsearch version and you met the other [requirements](#system-requirements). +There is also an easy way to check it automatically with `sudo gitlab-rake gitlab:check` command. -- Exception `Elasticsearch::Transport::Transport::Errors::RequestEntityTooLarge` +### `Elasticsearch::Transport::Transport::Errors::RequestEntityTooLarge` - ```plaintext - [413] {"Message":"Request size exceeded 10485760 bytes"} - ``` +```plaintext +[413] {"Message":"Request size exceeded 10485760 bytes"} +``` - This exception is seen when your Elasticsearch cluster is configured to reject - requests above a certain size (10MiB in this case). This corresponds to the - `http.max_content_length` setting in `elasticsearch.yml`. Increase it to a - larger size and restart your Elasticsearch cluster. +This exception is seen when your Elasticsearch cluster is configured to reject requests above a certain size (10MiB in this case). This corresponds to the `http.max_content_length` setting in `elasticsearch.yml`. Increase it to a larger size and restart your Elasticsearch cluster. - AWS has [fixed limits](https://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/aes-limits.html) - for this setting ("Maximum Size of HTTP Request Payloads"), based on the size of - the underlying instance. +AWS has [fixed limits](https://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/aes-limits.html) for this setting ("Maximum Size of HTTP Request Payloads"), based on the size of the underlying instance. ### My single node Elasticsearch cluster status never goes from `yellow` to `green` even though everything seems to be running properly @@ -953,7 +914,7 @@ Gitlab::Elastic::Indexer::Error: time="2020-01-23T09:13:00Z" level=fatal msg="he ``` You probably have not used either `http://` or `https://` as part of your value in the **"URL"** field of the Elasticsearch Integration Menu. Please make sure you are using either `http://` or `https://` in this field as the [Elasticsearch client for Go](https://github.com/olivere/elastic) that we are using [needs the prefix for the URL to be accepted as valid](https://github.com/olivere/elastic/commit/a80af35aa41856dc2c986204e2b64eab81ccac3a). -Once you have corrected the formatting of the URL, delete the index (via the [dedicated Rake task](#gitlab-advanced-search-rake-tasks)) and [reindex the content of your instance](#enabling-advanced-search). +Once you have corrected the formatting of the URL, delete the index (via the [dedicated Rake task](#gitlab-advanced-search-rake-tasks)) and [reindex the content of your instance](#enable-advanced-search). ### My Elasticsearch cluster has a plugin and the integration is not working diff --git a/doc/integration/facebook.md b/doc/integration/facebook.md index ded89dd93a4..58c53db7996 100644 --- a/doc/integration/facebook.md +++ b/doc/integration/facebook.md @@ -4,9 +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/engineering/ux/technical-writing/#assignments --- -# Facebook OAuth2 OmniAuth Provider **(FREE)** +# Facebook OAuth 2.0 OmniAuth Provider **(FREE)** -To enable the Facebook OmniAuth provider you must register your application with Facebook. Facebook generates an app ID and secret key for you to use. +To enable the Facebook OmniAuth provider you must register your application with +Facebook. Facebook generates an app ID and secret key for you to use. 1. Sign in to the [Facebook Developer Platform](https://developers.facebook.com/). @@ -14,8 +15,9 @@ To enable the Facebook OmniAuth provider you must register your application with 1. Select the type "Website" -1. Enter a name for your app. This can be anything. Consider something like "<Organization>'s GitLab" or "<Your Name>'s GitLab" or - something else descriptive. +1. Enter a name for your app. This can be anything. Consider something like + "<Organization>'s GitLab" or "<Your Name>'s GitLab" or something + else descriptive. 1. Choose "Create New Facebook App ID" @@ -49,7 +51,8 @@ To enable the Facebook OmniAuth provider you must register your application with 1. Choose "Show" next to the hidden "App Secret" -1. You should now see an app key and app secret (see screenshot). Keep this page open as you continue configuration. +1. You should now see an app key and app secret (see screenshot). Keep this page + open as you continue configuration.  @@ -101,4 +104,7 @@ To enable the Facebook OmniAuth provider you must register your application with 1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) for the changes to take effect if you installed GitLab via Omnibus or from source respectively. -On the sign in page there should now be a Facebook icon below the regular sign in form. Click the icon to begin the authentication process. Facebook asks the user to sign in and authorize the GitLab application. If everything goes well the user is returned to GitLab and signed in. +On the sign in page there should now be a Facebook icon below the regular sign +in form. Click the icon to begin the authentication process. Facebook asks the +user to sign in and authorize the GitLab application. If everything goes well +the user is returned to GitLab and signed in. diff --git a/doc/integration/github.md b/doc/integration/github.md index f3192e0af6c..0a96d67ac0c 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -188,7 +188,7 @@ GitHub account` when signing in, in GitLab: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Account**. +1. On the left sidebar, select **Account**. 1. In the **Social sign-in** section, select **Connect to GitHub**. After that, you should be able to sign in via GitHub successfully. diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md index a0b438c9ffa..1f35faacc2e 100644 --- a/doc/integration/gitlab.md +++ b/doc/integration/gitlab.md @@ -14,7 +14,7 @@ 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. Select **Edit profile**. -1. In the left sidebar, select **Applications**. +1. On the left sidebar, select **Applications**. 1. Provide the required details for **Add new application**. - Name: This can be anything. Consider something like `<Organization>'s GitLab` or `<Your Name>'s GitLab` or something else descriptive. - Redirect URI: diff --git a/doc/integration/gitpod.md b/doc/integration/gitpod.md index e3cd3075bc9..bafba2cdf02 100644 --- a/doc/integration/gitpod.md +++ b/doc/integration/gitpod.md @@ -44,11 +44,11 @@ With the Gitpod integration enabled for your GitLab instance, to enable it for y For GitLab self-managed instances, a GitLab administrator needs to: -1. Set up a Gitpod instance to integrate with GitLab. Refer to the [Gitpod documentation](https://www.gitpod.io/docs/self-hosted/latest/self-hosted/) +1. Set up a Gitpod instance to integrate with GitLab. Refer to the [Gitpod documentation](https://www.gitpod.io/docs/self-hosted/latest) to get your instance up and running. 1. Enable it in GitLab: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. - 1. In the left sidebar, select **Settings > General**. + 1. On the top bar, select **Menu > Admin**. + 1. On the left sidebar, select **Settings > General**. 1. Expand the **Gitpod** configuration section. 1. Check the **Enable Gitpod integration** checkbox. 1. Add your Gitpod instance URL (for example, `https://gitpod.example.com`). diff --git a/doc/integration/gmail_action_buttons_for_gitlab.md b/doc/integration/gmail_action_buttons_for_gitlab.md index f0bcc00c0fa..0468e5d0a42 100644 --- a/doc/integration/gmail_action_buttons_for_gitlab.md +++ b/doc/integration/gmail_action_buttons_for_gitlab.md @@ -12,10 +12,11 @@ If correctly set up, emails that require an action are marked in Gmail.  -To get this functioning, you need to be registered with Google. For instructions, see +To get this functioning, you must be registered with Google. For instructions, see [Register with Google](https://developers.google.com/gmail/markup/registering-with-google). -This process has many steps. Make sure that you fulfill all requirements set by Google to avoid your application being rejected by Google. +This process has many steps. Make sure that you fulfill all requirements set by +Google to avoid your application being rejected by Google. In particular, note: diff --git a/doc/integration/google.md b/doc/integration/google.md index a08944f65f1..4a2c61577ac 100644 --- a/doc/integration/google.md +++ b/doc/integration/google.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/engineering/ux/technical-writing/#assignments --- -# Google OAuth2 OmniAuth Provider **(FREE)** +# Google OAuth 2.0 OmniAuth Provider **(FREE)** -To enable the Google OAuth2 OmniAuth provider you must register your application +To enable the Google OAuth 2.0 OmniAuth provider you must register your application with Google. Google generates a client ID and secret key for you to use. -## Enabling Google OAuth +## Enable Google OAuth In Google's side: @@ -47,7 +47,7 @@ In Google's side: - Cloud Resource Manager API - Cloud Billing API - To do so you need to: + To do so you should: 1. Go to the [Google API Console](https://console.developers.google.com/apis/dashboard). 1. Click on **ENABLE APIS AND SERVICES** button at the top of the page. @@ -98,8 +98,8 @@ On your GitLab server: 1. Change `YOUR_APP_ID` to the client ID from the Google Developer page 1. Similarly, change `YOUR_APP_SECRET` to the client secret -1. Make sure that you configure GitLab to use a fully-qualified domain name, as Google doesn't accept - raw IP addresses. +1. Make sure that you configure GitLab to use a fully-qualified domain name, as + Google doesn't accept raw IP addresses. For Omnibus packages: @@ -115,8 +115,10 @@ On your GitLab server: ``` 1. Save the configuration file. -1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) for the changes to take effect if you - installed GitLab via Omnibus or from source respectively. +1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) + or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) for + the changes to take effect if you installed GitLab via Omnibus or from source + respectively. On the sign in page there should now be a Google icon below the regular sign in form. Click the icon to begin the authentication process. Google asks the diff --git a/doc/integration/jenkins.md b/doc/integration/jenkins.md index 8910e0978b0..18ae71a7059 100644 --- a/doc/integration/jenkins.md +++ b/doc/integration/jenkins.md @@ -74,7 +74,7 @@ Create a personal access token to authorize Jenkins' access to GitLab. 1. Sign in to GitLab as the user to be used with Jenkins. 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Access Tokens**. +1. On the left sidebar, select **Access Tokens**. 1. Create a personal access token with the **API** scope checkbox checked. For more details, see [Personal access tokens](../user/profile/personal_access_tokens.md). 1. Record the personal access token's value, because it's required in [Configure the Jenkins server](#configure-the-jenkins-server) section. diff --git a/doc/integration/jenkins_deprecated.md b/doc/integration/jenkins_deprecated.md index b7e4c4f0e26..e349bb4e88f 100644 --- a/doc/integration/jenkins_deprecated.md +++ b/doc/integration/jenkins_deprecated.md @@ -40,7 +40,7 @@ In GitLab, perform the following steps. ### Read access to repository Jenkins needs read access to the GitLab repository. We already specified a -private key to use in Jenkins, now we need to add a public one to the GitLab +private key to use in Jenkins, now we must add a public one to the GitLab project. For that case we need a Deploy key. Read the documentation on [how to set up a Deploy key](../user/project/deploy_keys/index.md). @@ -50,7 +50,8 @@ Now navigate to GitLab services page and activate Jenkins  -Done! When you push to GitLab, it creates a build for Jenkins. You can view the merge request build status with a link to the Jenkins build. +Done! When you push to GitLab, it creates a build for Jenkins. You can view the +merge request build status with a link to the Jenkins build. ### Multi-project Configuration diff --git a/doc/integration/jira/configure.md b/doc/integration/jira/configure.md index b11f367258d..d4e5a1bfca1 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/engineering/ux/technical-writing/#assignments --- -# Configure the Jira integration in GitLab +# Configure the Jira integration in GitLab **(FREE)** You can set up the [Jira integration](index.md#jira-integration) by configuring your project settings in GitLab. diff --git a/doc/integration/jira/connect-app.md b/doc/integration/jira/connect-app.md index e32bd4559f9..7d32c080fff 100644 --- a/doc/integration/jira/connect-app.md +++ b/doc/integration/jira/connect-app.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w NOTE: Only Jira users with administrator level access are able to install or configure -the GitLab app for Jira Cloud. +the GitLab.com for Jira Cloud app. ## GitLab.com for Jira Cloud app **(FREE SAAS)** @@ -60,6 +60,14 @@ 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 + +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/) +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). + ## Install the GitLab.com for Jira Cloud app for self-managed instances **(FREE SELF)** If your GitLab instance is self-managed, you must follow some @@ -78,10 +86,10 @@ self-managed GitLab instances with Jira Cloud, you can either: You can configure your Atlassian Cloud instance to allow you to install applications from outside the Marketplace, which allows you to install the application: -1. Sign in to your Jira instance as a user with administrator permissions. +1. Sign in to your Jira instance as a user with an Administrator role. 1. Place your Jira instance into [development mode](https://developer.atlassian.com/cloud/jira/platform/getting-started-with-connect/#step-2--enable-development-mode). -1. Sign in to your GitLab application as a user with [Administrator](../../user/permissions.md) permissions. +1. Sign in to your GitLab application as a user with an [Administrator](../../user/permissions.md) role. 1. Install the GitLab application from your self-managed GitLab instance, as described in the [Atlassian developer guides](https://developer.atlassian.com/cloud/jira/platform/getting-started-with-connect/#step-3--install-and-test-your-app): 1. In your Jira instance, go to **Apps > Manage Apps** and click **Upload app**: @@ -103,13 +111,13 @@ The **GitLab.com for Jira Cloud** app now displays under **Manage apps**. You ca click **Get started** to open the configuration page rendered from your GitLab instance. NOTE: -If you make changes to the application descriptor, you must uninstall, then reinstall, the +If a GitLab update makes changes to the application descriptor, you must uninstall, then reinstall, the application. ### Create a Marketplace listing **(FREE SELF)** If you prefer to not use development mode on your Jira instance, you can create -your own Marketplace listing for your instance, which enables your application +your own Marketplace listing for your instance. This enables your application to be installed from the Atlassian Marketplace. For full instructions, review the Atlassian [guide to creating a marketplace listing](https://developer.atlassian.com/platform/marketplace/installing-cloud-apps/#creating-the-marketplace-listing). To create a @@ -127,11 +135,15 @@ Review the for details. NOTE: -DVCS means distributed version control system. +Using this method, [updates are automated](#update-the-gitlabcom-for-jira-cloud-app) +the same way as when using our GitLab.com Marketplace listing. -## Troubleshooting GitLab.com for Jira Cloud app +## Troubleshoot GitLab.com for Jira Cloud app -The GitLab.com for Jira Cloud app uses an iframe to add namespaces on the settings page. Some browsers block cross-site cookies, which can lead to a message saying that the user needs to log in on GitLab.com even though the user is already logged in. +The GitLab.com for Jira Cloud app uses an iframe to add namespaces on the +settings page. Some browsers block cross-site cookies, which can lead to a +message saying that the user needs to log in on GitLab.com even though the user +is already logged in. > "You need to sign in or sign up before continuing." diff --git a/doc/integration/jira/development_panel.md b/doc/integration/jira/development_panel.md index c8ea224f18e..5a2ce8a0a75 100644 --- a/doc/integration/jira/development_panel.md +++ b/doc/integration/jira/development_panel.md @@ -65,11 +65,11 @@ For an overview of how to configure Jira Development panel integration, see [Agile Management - GitLab Jira Development panel integration](https://www.youtube.com/watch?v=VjVTOmMl85M). To simplify administration, we recommend that a GitLab group maintainer or group owner -(or instance administrator in the case of self-managed GitLab) set up the integration. +(or, if possible, instance administrator in the case of self-managed GitLab) set up the integration. | Jira usage | GitLab.com customers need | GitLab self-managed customers need | |------------|---------------------------|------------------------------------| -| [Atlassian cloud](https://www.atlassian.com/cloud) | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview) application installed from the [Atlassian Marketplace](https://marketplace.atlassian.com). This offers real-time sync between GitLab and Jira. For more information, see the documentation for the [GitLab.com for Jira Cloud app](connect-app.md). | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview), using a workaround process. See the documentation for [installing the GitLab Jira Cloud application for self-managed instances](connect-app.md#install-the-gitlabcom-for-jira-cloud-app-for-self-managed-instances) for more information. | +| [Atlassian cloud](https://www.atlassian.com/cloud) | The [GitLab.com for Jira Cloud app](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview) installed from the [Atlassian Marketplace](https://marketplace.atlassian.com). This offers real-time sync between GitLab.com and Jira. For more information, see the documentation for the [GitLab.com for Jira Cloud app](connect-app.md). | The [GitLab.com for Jira Cloud app](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview), using a workaround process. See the documentation for [installing the GitLab.com for Jira Cloud app for self-managed instances](connect-app.md#install-the-gitlabcom-for-jira-cloud-app-for-self-managed-instances) for more information. | | Your own server | The [Jira DVCS (distributed version control system) connector](dvcs.md). This syncs data hourly. | The [Jira DVCS Connector](dvcs.md). | Each GitLab project can be configured to connect to an entire Jira instance. That means after @@ -89,10 +89,6 @@ This integration is not supported on GitLab instances under a [relative URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab). For example, `http://example.com/gitlab`. -## Related topics - -- [Using Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html) in Jira - ## Troubleshooting ### Cookies for Oracle's Access Manager diff --git a/doc/integration/jira/dvcs.md b/doc/integration/jira/dvcs.md index 7d97312757e..664a0361da4 100644 --- a/doc/integration/jira/dvcs.md +++ b/doc/integration/jira/dvcs.md @@ -8,15 +8,16 @@ 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 and GitLab.com, you should use the -[GitLab.com for Jira Cloud app](connect-app.md) unless you specifically need the DVCS connector. +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 +DVCS connector. When you configure the Jira DVCS connector, make sure your GitLab and Jira instances are accessible. - **Self-managed GitLab**: Your GitLab instance must be accessible by Jira. -- **Jira Cloud**: Your instance must be accessible through the internet. - **Jira Server**: Your network must allow access to your instance. +- **Jira Cloud**: Your instance must be accessible through the internet. ## Smart commits @@ -61,25 +62,25 @@ you can still perform multiple actions in a single commit: ## Configure a GitLab application for DVCS -We recommend you create and use a `jira` user in GitLab, and use the account only -for integration work. A separate account ensures regular account maintenance does not affect -your integration. +We recommend you create and use a `jira` user in GitLab, and use the account +only for integration work. A separate account ensures regular account +maintenance does not affect your integration. If a `jira` user is not feasible, +you can set up this integration with your own account instead. 1. In GitLab, [create a user](../../user/profile/account/create_accounts.md) for Jira to - use to connect to GitLab. For Jira to access all projects, - a user with [administrator](../../user/permissions.md) permissions must - create the user with administrator permissions. + use to connect to GitLab. This user must be added to each project you want Jira to have access to, + or have an [Administrator](../../user/permissions.md) role to access all projects. 1. Sign in as the `jira` user. 1. In the top right corner, click the account's avatar, and select **Edit profile**. -1. In the left sidebar, select **Applications**. +1. On the left sidebar, select **Applications**. 1. In the **Name** field, enter a descriptive name for the integration, such as `Jira`. 1. In the **Redirect URI** field, enter the URI appropriate for your version of GitLab, replacing `<gitlab.example.com>` with your GitLab instance domain: - *For GitLab versions 13.0 and later* **and** *Jira versions 8.14 and later,* use the generated `Redirect URL` from [Linking GitLab accounts with Jira](https://confluence.atlassian.com/adminjiraserver/linking-gitlab-accounts-1027142272.html). - - *For GitLab versions 13.0 and later* **and** *Jira Cloud,* use `https://<gitlab.example.com>/login/oauth/callback`. - - *For GitLab versions 11.3 and later,* use `https://<gitlab.example.com>/login/oauth/callback`. + - *For GitLab versions 13.0 and later* **and** *Jira Cloud,* use `https://<gitlab.example.com>/login/oauth/callback`. + - *For GitLab versions 11.3 and later* **and** *Jira versions 8.13 and earlier,* use `https://<gitlab.example.com>/login/oauth/callback`. If you use GitLab.com, the URL is `https://gitlab.com/login/oauth/callback`. - *For GitLab versions 11.2 and earlier,* use `https://<gitlab.example.com>/-/jira/login/oauth/callback`. @@ -105,9 +106,9 @@ it completes, refreshes every 60 minutes: - *For Jira versions 8.13 and earlier:* Select **GitHub Enterprise**. 1. For **Team or User Account**, enter either: - *For Jira versions 8.14 and later:* - - The relative path of a top-level GitLab group that you have access to. + - The relative path of a top-level GitLab group that [the GitLab user](#configure-a-gitlab-application-for-dvcs) has access to. - *For Jira versions 8.13 and earlier:* - - The relative path of a top-level GitLab group that you have access to. + - The relative path of a top-level GitLab group that [the GitLab user](#configure-a-gitlab-application-for-dvcs) has access to. - The relative path of your personal namespace. 1. In the **Host URL** field, enter the URI appropriate for your version of GitLab, @@ -141,7 +142,7 @@ can refresh the data manually from the Jira interface: column, select the icon:  -## Troubleshooting your DVCS connection +## Troubleshoot your DVCS connection Refer to the items in this section if you're having problems with your DVCS connector. @@ -174,7 +175,8 @@ Error obtaining access token. Cannot access https://gitlab.example.com from Jira must have the appropriate certificate (such as your organization's root certificate) added to it . -Refer to Atlassian's documentation and Atlassian Support for assistance setting up Jira correctly: +Refer to Atlassian's documentation and Atlassian Support for assistance setting +up Jira correctly: - [Add a certificate](https://confluence.atlassian.com/kb/how-to-import-a-public-ssl-certificate-into-a-jvm-867025849.html) to the trust store. @@ -232,9 +234,17 @@ To resolve this issue: [Contact GitLab Support](https://about.gitlab.com/support/) if none of these reasons apply. +### `410 : Gone` error when connecting to Jira + +When you connect to Jira and synchronize repositories, you may receive a `410 : Gone` error. + +This issue occurs when you use the Jira DVCS connector and your integration is configured to use **GitHub Enterprise**. + +For more information and possible fixes, see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/340160). + ### Fix synchronization issues -If Jira displays incorrect information, such as deleted branches, you may need to +If Jira displays incorrect information, such as deleted branches, you may have to resynchronize the information. To do so: 1. In Jira, go to **Jira Administration > Applications > DVCS accounts**. diff --git a/doc/integration/jira/index.md b/doc/integration/jira/index.md index febd9907028..85f99b49c41 100644 --- a/doc/integration/jira/index.md +++ b/doc/integration/jira/index.md @@ -26,9 +26,7 @@ The supported Jira versions are `v6.x`, `v7.x`, and `v8.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). -To set up the integration, [configure the project settings](configure.md) in GitLab. -You can also configure these settings at a [group level](../../user/admin_area/settings/project_integration_management.md#manage-group-level-default-settings-for-a-project-integration), -and for self-managed GitLab, at an [instance level](../../user/admin_area/settings/project_integration_management.md#manage-instance-level-default-settings-for-a-project-integration). +To set up the integration, [configure the settings](configure.md) in GitLab. ### Jira development panel integration @@ -37,12 +35,9 @@ 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: - -- *If your installation uses Jira Cloud,* use the - [GitLab for Jira app](connect-app.md). -- *If either your Jira or GitLab installation is self-managed,* use the - [Jira DVCS Connector](dvcs.md). +To set up the Jira development panel integration, use the GitLab.com for Jira Cloud app +or the Jira DVCS (distributed version control system) connector, +[depending on your installation](development_panel.md#configure-the-integration). ### Direct feature comparison diff --git a/doc/integration/jira/jira_cloud_configuration.md b/doc/integration/jira/jira_cloud_configuration.md index e42a102e030..0cfffdb8ba4 100644 --- a/doc/integration/jira/jira_cloud_configuration.md +++ b/doc/integration/jira/jira_cloud_configuration.md @@ -11,10 +11,10 @@ on Atlassian cloud. To create the API token: 1. Sign in to [`id.atlassian.com`](https://id.atlassian.com/manage-profile/security/api-tokens) with your email address. Use an account with *write* access to Jira projects. -1. Go to **Settings > API tokens**. +1. Go to **Settings > Atlassian account settings > Security > Create and manage API tokens**. 1. Select **Create API token** to display a modal window with an API token. -1. To copy the API token, select **Copy to clipboard**, or select **View** and write - down the new API token. You need this value when you +1. In the dialog, enter a label for your token and select **Create**. +1. To copy the API token, select **Copy**, then paste the token somewhere safe. You need this value when you [configure GitLab](configure.md). You need the newly created token, and the email diff --git a/doc/integration/jira/jira_server_configuration.md b/doc/integration/jira/jira_server_configuration.md index 52e7e5e412b..32a8cd430f9 100644 --- a/doc/integration/jira/jira_server_configuration.md +++ b/doc/integration/jira/jira_server_configuration.md @@ -25,7 +25,7 @@ This process creates a user named `gitlab` and adds it to a new group named `git 1. Create a new user account (`gitlab`) with write access to projects in Jira. - **Email address**: Jira requires a valid email address, and sends a verification - email, which you need to set up the password. + email, which is required to set up the password. - **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 diff --git a/doc/integration/kerberos.md b/doc/integration/kerberos.md index ba3f246f5f5..48339144292 100644 --- a/doc/integration/kerberos.md +++ b/doc/integration/kerberos.md @@ -9,6 +9,11 @@ type: reference, how-to GitLab can integrate with [Kerberos](https://web.mit.edu/kerberos/) as an authentication mechanism. +WARNING: +GitLab CI/CD does not work with a Kerberos-enabled GitLab instance due to an unresolved +[bug in Git CLI](https://lore.kernel.org/git/YKNVop80H8xSTCjz@coredump.intra.peff.net/T/#mab47fd7dcb61fee651f7cc8710b8edc6f62983d5) +that fails to use job token authentication from the GitLab Runners. + ## Overview [Kerberos](https://web.mit.edu/kerberos/) is a secure method for authenticating a request for a service in a @@ -85,6 +90,9 @@ For source installations, make sure the `kerberos` gem group gitlab_rails['kerberos_keytab'] = "/etc/http.keytab" ``` + To avoid GitLab creating users automatically on their first sign in through Kerberos, + don't set `kerberos` for `gitlab_rails['omniauth_allow_single_sign_on']`. + 1. [Reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. GitLab now offers the `negotiate` authentication method for signing in and @@ -107,7 +115,7 @@ set up GitLab to create a new account when a Kerberos user tries to sign in. If you're an administrator, you can link a Kerberos account to an existing GitLab account. To do so: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Select a user, then select the **Identities** tab. 1. Select 'Kerberos SPNEGO' in the 'Provider' dropdown box. @@ -118,7 +126,7 @@ If you're not an administrator: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Account**. +1. On the left sidebar, select **Account**. 1. In the **Social sign-in** section, select **Connect Kerberos SPNEGO**. If you don't see a **Social sign-in** Kerberos option, follow the requirements in [Enable single sign-on](#enable-single-sign-on). @@ -147,7 +155,7 @@ With that information at hand: ``` 1. As an administrator, you can confirm the new, blocked account: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users** and review the **Blocked** tab. 1. You can enable the user. 1. If `block_auto_created_users` is false, the Kerberos user is diff --git a/doc/integration/mattermost/gitlab-mattermost.msc b/doc/integration/mattermost/gitlab-mattermost.msc new file mode 100644 index 00000000000..f6d4bf7aa68 --- /dev/null +++ b/doc/integration/mattermost/gitlab-mattermost.msc @@ -0,0 +1,28 @@ +msc { + # Use https://mscgen.js.org or mscgen to convert this into PNG + hscale="1.5", + wordwraparcs=on; + + user [ label="User", textbgcolor="blue", textcolor="white" ], + mattermost [ label="Mattermost", textbgcolor="red", textcolor="white"], + gitlab [ label="GitLab", textbgcolor="indigo", textcolor="white"]; + + user=>mattermost [label="GET https://mm.domain.com"]; + mattermost note gitlab [label="Obtain access code", textcolor="green"]; + mattermost=>gitlab [label="GET https://gitlab.domain.com/oauth/authorize", textcolor="indigo"]; + gitlab rbox user [label="GitLab user logs in (if necessary)"]; + gitlab rbox gitlab [label="GitLab verifies client_id matches an OAuth application"]; + gitlab=>user [label="GitLab asks user to authorize Mattermost OAuth app"]; + user=>gitlab [label="User clicks 'Allow'"]; + gitlab rbox gitlab [label="GitLab verifies redirect_uri matches list of valid URLs"]; + gitlab=>user [label="302 Redirect: https://mm.domain.com/signup/gitlab/complete"]; + user=>mattermost [label="GET https://mm.domain.com/signup/gitlab/complete", textcolor="red"]; + mattermost note gitlab [label="Exchange access code for access token", textcolor="green"]; + mattermost=>gitlab [label="POST http://gitlab.domain.com/oauth/token", textcolor="indigo"]; + gitlab=>gitlab [label="Doorkeeper::TokensController#create"]; + gitlab=>mattermost [label="Access token", textcolor="red"]; + mattermost note gitlab [label="Mattermost looks up GitLab user", textcolor="green"]; + mattermost=>gitlab [label="GET https://gitlab.domain.com/api/v4/user", textcolor="indigo"]; + gitlab=>mattermost [label="User details", textcolor="red"]; + mattermost=>user [label="Mattermost/GitLab user ready"]; +} diff --git a/doc/integration/mattermost/img/gitlab-mattermost.png b/doc/integration/mattermost/img/gitlab-mattermost.png Binary files differnew file mode 100644 index 00000000000..1eedcb391b0 --- /dev/null +++ b/doc/integration/mattermost/img/gitlab-mattermost.png diff --git a/doc/integration/mattermost/index.md b/doc/integration/mattermost/index.md new file mode 100644 index 00000000000..4830f8ba84e --- /dev/null +++ b/doc/integration/mattermost/index.md @@ -0,0 +1,495 @@ +--- +stage: Enablement +group: Distribution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# GitLab Mattermost + +NOTE: +This document applies to GitLab 11.0 and later. + +You can run a [GitLab Mattermost](https://gitlab.com/gitlab-org/gitlab-mattermost) +service on your GitLab server. Mattermost is not part of the single application that GitLab is. There is a good integration between with GitLab, and our Omnibus installer allows you to easily install it. But it is a separate application from a separate company. + +## Prerequisites + +Each release of GitLab Mattermost is compiled and manually tested on an AMD 64 chipset for Linux. ARM chipsets and operating systems, like Raspberry Pi, are not supported. + +## Getting started + +GitLab Mattermost expects to run on its own virtual host. In your DNS settings you will need +two entries pointing to the same machine, e.g., `gitlab.example.com` and +`mattermost.example.com`. + +GitLab Mattermost is disabled by default. To enable it: + +1. Edit `/etc/gitlab/gitlab.rb` and add the Mattermost external URL: + + ```ruby + mattermost_external_url 'https://mattermost.example.com' + ``` + +1. Reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +1. Confirm that GitLab Mattermost is reachable at `https://mattermost.example.com` and authorized to connect to GitLab. Authorizing Mattermost with GitLab allows users to use GitLab as an SSO provider. + +The Omnibus GitLab package attempts to automatically authorize GitLab Mattermost with GitLab if the applications are running on the same server. + +Automatic authorization requires access to the GitLab database. If the GitLab database is not available +you will need to manually authorize GitLab Mattermost for access to GitLab using the process described in the [Authorize GitLab Mattermost section](#authorize-gitlab-mattermost). + +## Configuring Mattermost + +Starting in GitLab 11.0, Mattermost can be configured using the Mattermost System Console. An extensive list of +Mattermost settings and where they can be set is available [in the Mattermost documentation](https://docs.mattermost.com/administration/config-settings.html). + +While using the System Console is recommended, you can also configure Mattermost using one of the following options: + +1. Edit the Mattermost configuration directly through `/var/opt/gitlab/mattermost/config.json`. +1. Specify environment variables used to run Mattermost by changing the `mattermost['env']` setting in `gitlab.rb`. Any settings configured in this way will be disabled from the System Console and cannot be changed without restarting Mattermost. + +## Running GitLab Mattermost with HTTPS + +Place the SSL certificate and SSL certificate key inside `/etc/gitlab/ssl`. If the directory doesn't exist, create it: + +```shell +sudo mkdir -p /etc/gitlab/ssl +sudo chmod 755 /etc/gitlab/ssl +sudo cp mattermost.gitlab.example.key mattermost.gitlab.example.crt /etc/gitlab/ssl/ +``` + +In `/etc/gitlab/gitlab.rb` specify the following configuration: + +```ruby +mattermost_external_url 'https://mattermost.gitlab.example' +mattermost_nginx['redirect_http_to_https'] = true +``` + +If you haven't named your certificate and key `mattermost.gitlab.example.crt` +and `mattermost.gitlab.example.key` then you'll need to also add the full paths +as shown below. + +```ruby +mattermost_nginx['ssl_certificate'] = "/etc/gitlab/ssl/mattermost-nginx.crt" +mattermost_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/mattermost-nginx.key" +``` + +where `mattermost-nginx.crt` and `mattermost-nginx.key` are SSL cert and key, respectively. + +Once the configuration is set, run `sudo gitlab-ctl reconfigure` to apply the changes. + +## Running GitLab Mattermost on its own server + +If you want to run GitLab and GitLab Mattermost on two separate servers the GitLab services will still be set up on your GitLab Mattermost server, but they will not accept user requests or +consume system resources. You can use the following settings and configuration details on the GitLab Mattermost server to effectively disable the GitLab service bundled into the Omnibus package. + +```ruby +mattermost_external_url 'http://mattermost.example.com' + +# Shut down GitLab services on the Mattermost server +gitlab_rails['enable'] = false +redis['enable'] = false +postgres_exporter['enable'] = false +``` + +Then follow the appropriate steps in the [Authorize GitLab Mattermost section](#authorize-gitlab-mattermost). Last, to enable +integrations with GitLab add the following on the GitLab Server: + +```ruby +gitlab_rails['mattermost_host'] = "https://mattermost.example.com" +``` + +By default GitLab Mattermost requires all users to sign up with GitLab and disables the sign-up by email option. See Mattermost [documentation on GitLab SSO](https://docs.mattermost.com/deployment/sso-gitlab.html). + +## Manually (re)authorizing GitLab Mattermost with GitLab + +### Reauthorize GitLab Mattermost + +To reauthorize GitLab Mattermost, you first need to revoke the existing +authorization. This can be done in the **Settings > Applications** area of GitLab. Then follow the steps below to complete authorization. + +### Authorize GitLab Mattermost + +Navigate to the **Settings > Applications** area in GitLab. Create a new application and for the **Redirect URI** use the following (replace `http` with `https` if you use HTTPS): + +```plaintext +http://mattermost.example.com/signup/gitlab/complete +http://mattermost.example.com/login/gitlab/complete +``` + +Note that you do not need to select any options under **Scopes**. Choose **Save application**. + +Once the application is created you will be provided with an `Application ID` and `Secret`. One other piece of information needed is the URL of GitLab instance. +Return to the server running GitLab Mattermost and edit the `/etc/gitlab/gitlab.rb` configuration file as follows using the values you received above: + +```ruby +mattermost['gitlab_enable'] = true +mattermost['gitlab_id'] = "12345656" +mattermost['gitlab_secret'] = "123456789" +mattermost['gitlab_scope'] = "" +mattermost['gitlab_auth_endpoint'] = "http://gitlab.example.com/oauth/authorize" +mattermost['gitlab_token_endpoint'] = "http://gitlab.example.com/oauth/token" +mattermost['gitlab_user_api_endpoint'] = "http://gitlab.example.com/api/v4/user" +``` + +Save the changes and then run `sudo gitlab-ctl reconfigure`. If there are no errors your GitLab and GitLab Mattermost should be configured correctly. + +### Specify numeric user and group identifiers + +Omnibus GitLab creates a user and group `mattermost`. You can specify the +numeric identifiers for these users in `/etc/gitlab/gitlab.rb` as follows: + +```ruby +mattermost['uid'] = 1234 +mattermost['gid'] = 1234 +``` + +Run `sudo gitlab-ctl reconfigure` to apply the changes. + +### Setting custom environment variables + +If necessary you can set custom environment variables to be used by Mattermost +via `/etc/gitlab/gitlab.rb`. This can be useful if the Mattermost server +is operated behind a corporate internet proxy. In `/etc/gitlab/gitlab.rb` +supply a `mattermost['env']` with a hash value. For example: + +```ruby +mattermost['env'] = {"HTTP_PROXY" => "my_proxy", "HTTPS_PROXY" => "my_proxy", "NO_PROXY" => "my_no_proxy"} +``` + +Run `sudo gitlab-ctl reconfigure` to apply the changes. + +### Connecting to the bundled PostgreSQL database + +If you need to connect to the bundled PostgreSQL database and are using the default Omnibus GitLab database configuration, you can connect as +the PostgreSQL superuser: + +```shell +sudo gitlab-psql -d mattermost_production +``` + +### Back up GitLab Mattermost + +GitLab Mattermost is not included in the regular [Omnibus GitLab backup](../../raketasks/backup_restore.md#back-up-gitlab) Rake task. + +The general Mattermost [backup and disaster recovery](https://docs.mattermost.com/deploy/backup-disaster-recovery.html) documentation can be used as a guide +on what needs to be backed up. + +#### Back up the bundled PostgreSQL database + +If you need to back up the bundled PostgreSQL database and are using the default Omnibus GitLab database configuration, you can back up using this command: + +```shell +sudo -i -u gitlab-psql -- /opt/gitlab/embedded/bin/pg_dump -h /var/opt/gitlab/postgresql mattermost_production | gzip > mattermost_dbdump_$(date --rfc-3339=date).sql.gz +``` + +#### Back up the `data` directory and `config.json` + +Mattermost has a `data` directory and `config.json` file that will need to be backed up as well: + +```shell +sudo tar -zcvf mattermost_data_$(date --rfc-3339=date).gz -C /var/opt/gitlab/mattermost data config.json +``` + +### Restore GitLab Mattermost + +If you have previously [created a backup of GitLab Mattermost](#back-up-gitlab-mattermost), you can run the following commands to restore it: + +```shell +# Stop Mattermost so we don't have any open database connections +sudo gitlab-ctl stop mattermost + +# Drop the Mattermost database +sudo -u gitlab-psql /opt/gitlab/embedded/bin/dropdb -U gitlab-psql -h /var/opt/gitlab/postgresql -p 5432 mattermost_production + +# Create the Mattermost database +sudo -u gitlab-psql /opt/gitlab/embedded/bin/createdb -U gitlab-psql -h /var/opt/gitlab/postgresql -p 5432 mattermost_production + +# Perform the database restore +# Replace /tmp/mattermost_dbdump_2021-08-05.sql.gz with your backup +sudo -u mattermost sh -c "zcat /tmp/mattermost_dbdump_2021-08-05.sql.gz | /opt/gitlab/embedded/bin/psql -U gitlab_mattermost -h /var/opt/gitlab/postgresql -p 5432 mattermost_production" + +# Restore the data directory and config.json +# Replace /tmp/mattermost_data_2021-08-09.gz with your backup +sudo tar -xzvf /tmp/mattermost_data_2021-08-09.gz -C /var/opt/gitlab/mattermost + +# Fix permissions if required +sudo chown -R mattermost:mattermost /var/opt/gitlab/mattermost/data +sudo chown mattermost:mattermost /var/opt/gitlab/mattermost/config.json + +# Start Mattermost +sudo gitlab-ctl start mattermost +``` + +### Mattermost Command Line Tools (CLI) + +NOTE: +This CLI will be replaced in a future release with the new [`mmctl` Command Line Tool](https://docs.mattermost.com/administration/mmctl-cli-tool.html). + +To use the [Mattermost Command Line Tools (CLI)](https://docs.mattermost.com/administration/command-line-tools.html), ensure that you are in the `/opt/gitlab/embedded/service/mattermost` directory when you run the CLI commands and that you specify the location of the configuration file. The executable is `/opt/gitlab/embedded/bin/mattermost`. + +```shell +cd /opt/gitlab/embedded/service/mattermost + +sudo /opt/gitlab/embedded/bin/chpst -e /opt/gitlab/etc/mattermost/env -P -U mattermost:mattermost -u mattermost:mattermost /opt/gitlab/embedded/bin/mattermost --config=/var/opt/gitlab/mattermost/config.json version +``` + +Until [#4745](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/4745) has been implemented, the command requires quite of bit typing and is hard to remember, so let's make a bash/zsh alias to make it a bit easier to remember. Add the following to your `~/.bashrc` or `~/.zshrc` file: + +```shell +alias mattermost-cli="cd /opt/gitlab/embedded/service/mattermost && sudo /opt/gitlab/embedded/bin/chpst -e /opt/gitlab/etc/mattermost/env -P -U mattermost:mattermost -u mattermost:mattermost /opt/gitlab/embedded/bin/mattermost --config=/var/opt/gitlab/mattermost/config.json $1" +``` + +Then source `~/.zshrc` or `~/.bashrc` with `source ~/.zshrc` or `source ~/.bashrc`. + +If successful, you can now run any Mattermost CLI command with your new shell alias `mattermost-cli`: + +```shell +$ mattermost-cli version + +[sudo] password for username: +{"level":"info","ts":1569614421.9058893,"caller":"utils/i18n.go:83","msg":"Loaded system translations for 'en' from '/opt/gitlab/embedded/service/mattermost/i18n/en.json'"} +{"level":"info","ts":1569614421.9062793,"caller":"app/server_app_adapters.go:58","msg":"Server is initializing..."} +{"level":"info","ts":1569614421.90976,"caller":"sqlstore/supplier.go:223","msg":"Pinging SQL master database"} +{"level":"info","ts":1569614422.0515099,"caller":"mlog/log.go:165","msg":"Starting up plugins"} +{"level":"info","ts":1569614422.0515954,"caller":"app/plugin.go:193","msg":"Syncing plugins from the file store"} +{"level":"info","ts":1569614422.086005,"caller":"app/plugin.go:228","msg":"Found no files in plugins file store"} +{"level":"info","ts":1569614423.9337213,"caller":"sqlstore/post_store.go:1301","msg":"Post.Message supports at most 16383 characters (65535 bytes)"} +{"level":"error","ts":1569614425.6317747,"caller":"go-plugin/stream.go:15","msg":" call to OnConfigurationChange failed, error: Must have a GitLab oauth client id","plugin_id":"com.github.manland.mattermost-plugin-gitlab","source":"plugin_stderr"} +{"level":"info","ts":1569614425.6875598,"caller":"mlog/sugar.go:19","msg":"Ensuring Surveybot exists","plugin_id":"com.mattermost.nps"} +{"level":"info","ts":1569614425.6953356,"caller":"app/server.go:216","msg":"Current version is 5.14.0 (5.14.2/Fri Aug 30 20:20:48 UTC 2019/817ee89711bf26d33f840ce7f59fba14da1ed168/none)"} +{"level":"info","ts":1569614425.6953766,"caller":"app/server.go:217","msg":"Enterprise Enabled: false"} +{"level":"info","ts":1569614425.6954057,"caller":"app/server.go:219","msg":"Current working directory is /opt/gitlab/embedded/service/mattermost/i18n"} +{"level":"info","ts":1569614425.6954265,"caller":"app/server.go:220","msg":"Loaded config","source":"file:///var/opt/gitlab/mattermost/config.json"} +Version: 5.14.0 +Build Number: 5.14.2 +Build Date: Fri Aug 30 20:20:48 UTC 2019 +Build Hash: 817ee89711bf26d33f840ce7f59fba14da1ed168 +Build Enterprise Ready: false +DB Version: 5.14.0 +``` + +For more details see [Mattermost Command Line Tools (CLI)](https://docs.mattermost.com/administration/command-line-tools.html) and the [Troubleshooting Mattermost CLI](#troubleshooting-the-mattermost-cli) below. + +## Configuring GitLab and Mattermost integrations + +As of 12.3, the Mattermost GitLab plugin is shipped with Omnibus GitLab: [Mattermost Plugin for GitLab documentation](https://github.com/mattermost/mattermost-plugin-gitlab). + +You can use the plugin to subscribe Mattermost to receive notifications about issues, merge requests, and pull requests as well as personal notifications regarding merge request reviews, unread messages, and task assignments. If you want to use slash commands to perform actions +such as creating and viewing issues, or to trigger deployments use GitLab [Mattermost slash commands](../../user/project/integrations/mattermost_slash_commands.md). + +The plugin and slash commands can be used together or individually. + +## Email Notifications + +### Setting up SMTP for GitLab Mattermost + +These settings are configured through the Mattermost System Console by the System Administrator. +On the **Environment > SMTP** tab of the **System Console**, you can enter the SMTP credentials given by your SMTP provider, or `127.0.0.1` and port `25` to use `sendmail`. More information on the specific settings +that are needed is available in the [Mattermost documentation](https://docs.mattermost.com/install/smtp-email-setup.html). + +These settings can also be configured in `/var/opt/gitlab/mattermost/config.json`. + +### Email batching + +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**. + +This setting can also be configured in `/var/opt/gitlab/mattermost/config.json`. + +## Upgrading GitLab Mattermost + +Below is a list of Mattermost versions for GitLab 11.10 and later: + +| GitLab Version | Mattermost Version | +| :------------ |:----------------| +| 11.11 | 5.10 | +| 12.0 | 5.11 | +| 12.1 | 5.12 | +| 12.2 | 5.13 | +| 12.3 | 5.14 | +| 12.4 | 5.15 | +| 12.5 | 5.16 | +| 12.6 | 5.17 | +| 12.7 | 5.17 | +| 12.8 | 5.19 | +| 12.9 | 5.20 | +| 12.10 | 5.21 | +| 13.0 | 5.22 | +| 13.1 | 5.23 | +| 13.2 | 5.24 | +| 13.3 | 5.25 | +| 13.4 | 5.26 | +| 13.5 | 5.27 | +| 13.6 | 5.28 | +| 13.7 | 5.29 | +| 13.8 | 5.30 | +| 13.9 | 5.31 | +| 13.10 | 5.32 | +| 13.11 | 5.33 | +| 13.12 | 5.34 | +| 14.0 | 5.35 | +| 14.1 | 5.36 | +| 14.2 | 5.37 | +| 14.3 | 5.38 | + +NOTE: +When upgrading the Mattermost version, it is essential to check the +[Important Upgrade Notes](https://docs.mattermost.com/administration/important-upgrade-notes.html) +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 that process can only be used if Mattermost configuration settings have not been changed outside of GitLab (i.e., no changes to Mattermost's `config.json` +file have been made, either directly or via the Mattermost **System Console** which saves back 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. + +If this is not the case, there are two options: + +1. Update [`gitlab.rb`](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-config-template/gitlab.rb.template#L706) + with the changes done to `config.json`. This might require adding some parameters as not all + settings in `config.json` are available in `gitlab.rb`. Once complete, Omnibus GitLab should be + able to upgrade GitLab Mattermost from one version to the next. +1. Migrate Mattermost outside of the directory controlled by Omnibus GitLab so it can be administered + and upgraded independently. Follow the [Mattermost Migration Guide](https://docs.mattermost.com/administration/migrating.html) + to move your Mattermost configuration settings and data to another directory or server independent + from Omnibus GitLab. + +For a complete list of upgrade notices and special considerations for older versions, see the [Mattermost documentation](https://docs.mattermost.com/administration/important-upgrade-notes.html). + +## Upgrading GitLab Mattermost from versions prior to 11.0 + +With version 11.0, GitLab introduced breaking changes which affected Mattermost configuration. +In versions prior to GitLab 11.0 all +Mattermost-related settings were configurable from the `gitlab.rb` file, which +generated the Mattermost `config.json` file. However, Mattermost also +permitted configuration via its System Console. This configuration ended up in +the same `config.json` file, which resulted in changes made via the System Console being +overwritten when users ran `gitlab-ctl reconfigure`. + +To resolve this problem, `gitlab.rb` includes only the +configuration necessary for GitLab<=>Mattermost integration in 11.0. GitLab no longer +generates the `config.json` file, and instead passes limited configuration settings via environment variables. + +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, +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 +in preparation for GitLab 11.0: + +1. Upgrade to version 10.x which supports the new `mattermost['env']` setting. +1. Configure any settings not listed above through the `mattermost['env']` setting. Mattermost requires + environment variables to be provided in `MM_<CATEGORY>SETTINGS_<ATTRIBUTE>` format. Below is an example + of how to convert the old settings syntax to the new one. + +The following settings in `gitlab.rb`: + +```ruby +mattermost['service_maximum_login_attempts'] = 10 +mattermost['team_teammate_name_display'] = "full_name" +mattermost['sql_max_idle_conns'] = 10 +mattermost['log_file_level'] = 'INFO' +mattermost['email_batching_interval'] = 30 +mattermost['file_enable_file_attachments'] = true +mattermost['ratelimit_memory_store_size'] = 10000 +mattermost['support_terms_of_service_link'] = "/static/help/terms.html" +mattermost['privacy_show_email_address'] = true +mattermost['localization_available_locales'] = "en,es,fr,ja,pt-BR" +mattermost['webrtc_enable'] = false +``` + +Would translate to: + +```ruby +mattermost['env'] = { + 'MM_SERVICESETTINGS_MAXIMUMLOGINATTEMPTS' => '10', + 'MM_TEAMSETTINGS_TEAMMATENAMEDISPLAY' => 'full_name', + 'MM_SQLSETTINGS_MAXIDLECONNS' => '10', + 'MM_LOGSETTINGS_FILELEVEL' => 'INFO', + 'MM_EMAILSETTINGS_BATCHINGINTERVAL' => '30', + 'MM_FILESETTINGS_ENABLEFILEATTACHMENTS' => 'true', + 'MM_RATELIMITSETTINGS_MEMORYSTORESIZE' => '10000', + 'MM_SUPPORTSETTINGS_TERMSOFSERVICELINK' => '/static/help/terms.html', + 'MM_PRIVACYSETTINGS_SHOWEMAILADDRESS' => 'true', + 'MM_LOCALIZATIONSETTINGS_AVAILABLELOCALES' => 'en,es,fr,ja,pt-BR', + 'MM_WEBRTCSETTINGS_ENABLE' => 'false' + } +``` + +Refer to the [Mattermost Configuration Settings +documentation](https://docs.mattermost.com/administration/config-settings.html) +for details about categories, configuration values, etc. + +There are a few exceptions to this rule: + +1. `ServiceSettings.ListenAddress` configuration of Mattermost is configured + by `mattermost['service_address']` and `mattermost['service_port']` settings. +1. Configuration settings named in an inconsistent way are given in the + following table. Use these mappings when converting them to environment + variables. + +|`gitlab.rb` configuration|Environment variable| +|---|---| +|`mattermost['service_lets_encrypt_cert_cache_file']`|`MM_SERVICESETTINGS_LETSENCRYPTCERTIFICATECACHEFILE`| +|`mattermost['service_user_access_tokens']`|`MM_SERVICESETTINGS_ENABLEUSERACCESSTOKENS`| +|`mattermost['log_console_enable']`|`MM_LOGSETTINGS_ENABLECONSOLE`| +|`mattermost['email_enable_batching']`|`MM_EMAILSETTINGS_ENABLEEMAILBATCHING`| +|`mattermost['email_batching_buffer_size']`|`MM_EMAILSETTINGS_EMAILBATCHINGBUFFERSIZE`| +|`mattermost['email_batching_interval']`|`MM_EMAILSETTINGS_EMAILBATCHINGINTERVAL`| +|`mattermost['email_smtp_auth']`|`MM_EMAILSETTINGS_ENABLESMTPAUTH`| +|`mattermost['email_notification_content_type']`|`MM_EMAILSETTINGS_NOTIFICATIONCONTENTTYPE`| +|`mattermost['ratelimit_enable_ratelimiter']`|`MM_RATELIMITSETTINGS_ENABLE`| +|`mattermost['support_email']`|`MM_SUPPORTSETTINGS_SUPPORTEMAIL`| +|`mattermost['localization_server_locale']`|`MM_LOCALIZATIONSETTINGS_DEFAULTSERVERLOCALE`| +|`mattermost['localization_client_locale']`|`MM_LOCALIZATIONSETTINGS_DEFAULTCLIENTLOCALE`| +|`mattermost['webrtc_gateway_stun_uri']`|`MM_WEBRTCSETTINGS_STUN_URI`| +|`mattermost['webrtc_gateway_turn_uri']`|`MM_WEBRTCSETTINGS_TURN_URI`| +|`mattermost['webrtc_gateway_turn_username']`|`MM_WEBRTCSETTINGS_TURN_USERNAME`| +|`mattermost['webrtc_gateway_turn_sharedkey']`|`MM_WEBRTCSETTINGS_TURN_SHAREDKEY`| + +NOTE: +GitLab 11.0 no longer generates `config.json` file from the configuration specified +in `gitlab.rb`. Users are responsible for managing this file which can be done via the +Mattermost System Console or manually. +If a configuration setting is specified via both the `gitlab.rb` (as an environment variable) +and `config.json` files, the environment variable gets precedence. + +If you encounter any issues [visit the GitLab Mattermost troubleshooting forum](https://forum.mattermost.org/t/upgrading-to-gitlab-mattermost-in-gitlab-8-9/1735) and share any relevant portions of `mattermost.log` along with the step at which you encountered issues. + +### Upgrading GitLab Mattermost outside of GitLab + +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 + +The following image is a sequence diagram for how GitLab works as an OAuth2 +provider for Mattermost. You can use this to troubleshoot errors +in getting the integration to work: + + + +## Troubleshooting the Mattermost CLI + +### Failed to ping DB retrying in 10 seconds err=dial tcp: lookup dockerhost: no such host + +As of version 11.0, majority of the Mattermost settings are now configured via environmental variables. The error is mainly due to the database connection string being commented out in `gitlab.rb` and the database connection settings being set in environmental variables. Additionally, the connection string in the `gitlab.rb` is for MySQL which is no longer supported as of 12.1. + +You can fix this by setting up a `mattermost-cli` [shell alias](#mattermost-command-line-tools-cli). + +## Community support resources + +For help and support around your GitLab Mattermost deployment please see: + +- [Troubleshooting Forum](https://forum.mattermost.org/t/how-to-use-the-troubleshooting-forum/150) for configuration questions and issues. +- [Troubleshooting FAQ](https://docs.mattermost.com/install/troubleshooting.html). +- [Mattermost GitLab Issues Support Handbook](https://docs.mattermost.com/process/support.html?highlight=omnibus#gitlab-issues). +- [GitLab Mattermost issue tracker](https://gitlab.com/gitlab-org/gitlab-mattermost/-/issues) for verified bugs with repro steps. diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md index 596fff47716..5df6c4f28b7 100644 --- a/doc/integration/oauth_provider.md +++ b/doc/integration/oauth_provider.md @@ -4,17 +4,17 @@ group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab as OAuth2 authentication service provider +# GitLab as an OAuth 2.0 authentication service provider -This document describes how you can use GitLab as an OAuth 2 +This document describes how you can use GitLab as an OAuth 2.0 authentication service provider. If you want to use: -- The [OAuth2](https://oauth.net/2/) protocol to access GitLab resources on user's behalf, - see [OAuth2 provider](../api/oauth2.md). -- Other OAuth 2 authentication service providers to sign in to - GitLab, see the [OAuth2 client documentation](omniauth.md). +- The [OAuth 2.0](https://oauth.net/2/) protocol to access GitLab resources on + a user's behalf, see [OAuth 2.0 provider](../api/oauth2.md). +- Other OAuth 2.0 authentication service providers to sign in to + GitLab, see the [OAuth 2.0 client documentation](omniauth.md). - The related API, see [Applications API](../api/applications.md). ## Introduction to OAuth @@ -48,7 +48,7 @@ To add a new application for your user: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Applications**. +1. On the left sidebar, select **Applications**. 1. Enter a **Name**, **Redirect URI** and OAuth 2 scopes as defined in [Authorized Applications](#authorized-applications). The **Redirect URI** is the URL where users are sent after they authorize with GitLab. 1. Select **Save application**. GitLab provides: @@ -81,7 +81,7 @@ To add a new application for a group: To create an application for your GitLab instance: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Applications**. 1. Select **New application**. diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index bba3252fe76..7dc775c2557 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -7,8 +7,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # OmniAuth **(FREE)** GitLab leverages OmniAuth to allow users to sign in using Twitter, GitHub, and -other popular services. [OmniAuth](https://rubygems.org/gems/omniauth/) is -"a generalized Rack framework for multiple-provider authentication, built on Ruby. +other popular services. [OmniAuth](https://rubygems.org/gems/omniauth/) is a +"generalized Rack framework for multiple-provider authentication" built on Ruby. Configuring OmniAuth does not prevent standard GitLab authentication or LDAP (if configured) from continuing to work. Users can choose to sign in using any @@ -22,36 +22,38 @@ of the configured mechanisms. ## Supported Providers -This is a list of the current supported OmniAuth providers. Before proceeding on each provider's documentation, -make sure to first read this document as it contains some settings that are common for all providers. - -|Provider documentation |OmniAuth provider name | -|-----------------------------------------------------------------|--------------------------| -|[Atlassian Crowd](../administration/auth/crowd.md) |`crowd` | -|[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#microsoft-azure-oauth2-omniauth-provider-v2) |`azure_activedirectory_v2`| -|[Azure v1](azure.md) |`azure_oauth2` | -|[Bitbucket Cloud](bitbucket.md) |`bitbucket` | -|[CAS](cas.md) |`cas3` | -|[Facebook](facebook.md) |`facebook` | -|[Generic OAuth2](oauth2_generic.md) |`oauth2_generic` | -|[GitHub](github.md) |`github` | -|[GitLab.com](gitlab.md) |`gitlab` | -|[Google](google.md) |`google_oauth2` | -|[JWT](../administration/auth/jwt.md) |`jwt` | -|[Kerberos](kerberos.md) |`kerberos` | -|[OpenID Connect](../administration/auth/oidc.md) |`openid_connect` | -|[Salesforce](salesforce.md) |`salesforce` | -|[SAML](saml.md) |`saml` | -|[Shibboleth](shibboleth.md) |`shibboleth` | -|[Twitter](twitter.md) |`twitter` | +This is a list of the current supported OmniAuth providers. Before proceeding on +each provider's documentation, make sure to first read this document as it +contains some settings that are common for all providers. + +| Provider documentation | OmniAuth provider name | +|---------------------------------------------------------------------|----------------------------| +| [Atlassian Crowd](../administration/auth/crowd.md) | `crowd` | +| [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#microsoft-azure-oauth-20-omniauth-provider-v2) | `azure_activedirectory_v2` | +| [Azure v1](azure.md) | `azure_oauth2` | +| [Bitbucket Cloud](bitbucket.md) | `bitbucket` | +| [CAS](cas.md) | `cas3` | +| [Facebook](facebook.md) | `facebook` | +| [Generic OAuth 2.0](oauth2_generic.md) | `oauth2_generic` | +| [GitHub](github.md) | `github` | +| [GitLab.com](gitlab.md) | `gitlab` | +| [Google](google.md) | `google_oauth2` | +| [JWT](../administration/auth/jwt.md) | `jwt` | +| [Kerberos](kerberos.md) | `kerberos` | +| [OpenID Connect](../administration/auth/oidc.md) | `openid_connect` | +| [Salesforce](salesforce.md) | `salesforce` | +| [SAML](saml.md) | `saml` | +| [Shibboleth](shibboleth.md) | `shibboleth` | +| [Twitter](twitter.md) | `twitter` | ## Initial OmniAuth Configuration -The OmniAuth provider names from the table above are needed to configure a few global settings that are in common for all providers. +The OmniAuth provider names from the table above are needed to configure a few +global settings that are in common for all providers. NOTE: Starting from GitLab 11.4, OmniAuth is enabled by default. If you're using an @@ -65,18 +67,19 @@ earlier version, you must explicitly enable it. gitlab_rails['omniauth_allow_single_sign_on'] = ['azure_activedirectory_v2', 'google_oauth2'] ``` - The value defaults to `false`. If `false` users must be created manually, or they can't sign in by using OmniAuth. + The value defaults to `false`. If `false` users must be created manually, or + they can't sign in by using OmniAuth. + - `auto_link_ldap_user` can be used if you have [LDAP / ActiveDirectory](../administration/auth/ldap/index.md) integration enabled. It defaults to `false`. When enabled, users automatically created through an OmniAuth provider have their LDAP identity created in GitLab as well. -- `block_auto_created_users` defaults to `true`. If `true` auto created users will - be blocked by default and must be unblocked by an administrator before - they are able to sign in. +- `block_auto_created_users` defaults to `true`. If `true`, auto created users will + be blocked pending approval by an administrator before they are able to sign in. NOTE: If you set `block_auto_created_users` to `false`, make sure to only define providers under `allow_single_sign_on` that you are able to control, like -SAML, Shibboleth, Crowd, or Google. Otherwise, set it to `false`, or any user on +SAML, Shibboleth, Crowd, or Google. Otherwise, set it to `true`, or any user on the Internet can successfully sign in to your GitLab without administrative approval. @@ -150,7 +153,7 @@ OmniAuth provider for an existing user. 1. Sign in normally - whether standard sign in, LDAP, or another OmniAuth provider. 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Account**. +1. On the left sidebar, select **Account**. 1. In the **Connected Accounts** section, select the desired OmniAuth provider, such as Twitter. 1. The user is redirected to the provider. After the user authorizes GitLab, they are redirected back to GitLab. @@ -166,23 +169,21 @@ Automatic linking using this method works for all providers [except the SAML provider](https://gitlab.com/gitlab-org/gitlab/-/issues/338293). For automatic linking using the SAML provider, see [SAML-specific](saml.md#general-setup) instructions. -As an example, the following configuration is used to enable the auto link feature for both: - -- OpenID Connect provider. -- Twitter OAuth provider. +As an example, the following configuration is used to enable the auto link +feature for both an **OpenID Connect provider** and a **Twitter OAuth provider**. -**For Omnibus installations** +- **For Omnibus installations** -```ruby -gitlab_rails['omniauth_auto_link_user'] = ["openid_connect", "twitter"] -``` + ```ruby + gitlab_rails['omniauth_auto_link_user'] = ["openid_connect", "twitter"] + ``` -**For installations from source** +- **For installations from source** -```yaml -omniauth: - auto_link_user: ["openid_connect", "twitter"] -``` + ```yaml + omniauth: + auto_link_user: ["openid_connect", "twitter"] + ``` ## Configure OmniAuth Providers as External @@ -197,18 +198,18 @@ If you decide to remove an OmniAuth provider from the external providers list, you must manually update the users that use this method to sign in if you want their accounts to be upgraded to full internal accounts. -**For Omnibus installations** +- **For Omnibus installations** -```ruby -gitlab_rails['omniauth_external_providers'] = ['twitter', 'google_oauth2'] -``` + ```ruby + gitlab_rails['omniauth_external_providers'] = ['twitter', 'google_oauth2'] + ``` -**For installations from source** +- **For installations from source** -```yaml -omniauth: - external_providers: ['twitter', 'google_oauth2'] -``` + ```yaml + omniauth: + external_providers: ['twitter', 'google_oauth2'] + ``` ## Using Custom OmniAuth Providers @@ -217,7 +218,7 @@ The following information only applies for installations from source. GitLab uses [OmniAuth](https://github.com/omniauth/omniauth) for authentication and already ships with a few providers pre-installed, such as LDAP, GitHub, and Twitter. You may also -need to integrate with other authentication solutions. For +have to integrate with other authentication solutions. For these cases, you can use the OmniAuth provider. ### Steps @@ -268,8 +269,8 @@ By default, **Sign In** is enabled by using all the OAuth Providers that have be To enable/disable an OmniAuth provider: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, go to **Settings**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, go to **Settings**. 1. Scroll to the **Sign-in Restrictions** section, and click **Expand**. 1. Below **Enabled OAuth Sign-In sources**, select the checkbox for each provider you want to enable or disable. @@ -283,18 +284,18 @@ has an effect if providers are configured and [enabled](#enable-or-disable-sign- If OmniAuth providers are causing problems even when individually disabled, you can disable the entire OmniAuth subsystem by modifying the configuration file: -**For Omnibus installations** +- **For Omnibus installations** -```ruby -gitlab_rails['omniauth_enabled'] = false -``` + ```ruby + gitlab_rails['omniauth_enabled'] = false + ``` -**For installations from source** +- **For installations from source**: -```yaml -omniauth: - enabled: false -``` + ```yaml + omniauth: + enabled: false + ``` ## Keep OmniAuth user profiles up to date @@ -302,18 +303,20 @@ You can enable profile syncing from selected OmniAuth providers and for all or f When authenticating using LDAP, the user's name and email are always synced. -```ruby -gitlab_rails['omniauth_sync_profile_from_provider'] = ['twitter', 'google_oauth2'] -gitlab_rails['omniauth_sync_profile_attributes'] = ['name', 'email', 'location'] -``` +- **For Omnibus installations** + + ```ruby + gitlab_rails['omniauth_sync_profile_from_provider'] = ['twitter', 'google_oauth2'] + gitlab_rails['omniauth_sync_profile_attributes'] = ['name', 'email', 'location'] + ``` -**For installations from source** +- **For installations from source** -```yaml -omniauth: - sync_profile_from_provider: ['twitter', 'google_oauth2'] - sync_profile_attributes: ['email', 'location'] -``` + ```yaml + omniauth: + sync_profile_from_provider: ['twitter', 'google_oauth2'] + sync_profile_attributes: ['email', 'location'] + ``` ## Bypassing two factor authentication @@ -325,16 +328,18 @@ or as `true` or `false` to allow all providers (or none). This option should be configured only for providers which already have two factor authentication (default: false). This configuration doesn't apply to SAML. -```ruby -gitlab_rails['omniauth_allow_bypass_two_factor'] = ['twitter', 'google_oauth2'] -``` +- **For Omnibus package** -**For installations from source** + ```ruby + gitlab_rails['omniauth_allow_bypass_two_factor'] = ['twitter', 'google_oauth2'] + ``` + +- **For installations from source** -```yaml -omniauth: - allow_bypass_two_factor: ['twitter', 'google_oauth2'] -``` + ```yaml + omniauth: + allow_bypass_two_factor: ['twitter', 'google_oauth2'] + ``` ## Automatically sign in with provider @@ -342,25 +347,25 @@ You can add the `auto_sign_in_with_provider` setting to your GitLab configuration to redirect login requests to your OmniAuth provider for authentication. This removes the need to click a button before actually signing in. -For example, when using the [Azure v2 integration](azure.md#microsoft-azure-oauth2-omniauth-provider-v2), set the following to enable auto +For example, when using the [Azure v2 integration](azure.md#microsoft-azure-oauth-20-omniauth-provider-v2), set the following to enable auto sign-in: -For Omnibus package: +- **For Omnibus package** -```ruby -gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'azure_activedirectory_v2' -``` + ```ruby + gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'azure_activedirectory_v2' + ``` -For installations from source: +- **For installations from source** -```yaml -omniauth: - auto_sign_in_with_provider: azure_activedirectory_v2 -``` + ```yaml + omniauth: + auto_sign_in_with_provider: azure_activedirectory_v2 + ``` Keep in mind that every sign-in attempt is redirected to the OmniAuth provider; you can't sign in using local credentials. Ensure at least -one of the OmniAuth users has administrator permissions. +one of the OmniAuth users has an administrator role. You may also bypass the auto sign in feature by browsing to `https://gitlab.example.com/users/sign_in?auto_sign_in=false`. @@ -378,18 +383,22 @@ After you ensure your image is optimized for rendering at 64 x 64 pixels, you can override this icon in one of two ways: - **Provide a custom image path**: + 1. *If you are hosting the image outside of your GitLab server domain,* ensure your [content security policies](https://docs.gitlab.com/omnibus/settings/configuration.html#content-security-policy) are configured to allow access to the image file. 1. Depending on your method of installing GitLab, add a custom `icon` parameter to your GitLab configuration file. Read [OpenID Connect OmniAuth provider](../administration/auth/oidc.md) for an example for the OpenID Connect provider. + - **Directly embed an image in a configuration file**: This example creates a Base64-encoded version of your image you can serve through a [Data URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs): + 1. Encode your image file with GNU `base64` command (such as `base64 -w 0 <logo.png>`) which returns a single-line `<base64-data>` string. - 1. Add the Base64-encoded data to a custom `icon` parameter in your GitLab configuration file: + 1. Add the Base64-encoded data to a custom `icon` parameter in your GitLab + configuration file: ```yaml omniauth: diff --git a/doc/integration/openid_connect_provider.md b/doc/integration/openid_connect_provider.md index 84457485382..dd65fb4822a 100644 --- a/doc/integration/openid_connect_provider.md +++ b/doc/integration/openid_connect_provider.md @@ -49,6 +49,7 @@ The following user information is shared with clients: | `website` | `string` | URL for the user's website | `profile` | `string` | URL for the user's GitLab profile | `picture` | `string` | URL for the user's GitLab avatar -| `groups` | `array` | Names of the groups the user is a member of +| `groups` | `array` | Paths for the groups the user is a member of, either directly or through an ancestor group. +| `groups_direct` | `array` | Paths for the groups the user is a direct member of. -The claims `sub`, `sub_legacy`, `email` and `email_verified` are included in the ID token, all other claims are available from the `/oauth/userinfo` endpoint used by OIDC clients. +The claims `sub`, `sub_legacy`, `email`, `email_verified` and `groups_direct` are included in the ID token. All other claims are available from the `/oauth/userinfo` endpoint used by OIDC clients. diff --git a/doc/integration/recaptcha.md b/doc/integration/recaptcha.md index 656ed8b8647..fd5170d615f 100644 --- a/doc/integration/recaptcha.md +++ b/doc/integration/recaptcha.md @@ -18,21 +18,23 @@ To use reCAPTCHA, first you must create a site and private key. 1. Fill out the form necessary to obtain reCAPTCHA v2 keys. 1. Log in to your GitLab server, with administrator credentials. 1. Go to Reporting Applications Settings in the Admin Area (`admin/application_settings/reporting`). +1. Expand the **Spam and Anti-bot Protection** section. 1. Fill all reCAPTCHA fields with keys from previous steps. -1. Check the `Enable reCAPTCHA` checkbox. +1. Select the **Enable reCAPTCHA** checkbox. +1. To enable reCAPTCHA for logins via password, select the **Enable reCAPTCHA for login** checkbox. 1. Save the configuration. 1. Change the first line of the `#execute` method in `app/services/spam/spam_verdict_service.rb` - to `return CONDITONAL_ALLOW` so that the spam check short-circuits and triggers the response to + to `return CONDITIONAL_ALLOW` so that the spam check short-circuits and triggers the response to return `recaptcha_html`. NOTE: Make sure you are viewing an issuable in a project that is public. If you're working with an issue, the issue is public. -## Enabling reCAPTCHA for user logins via passwords +## Enable reCAPTCHA for user logins using the HTTP header -By default, reCAPTCHA is only enabled for user registrations. To enable it for -user logins via passwords, the `X-GitLab-Show-Login-Captcha` HTTP header must -be set. For example, in NGINX, this can be done via the `proxy_set_header` +You can enable reCAPTCHA for user logins via password [in the user interface](#configuration) +or by setting the `X-GitLab-Show-Login-Captcha` HTTP header. +For example, in NGINX, this can be done via the `proxy_set_header` configuration variable: ```nginx diff --git a/doc/integration/saml.md b/doc/integration/saml.md index ee3e2f574c7..b89772ba2ca 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -7,9 +7,11 @@ type: reference # SAML OmniAuth Provider **(FREE SELF)** -This page describes instance-wide SAML for self-managed GitLab instances. For SAML on GitLab.com, see [SAML SSO for GitLab.com groups](../user/group/saml_sso/index.md). +This page describes instance-wide SAML for self-managed GitLab instances. For +SAML on GitLab.com, see [SAML SSO for GitLab.com groups](../user/group/saml_sso/index.md). -You should also reference the [OmniAuth documentation](omniauth.md) for general settings that apply to all OmniAuth providers. +You should also reference the [OmniAuth documentation](omniauth.md) for general +settings that apply to all OmniAuth providers. ## Glossary of common terms @@ -19,7 +21,7 @@ You should also reference the [OmniAuth documentation](omniauth.md) for general | Service provider (SP) | GitLab can be configured as a SAML 2.0 SP. | | Assertion | A piece of information about a user's identity, such as their name or role. Also known as claims or attributes. | | Single Sign-On (SSO) | Name of authentication scheme. | -| Assertion consumer service URL | The callback on GitLab where users will be redirected after successfully authenticating with the identity provider. | +| Assertion consumer service URL | The callback on GitLab where users are redirected after successfully authenticating with the identity provider. | | Issuer | How GitLab identifies itself to the identity provider. Also known as a "Relying party trust identifier". | | Certificate fingerprint | Used to confirm that communications over SAML are secure by checking that the server is signing communications with the correct certificate. Also known as a certificate thumbprint. | @@ -209,7 +211,7 @@ for a full list of supported assertions. ## SAML Groups -You can require users to be members of a certain group, or assign users [external](../user/permissions.md#external-users), admin or [auditor](../user/permissions.md#auditor-users) roles based on group membership. +You can require users to be members of a certain group, or assign users [external](../user/permissions.md#external-users), administrator or [auditor](../user/permissions.md#auditor-users) roles based on group membership. These groups are checked on each SAML login and user attributes updated as necessary. This feature **does not** allow you to automatically add users to GitLab [Groups](../user/group/index.md). @@ -221,13 +223,13 @@ and whether you've installed [GitLab Enterprise Edition (EE)](https://about.gitl |------------------------------|--------------------|--------------------------------------| | [Required](#required-groups) | **(FREE SELF)** | Yes | | [External](#external-groups) | **(FREE SELF)** | No | -| [Admin](#admin-groups) | **(FREE SELF)** | Yes | +| [Admin](#administrator-groups) | **(FREE SELF)** | Yes | | [Auditor](#auditor-groups) | **(PREMIUM SELF)** | Yes | ### Requirements -First you need to tell GitLab where to look for group information. For this you -need to make sure that your IdP server sends a specific `AttributeStatement` along +First tell GitLab where to look for group information. For this, you +must make sure that your IdP server sends a specific `AttributeStatement` along with the regular SAML response. Here is an example: ```xml @@ -242,17 +244,18 @@ with the regular SAML response. Here is an example: ``` The name of the attribute can be anything you like, but it must contain the groups -to which a user belongs. In order to tell GitLab where to find these groups, you need +to which a user belongs. To tell GitLab where to find these groups, you need to add a `groups_attribute:` element to your SAML settings. ### Required groups **(FREE SELF)** -Your IdP passes Group Information to the SP (GitLab) in the SAML Response. You need to configure GitLab to identify: +Your IdP passes Group information to the SP (GitLab) in the SAML Response. +To use this response, configure GitLab to identify: - Where to look for the groups in the SAML response via the `groups_attribute` setting - Which group membership is requisite to sign in via the `required_groups` setting -When `required_groups` is not set or it is empty, anyone with proper authentication +When `required_groups` is empty or not set, anyone with proper authentication is able to use the service. Example: @@ -273,7 +276,9 @@ Example: ### External groups **(FREE SELF)** -SAML login supports automatic identification on whether a user should be considered an [external user](../user/permissions.md#external-users). This is based on the user's group membership in the SAML identity provider. +SAML login supports the automatic identification of a user as an +[external user](../user/permissions.md#external-users). This is based on the user's group +membership in the SAML identity provider. ```yaml { name: 'saml', @@ -289,11 +294,13 @@ SAML login supports automatic identification on whether a user should be conside } } ``` -### Admin groups **(FREE SELF)** +### Administrator groups **(FREE SELF)** -The requirements are the same as the previous settings, your IdP needs to pass Group information to GitLab, you need to tell -GitLab where to look for the groups in the SAML response, and which group(s) should be -considered admin users. +The requirements are the same as the previous settings: + +- The IdP must pass Group information to GitLab. +- GitLab must know where to look for the groups in the SAML response, as well as + which group(s) grant the user an administrator role. ```yaml { name: 'saml', @@ -313,9 +320,11 @@ considered admin users. > Introduced in GitLab 11.4. -The requirements are the same as the previous settings, your IdP needs to pass Group information to GitLab, you need to tell -GitLab where to look for the groups in the SAML response, and which group(s) should be -considered [auditor users](../user/permissions.md#auditor-users). +The requirements are the same as the previous settings: + +- The IdP must pass Group information to GitLab. +- GitLab should know where to look for the groups in the SAML response, as well as which + group(s) entail that a given user is an [auditor user](../user/permissions.md#auditor-users). ```yaml { name: 'saml', @@ -333,8 +342,8 @@ considered [auditor users](../user/permissions.md#auditor-users). ## Bypass two factor authentication -If you want some SAML authentication methods to count as 2FA on a per session basis, you can register them in the -`upstream_two_factor_authn_contexts` list. +If you want some SAML authentication methods to count as 2FA on a per session +basis, you can register them in the `upstream_two_factor_authn_contexts` list. In addition to the changes in GitLab, make sure that your IdP is returning the `AuthnContext`. For example: @@ -411,7 +420,7 @@ In addition to the changes in GitLab, make sure that your IdP is returning the ### `auto_sign_in_with_provider` You can add this setting to your GitLab configuration to automatically redirect you -to your SAML server for authentication, thus removing the need to click a button +to your SAML server for authentication. This removes the requirement to click a button before actually signing in. For Omnibus package: @@ -429,7 +438,7 @@ omniauth: Keep in mind that every sign in attempt redirects to the SAML server; you cannot sign in using local credentials. Ensure at least one of the -SAML users has admin permissions. +SAML users has an administrator role. You may also bypass the auto sign-in feature by browsing to `https://gitlab.example.com/users/sign_in?auto_sign_in=false`. @@ -464,9 +473,14 @@ args: { } ``` -#### Setting a username +#### Set a username + +By default, the email in the SAML response is used to automatically generate the +user's GitLab username. If you'd like to set another attribute as the username, +assign it to the `nickname` OmniAuth `info` hash attribute. -By default, the email in the SAML response is used to automatically generate the user's GitLab username. If you'd like to set another attribute as the username, assign it to the `nickname` OmniAuth `info` hash attribute. For example, if you wanted to set the `username` attribute in your SAML Response to the username in GitLab, use the following setting: +For example, if you want to set the `username` attribute in your SAML Response to the username +in GitLab, use the following setting: ```yaml args: { @@ -482,7 +496,7 @@ args: { ### `allowed_clock_drift` The clock of the Identity Provider may drift slightly ahead of your system clocks. -To allow for a small amount of clock drift you can use `allowed_clock_drift` within +To allow for a small amount of clock drift, you can use `allowed_clock_drift` in your settings. Its value must be given in a number (and/or fraction) of seconds. The value given is added to the current time at which the response is validated. @@ -572,7 +586,8 @@ This may be the case, for example, if you terminate TLS encryption early at a lo balancer and include sensitive details in assertions that you do not want appearing in logs. Most organizations should not need additional encryption at this layer. -The SAML integration supports EncryptedAssertion. You need to define the private key and the public certificate of your GitLab instance in the SAML settings: +The SAML integration supports EncryptedAssertion. You should define the private +key and the public certificate of your GitLab instance in the SAML settings: ```yaml args: { @@ -602,7 +617,7 @@ SAML Requests use the SAML redirect binding, so this isn't necessary (unlike the SAML POST binding, where signing is required to prevent intermediaries from tampering with the requests). -To sign, you need to create a private key and public certificate pair for your +To sign, create a private key and public certificate pair for your GitLab instance to use for SAML. The settings for signing can be set in the `security` section of the configuration. @@ -653,7 +668,7 @@ The [Generated passwords for users created through integrated authentication](.. For information on the GitLab.com implementation, please see the [SAML SSO for GitLab.com groups page](../user/group/saml_sso). -Group SAML SSO helps if you need to allow access via multiple SAML identity providers, but as a multi-tenant solution is less suited to cases where you administer your own GitLab instance. +Group SAML SSO helps if you have to allow access via multiple SAML identity providers, but as a multi-tenant solution is less suited to cases where you administer your own GitLab instance. To proceed with configuring Group SAML SSO instead, enable the `group_saml` OmniAuth provider. This can be done from: @@ -668,7 +683,7 @@ Group SAML on a self-managed instance is limited when compared to the recommende - [LDAP compatibility](../administration/auth/ldap/index.md). - [LDAP Group Sync](../user/group/index.md#manage-group-memberships-via-ldap). - [Required groups](#required-groups). -- [Admin groups](#admin-groups). +- [Administrator groups](#administrator-groups). - [Auditor groups](#auditor-groups). ### Omnibus installations @@ -750,7 +765,7 @@ Make sure you have access to a Google Workspace [Super Admin](https://support.go | First name | `first_name` | Required value to communicate with GitLab. | | Last name | `last_name` | Required value to communicate with GitLab. | -You also need to setup the following SAML attribute mappings: +You also must setup the following SAML attribute mappings: | Google Directory attributes | App attributes | |-----------------------------------|----------------| @@ -767,8 +782,9 @@ When configuring the Google Workspace SAML app, be sure to record the following | SSO URL | Depends | Google Identity Provider details. Set to the GitLab `idp_sso_target_url` setting. | | Certificate | Downloadable | Run `openssl x509 -in <your_certificate.crt> -noout -fingerprint` to generate the SHA1 fingerprint that can be used in the `idp_cert_fingerprint` setting. | -While the Google Workspace Admin provides IdP metadata, Entity ID and SHA-256 fingerprint, -GitLab does not need that information to connect to the Google Workspace SAML app. +While the Google Workspace Admin provides IdP metadata, Entity ID, and SHA-256 +fingerprint, they are not required. GitLab does not need that information to +connect to the Google Workspace SAML app. ## Troubleshooting @@ -778,9 +794,10 @@ You can find the base64-encoded SAML Response in the [`production_json.log`](../ ### GitLab+SAML Testing Environments -If you need to troubleshoot, [a complete GitLab+SAML testing environment using Docker compose](https://gitlab.com/gitlab-com/support/toolbox/replication/tree/master/compose_files) is available. +To troubleshoot, [a complete GitLab+SAML testing environment using Docker compose](https://gitlab.com/gitlab-com/support/toolbox/replication/tree/master/compose_files) +is available. -If you only need a SAML provider for testing, a [quick start guide to start a Docker container](../administration/troubleshooting/test_environments.md#saml) with a plug and play SAML 2.0 Identity Provider (IdP) is available. +If you only require a SAML provider for testing, a [quick start guide to start a Docker container](../administration/troubleshooting/test_environments.md#saml) with a plug and play SAML 2.0 Identity Provider (IdP) is available. ### 500 error after login @@ -794,8 +811,8 @@ claim name `email` or `mail`. ### 422 error after login If you see a "422 error" in GitLab when you are redirected from the SAML -sign-in page, you might have an incorrectly configured assertion consumer -service (ACS) URL on the identity provider. +sign-in page, you might have an incorrectly configured Assertion Consumer +Service (ACS) URL on the identity provider. Make sure the ACS URL points to `https://gitlab.example.com/users/auth/saml/callback`, where `gitlab.example.com` is the URL of your GitLab instance. @@ -845,14 +862,17 @@ is not providing this information, all SAML requests fail. Make sure this information is provided. -Another issue that can result in this error is when the correct information is being sent by the IdP, but the attributes don't match the names in the OmniAuth `info` hash. In this case, you need to set `attribute_statements` in the SAML configuration to [map the attribute names in your SAML Response to the corresponding OmniAuth `info` hash names](#attribute_statements). +Another issue that can result in this error is when the correct information is being sent by +the IdP, but the attributes don't match the names in the OmniAuth `info` hash. In this case, +you must set `attribute_statements` in the SAML configuration to [map the attribute names in +your SAML Response to the corresponding OmniAuth `info` hash names](#attribute_statements). ### Key validation error, Digest mismatch or Fingerprint mismatch These errors all come from a similar place, the SAML certificate. SAML requests -need to be validated using a fingerprint, a certificate or a validator. +must be validated using either a fingerprint, a certificate, or a validator. -For this you need to take the following into account: +For this requirement, be sure to take the following into account: - If a fingerprint is used, it must be the SHA1 fingerprint - If no certificate is provided in the settings, a fingerprint or fingerprint diff --git a/doc/integration/slash_commands.md b/doc/integration/slash_commands.md index b9b5f394e3c..4059aef9de3 100644 --- a/doc/integration/slash_commands.md +++ b/doc/integration/slash_commands.md @@ -4,36 +4,40 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Slash Commands **(FREE)** +# Slash commands in Mattermost and Slack **(FREE)** > - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24780) to GitLab Free in 11.9. -Slash commands in Mattermost and Slack allow you to control GitLab and view GitLab content right inside your chat client, without having to leave it. For Slack, this requires an [integration configuration](../user/project/integrations/slack_slash_commands.md). Type the command as a message in your chat client to activate it. +If you want to control and view GitLab content while you're +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). -Commands are scoped to a project, with a trigger term that is specified during configuration. +Slash commands are scoped to a project +and require the trigger command specified during configuration. -We suggest you use the project name as the trigger term for simplicity and clarity. +We suggest you use the project name as the trigger command for simplicity and clarity. -Taking the trigger term as `project-name`, the commands are: +Assuming `project-name` is the trigger command, the slash commands are: | Command | Effect | | ------- | ------ | -| `/project-name help` | Shows all available slash commands | -| `/project-name issue new <title> <shift+return> <description>` | Creates a new issue with title `<title>` and description `<description>` | -| `/project-name issue show <id>` | Shows the issue with ID `<id>` | -| `/project-name issue close <id>` | Closes the issue with ID `<id>` | -| `/project-name issue search <query>` | Shows up to 5 issues matching `<query>` | -| `/project-name issue move <id> to <project>` | Moves issue ID `<id>` to `<project>` | -| `/project-name issue comment <id> <shift+return> <comment>` | Adds a new comment to an issue with ID `<id>` and comment body `<comment>` | -| `/project-name deploy <from> to <to>` | Deploy from the `<from>` environment to the `<to>` environment | -| `/project-name run <job name> <arguments>` | Execute [ChatOps](../ci/chatops/index.md) job `<job name>` on the default branch | +| `/project-name help` | Shows all available slash commands. | +| `/project-name issue new <title> <shift+return> <description>` | Creates a new issue with title `<title>` and description `<description>`. | +| `/project-name issue show <id>` | Shows the issue with ID `<id>`. | +| `/project-name issue close <id>` | Closes the issue with ID `<id>`. | +| `/project-name issue search <query>` | Shows up to 5 issues matching `<query>`. | +| `/project-name issue move <id> to <project>` | Moves the issue with ID `<id>` to `<project>`. | +| `/project-name issue comment <id> <shift+return> <comment>` | Adds a new comment with comment body `<comment>` to the issue with ID `<id>`. | +| `/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 Slack application](../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 -It's possible to create new issue, display issue details and search up to 5 issues. +You can create a new issue, display issue details, and search up to 5 issues. ## Deploy command @@ -41,7 +45,7 @@ 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 tries to find an action -which name equals the environment name we want to deploy to. +If more than one action is defined, GitLab finds an action +name that equals the environment name to deploy to. -The command returns an error when no matching action has been found. +The command returns an error if no matching action is found. diff --git a/doc/integration/sourcegraph.md b/doc/integration/sourcegraph.md index 86ca389e9b2..6f0027aedc7 100644 --- a/doc/integration/sourcegraph.md +++ b/doc/integration/sourcegraph.md @@ -76,8 +76,8 @@ You can skip this step if you already have your GitLab repositories searchable i ### Configure your GitLab instance with Sourcegraph -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Sourcegraph** configuration section. 1. Check **Enable Sourcegraph**. 1. Set the Sourcegraph URL to your Sourcegraph instance, such as `https://sourcegraph.example.com`. diff --git a/doc/integration/trello_power_up.md b/doc/integration/trello_power_up.md index df1d9270bd5..96150440e53 100644 --- a/doc/integration/trello_power_up.md +++ b/doc/integration/trello_power_up.md @@ -42,7 +42,7 @@ To find it in GitLab: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Access Tokens**. +1. On the left sidebar, select **Access Tokens**. Learn more about generating a personal access token in the [Personal Access Token Documentation](../user/profile/personal_access_tokens.md). diff --git a/doc/integration/twitter.md b/doc/integration/twitter.md index 1d711ea271e..6bc467ed7b2 100644 --- a/doc/integration/twitter.md +++ b/doc/integration/twitter.md @@ -4,9 +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/engineering/ux/technical-writing/#assignments --- -# Twitter OAuth2 OmniAuth Provider **(FREE)** +# Twitter OAuth 2.0 OmniAuth Provider **(FREE)** -To enable the Twitter OmniAuth provider you must register your application with Twitter. Twitter generates a client ID and secret key for you to use. +To enable the Twitter OmniAuth provider you must register your application with +Twitter. Twitter generates a client ID and secret key for you to use. 1. Sign in to [Twitter Application Management](https://developer.twitter.com/apps). diff --git a/doc/integration/vault.md b/doc/integration/vault.md index c98990bcb0e..ebfa91c7516 100644 --- a/doc/integration/vault.md +++ b/doc/integration/vault.md @@ -23,7 +23,7 @@ The following assumes you already have Vault installed and running. 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. - 1. In the left sidebar, select **Applications**. + 1. On the left sidebar, select **Applications**. 1. Fill out the application **Name** and [**Redirect URI**](https://www.vaultproject.io/docs/auth/jwt#redirect-uris). 1. Select the **OpenID** scope. 1. Select **Save application**. diff --git a/doc/intro/index.md b/doc/intro/index.md index a40293955a9..af50726e30c 100644 --- a/doc/intro/index.md +++ b/doc/intro/index.md @@ -1,49 +1,9 @@ --- -stage: Create -group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -comments: false +redirect_to: '../topics/use_gitlab.md' +remove_date: '2021-12-08' --- -# Get started with GitLab **(FREE)** +This document was moved to [another location](../topics/use_gitlab.md). -## Organize - -Create projects and groups. - -- [Create a new project](../user/project/working_with_projects.md#create-a-project) -- [Create a new group](../user/group/index.md#create-a-group) - -## Prioritize - -Create issues, labels, milestones, cast your vote, and review issues. - -- [Create an issue](../user/project/issues/managing_issues.md#create-a-new-issue) -- [Assign labels to issues](../user/project/labels.md) -- [Use milestones as an overview of your project's tracker](../user/project/milestones/index.md) -- [Use voting to express your like/dislike to issues and merge requests](../user/award_emojis.md) - -## Collaborate - -Create merge requests and review code. - -- [Fork a project and contribute to it](../user/project/repository/forking_workflow.md) -- [Create a new merge request](../user/project/merge_requests/creating_merge_requests.md) -- [Automatically close issues from merge requests](../user/project/issues/managing_issues.md#closing-issues-automatically) -- [Automatically merge when pipeline succeeds](../user/project/merge_requests/merge_when_pipeline_succeeds.md) -- [Revert any commit](../user/project/merge_requests/revert_changes.md) -- [Cherry-pick any commit](../user/project/merge_requests/cherry_pick_changes.md) - -## Test and Deploy - -Use the built-in continuous integration in GitLab. - -- [Get started with GitLab CI/CD](../ci/quick_start/index.md) - -## Install and Update - -Install and update your GitLab installation. - -- [Install GitLab](https://about.gitlab.com/install/) -- [Update GitLab](https://about.gitlab.com/update/) -- [Explore Omnibus GitLab configuration options](https://docs.gitlab.com/omnibus/settings/configuration.html) +<!-- This redirect file can be deleted after <2021-12-08>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/operations/error_tracking.md b/doc/operations/error_tracking.md index 9234ca36634..e694105d794 100644 --- a/doc/operations/error_tracking.md +++ b/doc/operations/error_tracking.md @@ -50,7 +50,7 @@ You may also want to enable Sentry's GitLab integration by following the steps i ### Enable GitLab Runner To configure GitLab Runner with Sentry, you must add the value for `sentry_dsn` to your GitLab -Runner's `config.toml` configuration file, as referenced in [GitLab Runner Advanced Configuraton](https://docs.gitlab.com/runner/configuration/advanced-configuration.html). +Runner's `config.toml` configuration file, as referenced in [GitLab Runner Advanced Configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html). While setting up Sentry, select **Go** if you're asked for the project type. If you see the following error in your GitLab Runner logs, then you should specify the deprecated @@ -108,3 +108,54 @@ clicking the **Resolve** button near the top of the page. Marking an error as resolved indicates that the error has stopped firing events. If a GitLab issue is linked to the error, then the issue closes. If another event occurs, the error reverts to unresolved. + +## Integrated error tracking + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/329596) in GitLab 14.3. + +Integrated error tracking is a lightweight alternative to Sentry backend. +You still use Sentry SDK with your application. But you don't need to deploy Sentry +or set up for cloud-hosted Sentry. Instead, you use GitLab as a backend for it. + +Sentry backend automatically assigns a Data Source Name (DSN) for every project you create. +GitLab does the same. You should be able to find a DSN for your project in the GitLab error tracking +settings. By using a GitLab-provided DSN, your application connects to GitLab to report an error. +Those errors are stored in the GitLab database and rendered by the GitLab UI, in the same way as +Sentry integration. + +### Project settings + +The feature should be enabled on the project level. However, there is no UI to enable this feature yet. +You must use the GitLab API to enable it. + +#### How to enable + +1. Select **GitLab** as the error tracking backend for your project: + +  + +1. Create a client key (DSN) to use with Sentry SDK in your application. Make sure to save the + response, as it contains a DSN: + + ```shell + curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/projects/PROJECT_ID/error_tracking/client_keys" + ``` + +1. Take the DSN from the previous step and configure your Sentry SDK with it. Errors are now + reported to the GitLab collector and are visible in the [GitLab UI](#error-tracking-list). + +#### How to disable + +To disable the feature, run this command. This is the same command as the one that enables the +feature, but with a `false` value instead: + +```shell +curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/projects/PROJECT_ID/error_tracking/settings?active=false&integrated=false" +``` + +#### Limitations + +The Integrated Error Tracking feature was built and tested with Sentry SDK for Ruby. Other languages and frameworks +are not tested and might not work. Check [the compatibility issue](https://gitlab.com/gitlab-org/gitlab/-/issues/340178) for more information. diff --git a/doc/operations/img/error_tracking_setting_v14_3.png b/doc/operations/img/error_tracking_setting_v14_3.png Binary files differnew file mode 100644 index 00000000000..14306130c97 --- /dev/null +++ b/doc/operations/img/error_tracking_setting_v14_3.png diff --git a/doc/operations/metrics/alerts.md b/doc/operations/metrics/alerts.md index ea4dd7e34cb..a3d741b78ea 100644 --- a/doc/operations/metrics/alerts.md +++ b/doc/operations/metrics/alerts.md @@ -61,7 +61,7 @@ Prometheus server to use the ## Trigger actions from alerts **(ULTIMATE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4925) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.11. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4925) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.11. Alerts can be used to trigger actions, like opening an issue automatically (disabled by default since `13.1`). To configure the actions: diff --git a/doc/policy/alpha-beta-support.md b/doc/policy/alpha-beta-support.md new file mode 100644 index 00000000000..be634bbf7be --- /dev/null +++ b/doc/policy/alpha-beta-support.md @@ -0,0 +1,40 @@ +--- +stage: Enablement +group: Distribution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Support for Alpha, Beta, and Generally Available Features **(PREMIUM)** + +Some GitLab features are released as [Alpha or Beta versions](https://about.gitlab.com/support/statement-of-support.html#alpha--beta-features) which are not fully supported. All other features are considered to be Generally Available (GA). + +## Alpha Features + +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. +- Data loss can occur (be that through bugs or updates). + +Support is **not** provided for Alpha features and issues with them should be opened in the [GitLab issue tracker](https://gitlab.com/gitlab-org/gitlab/issues). + +## Beta Features + +Characteristics of beta features: + +- Not ready for production use. +- Unstable and can cause performance and stability issues. +- Configuration and dependencies are not likely to change. +- Features and functions are not likely to change. +- Data loss is not likely. + +Your Support Contract provides **best-efforts** support for Beta features, with the expectation that issues will require extra time and assistance from development to troubleshoot. + +## Generally Available (GA) + +Generally Available features means that they passed the [Production Readiness Review](https://gitlab.com/gitlab-com/gl-infra/readiness/-/blob/master/.gitlab/issue_templates/production_readiness.md) for GitLab.com, and are: + +- Ready for production use at any scale. +- Fully documented and supported. diff --git a/doc/policy/maintenance.md b/doc/policy/maintenance.md index d8b36fcaa6d..f7c64895c78 100644 --- a/doc/policy/maintenance.md +++ b/doc/policy/maintenance.md @@ -64,10 +64,10 @@ one major version. For example, it is safe to: - `12.10.1` -> `12.10.8` NOTE: -Version specific changes in Omnibus GitLab Linux packages can be found in [the Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/update/README.html#version-specific-changes). +Version specific changes in Omnibus GitLab Linux packages can be found in [the Omnibus GitLab documentation](../update/package/index.md#version-specific-changes). NOTE: -Instructions are available for downloading an Omnibus GitLab Linux package locally and [manually installing](https://docs.gitlab.com/omnibus/manual_install.html) it. +Instructions are available for downloading an Omnibus GitLab Linux package locally and [manually installing](../update/package/index.md#upgrade-using-a-manually-downloaded-package) it. NOTE: A step-by-step guide to [upgrading the Omnibus-bundled PostgreSQL is documented separately](https://docs.gitlab.com/omnibus/settings/database.html#upgrade-packaged-postgresql-server). diff --git a/doc/public_access/public_access.md b/doc/public_access/public_access.md index 2cbcae31db3..1b4e1e64562 100644 --- a/doc/public_access/public_access.md +++ b/doc/public_access/public_access.md @@ -5,9 +5,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Project visibility +# Project and group visibility -GitLab allows [Owners](../user/permissions.md) to set a project's visibility as: +GitLab allows [Owners](../user/permissions.md) to set a project's or group's visibility as: - **Public** - **Internal** @@ -18,7 +18,7 @@ for your GitLab instance). For example, <https://gitlab.com/public>. You can control the visibility of individual features with [project feature settings](../user/permissions.md#project-features). -## Public projects +## Public projects and groups Public projects can be cloned **without any** authentication over HTTPS. @@ -31,7 +31,7 @@ By default, `/public` is visible to unauthenticated users. However, if the [**Public** visibility level](../user/admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels) is restricted, `/public` is visible only to signed-in users. -## Internal projects +## Internal projects and groups Internal projects can be cloned by any signed-in user except [external users](../user/permissions.md#external-users). @@ -47,7 +47,7 @@ and snippets on GitLab.com. Existing projects, groups, and snippets using the `I visibility setting keep this setting. You can read more about the change in the [relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/12388). -## Private projects +## Private projects and groups Private projects can only be cloned and viewed by project members (except for guests). @@ -62,7 +62,19 @@ Prerequisite: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Settings > General**. 1. Expand **Visibility, project features, permissions**. -1. Change **Project visibility** to either Public, Internal, or Private. +1. Change **Project visibility** to either **Private**, **Internal**, or **Public**. +1. Select **Save changes**. + +## Change group visibility + +Prerequisite: + +- You must have the Owner role for a group. + +1. On the top bar, select **Menu > Groups** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Naming, visibility**. +1. Under **Visibility level** select either **Private**, **Internal**, or **Public**. 1. Select **Save changes**. ## Restrict use of public or internal projects diff --git a/doc/push_rules/push_rules.md b/doc/push_rules/push_rules.md index 28dd3265465..9a8c0d79395 100644 --- a/doc/push_rules/push_rules.md +++ b/doc/push_rules/push_rules.md @@ -87,7 +87,7 @@ at the project level or the [group level](../user/group/index.md#group-push-rule To create global push rules: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Push Rules**. To override global push rules in a project's settings: @@ -141,8 +141,7 @@ Feature.disable(:reject_unsigned_commits_by_gitlab) ## Prevent pushing secrets to the repository -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385) in GitLab 8.12. -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. Secrets such as credential files, SSH private keys, and other files containing secrets should never be committed to source control. GitLab enables you to turn on a predefined denylist of files which can't be @@ -217,8 +216,7 @@ id_ecdsa ## Prohibited file names -> - Introduced in GitLab 7.10. -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. Each filename contained in a Git push is compared to the regular expression in this field. Filenames in Git consist of both the file's name and any directory that may precede it. A singular regular expression can contain multiple independent matches used as exclusions. File names can be broadly matched to any location in the repository, or restricted to specific locations. Filenames can also be partial matches used to exclude file types by extension. diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md index e9c9659d4f5..b6f772dee17 100644 --- a/doc/raketasks/backup_restore.md +++ b/doc/raketasks/backup_restore.md @@ -347,18 +347,21 @@ sudo -u git -H GITLAB_ASSUME_YES=1 bundle exec rake gitlab:backup:restore RAILS_ #### Back up Git repositories concurrently -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37158) in GitLab 13.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37158) in GitLab 13.3. +> - [Concurrent restore introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/69330) in GitLab 14.3 When using [multiple repository storages](../administration/repository_storage_paths.md), -repositories can be backed up concurrently to help fully use CPU time. The +repositories can be backed up or restored concurrently to help fully use CPU time. The following variables are available to modify the default behavior of the Rake task: - `GITLAB_BACKUP_MAX_CONCURRENCY`: The maximum number of projects to back up at - the same time. Defaults to `1`. + the same time. Defaults to the number of logical CPUs (in GitLab 14.1 and + earlier, defaults to `1`). - `GITLAB_BACKUP_MAX_STORAGE_CONCURRENCY`: The maximum number of projects to back up at the same time on each storage. This allows the repository backups - to be spread across storages. Defaults to `1`. + to be spread across storages. Defaults to `2` (in GitLab 14.1 and earlier, + defaults to `1`). For example, for Omnibus GitLab installations with 4 repository storages: @@ -404,6 +407,67 @@ For Omnibus GitLab packages: 1. [Reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect +##### S3 Encrypted Buckets + +AWS supports these [modes for server side encryption](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html): + +- Amazon S3-Managed Keys (SSE-S3) +- Customer Master Keys (CMKs) Stored in AWS Key Management Service (SSE-KMS) +- Customer-Provided Keys (SSE-C) + +Use your mode of choice with GitLab. Each mode has similar, but slightly +different, configuration methods. + +###### SSE-S3 + +To enable SSE-S3, in the backup storage options set the `server_side_encryption` +field to `AES256`. For example, in Omnibus GitLab: + +```ruby +gitlab_rails['backup_upload_storage_options'] = { + 'server_side_encryption' => 'AES256' +} +``` + +###### SSE-KMS + +To enable SSE-KMS, you'll 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` config setting, set: + +- `server_side_encryption` to `aws:kms`. +- `server_side_encryption_kms_key_id` to the ARN of the key. + +For example, in Omnibus GitLab: + +```ruby +gitlab_rails['backup_upload_storage_options'] = { + 'server_side_encryption' => 'aws:kms', + 'server_side_encryption_kms_key_id' => 'arn:aws:<YOUR KMS KEY ID>:' +} +``` + +###### SSE-C + +SSE-C requires you to set these encryption options: + +- `backup_encryption`: AES256. +- `backup_encryption_key`: Unencoded, 32-byte (256 bits) key. The upload fails if this isn't exactly 32 bytes. + +For example, in Omnibus GitLab: + +```ruby +gitlab_rails['backup_encryption'] = 'AES256' +gitlab_rails['backup_encryption_key'] = '<YOUR 32-BYTE KEY HERE>' +``` + +If the key contains binary characters and cannot be encoded in UTF-8, +instead, specify the key with the `GITLAB_BACKUP_ENCRYPTION_KEY` environment variable. +For example: + +```ruby +gitlab_rails['env'] = { 'GITLAB_BACKUP_ENCRYPTION_KEY' => "\xDE\xAD\xBE\xEF" * 8 } +``` + ##### Digital Ocean Spaces This example can be used for a bucket in Amsterdam (AMS3): @@ -455,15 +519,25 @@ For installations from source: # use_iam_profile: 'true' # The remote 'directory' to store your backups. For S3, this would be the bucket name. remote_directory: 'my.s3.bucket' - # Turns on AWS Server-Side Encryption with Amazon S3-Managed Keys for backups, this is optional - # encryption: 'AES256' - # Turns on AWS Server-Side Encryption with Amazon Customer-Provided Encryption Keys for backups, this is optional - # This should be set to the encryption key for Amazon S3 to use to encrypt or decrypt your data. - # 'encryption' must also be set in order for this to have any effect. - # To avoid storing the key on disk, the key can also be specified via the `GITLAB_BACKUP_ENCRYPTION_KEY` environment variable. - # encryption_key: '<key>' # Specifies Amazon S3 storage class to use for backups, this is optional # storage_class: 'STANDARD' + # + # Turns on AWS Server-Side Encryption with Amazon Customer-Provided Encryption Keys for backups, this is optional + # 'encryption' must be set in order for this to have any effect. + # 'encryption_key' should be set to the 256-bit encryption key for Amazon S3 to use to encrypt or decrypt. + # To avoid storing the key on disk, the key can also be specified via the `GITLAB_BACKUP_ENCRYPTION_KEY` your data. + # encryption: 'AES256' + # encryption_key: '<key>' + # + # + # Turns on AWS Server-Side Encryption with Amazon S3-Managed keys (optional) + # https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html + # For SSE-S3, set 'server_side_encryption' to 'AES256'. + # For SS3-KMS, set 'server_side_encryption' to 'aws:kms'. Set + # 'server_side_encryption_kms_key_id' to the ARN of customer master key. + # storage_options: + # server_side_encryption: 'aws:kms' + # server_side_encryption_kms_key_id: 'arn:aws:kms:YOUR-KEY-ID-HERE' ``` 1. [Restart GitLab](../administration/restart_gitlab.md#installations-from-source) @@ -807,7 +881,7 @@ You can restore a backup only to _the exact same version and type (CE/EE)_ of GitLab that you created it on (for example CE 9.1.0). If your backup is a different version than the current installation, you must -[downgrade your GitLab installation](https://docs.gitlab.com/omnibus/update/README.html#downgrade) +[downgrade your GitLab installation](../update/package/downgrade.md) before restoring the backup. ### Restore prerequisites @@ -1138,7 +1212,8 @@ There are a few possible downsides to this: the last project that gets backed up. - Fork networks should be entirely read-only while the projects inside get backed up to prevent potential changes to the pool repository. -There is an **experimental** script that attempts to automate this process in [Snippet 2149205](https://gitlab.com/-/snippets/2149205). +There is an **experimental** script that attempts to automate this process in +[the Geo team Runbooks project](https://gitlab.com/gitlab-org/geo-team/runbooks/-/tree/main/experimental-online-backup-through-rsync). ## Backup and restore for installations using PgBouncer @@ -1295,7 +1370,7 @@ Be sure to create a full database backup before attempting any changes. #### Disable user two-factor authentication (2FA) Users with 2FA enabled can't sign in to GitLab. In that case, you must -[disable 2FA for everyone](../security/two_factor_authentication.md#disabling-2fa-for-everyone), +[disable 2FA for everyone](../security/two_factor_authentication.md#disable-2fa-for-everyone), after which users must reactivate 2FA. #### Reset CI/CD variables diff --git a/doc/raketasks/cleanup.md b/doc/raketasks/cleanup.md index 9f79d3cc675..c2d3c540cbf 100644 --- a/doc/raketasks/cleanup.md +++ b/doc/raketasks/cleanup.md @@ -207,10 +207,6 @@ sudo gitlab-rake gitlab:cleanup:sessions:active_sessions_lookup_keys bundle exec rake gitlab:cleanup:sessions:active_sessions_lookup_keys RAILS_ENV=production ``` -## Cleaning up stale Redis sessions - -[Clean up stale sessions](../administration/operations/cleaning_up_redis_sessions.md) to compact the Redis database after you upgrade to GitLab 7.3. - ## Container Registry garbage collection Container Registry can use considerable amounts of disk space. To clear up diff --git a/doc/raketasks/features.md b/doc/raketasks/features.md index ba14293a9fd..3248f7370e8 100644 --- a/doc/raketasks/features.md +++ b/doc/raketasks/features.md @@ -10,7 +10,8 @@ This Rake task enables [namespaces](../user/group/index.md#namespaces) for proje ## Enable usernames and namespaces for user projects -This command enables the namespaces feature introduced in GitLab 4.0. It moves every project in its namespace folder. +This command enables the namespaces feature. It moves every project in its +namespace folder. The **repository location changes as part of this task**, so you must **update all your Git URLs** to point to the new location. @@ -19,7 +20,7 @@ To change your username: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Account**. +1. On the left sidebar, select **Account**. 1. In the **Change username** section, type the new username. 1. Select **Update username**. diff --git a/doc/security/password_length_limits.md b/doc/security/password_length_limits.md index 847656d8d17..bedf2ac3ab1 100644 --- a/doc/security/password_length_limits.md +++ b/doc/security/password_length_limits.md @@ -30,7 +30,7 @@ The user password length is set to a minimum of 8 characters by default. To change the minimum password length using GitLab UI: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General** and expand **Sign-up restrictions**.  diff --git a/doc/security/rack_attack.md b/doc/security/rack_attack.md index 6d2725d1ec1..4894af1fa19 100644 --- a/doc/security/rack_attack.md +++ b/doc/security/rack_attack.md @@ -109,7 +109,7 @@ The following settings can be configured: - `enabled`: By default this is set to `false`. Set this to `true` to enable Rack Attack. - `ip_whitelist`: Whitelist any IPs from being blocked. They must be formatted as strings within a Ruby array. - CIDR notation is supported in GitLab v12.1 and up. + CIDR notation is supported in GitLab 12.1 and later. For example, `["127.0.0.1", "127.0.0.2", "127.0.0.3", "192.168.0.1/24"]`. - `maxretry`: The maximum amount of times a request can be made in the specified time. diff --git a/doc/security/rate_limits.md b/doc/security/rate_limits.md index e698341b4b5..6045dece0c2 100644 --- a/doc/security/rate_limits.md +++ b/doc/security/rate_limits.md @@ -34,6 +34,7 @@ These are rate limits you can set in the Admin Area of your instance: - [Raw endpoints rate limits](../user/admin_area/settings/rate_limits_on_raw_endpoints.md) - [User and IP rate limits](../user/admin_area/settings/user_and_ip_rate_limits.md) - [Package registry rate limits](../user/admin_area/settings/package_registry_rate_limits.md) +- [Git LFS rate limits](../user/admin_area/settings/git_lfs_rate_limits.md) ## Non-configurable limits diff --git a/doc/security/ssh_keys_restrictions.md b/doc/security/ssh_keys_restrictions.md index 55eeaae5458..239949b5568 100644 --- a/doc/security/ssh_keys_restrictions.md +++ b/doc/security/ssh_keys_restrictions.md @@ -5,7 +5,7 @@ group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Restrict allowed SSH key technologies and minimum length +# Restrict allowed SSH key technologies and minimum length **(FREE SELF)** `ssh-keygen` allows users to create RSA keys with as few as 768 bits, which falls well below recommendations from certain standards groups (such as the US @@ -20,7 +20,7 @@ algorithms. GitLab allows you to restrict the allowed SSH key technology as well as specify the minimum key length for each technology: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General** (`/admin/application_settings/general`). 1. Expand the **Visibility and access controls** section: @@ -36,6 +36,16 @@ An icon is visible to the user of a restricted key in the SSH keys section of th Hovering over this icon tells you why the key is restricted. +## Default settings + +By default, the GitLab.com and self-managed settings for the +[supported key types](../ssh/index.md#supported-ssh-key-types) are: + +- RSA SSH keys are allowed. +- DSA SSH keys are forbidden ([since GitLab 11.0](https://about.gitlab.com/releases/2018/06/22/gitlab-11-0-released/#support-for-dsa-ssh-keys)). +- ECDSA SSH keys are allowed. +- ED25519 SSH keys are allowed. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/security/token_overview.md b/doc/security/token_overview.md index c00e5bff383..4e72033fd77 100644 --- a/doc/security/token_overview.md +++ b/doc/security/token_overview.md @@ -71,7 +71,7 @@ You can use the runner registration token to add runners that execute jobs in a After registration, the runner receives an authentication token, which it uses to authenticate with GitLab when picking up jobs from the job queue. The authentication token is stored locally in the runner's [`config.toml`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html) file. -After authentication with GitLab, the runner receives a [job token](../api/index.md#gitlab-cicd-job-token), which it uses to execute the job. +After authentication with GitLab, the runner receives a [job token](../ci/jobs/ci_job_token.md), which it uses to execute the job. In case of Docker Machine/Kubernetes/VirtualBox/Parallels/SSH executors, the execution environment has no access to the runner authentication token, because it stays on the runner machine. They have access to the job token only, which is needed to execute the job. @@ -79,7 +79,7 @@ Malicious access to a runner's file system may expose the `config.toml` file and ## CI/CD job tokens -The [CI/CD](../api/index.md#gitlab-cicd-job-token) job token +The [CI/CD](../ci/jobs/ci_job_token.md) job token is a short lived token only valid for the duration of a job. It gives a CI/CD job access to a limited amount of API endpoints. API authentication uses the job token, by using the authorization of the user @@ -105,7 +105,7 @@ This table shows available scopes per token. Scopes can be limited further on to 1. Limited to the one project. 1. Runner registration and authentication token don't provide direct access to repositories, but can be used to register and authenticate a new runner that may execute jobs which do have access to the repository -1. Limited to certain [endpoints](../api/index.md#gitlab-cicd-job-token). +1. Limited to certain [endpoints](../ci/jobs/ci_job_token.md). ## Security considerations diff --git a/doc/security/two_factor_authentication.md b/doc/security/two_factor_authentication.md index a009fa9964d..a5b01a1b27d 100644 --- a/doc/security/two_factor_authentication.md +++ b/doc/security/two_factor_authentication.md @@ -5,17 +5,15 @@ group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Enforce Two-factor Authentication (2FA) +# Enforce two-factor authentication **(FREE SELF)** -Two-factor Authentication (2FA) provides an additional level of security to your -users' GitLab account. After being enabled, in addition to supplying their -username and password to sign in, they are prompted for a code generated by an -application on their phone. +Two-factor authentication (2FA) provides an additional level of security to your +users' GitLab account. When enabled, users are prompted for a code generated by an application in +addition to supplying their username and password to sign in. -You can read more about it here: -[Two-factor Authentication (2FA)](../user/profile/account/two_factor_authentication.md) +Read more about [two-factor authentication (2FA)](../user/profile/account/two_factor_authentication.md) -## Enforcing 2FA for all users +## Enforce 2FA for all users Users on GitLab can enable it without any administrator's intervention. If you want to enforce everyone to set up 2FA, you can choose from two different ways: @@ -28,18 +26,27 @@ cannot leave the 2FA configuration area at `/-/profile/two_factor_auth`. To enable 2FA for all users: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General** (`/admin/application_settings/general`). 1. Expand the **Sign-in restrictions** section, where you can configure both. If you want 2FA enforcement to take effect during the next sign-in attempt, change the grace period to `0`. -## Enforcing 2FA for all users in a group +## Disable 2FA enforcement through rails console + +Using the [rails console](../administration/operations/rails_console.md), enforcing 2FA for +all user can be disabled. Connect to the rails console and run: + +```ruby +Gitlab::CurrentSettings.update!('require_two_factor_authentication': false) +``` + +## Enforce 2FA for all users in a group **(FREE)** > [Introduced in](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24965) GitLab 12.0, 2FA settings for a group are also applied to subgroups. -If you want to enforce 2FA only for certain groups: +To enforce 2FA only for certain groups: 1. Go to the group's **Settings > General** page. 1. Expand the **Permissions, LFS, 2FA** section. @@ -47,11 +54,11 @@ If you want to enforce 2FA only for certain groups: You can also specify a grace period in the **Time before enforced** option. -To change this setting, you need to be administrator or owner of the group. +To change this setting, you must be an administrator or owner of the group. If you want to enforce 2FA only for certain groups, you can enable it in the group settings and specify a grace period as above. To change this setting you -need to be administrator or owner of the group. +must be administrator or owner of the group. The following are important notes about 2FA: @@ -74,13 +81,13 @@ The following are important notes about 2FA: This action causes all subgroups with 2FA requirements to stop requiring that from their members. -## Disabling 2FA for everyone +## Disable 2FA for everyone WARNING: -Disabling 2FA for everyone does not disable the [enforce 2FA for all users](#enforcing-2fa-for-all-users) -or [enforce 2FA for all users in a group](#enforcing-2fa-for-all-users-in-a-group) -settings. In addition to the steps in this section, you must disable any enforced 2FA -settings so users aren't asked to set up 2FA again, the next time the user signs in to GitLab. +Disabling 2FA for everyone does not disable the [enforce 2FA for all users](#enforce-2fa-for-all-users) +or [enforce 2FA for all users in a group](#enforce-2fa-for-all-users-in-a-group) +settings. You must also disable any enforced 2FA settings so users aren't asked to set up 2FA again +when they next sign in to GitLab. There may be some special situations where you want to disable 2FA for everyone even when forced 2FA is disabled. There is a Rake task for that: @@ -97,26 +104,26 @@ WARNING: This is a permanent and irreversible action. Users have to reactivate 2FA from scratch if they want to use it again. -## Two-factor Authentication (2FA) for Git over SSH operations **(PREMIUM)** +## 2FA for Git over SSH operations **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/270554) in GitLab 13.7. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/299088) from GitLab Free to GitLab Premium in 13.9. > - It's [deployed behind a feature flag](../user/feature_flags.md), disabled by default. > - It's disabled on GitLab.com. > - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-two-factor-authentication-2fa-for-git-operations). +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-2fa-for-git-operations). WARNING: This feature might not be available to you. Check the **version history** note above for details. -Two-factor authentication can be enforced for Git over SSH operations. The OTP +Two-factor authentication can be enforced for Git over SSH operations. The one-time password (OTP) verification can be done via a GitLab Shell command: ```shell ssh git@<hostname> 2fa_verify ``` -Once the OTP is verified, Git over SSH operations can be used for a session duration of +After the OTP is verified, Git over SSH operations can be used for a session duration of 15 minutes (default) with the associated SSH key. ### Security limitation @@ -126,9 +133,9 @@ Once the OTP is verified, Git over SSH operations can be used for a session dura Once an OTP is verified, anyone can run Git over SSH with that private SSH key for the configured [session duration](../user/admin_area/settings/account_and_limit_settings.md#customize-session-duration-for-git-operations-when-2fa-is-enabled). -### Enable or disable Two-factor Authentication (2FA) for Git operations +### Enable or disable 2FA for Git operations -Two-factor Authentication (2FA) for Git operations is under development and not +2FA for Git operations is under development and not ready for production use. It is deployed behind a feature flag that is **disabled by default**. [GitLab administrators with access to the GitLab Rails console](../administration/feature_flags.md) can enable it. @@ -147,7 +154,7 @@ Feature.disable(:two_factor_for_cli) The feature flag affects these features: -- [Two-factor Authentication (2FA) for Git over SSH operations](#two-factor-authentication-2fa-for-git-over-ssh-operations). +- [Two-factor Authentication (2FA) for Git over SSH operations](#2fa-for-git-over-ssh-operations). - [Customize 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). <!-- ## Troubleshooting diff --git a/doc/security/user_email_confirmation.md b/doc/security/user_email_confirmation.md index 1b39937acbe..09e1e09b676 100644 --- a/doc/security/user_email_confirmation.md +++ b/doc/security/user_email_confirmation.md @@ -11,7 +11,7 @@ GitLab can be configured to require confirmation of a user's email address when the user signs up. When this setting is enabled, the user is unable to sign in until they confirm their email address. -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General** (`/admin/application_settings/general`). 1. Expand the **Sign-up restrictions** section and look for the **Send confirmation email on sign-up** option. diff --git a/doc/security/webhooks.md b/doc/security/webhooks.md index b0535d0bcaf..c0e5d0695cc 100644 --- a/doc/security/webhooks.md +++ b/doc/security/webhooks.md @@ -46,8 +46,8 @@ to `127.0.0.1`, `::1` and `0.0.0.0`, as well as IPv4 `10.0.0.0/8`, `172.16.0.0/1 This behavior can be overridden: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Network**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Network**. 1. Expand the **Outbound requests** section:  1. Select **Allow requests to the local network from web hooks and services**. @@ -65,8 +65,8 @@ You can allow certain domains and IP addresses to be accessible to both *system and *webhooks* even when local requests are not allowed by adding them to the allowlist: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Network** (`/admin/application_settings/network`) +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Network** (`/admin/application_settings/network`) and expand **Outbound requests**:  diff --git a/doc/ssh/index.md b/doc/ssh/index.md index c4e651a0072..94c157697ce 100644 --- a/doc/ssh/index.md +++ b/doc/ssh/index.md @@ -101,7 +101,7 @@ If you do not have an existing SSH key pair, generate a new one. You can also dedicate the SSH key pair to a [specific host](#configure-ssh-to-point-to-a-different-directory). -1. Specify a [passphrase](https://www.ssh.com/ssh/passphrase): +1. Specify a [passphrase](https://www.ssh.com/academy/ssh/passphrase): ```plaintext Enter passphrase (empty for no passphrase): @@ -318,7 +318,7 @@ on the files make them readable to you but not accessible to others. ## Configure two-factor authentication (2FA) You can set up two-factor authentication (2FA) for -[Git over SSH](../security/two_factor_authentication.md#two-factor-authentication-2fa-for-git-over-ssh-operations). +[Git over SSH](../security/two_factor_authentication.md#2fa-for-git-over-ssh-operations). ## Use EGit on Eclipse diff --git a/doc/subscriptions/bronze_starter.md b/doc/subscriptions/bronze_starter.md index 410759aa506..327fb8887ad 100644 --- a/doc/subscriptions/bronze_starter.md +++ b/doc/subscriptions/bronze_starter.md @@ -32,7 +32,7 @@ the tiers are no longer mentioned in GitLab documentation: - [Overriding user permissions](../user/group/index.md#override-user-permissions) - [User contribution analytics](../user/group/contribution_analytics/index.md) - [Kerberos integration](../integration/kerberos.md) -- Issue Boards: +- Issue boards: - [Configurable issue boards](../user/project/issue_board.md#configurable-issue-boards) - [Sum of issue weights](../user/project/issue_board.md#sum-of-issue-weights) - [Work In Progress limits](../user/project/issue_board.md#work-in-progress-limits) @@ -51,13 +51,13 @@ the tiers are no longer mentioned in GitLab documentation: - Syncing information through LDAP: - Groups: [one group](../administration/auth/ldap/ldap-troubleshooting.md#sync-one-group), [all groups programmatically](../administration/auth/ldap/index.md#group-sync), - [group sync schedule](../administration/auth/ldap/index.md#adjusting-ldap-group-sync-schedule), and + [group sync schedule](../administration/auth/ldap/index.md#adjust-ldap-group-sync-schedule), and [all groups manually](../administration/auth/ldap/ldap-troubleshooting.md#sync-all-groups) - [Configuration settings](../administration/auth/ldap/index.md#ldap-sync-configuration-settings) - Users: [all users](../administration/auth/ldap/index.md#user-sync), [administrators](../administration/auth/ldap/index.md#administrator-sync), - [user sync schedule](../administration/auth/ldap/index.md#adjusting-ldap-user-sync-schedule) - - [Adding group links](../administration/auth/ldap/index.md#adding-group-links) + [user sync schedule](../administration/auth/ldap/index.md#adjust-ldap-user-sync-schedule) + - [Adding group links](../administration/auth/ldap/index.md#add-group-links) - [Lock memberships to LDAP synchronization](../administration/auth/ldap/index.md#global-group-memberships-lock) - Rake tasks for [LDAP tasks](../administration/raketasks/ldap.md), including [syncing groups](../administration/raketasks/ldap.md#run-a-group-sync) @@ -102,7 +102,7 @@ the tiers are no longer mentioned in GitLab documentation: - [Shared runners pipeline minutes quota](../user/admin_area/settings/continuous_integration.md#shared-runners-pipeline-minutes-quota) - [Push rules](../push_rules/push_rules.md) - SAML for self-managed GitLab instance: - - [Administrator groups](../integration/saml.md#admin-groups) + - [Administrator groups](../integration/saml.md#administrator-groups) - [Auditor groups](../integration/saml.md#auditor-groups) - [External groups](../integration/saml.md#external-groups) - [Required groups](../integration/saml.md#required-groups) diff --git a/doc/subscriptions/gitlab_com/index.md b/doc/subscriptions/gitlab_com/index.md index 55fb77fe927..cecbb362cb9 100644 --- a/doc/subscriptions/gitlab_com/index.md +++ b/doc/subscriptions/gitlab_com/index.md @@ -91,21 +91,34 @@ The following table describes details of your subscription: > - [Updated](https://gitlab.com/gitlab-org/gitlab/-/issues/292086) in GitLab 13.8 to include public email address. -To view a list of seats being used, go to **Settings > Billing**. -Under **Seats currently in use**, select **See usage**. - -You can also see this information in your group settings by going to **Menu > Groups > Your Group > Settings > Usage Quotas**, and the information about **Seat usage** will be under the **Seats** tab. - The **Seat usage** page lists all users occupying seats. Details for each user include: - Full name - Username - Public email address (if they have provided one in their [user settings](../../user/profile/index.md#access-your-user-settings)) -The Seat usage listing is updated live, but the usage statistics on the billing page are updated +The seat usage listing is updated live, but the usage statistics on the billing page are updated only once per day. For this reason there can be a minor difference between the seat usage listing and the billing page. +Every user is included in seat usage, with the following exceptions: + +- Users who are pending approval. +- Members with the Guest role on an Ultimate subscription. +- Users without project or group memberships on an Ultimate subscription. +- GitLab-created service accounts: `Ghost User` and bots + ([`Support Bot`](../../user/project/service_desk.md#support-bot-user), + [`Project bot users`](../../user/project/settings/project_access_tokens.md#project-bot-users), and + so on.) + +### View seat usage + +To view a list of seats being used: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > Usage Quotas**. +1. Under the **Seats** tab, view usage information. + ### Search seat usage > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/262875) in GitLab 13.8. @@ -326,7 +339,7 @@ Quotas apply to: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. - 1. In the left sidebar, select **[Usage Quotas](https://gitlab.com/-/profile/usage_quotas#pipelines-quota-tab)**. + 1. On the left sidebar, select **[Usage Quotas](https://gitlab.com/-/profile/usage_quotas#pipelines-quota-tab)**. Only pipeline minutes for GitLab shared runners are restricted. If you have a specific runner set up for your projects, there is no limit to your build time on GitLab SaaS. @@ -362,7 +375,7 @@ To purchase additional minutes for your personal namespace: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Usage Quotas**. +1. On the left sidebar, select **Usage Quotas**. 1. Select **Buy additional minutes** and GitLab redirects you to the Customers Portal. 1. Locate the subscription card that's linked to your personal namespace on GitLab SaaS, click **Buy more CI minutes**, and complete the details about the transaction. Once we have processed your payment, the extra CI minutes are synced to your personal namespace. 1. To confirm the available CI minutes for your personal projects, go to the **Usage Quotas** settings again. diff --git a/doc/subscriptions/quarterly_reconciliation.md b/doc/subscriptions/quarterly_reconciliation.md index af9fec1ddc4..f9cca079e76 100644 --- a/doc/subscriptions/quarterly_reconciliation.md +++ b/doc/subscriptions/quarterly_reconciliation.md @@ -18,3 +18,31 @@ pay 25% of what you would have paid previously. This results in substantial savi If it's not possible for you to participate in quarterly reconciliations, you can opt out of the process by using a contract amendment. In that case, you default to the annual review. + +## Timeline for invoicing and payment + +At the end of each subscription quarter, GitLab notifies you about overages. +The date you're notified about the overage is not the same as the date +you are billed. + +### GitLab SaaS + +Group owners receive an email **on the reconciliation date**. +The email communicates the [overage seat quantity](gitlab_com/index.md#seats-owed-example) +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 terms. + +### Self-managed instances + +Admins receive an email **six days after the reconciliation date**. +This email communicates the [overage seat quantity](self_managed/index.md#users-over-license) +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. diff --git a/doc/subscriptions/self_managed/index.md b/doc/subscriptions/self_managed/index.md index 51913ac2650..72bd1c2b4f7 100644 --- a/doc/subscriptions/self_managed/index.md +++ b/doc/subscriptions/self_managed/index.md @@ -49,7 +49,7 @@ Prorated charges are not possible without a quarterly usage report. You can view users for your license and determine if you've gone over your subscription. -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left menu, select **Subscription**. The lists of users are displayed. @@ -154,7 +154,7 @@ See the [quarterly subscription reconciliation section](../quarterly_reconciliat 1. When you purchase a GitLab self-managed plan, an activation code is generated. This activation code is sent to the email address associated with the Customers Portal account. -1. In GitLab, on the top bar, select **Menu >** **{admin}** **Admin**. +1. In GitLab, on the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Subscription** and paste the activation code in the text field. 1. Select **Activate**. @@ -237,7 +237,7 @@ The daily job provides **only** the following information to the Customers Porta You can manually sync your subscription details at any time. -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Subscription**. 1. In the **Subscription details** section, select **Sync subscription details**. @@ -246,7 +246,7 @@ A job is queued. When the job finishes, the subscription details are updated. #### Troubleshooting cloud licensing sync If the sync job is not working, ensure you allow network traffic from your GitLab instance -to IP address `104.46.106.135:443` (`customers.gitlab.com`). +to IP address `104.18.26.123:443` (`customers.gitlab.com`). ## Obtain a subscription @@ -265,7 +265,7 @@ instance, ensure you're purchasing enough seats to If you are an administrator, you can view the status of your subscription: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **License**. The **License** page includes the following details: diff --git a/doc/system_hooks/system_hooks.md b/doc/system_hooks/system_hooks.md index f86d3940a33..7dd0701329d 100644 --- a/doc/system_hooks/system_hooks.md +++ b/doc/system_hooks/system_hooks.md @@ -52,8 +52,8 @@ for Push and Tag events, but we never display commits. To create a system hook: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **System Hooks**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **System Hooks**. 1. Provide the **URL** and **Secret Token**. 1. Select the checkbox next to each **Trigger** you want to enable. 1. Select **Enable SSL verification**, if desired. diff --git a/doc/tools/email.md b/doc/tools/email.md index 8ba275903da..0429b9b952e 100644 --- a/doc/tools/email.md +++ b/doc/tools/email.md @@ -22,8 +22,8 @@ For information about email notifications originating from GitLab, read ## Sending emails to users from within GitLab -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Overview > Users**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Overview > Users**. 1. Select **Send email to users**.  diff --git a/doc/topics/authentication/index.md b/doc/topics/authentication/index.md index 83c9e180c1c..25e6e590f77 100644 --- a/doc/topics/authentication/index.md +++ b/doc/topics/authentication/index.md @@ -11,7 +11,7 @@ This page gathers all the resources for the topic **Authentication** within GitL ## GitLab users - [SSH](../../ssh/index.md) -- [Two-Factor Authentication (2FA)](../../user/profile/account/two_factor_authentication.md#two-factor-authentication) +- [Two-factor authentication (2FA)](../../user/profile/account/two_factor_authentication.md#two-factor-authentication) - [Why do I keep getting signed out?](../../user/profile/index.md#why-do-i-keep-getting-signed-out) - **Articles:** - [Support for Universal 2nd Factor Authentication - YubiKeys](https://about.gitlab.com/blog/2016/06/22/gitlab-adds-support-for-u2f/) @@ -23,7 +23,7 @@ This page gathers all the resources for the topic **Authentication** within GitL ## GitLab administrators - [LDAP](../../administration/auth/ldap/index.md) -- [Enforce Two-factor Authentication (2FA)](../../security/two_factor_authentication.md#enforce-two-factor-authentication-2fa) +- [Enforce two-factor authentication (2FA)](../../security/two_factor_authentication.md) - **Articles:** - [Feature Highlight: LDAP Integration](https://about.gitlab.com/blog/2014/07/10/feature-highlight-ldap-sync/) - [Debugging LDAP](https://about.gitlab.com/handbook/support/workflows/debugging_ldap.html) @@ -43,7 +43,7 @@ This page gathers all the resources for the topic **Authentication** within GitL - [Personal access tokens](../../api/index.md#personalproject-access-tokens) - [Project access tokens](../../api/index.md#personalproject-access-tokens) - [Impersonation tokens](../../api/index.md#impersonation-tokens) -- [GitLab as an OAuth2 provider](../../api/oauth2.md#gitlab-as-an-oauth2-provider) +- [GitLab as an OAuth2 provider](../../api/oauth2.md#gitlab-as-an-oauth-20-provider) ## Third-party resources diff --git a/doc/topics/autodevops/customize.md b/doc/topics/autodevops/customize.md index 72f688a0ed5..f8b63f5b41a 100644 --- a/doc/topics/autodevops/customize.md +++ b/doc/topics/autodevops/customize.md @@ -373,6 +373,8 @@ applications. |-----------------------------------------|------------------------------------| | `ADDITIONAL_HOSTS` | Fully qualified domain names specified as a comma-separated list that are added to the Ingress hosts. | | `<ENVIRONMENT>_ADDITIONAL_HOSTS` | For a specific environment, the fully qualified domain names specified as a comma-separated list that are added to the Ingress hosts. This takes precedence over `ADDITIONAL_HOSTS`. | +| `AUTO_BUILD_IMAGE_VERSION` | Customize the image version used for the `build` job. See [list of versions](https://gitlab.com/gitlab-org/cluster-integration/auto-build-image/-/releases). | +| `AUTO_DEPLOY_IMAGE_VERSION` | Customize the image version used for Kubernetes deployment jobs. See [list of versions](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/releases). | | `AUTO_DEVOPS_ATOMIC_RELEASE` | As of GitLab 13.0, Auto DevOps uses [`--atomic`](https://v2.helm.sh/docs/helm/#options-43) for Helm deployments by default. Set this variable to `false` to disable the use of `--atomic` | | `AUTO_DEVOPS_BUILD_IMAGE_CNB_ENABLED` | Set to `false` to use Herokuish instead of Cloud Native Buildpacks with Auto Build. [More details](stages.md#auto-build-using-cloud-native-buildpacks). | | `AUTO_DEVOPS_BUILD_IMAGE_CNB_BUILDER` | The builder used when building with Cloud Native Buildpacks. The default builder is `heroku/buildpacks:18`. [More details](stages.md#auto-build-using-cloud-native-buildpacks). | @@ -390,6 +392,7 @@ applications. | `CANARY_ENABLED` | From GitLab 11.0, used to define a [deploy policy for canary environments](#deploy-policy-for-canary-environments). | | `CANARY_PRODUCTION_REPLICAS` | Number of canary replicas to deploy for [Canary Deployments](../../user/project/canary_deployments.md) in the production environment. Takes precedence over `CANARY_REPLICAS`. Defaults to 1. | | `CANARY_REPLICAS` | Number of canary replicas to deploy for [Canary Deployments](../../user/project/canary_deployments.md). Defaults to 1. | +| `DAST_AUTO_DEPLOY_IMAGE_VERSION` | Customize the image version used for DAST deployments on the default branch. Should usually be the same as `AUTO_DEPLOY_IMAGE_VERSION`. See [list of versions](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/releases). | | `DOCKERFILE_PATH` | From GitLab 13.2, allows overriding the [default Dockerfile path for the build stage](#custom-dockerfile) | | `HELM_RELEASE_NAME` | From GitLab 12.1, allows the `helm` release name to be overridden. Can be used to assign unique release names when deploying multiple projects to a single namespace. | | `HELM_UPGRADE_VALUES_FILE` | From GitLab 12.6, allows the `helm upgrade` values file to be overridden. Defaults to `.gitlab/auto-deploy-values.yaml`. | @@ -461,7 +464,7 @@ The following table lists variables used to disable jobs. | `license_scanning` | `LICENSE_MANAGEMENT_DISABLED` | [From GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22773) | If the variable is present, the job isn't created. | | `load_performance` | `LOAD_PERFORMANCE_DISABLED` | From GitLab 13.2 | If the variable is present, the job isn't created. | | `nodejs-scan-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | -| `performance` | `PERFORMANCE_DISABLED` | GitLab 11.0 to GitLab 13.12 | Browser performance. If the variable is present, the job isn't created. Replaced by `browser_peformance`. | +| `performance` | `PERFORMANCE_DISABLED` | GitLab 11.0 to GitLab 13.12 | Browser performance. If the variable is present, the job isn't created. Replaced by `browser_performance`. | | `browser_performance` | `BROWSER_PERFORMANCE_DISABLED` | From GitLab 14.0 | Browser performance. If the variable is present, the job isn't created. Replaces `performance`. | | `phpcs-security-audit-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | | `pmd-apex-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | @@ -491,9 +494,9 @@ these prefixed variables available to the deployed application as environment va To configure your application variables: -1. Go to your project's **Settings > CI/CD**, then expand the - **Variables** section. - +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Variables**. 1. Create a CI/CD variable, ensuring the key is prefixed with `K8S_SECRET_`. For example, you can create a variable with key `K8S_SECRET_RAILS_MASTER_KEY`. diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index f4936e9162d..e232af05d50 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -105,7 +105,7 @@ test your application. If you want to build, test, and deploy your app: -1. See the [requirements for deployment](requirements.md). +1. View the [requirements for deployment](requirements.md). 1. [Enable Auto DevOps](#enable-or-disable-auto-devops). 1. Follow the [quick start guide](#quick-start). @@ -153,16 +153,18 @@ precedence over the Auto DevOps pipeline. To enable Auto DevOps for a project: -1. Go to your project's **Settings > CI/CD > Auto DevOps**. -1. Select the **Default to Auto DevOps pipeline**. -1. (Recommended) Add the [base domain](requirements.md#auto-devops-base-domain). -1. (Recommended) Choose the [deployment strategy](requirements.md#auto-devops-deployment-strategy). +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Auto DevOps**. +1. Select the **Default to Auto DevOps pipeline** checkbox. +1. Optional but recommended. Add the [base domain](requirements.md#auto-devops-base-domain). +1. Optional but recommended. Choose the [deployment strategy](requirements.md#auto-devops-deployment-strategy). 1. Select **Save changes**. GitLab triggers the Auto DevOps pipeline on the default branch. -To disable it, follow the same process and deselect **Default to Auto -DevOps pipeline**. +To disable it, follow the same process and clear the +**Default to Auto DevOps pipeline** checkbox. #### At the group level @@ -180,20 +182,22 @@ at the group level. To enable Auto DevOps for a group: -1. Go to your group's **Settings > CI/CD > Auto DevOps**. -1. Select **Default to Auto DevOps pipeline**. +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Auto DevOps**. +1. Select the **Default to Auto DevOps pipeline** checkbox. 1. Select **Save changes**. +To disable Auto DevOps on the group level, follow the same process and +clear the **Default to Auto DevOps pipeline** checkbox. + After enabling Auto DevOps at the group level, you can trigger the Auto DevOps pipeline for any project that belongs to that group. To do so: -1. Go to the project's homepage. +1. On the top bar, select **Menu > Projects** and find your project. 1. Make sure the project doesn't contain a `.gitlab-ci.yml` file. -1. From the project's sidebar, go to **CI/CD > Pipelines**. -1. Select **Run pipeline** to trigger the Auto DevOps pipeline. - -To disable Auto DevOps on the group level, follow the same process and -deselect **Default to Auto DevOps pipeline**. +1. On the left sidebar, select **CI/CD > Pipelines**. +1. To trigger the Auto DevOps pipeline, select **Run pipeline**. #### At the instance level **(FREE SELF)** @@ -210,10 +214,11 @@ can still enable Auto DevOps at the group and project levels. To enable Auto DevOps for your instance: -1. From the top bar, select **Menu >** **{admin}** **Admin**. -1. Go to **Settings > CI/CD > Continuous Integration and Deployment**. -1. Select **Default to Auto DevOps pipeline**. -1. (Optional) Add the Auto DevOps [base domain](requirements.md#auto-devops-base-domain). +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Auto DevOps**. +1. Select the **Default to Auto DevOps pipeline** checkbox. +1. Optional. Add the Auto DevOps [base domain](requirements.md#auto-devops-base-domain). 1. Select **Save changes**. When enabled, it attempts to run Auto DevOps pipelines in every project. If the @@ -224,7 +229,7 @@ If a [CI/CD configuration file](../../ci/yaml/index.md) is present, it remains unchanged and Auto DevOps doesn't affect it. To disable Auto DevOps in the instance level, follow the same process -and deselect the **Default to Auto DevOps pipeline** checkbox. +and clear the **Default to Auto DevOps pipeline** checkbox. ### Quick start diff --git a/doc/topics/autodevops/prepare_deployment.md b/doc/topics/autodevops/prepare_deployment.md index 830aff11824..c23774b1ffd 100644 --- a/doc/topics/autodevops/prepare_deployment.md +++ b/doc/topics/autodevops/prepare_deployment.md @@ -12,7 +12,7 @@ recommend that you prepare them before enabling Auto DevOps. ## Deployment strategy -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/38542) in GitLab 11.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/38542) in GitLab 11.0. When using Auto DevOps to deploy your applications, choose the [continuous deployment strategy](../../ci/introduction/index.md) @@ -44,7 +44,7 @@ To define the base domain, either: - In the project, group, or instance level: go to your cluster settings and add it there. - In the project or group level: add it as an environment variable: `KUBE_INGRESS_BASE_DOMAIN`. -- In the instance level: go to **Menu >** **{admin}** **Admin > Settings > CI/CD> Continuous Integration and Delivery** and add it there. +- In the instance level: go to **Menu > Admin > Settings > CI/CD > Continuous Integration and Delivery** and add it there. The base domain variable `KUBE_INGRESS_BASE_DOMAIN` follows the same order of precedence as other environment [variables](../../ci/variables/index.md#cicd-variable-precedence). diff --git a/doc/topics/autodevops/quick_start_guide.md b/doc/topics/autodevops/quick_start_guide.md index 2cf5a5befd7..59c61da0c45 100644 --- a/doc/topics/autodevops/quick_start_guide.md +++ b/doc/topics/autodevops/quick_start_guide.md @@ -6,7 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Tutorial: Use Auto DevOps to deploy an application to Google Kubernetes Engine **(FREE)** -This step-by-step guide helps you use [Auto DevOps](index.md) to In this tutorial, we'll help you to get started with [Auto DevOps](index.md) through an example of how to deploy an application to Google Kubernetes Engine (GKE). @@ -244,7 +243,7 @@ you to common environment tasks: - **Stop environment** (**{stop}**) - For more information, see [Stopping an environment](../../ci/environments/index.md#stop-an-environment) -GitLab displays the [Deploy Board](../../user/project/deploy_boards.md) below the +GitLab displays the [deploy board](../../user/project/deploy_boards.md) below the environment's information, with squares representing pods in your Kubernetes cluster, color-coded to show their status. Hovering over a square on the deploy board displays the state of the deployment, and selecting the square diff --git a/doc/topics/autodevops/requirements.md b/doc/topics/autodevops/requirements.md index 535ec18e5b6..8dd7c0317d9 100644 --- a/doc/topics/autodevops/requirements.md +++ b/doc/topics/autodevops/requirements.md @@ -42,7 +42,9 @@ that works best for your needs: You can choose the deployment method when enabling Auto DevOps or later: -1. In GitLab, go to your project's **Settings > CI/CD > Auto DevOps**. +1. In GitLab, on the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Auto DevOps**. 1. Choose the deployment strategy. 1. Select **Save changes**. @@ -60,7 +62,7 @@ To define the base domain, either: - In the project, group, or instance level: go to your cluster settings and add it there. - In the project or group level: add it as an environment variable: `KUBE_INGRESS_BASE_DOMAIN`. -- In the instance level: go to **Menu >** **{admin}** **Admin > Settings > CI/CD> Continuous Integration and Delivery** and add it there. +- In the instance level: go to **Menu > Admin > Settings > CI/CD > Continuous Integration and Delivery** and add it there. The base domain variable `KUBE_INGRESS_BASE_DOMAIN` follows the same order of precedence as other environment [variables](../../ci/variables/index.md#cicd-variable-precedence). @@ -181,9 +183,9 @@ You can choose to target [AWS ECS](../../ci/cloud_deployment/index.md) as a depl To get started on Auto DevOps to AWS ECS, you must add a specific CI/CD variable. To do so, follow these steps: -1. In your project, go to **Settings > CI/CD** and expand the **Variables** - section. - +1. In GitLab, on the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Auto DevOps**. 1. Specify which AWS platform to target during the Auto DevOps deployment by adding the `AUTO_DEVOPS_PLATFORM_TARGET` variable with one of the following values: - `FARGATE` if the service you're targeting must be of launch type FARGATE. diff --git a/doc/topics/autodevops/stages.md b/doc/topics/autodevops/stages.md index 3b595cc7ea8..9e6f3103664 100644 --- a/doc/topics/autodevops/stages.md +++ b/doc/topics/autodevops/stages.md @@ -425,9 +425,9 @@ including support for `Deployment` in the `extensions/v1beta1` version. To use Auto Deploy on a Kubernetes 1.16+ cluster: 1. If you are deploying your application for the first time in GitLab 13.0 or - newer, no configuration should be required. + later, no configuration should be required. -1. In GitLab 12.10 or older, set the following in the [`.gitlab/auto-deploy-values.yaml` file](customize.md#customize-values-for-helm-chart): +1. In GitLab 12.10 and earlier, set the following in the [`.gitlab/auto-deploy-values.yaml` file](customize.md#customize-values-for-helm-chart): ```yaml deploymentApiVersion: apps/v1 @@ -696,11 +696,12 @@ To use Auto Monitoring: 1. [Install and configure the Auto DevOps requirements](requirements.md). 1. [Enable Auto DevOps](index.md#enable-or-disable-auto-devops), if you haven't done already. -1. Navigate to your project's **{rocket}** **CI/CD > Pipelines** and click **Run pipeline**. +1. On the left sidebar, select **CI/CD > Pipelines**. +1. Select **Run pipeline**. 1. After the pipeline finishes successfully, open the [monitoring dashboard for a deployed environment](../../ci/environments/index.md#monitor-environments) to view the metrics of your deployed application. To view the metrics of the - whole Kubernetes cluster, navigate to **Operations > Metrics**. + whole Kubernetes cluster, on the left sidebar, select **Monitor > Metrics**.  diff --git a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md index e4378ce2d78..7ddcdcbacb5 100644 --- a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md +++ b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md @@ -159,7 +159,7 @@ steps to upgrade to v2: To use a specific version of Auto Deploy dependencies, specify the previous Auto Deploy stable template that contains the [desired version of `auto-deploy-image` and `auto-deploy-app`](#verify-dependency-versions). -For example, if the template is bundled in GitLab v13.3, change your `.gitlab-ci.yml` to: +For example, if the template is bundled in GitLab 13.3, change your `.gitlab-ci.yml` to: ```yaml include: @@ -258,7 +258,7 @@ change. If that happens, the deployment job fails with a message similar to: ```plaintext ************************************************************************************* [WARNING] -Detected a major version difference between the the chart that is currently deploying (auto-deploy-app-v0.7.0), and the previously deployed chart (auto-deploy-app-v1.0.0). +Detected a major version difference between the chart that is currently deploying (auto-deploy-app-v0.7.0), and the previously deployed chart (auto-deploy-app-v1.0.0). A new major version might not be backward compatible with the current release (production). The deployment could fail or be stuck in an unrecoverable status. ... ``` diff --git a/doc/topics/git/cherry_picking.md b/doc/topics/git/cherry_picking.md index 4a875e25e1b..64d1914019d 100644 --- a/doc/topics/git/cherry_picking.md +++ b/doc/topics/git/cherry_picking.md @@ -5,49 +5,76 @@ info: To determine the technical writer assigned to the Stage/Group associated w comments: false --- -# Cherry pick **(FREE)** +# Cherry-pick a Git commit **(FREE)** -Given an existing commit on one branch, apply the change to another branch. +In Git, you can *cherry-pick* a commit (a set of changes) from an existing branch, +and apply those changes to another branch. Cherry-picks can help you: -This can be useful for backporting bug fixes to previous release branches. Make -the commit on the default branch, and then cherry pick it into the release branch. +- Backport bug fixes from the default branch to previous release branches. +- Copy changes from a fork + [to the upstream repository](../../user/project/merge_requests/cherry_pick_changes.md#cherry-pick-into-a-project). -## Sample workflow +You can cherry-pick commits from the command line. In the GitLab user interface, +you can also: -1. Check out a new `stable` branch from the default branch: +- Cherry-pick [all changes from a merge request](../../user/project/merge_requests/cherry_pick_changes.md#cherry-pick-a-merge-request). +- Cherry-pick [a single commit](../../user/project/merge_requests/cherry_pick_changes.md#cherry-pick-a-commit). +- Cherry-pick [from a fork to the upstream repository](../../user/project/merge_requests/cherry_pick_changes.md#cherry-pick-into-a-project). + +## Cherry-pick from the command line + +These instructions explain how to cherry-pick a commit from the default branch (`main`) +into a different branch (`stable`): + +1. Check out the default branch, then check out a new `stable` branch based on it: ```shell - git checkout master + git checkout main git checkout -b stable ``` 1. Change back to the default branch: ```shell - git checkout master + git checkout main ``` -1. Make any required changes, then commit the changes: +1. Make your changes, then commit them: ```shell git add changed_file.rb git commit -m 'Fix bugs in changed_file.rb' ``` -1. Review the commit log and copy the SHA of the latest commit: +1. Display the commit log: ```shell - git log + $ git log + + commit 0000011111222223333344444555556666677777 + Merge: 88888999999 aaaaabbbbbb + Author: user@example.com + Date: Tue Aug 31 21:19:41 2021 +0000 ``` -1. Check out the `stable` branch: +1. Identify the `commit` line, and copy the string of letters and numbers on that line. + This information is the SHA (Secure Hash Algorithm) of the commit. The SHA is + a unique identifier for this commit, and you need it in a future step. + +1. Now that you know the SHA, check out the `stable` branch again: ```shell git checkout stable ``` -1. Cherry pick the commit by using the SHA copied previously: +1. Cherry-pick the commit into the `stable` branch, and change `SHA` to your commit + SHA: ```shell - git cherry-pick <commit SHA> + git cherry-pick <SHA> ``` + +## Related links + +- Cherry-pick commits with [the Commits API](../../api/commits.md#cherry-pick-a-commit) +- Git documentation [for cherry-picks](https://git-scm.com/docs/git-cherry-pick) diff --git a/doc/topics/git/git_rebase.md b/doc/topics/git/git_rebase.md index 0e288f1445e..b09f9fa0f6c 100644 --- a/doc/topics/git/git_rebase.md +++ b/doc/topics/git/git_rebase.md @@ -228,8 +228,13 @@ git push --force-with-lease origin my-feature-branch ``` If the branch you want to force-push is [protected](../../user/project/protected_branches.md), -you can't force-push to it unless you unprotect it first. Then you can -force-push and re-protect it. +you can't force push to it unless you either: + +- 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. ## Merge conflicts diff --git a/doc/topics/git/index.md b/doc/topics/git/index.md index c1e766a7c48..e95d8121b66 100644 --- a/doc/topics/git/index.md +++ b/doc/topics/git/index.md @@ -34,8 +34,8 @@ The following resources can help you get started with Git: - [Edit files through the command line](../../gitlab-basics/command-line-commands.md) - [GitLab Git Cheat Sheet (download)](https://about.gitlab.com/images/press/git-cheat-sheet.pdf) - Commits: - - [Revert a commit](../../user/project/merge_requests/revert_changes.md#reverting-a-commit) - - [Cherry-picking a commit](../../user/project/merge_requests/cherry_pick_changes.md#cherry-picking-a-commit) + - [Revert a commit](../../user/project/merge_requests/revert_changes.md#revert-a-commit) + - [Cherry-picking a commit](../../user/project/merge_requests/cherry_pick_changes.md#cherry-pick-a-commit) - [Squashing commits](../gitlab_flow.md#squashing-commits-with-rebase) - [Squash-and-merge](../../user/project/merge_requests/squash_and_merge.md) - [Signing commits](../../user/project/repository/gpg_signed_commits/index.md) @@ -58,7 +58,7 @@ The following are resources on version control concepts: You can do many Git tasks from the command line: - [Bisect](bisect.md). -- [Cherry pick](cherry_picking.md). +- [Cherry-pick](cherry_picking.md). - [Feature branching](feature_branching.md). - [Getting started with Git](getting_started.md). - [Git add](git_add.md). diff --git a/doc/topics/git/lfs/migrate_to_git_lfs.md b/doc/topics/git/lfs/migrate_to_git_lfs.md index d1231257f38..2786368a9d7 100644 --- a/doc/topics/git/lfs/migrate_to_git_lfs.md +++ b/doc/topics/git/lfs/migrate_to_git_lfs.md @@ -7,6 +7,11 @@ description: "How to migrate an existing Git repository to Git LFS with BFG." # Migrate a Git repository into Git LFS with BFG +WARNING: +The following documentation is deprecated. We recommend using +[`git lfs migrate`](https://github.com/git-lfs/git-lfs/blob/main/docs/man/git-lfs-migrate.1.ronn) +instead of the method documented below. + Using Git LFS can help you to reduce the size of your Git repository and improve its performance. 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 4d58c7ab455..9786d1399f7 100644 --- a/doc/topics/git/numerous_undo_possibilities_in_git/index.md +++ b/doc/topics/git/numerous_undo_possibilities_in_git/index.md @@ -209,7 +209,7 @@ To recover from multiple incorrect commits: The commits are now `A-B-C-D-E`. Alternatively, with GitLab, -you can [cherry-pick](../../../user/project/merge_requests/cherry_pick_changes.md#cherry-picking-a-commit) +you can [cherry-pick](../../../user/project/merge_requests/cherry_pick_changes.md#cherry-pick-a-commit) that commit into a new merge request. NOTE: @@ -388,7 +388,6 @@ git filter-branch --tree-filter 'rm filename' HEAD The `git filter-branch` command might be slow on large repositories. Tools are available to execute Git commands more quickly. -An alternative is the open source community-maintained tool [BFG](https://rtyley.github.io/bfg-repo-cleaner/). These tools are faster because they do not provide the same feature set as `git filter-branch` does, but focus on specific use cases. diff --git a/doc/topics/gitlab_flow.md b/doc/topics/gitlab_flow.md index d9aff6c35e5..e831c35a8ea 100644 --- a/doc/topics/gitlab_flow.md +++ b/doc/topics/gitlab_flow.md @@ -7,8 +7,6 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/gitlab_flow.html' # Introduction to GitLab Flow **(FREE)** - - Git allows a wide variety of branching strategies and workflows. Because of this, many organizations end up with workflows that are too complicated, not clearly defined, or not integrated with issue tracking systems. Therefore, we propose GitLab flow as a clearly defined set of best practices. @@ -16,9 +14,16 @@ It combines [feature-driven development](https://en.wikipedia.org/wiki/Feature-d Organizations coming to Git from other version control systems frequently find it hard to develop a productive workflow. This article describes GitLab flow, which integrates the Git workflow with an issue tracking system. -It offers a transparent and effective way to work with Git. - - +It offers a transparent and effective way to work with Git: + +```mermaid +graph LR + subgraph Git workflow + A[Working copy] --> |git add| B[Index] + B --> |git commit| C[Local repository] + C --> |git push| D[Remote repository] + end +``` When converting to Git, you have to get used to the fact that it takes three steps to share a commit with colleagues. Most version control systems have only one step: committing from the working copy to a shared server. @@ -26,8 +31,6 @@ In Git, you add files from the working copy to the staging area. After that, you The third step is pushing to a shared remote repository. After getting used to these three steps, the next challenge is the branching model. - - Because many organizations new to Git have no conventions for how to work with it, their repositories can quickly become messy. The biggest problem is that many long-running branches emerge that all contain part of the changes. People have a hard time figuring out which branch has the latest code, or which branch to deploy to production. @@ -65,10 +68,20 @@ For example, many projects do releases but don't need to do hotfixes. ## GitHub flow as a simpler alternative - - In reaction to Git flow, GitHub created a simpler alternative. -[GitHub flow](https://guides.github.com/introduction/flow/index.html) has only feature branches and a `main` branch. +[GitHub flow](https://guides.github.com/introduction/flow/index.html) has only feature branches and a `main` branch: + +```mermaid +graph TD + subgraph Feature branches in GitHub Flow + A[main branch] ===>B[main branch] + D[nav branch] --> |add navigation| B + B ===> C[main branch] + E[feature-branch] --> |add feature| C + C ==> F[main branch] + end +``` + This flow is clean and straightforward, and many organizations have adopted it with great success. Atlassian recommends [a similar strategy](https://www.atlassian.com/blog/git/simple-git-workflow-is-simple), although they rebase feature branches. Merging everything into the `main` branch and frequently deploying means you minimize the amount of unreleased code. This approach is in line with lean and continuous delivery best practices. @@ -77,8 +90,6 @@ With GitLab flow, we offer additional guidance for these questions. ## Production branch with GitLab flow - - GitHub flow assumes you can deploy to production every time you merge a feature branch. While this is possible in some cases, such as SaaS applications, there are some cases where this is not possible, such as: @@ -88,7 +99,22 @@ 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 make 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 `development` into the production branch: + +```mermaid +graph TD + subgraph Production branch in GitLab Flow + A[development] ==>B[development] + B ==> C[development] + C ==> D[development] + + E[production] ====> F[production] + C --> |deployment| F + D ==> G[development] + F ==> H[production] + end +``` + If you need to know what code is in production, you can check out the production branch to see. The approximate time of deployment is visible as the merge commit in the version control system. This time is pretty accurate if you automatically deploy your production branch. @@ -97,26 +123,66 @@ This flow prevents the overhead of releasing, tagging, and merging that happens ## Environment branches with GitLab flow - - -It might be a good idea to have an environment that is automatically updated to the `main` branch. +It might be a good idea to have an environment that is automatically updated to the `staging` branch. Only, in this case, the name of this environment might differ from the branch name. -Suppose you have a staging environment, a pre-production environment, and a production environment. -In this case, deploy the `main` branch to staging. -To deploy to pre-production, create a merge request from the `main` branch to the pre-production branch. -Go live by merging the pre-production branch into the production branch. +Suppose you have a staging environment, a pre-production environment, and a production environment: + +```mermaid +graph LR + subgraph Environment branches in GitLab Flow + + A[staging] ==> B[staging] + B ==> C[staging] + C ==> D[staging] + + A --> |deploy to<br>pre-prod| G + + F[pre-prod] ==> G[pre-prod] + G ==> H[pre-prod] + H ==> I[pre-prod] + + C --> |deploy to<br>pre-prod| I + + J[production] ==> K[production] + K ==> L[production] + + G --> |production <br>deployment| K + + end +``` + +In this case, deploy the `staging` branch to your staging environment. +To deploy to pre-production, create a merge request from the `staging` branch to the `pre-prod` branch. +Go live by merging the `pre-prod` branch into the `production` branch. This workflow, where commits only flow downstream, ensures that everything is tested in all environments. -If you need to cherry-pick a commit with a hotfix, it is common to develop it on a feature branch and merge it into `main` with a merge request. +If you need to cherry-pick a commit with a hotfix, it is common to develop it on a feature branch and merge it into `production` with a merge request. In this case, do not delete the feature branch yet. -If `main` passes automatic testing, you then merge the feature branch into the other branches. +If `production` passes automatic testing, you then merge the feature branch into the other branches. If this is not possible because more manual testing is required, you can send merge requests from the feature branch to the downstream branches. ## Release branches with GitLab flow - +You should work with release branches only if you need to release software to +the outside world. In this case, each branch contains a minor version, such as +`2.3-stable` or `2.4-stable`: + +```mermaid +graph LR + A:::main ===> B((main)) + B:::main ==> C((main)) + C:::main ==> D((main)) + D:::main ==> E((main)) + + A((main)) ----> F((2.3-stable)):::first + F --> G((2.3-stable)):::first + C -.-> |cherry-pick| G + D --> H((2.4-stable)):::second + + classDef main fill:#f4f0ff,stroke:#7b58cf + classDef first fill:#e9f3fc,stroke:#1f75cb + classDef second fill:#ecf4ee,stroke:#108548 +``` -You only need to work with release branches if you need to release software to the outside world. -In this case, each branch contains a minor version, such as `2-3-stable` or `2-4-stable`. Create stable branches using `main` as a starting point, and branch as late as possible. By doing this, you minimize the length of time during which you have to apply bug fixes to multiple branches. After announcing a release branch, only add serious bug fixes to the branch. @@ -167,8 +233,6 @@ When you reopen an issue you need to create a new merge request. ## Issue tracking with GitLab flow - - GitLab flow is a way to make the relation between the code and the issue tracker more transparent. Any significant change to the code should start with an issue that describes the goal. @@ -207,8 +271,6 @@ It is possible that one feature branch solves more than one issue. ## Linking and closing issues from merge requests - - Link to issues by mentioning them in commit messages or the description of a merge request, for example, "Fixes #16" or "Duck typing is preferred. See #12." GitLab then creates links to the mentioned issues and creates comments in the issues linking back to the merge request. @@ -218,10 +280,35 @@ If you have an issue that spans across multiple repositories, create an issue fo ## Squashing commits with rebase - - With Git, you can use an interactive rebase (`rebase -i`) to squash multiple commits into one or reorder them. -This feature helps you replace a couple of small commits with a single commit, or if you want to make the order more logical. +This feature helps you replace a couple of small commits with a single commit, or if you want to make the order more logical: + +```shell +pick c6ee4d3 add a new file to the repo +pick c3c130b change readme + +# Rebase 168afa0..c3c130b onto 168afa0 +# +# Commands: +# p, pick = use commit +# r, reword = use commit, but edit the commit message +# e, edit = use commit, but stop for amending +# s, squash = use commit, but meld into previous commit +# f, fixup = like "squash", but discard this commit's log message +# x, exec = run command (the rest of the line) using shell +# +# These lines can be re-ordered; they are executed from top to bottom. +# +# If you remove a line here THAT COMMIT WILL BE LOST. +# +# However, if you remove everything, the rebase will be aborted. +# +# Note that empty commits are commented out +~ +~ +~ +"~/demo/gitlab-ce/.git/rebase-merge/git-rebase-todo" 20L, 673C +``` However, you should avoid rebasing commits you have pushed to a remote server if you have other active contributors in the same branch. Because rebasing creates new commits for all your changes, it can cause confusion because the same change would have multiple identifiers. @@ -244,8 +331,6 @@ Git does not allow you to merge the code again otherwise. ## Reducing merge commits in feature branches - - Having lots of merge commits can make your repository history messy. Therefore, you should try to avoid merge commits in feature branches. Often, people avoid merge commits by just using rebase to reorder their commits after the commits on the `main` branch. @@ -303,13 +388,19 @@ Sharing your work before it's complete also allows for discussion and feedback a ## How to write a good commit message - - A commit message should reflect your intention, not just the contents of the commit. -You can see the changes in a commit, so the commit message should explain why you made those changes. +You can see the changes in a commit, so the commit message should explain why you made those changes: + +```shell +# This commit message doesn't give enough information +git commit -m 'Improve XML generation' + +# These commit messages clearly state the intent of the commit +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 example, "Improve XML generation" could be better written as "Properly escape special characters in XML generation." For more information about formatting commit messages, please see this excellent [blog post by Tim Pope](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 @@ -326,8 +417,6 @@ Issue: gitlab.com/gitlab-org/gitlab/-/issues/1 ## Testing before merging - - In old workflows, the continuous integration (CI) server commonly ran tests on the `main` branch only. Developers had to ensure their code did not break the `main` branch. When using GitLab flow, developers create their branches from this `main` branch, so it is essential that it never breaks. @@ -343,8 +432,6 @@ As said before, if you often have feature branches that last for more than a few ## Working with feature branches - - When creating a feature branch, always branch from an up-to-date `main`. If you know before you start that your work depends on another branch, you can also branch from there. If you need to merge in another branch after starting, explain the reason in the merge commit. diff --git a/doc/topics/img/gitlab_flow.png b/doc/topics/img/gitlab_flow.png Binary files differdeleted file mode 100644 index c12405455f9..00000000000 --- a/doc/topics/img/gitlab_flow.png +++ /dev/null diff --git a/doc/topics/img/gitlab_flow_ci_mr.png b/doc/topics/img/gitlab_flow_ci_mr.png Binary files differdeleted file mode 100644 index 85a609cb814..00000000000 --- a/doc/topics/img/gitlab_flow_ci_mr.png +++ /dev/null diff --git a/doc/topics/img/gitlab_flow_close_issue_mr.png b/doc/topics/img/gitlab_flow_close_issue_mr.png Binary files differdeleted file mode 100644 index 70de2fb6cee..00000000000 --- a/doc/topics/img/gitlab_flow_close_issue_mr.png +++ /dev/null diff --git a/doc/topics/img/gitlab_flow_environment_branches.png b/doc/topics/img/gitlab_flow_environment_branches.png Binary files differdeleted file mode 100644 index 0aff33c6bb8..00000000000 --- a/doc/topics/img/gitlab_flow_environment_branches.png +++ /dev/null diff --git a/doc/topics/img/gitlab_flow_four_stages.png b/doc/topics/img/gitlab_flow_four_stages.png Binary files differdeleted file mode 100644 index 3ef6a33d2d4..00000000000 --- a/doc/topics/img/gitlab_flow_four_stages.png +++ /dev/null diff --git a/doc/topics/img/gitlab_flow_git_pull.png b/doc/topics/img/gitlab_flow_git_pull.png Binary files differdeleted file mode 100644 index 0e56e59471c..00000000000 --- a/doc/topics/img/gitlab_flow_git_pull.png +++ /dev/null diff --git a/doc/topics/img/gitlab_flow_github_flow.png b/doc/topics/img/gitlab_flow_github_flow.png Binary files differdeleted file mode 100644 index 21a22becdb6..00000000000 --- a/doc/topics/img/gitlab_flow_github_flow.png +++ /dev/null diff --git a/doc/topics/img/gitlab_flow_good_commit.png b/doc/topics/img/gitlab_flow_good_commit.png Binary files differdeleted file mode 100644 index ceb0d4b1691..00000000000 --- a/doc/topics/img/gitlab_flow_good_commit.png +++ /dev/null diff --git a/doc/topics/img/gitlab_flow_merge_commits.png b/doc/topics/img/gitlab_flow_merge_commits.png Binary files differdeleted file mode 100644 index 4a80811c6e3..00000000000 --- a/doc/topics/img/gitlab_flow_merge_commits.png +++ /dev/null diff --git a/doc/topics/img/gitlab_flow_merge_request.png b/doc/topics/img/gitlab_flow_merge_request.png Binary files differdeleted file mode 100644 index 010e95983fc..00000000000 --- a/doc/topics/img/gitlab_flow_merge_request.png +++ /dev/null diff --git a/doc/topics/img/gitlab_flow_messy_flow.png b/doc/topics/img/gitlab_flow_messy_flow.png Binary files differdeleted file mode 100644 index 4fa22d2bb5d..00000000000 --- a/doc/topics/img/gitlab_flow_messy_flow.png +++ /dev/null diff --git a/doc/topics/img/gitlab_flow_production_branch.png b/doc/topics/img/gitlab_flow_production_branch.png Binary files differdeleted file mode 100644 index c132d51bfb6..00000000000 --- a/doc/topics/img/gitlab_flow_production_branch.png +++ /dev/null diff --git a/doc/topics/img/gitlab_flow_rebase.png b/doc/topics/img/gitlab_flow_rebase.png Binary files differdeleted file mode 100644 index fe865177ba8..00000000000 --- a/doc/topics/img/gitlab_flow_rebase.png +++ /dev/null diff --git a/doc/topics/img/gitlab_flow_release_branches.png b/doc/topics/img/gitlab_flow_release_branches.png Binary files differdeleted file mode 100644 index 0a7f61d0248..00000000000 --- a/doc/topics/img/gitlab_flow_release_branches.png +++ /dev/null diff --git a/doc/topics/offline/index.md b/doc/topics/offline/index.md index df6e1f9491e..a48ac9feb1a 100644 --- a/doc/topics/offline/index.md +++ b/doc/topics/offline/index.md @@ -4,7 +4,7 @@ group: Distribution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Offline GitLab +# Offline GitLab **(FREE SELF)** Computers in an offline environment are isolated from the public internet as a security measure. This page lists all the information available for running GitLab in an offline environment. diff --git a/doc/topics/offline/quick_start_guide.md b/doc/topics/offline/quick_start_guide.md index dd1ddeb31ff..09fae2b1fd5 100644 --- a/doc/topics/offline/quick_start_guide.md +++ b/doc/topics/offline/quick_start_guide.md @@ -4,7 +4,7 @@ group: Distribution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Getting started with an offline GitLab Installation +# Getting started with an offline GitLab Installation **(FREE SELF)** This is a step-by-step guide that helps you install, configure, and use a self-managed GitLab instance entirely offline. diff --git a/doc/update/deprecations.md b/doc/update/deprecations.md new file mode 100644 index 00000000000..d453c5d8336 --- /dev/null +++ b/doc/update/deprecations.md @@ -0,0 +1,67 @@ +--- +stage: none +group: none +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +--- + +# Deprecated feature removal schedule + +<!-- +This page is automatically generated from the YAML files in `/data/deprecations` by the rake task +located at `lib/tasks/gitlab/docs/compile_deprecations.rake`. + +Do not edit this page directly. + +To add a deprecation, use the example.yml file in `/data/deprecations/templates` as a template, +then run `bin/rake gitlab:docs:compile_deprecations`. +--> + +## 15.0 + +### Legacy database configuration + +The syntax of [GitLabs database](https://docs.gitlab.com/omnibus/settings/database.html) +configuration located in `database.yml` is changing and the legacy format is deprecated. The legacy format +supported using a single PostgreSQL adapter, whereas the new format is changing to support multiple databases. The `main:` database needs to be defined as a first configuration item. + +This deprecation mainly impacts users compiling GitLab from source because Omnibus will handle this configuration automatically. + +Announced: 2021-09-22 + +### Audit events for repository push events + +Audit events for [repository events](../administration/audit_events.md#repository-push) are now deprecated and will be removed in GitLab 15.0. + +These events have always been disabled by default and had to be manually enabled with a +feature flag. Enabling them can cause too many events to be generated which can +dramatically slow down GitLab instances. For this reason, they are being removed. + +Announced: 2021-09-02 + +### OmniAuth Kerberos gem + +The `omniauth-kerberos` gem will be removed in our next major release, GitLab 15.0. + +This gem has not been maintained and has very little usage. We therefore plan to remove support for this authentication method and recommend using the Kerberos [SPNEGO](https://en.wikipedia.org/wiki/SPNEGO) integration instead. You can follow the [upgrade instructions](../integration/kerberos.md#upgrading-from-password-based-to-ticket-based-kerberos-sign-ins) to upgrade from the `omniauth-kerberos` integration to the supported one. + +Note that we are not deprecating the Kerberos SPNEGO integration, only the old password-based Kerberos integration. + +Announced: 2021-09-22 + +### GitLab Serverless + +[GitLab Serverless](../user/project/clusters/serverless/index.md) is a feature set to support Knative-based serverless development with automatic deployments and monitoring. + +We decided to remove the GitLab Serverless features as they never really resonated with our users. Besides, given the continuous development of Kubernetes and Knative, our current implementations do not even work with recent versions. + +Announced: 2021-09-22 + +## 14.4 + +### Rename Task Runner pod to Toolbox + +The Task Runner pod is used to execute periodic housekeeping tasks within the GitLab application and is often confused with the GitLab Runner. Thus, [Task Runner will be renamed to Toolbox](https://gitlab.com/groups/gitlab-org/charts/-/epics/25). + +This will result in the rename of the sub-chart: `gitlab/task-runner` to `gitlab/toolbox`. Resulting pods will be named along the lines of `{{ .Release.Name }}-toolbox`, which will often be `gitlab-toolbox`. They will be locatable with the label `app=toolbox`. + +Announced: 2021-09-22 diff --git a/doc/update/index.md b/doc/update/index.md index 4b7e63a8277..fadb55684f8 100644 --- a/doc/update/index.md +++ b/doc/update/index.md @@ -32,12 +32,12 @@ official ways to update GitLab: ### Linux packages (Omnibus GitLab) -The [Omnibus update guide](https://docs.gitlab.com/omnibus/update/) +The [package upgrade guide](package/index.md) contains the steps needed to update a package installed by official GitLab repositories. There are also instructions when you want to -[update to a specific version](https://docs.gitlab.com/omnibus/update/#multi-step-upgrade-using-the-official-repositories). +[update to a specific version](package/index.md#upgrade-to-a-specific-version-using-the-official-repositories). ### Installation from source @@ -70,6 +70,10 @@ Instructions on how to update a cloud-native deployment are in Use the [version mapping](https://docs.gitlab.com/charts/installation/version_mappings.html) from the chart version to GitLab version to determine the [upgrade path](#upgrade-paths). +## Plan your upgrade + +See the guide to [plan your GitLab upgrade](plan_your_upgrade.md). + ## Checking for background migrations before upgrading Certain major/minor releases may require different migrations to be @@ -79,7 +83,7 @@ finished before you update to the newer version. To check the status of [batched background migrations](../user/admin_area/monitoring/background_migrations.md): -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Monitoring > Background Migrations**.  @@ -174,15 +178,15 @@ migration](../integration/elasticsearch.md#retry-a-halted-migration). ## Upgrade paths -Upgrading across multiple GitLab versions in one go is *only possible with downtime*. -The following examples assume a downtime upgrade. -See the section below for [zero downtime upgrades](#upgrading-without-downtime). +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). 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`](#upgrades-from-versions-earlier-than-812) -> `8.17.7` -> `9.5.10` -> `10.8.7` -> [`11.11.8`](#1200) -> `12.0.12` -> [`12.1.17`](#1210) -> `12.10.14` -> `13.0.14` -> [`13.1.11`](#1310) -> [latest `13.12.Z`](https://about.gitlab.com/releases/categories/releases/) -> [latest `14.0.Z`](#1400) -> [`14.1.Z`](#1410) -> [latest `14.Y.Z`](https://about.gitlab.com/releases/categories/releases/) +`8.11.Z` -> `8.12.0` -> `8.17.7` -> `9.5.10` -> `10.8.7` -> [`11.11.8`](#1200) -> `12.0.12` -> [`12.1.17`](#1210) -> `12.10.14` -> `13.0.14` -> [`13.1.11`](#1310) -> [`13.8.8`](#1388) -> [latest `13.12.Z`](https://about.gitlab.com/releases/categories/releases/) -> [latest `14.0.Z`](#1400) -> [latest `14.Y.Z`](https://about.gitlab.com/releases/categories/releases/) The following table, while not exhaustive, shows some examples of the supported upgrade paths. @@ -190,7 +194,7 @@ upgrade paths. | Target version | Your version | Supported upgrade path | Note | | -------------- | ------------ | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `14.1.2` | `13.9.2` | `13.9.2` -> `13.12.9` -> `14.0.7` -> `14.1.2` | Two intermediate versions are required: `13.12` and `14.0`, then `14.1`. | -| `13.5.4` | `12.9.2` | `12.9.2` -> `12.10.14` -> `13.0.14` -> `13.1.11` -> `13.5.4` | Three intermediate versions are required: `12.10`, `13.0` and `13.1`, then `13.5.4`. | +| `13.12.10` | `12.9.2` | `12.9.2` -> `12.10.14` -> `13.0.14` -> `13.1.11` -> `13.8.8` -> `13.12.10` | Four intermediate versions are required: `12.10`, `13.0`, `13.1` and `13.8.8`, then `13.12.10`. | | `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`, then `13.2.10`. | | `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`, then `12.10.14`. | | `12.9.5` | `10.4.5` | `10.4.5` -> `10.8.7` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.9.5` | Four intermediate versions are required: `10.8`, `11.11`, `12.0` and `12.1`, then `12.9.5`. | @@ -229,76 +233,7 @@ upgraded to. This is to ensure [compatibility with GitLab versions](https://docs ## Upgrading without downtime -Starting with GitLab 9.1.0 it's possible to upgrade to a newer major, minor, or -patch version of GitLab without having to take your GitLab instance offline. -However, for this to work there are the following requirements: - -- You can only upgrade 1 minor release at a time. So from 9.1 to 9.2, not to - 9.3. If you skip releases, database modifications may be run in the wrong - sequence [and leave the database schema in a broken state](https://gitlab.com/gitlab-org/gitlab/-/issues/321542). -- You have to use [post-deployment - migrations](../development/post_deployment_migrations.md) (included in - [zero downtime update steps below](#steps)). -- You are using PostgreSQL. Starting from GitLab 12.1, MySQL is not supported. -- Multi-node GitLab instance. Single-node instances may experience brief interruptions - [as services restart (Puma in particular)](https://docs.gitlab.com/omnibus/update/README.html#single-node-deployment). - -Most of the time you can safely upgrade from a patch release to the next minor -release if the patch release is not the latest. For example, upgrading from -9.1.1 to 9.2.0 should be safe even if 9.1.2 has been released. We do recommend -you check the release posts of any releases between your current and target -version just in case they include any migrations that may require you to upgrade -1 release at a time. - -Some releases may also include so called "background migrations". These -migrations are performed in the background by Sidekiq and are often used for -migrating data. Background migrations are only added in the monthly releases. - -Certain major/minor releases may require a set of background migrations to be -finished. To guarantee this, such a release processes any remaining jobs -before continuing the upgrading procedure. While this doesn't require downtime -(if the above conditions are met) we require that you [wait for background -migrations to complete](#checking-for-background-migrations-before-upgrading) -between each major/minor release upgrade. -The time necessary to complete these migrations can be reduced by -increasing the number of Sidekiq workers that can process jobs in the -`background_migration` queue. To see the size of this queue, -[Check for background migrations before upgrading](#checking-for-background-migrations-before-upgrading). - -As a rule of thumb, any database smaller than 10 GB doesn't take too much time to -upgrade; perhaps an hour at most per minor release. Larger databases however may -require more time, but this is highly dependent on the size of the database and -the migrations that are being performed. - -### Examples - -To help explain this, let's look at some examples. - -**Example 1:** You are running a large GitLab installation using version 9.4.2, -which is the latest patch release of 9.4. When GitLab 9.5.0 is released this -installation can be safely upgraded to 9.5.0 without requiring downtime if the -requirements mentioned above are met. You can also skip 9.5.0 and upgrade to -9.5.1 after it's released, but you **can not** upgrade straight to 9.6.0; you -_have_ to first upgrade to a 9.5.Z release. - -**Example 2:** You are running a large GitLab installation using version 9.4.2, -which is the latest patch release of 9.4. GitLab 9.5 includes some background -migrations, and 10.0 requires these to be completed (processing any -remaining jobs for you). Skipping 9.5 is not possible without downtime, and due -to the background migrations would require potentially hours of downtime -depending on how long it takes for the background migrations to complete. To -work around this you have to upgrade to 9.5.Z first, then wait at least a -week before upgrading to 10.0. - -**Example 3:** You use MySQL as the database for GitLab. Any upgrade to a new -major/minor release requires downtime. If a release includes any background -migrations this could potentially lead to hours of downtime, depending on the -size of your database. To work around this you must use PostgreSQL and -meet the other online upgrade requirements mentioned above. - -### Steps - -Steps to [upgrade without downtime](https://docs.gitlab.com/omnibus/update/README.html#zero-downtime-updates). +Read how to [upgrade without downtime](zero_downtime.md). ## Upgrading between editions @@ -320,7 +255,7 @@ Edition, follow the guides below based on the installation method: to a version upgrade: stop the server, get the code, update configuration files for the new functionality, install libraries and do migrations, update the init script, start the application and check its status. -- [Omnibus CE to EE](https://docs.gitlab.com/omnibus/update/README.html#update-community-edition-to-enterprise-edition) - Follow this guide to update your Omnibus +- [Omnibus CE to EE](package/convert_to_ee.md) - Follow this guide to update your Omnibus GitLab Community Edition to the Enterprise Edition. ### Enterprise to Community Edition @@ -351,21 +286,43 @@ These include: Apart from the instructions in this section, you should also check the installation-specific upgrade instructions, based on how you installed GitLab: -- [Linux packages (Omnibus GitLab)](https://docs.gitlab.com/omnibus/update/README.html#version-specific-changes) +- [Linux packages (Omnibus GitLab)](../update/package/index.md#version-specific-changes) - [Helm charts](https://docs.gitlab.com/charts/installation/upgrade.html) 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. +### 14.3.0 + +Ruby 2.7.4 is required. Refer to [the Ruby installation instructions](../install/installation.md#2-ruby) +for how to proceed. + +- GitLab 14.3.0 contains post-deployment migrations to [address Primary Key overflow risk for tables with an integer PK](https://gitlab.com/groups/gitlab-org/-/epics/4785) for the tables listed below: + + - [`ci_builds.id`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/70245) + - [`ci_builds.stage_id`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66688) + - [`ci_builds_metadata`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/65692) + - [`taggings`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66625) + - [`events`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/64779) + + If the migrations are executed as part of a no-downtime deployment, there's a risk of failure due to lock conflicts with the application logic, resulting in lock timeout or deadlocks. In each case, these migrations are safe to re-run until successful: + + ```shell + # For Omnibus GitLab + sudo gitlab-rake db:migrate + + # For source installations + sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production + ``` + ### 14.2.0 - Due to an issue where `BatchedBackgroundMigrationWorkers` were [not working](https://gitlab.com/gitlab-org/charts/gitlab/-/issues/2785#note_614738345) for self-managed instances, a [fix was created](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/65106) - and a [14.0.Z](#1400) version was released. If you haven't updated to 14.0.Z, you need - to update to at least 14.1.0 that contains the same fix before you update to - to 14.2. + and a [14.0.Z](#1400) version was released. If you haven't updated to 14.0.5, you need + to update to at least 14.1.0 that contains the same fix before you update to 14.2. - GitLab 14.2.0 contains background migrations to [address Primary Key overflow risk for tables with an integer PK](https://gitlab.com/groups/gitlab-org/-/epics/4785) for the tables listed below: - [`ci_build_needs`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/65216) @@ -393,7 +350,7 @@ and [Helm Chart deployments](https://docs.gitlab.com/charts/). They come with ap - Due to an issue where `BatchedBackgroundMigrationWorkers` were [not working](https://gitlab.com/gitlab-org/charts/gitlab/-/issues/2785#note_614738345) for self-managed instances, a [fix was created](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/65106) - and a [14.0.Z](#1400) version was released. If you haven't updated to 14.0.Z, you need + and a [14.0.Z](#1400) version was released. If you haven't updated to 14.0.5, you need to update to at least 14.1.0 that contains the same fix before you update to a later version. @@ -480,6 +437,17 @@ DETAIL: trigger trigger_0d588df444c8 on table application_settings depends on co To work around this bug, follow the previous steps to complete the update. More details are available [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/324160). +### 13.8.8 + +GitLab 13.8 includes a background migration to address [an issue with duplicate service records](https://gitlab.com/gitlab-org/gitlab/-/issues/290008). If duplicate services are present, this background migration must complete before a unique index is applied to the services table, which was [introduced in GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52563). Upgrades from GitLab 13.8 and earlier to later versions must include an intermediate upgrade to GitLab 13.8.8 and [must wait until the background migrations complete](#checking-for-background-migrations-before-upgrading) before proceeding. + +If duplicate services are still present, an upgrade to 13.9.x or later results in a failed upgrade with the following error: + +```console +PG::UniqueViolation: ERROR: could not create unique index "index_services_on_project_id_and_type_unique" +DETAIL: Key (project_id, type)=(NNN, ServiceName) is duplicated. +``` + ### 13.6.0 Ruby 2.7.2 is required. GitLab does not start with Ruby 2.6.6 or older versions. @@ -528,7 +496,7 @@ The Rails upgrade included a change to CSRF token generation which is not backwards-compatible - GitLab servers with the new Rails version generate CSRF tokens that are not recognizable by GitLab servers with the older Rails version - which could cause non-GET requests to -fail for [multi-node GitLab installations](https://docs.gitlab.com/omnibus/update/#multi-node--ha-deployment). +fail for [multi-node GitLab installations](zero_downtime.md#multi-node--ha-deployment). So, if you are using multiple Rails servers and specifically upgrading from 13.0, all servers must first be upgraded to 13.1.Z before upgrading to 13.2.0 or later: @@ -577,12 +545,6 @@ After upgraded to 11.11.8 you can safely upgrade to 12.0.Z. See our [documentation on upgrade paths](../policy/maintenance.md#upgrade-recommendations) for more information. -### Upgrades from versions earlier than 8.12 - -- `8.11.Z` and earlier: you might have to upgrade to `8.12.0` specifically before you can upgrade to `8.17.7`. This was [reported in an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/207259). -- [CI changes prior to version 8.0](https://docs.gitlab.com/omnibus/update/README.html#updating-gitlab-ci-from-prior-540-to-version-714-via-omnibus-gitlab) - when it was merged into GitLab. - ## Miscellaneous - [MySQL to PostgreSQL](mysql_to_postgresql.md) guides you through migrating diff --git a/doc/update/package/convert_to_ee.md b/doc/update/package/convert_to_ee.md new file mode 100644 index 00000000000..2cc54e2c8cf --- /dev/null +++ b/doc/update/package/convert_to_ee.md @@ -0,0 +1,118 @@ +--- +stage: Enablement +group: Distribution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Convert Community Edition to Enterprise Edition **(FREE SELF)** + +To convert an existing GitLab Community Edition (CE) server installed using the Omnibus GitLab +packages to GitLab [Enterprise Edition](https://about.gitlab.com/pricing/) (EE), you install the EE +package on top of CE. + +Converting from the same version of CE to EE is not explicitly necessary, and any standard upgrade +(for example, CE 12.0 to EE 12.1) should work. However, in the following steps we assume that +you are upgrading the same version (for example, CE 12.1 to EE 12.1), which is **recommended**. + +WARNING: +When updating to EE from CE, avoid reverting back to CE if you plan on going to EE again in the +future. Reverting back to CE can cause +[database issues](index.md#500-error-when-accessing-project--settings--repository) +that may require Support intervention. + +The steps can be summed up to: + +1. Find the currently installed GitLab version: + + **For Debian/Ubuntu** + + ```shell + sudo apt-cache policy gitlab-ce | grep Installed + ``` + + The output should be similar to: `Installed: 13.0.4-ce.0`. In that case, + the equivalent Enterprise Edition version will be: `13.0.4-ee.0`. Write this + value down. + + **For CentOS/RHEL** + + ```shell + sudo rpm -q gitlab-ce + ``` + + The output should be similar to: `gitlab-ce-13.0.4-ce.0.el8.x86_64`. In that + case, the equivalent Enterprise Edition version will be: + `gitlab-ee-13.0.4-ee.0.el8.x86_64`. Write this value down. + +1. Add the `gitlab-ee` [Apt or Yum repository](https://packages.gitlab.com/gitlab/gitlab-ee/install): + + **For Debian/Ubuntu** + + ```shell + curl --silent "https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.deb.sh" | sudo bash + ``` + + **For CentOS/RHEL** + + ```shell + curl --silent "https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.rpm.sh" | sudo bash + ``` + + The above command will find your OS version and automatically set up the + repository. If you are not comfortable installing the repository through a + piped script, you can first + [check its contents](https://packages.gitlab.com/gitlab/gitlab-ee/install). + +1. Next, install the `gitlab-ee` package. Note that this will automatically + uninstall the `gitlab-ce` package on your GitLab server. `reconfigure` + Omnibus right after the `gitlab-ee` package is installed. **Make sure that you + install the exact same GitLab version**: + + **For Debian/Ubuntu** + + ```shell + ## Make sure the repositories are up-to-date + sudo apt-get update + + ## Install the package using the version you wrote down from step 1 + sudo apt-get install gitlab-ee=13.0.4-ee.0 + + ## Reconfigure GitLab + sudo gitlab-ctl reconfigure + ``` + + **For CentOS/RHEL** + + ```shell + ## Install the package using the version you wrote down from step 1 + sudo yum install gitlab-ee-13.0.4-ee.0.el8.x86_64 + + ## Reconfigure GitLab + sudo gitlab-ctl reconfigure + ``` + +1. Now go to the GitLab admin panel of your server (`/admin/license/new`) and + upload your license file. + +1. After you confirm that GitLab is working as expected, you may remove the old + Community Edition repository: + + **For Debian/Ubuntu** + + ```shell + sudo rm /etc/apt/sources.list.d/gitlab_gitlab-ce.list + ``` + + **For CentOS/RHEL** + + ```shell + sudo rm /etc/yum.repos.d/gitlab_gitlab-ce.repo + ``` + +That's it! You can now use GitLab Enterprise Edition! To update to a newer +version, follow [Update using the official repositories](index.md#upgrade-using-the-official-repositories). + +NOTE: +If you want to use `dpkg`/`rpm` instead of `apt-get`/`yum`, go through the first +step to find the current GitLab version and then follow +[Update using a manually-downloaded package](index.md#upgrade-using-a-manually-downloaded-package). diff --git a/doc/update/package/downgrade.md b/doc/update/package/downgrade.md new file mode 100644 index 00000000000..9a528f5ee44 --- /dev/null +++ b/doc/update/package/downgrade.md @@ -0,0 +1,83 @@ +--- +stage: Enablement +group: Distribution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Downgrade **(FREE SELF)** + +This section contains general information on how to revert to an earlier version +of a package. + +WARNING: +You must at least have a database backup created under the version you are +downgrading to. Ideally, you should have a +[full backup archive](../../raketasks/backup_restore.md#back-up-gitlab) +on hand. + +The example below demonstrates the downgrade procedure when downgrading between minor +and patch versions (for example, from 13.0.6 to 13.0.5). + +When downgrading between major versions, take into account the +[specific version changes](index.md#version-specific-changes) that occurred when you upgraded +to the major version you are downgrading from. + +These steps consist of: + +- Stopping GitLab +- Removing the current package +- Installing the old package +- Reconfiguring GitLab +- Restoring the backup +- Starting GitLab + +Steps: + +1. Stop GitLab and remove the current package: + + ```shell + # If running Puma + sudo gitlab-ctl stop puma + + # Stop sidekiq + sudo gitlab-ctl stop sidekiq + + # If on Ubuntu: remove the current package + sudo dpkg -r gitlab-ee + + # If on Centos: remove the current package + sudo yum remove gitlab-ee + ``` + +1. Identify the GitLab version you want to downgrade to: + + ```shell + # (Replace with gitlab-ce if you have GitLab FOSS installed) + + # Ubuntu + sudo apt-cache madison gitlab-ee + + # CentOS: + sudo yum --showduplicates list gitlab-ee + ``` + +1. Downgrade GitLab to the desired version (for example, to GitLab 13.0.5): + + ```shell + # (Replace with gitlab-ce if you have GitLab FOSS installed) + + # Ubuntu + sudo apt install gitlab-ee=13.0.5-ee.0 + + # CentOS: + sudo yum install gitlab-ee-13.0.5-ee.0.el8 + ``` + +1. Reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +1. [Restore GitLab](../../raketasks/backup_restore.md#restore-for-omnibus-gitlab-installations) + to complete the downgrade. diff --git a/doc/update/package/index.md b/doc/update/package/index.md new file mode 100644 index 00000000000..44be79f22fb --- /dev/null +++ b/doc/update/package/index.md @@ -0,0 +1,278 @@ +--- +stage: Enablement +group: Distribution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Upgrade GitLab using the GitLab Package **(FREE SELF)** + +This section describes how to upgrade GitLab to a new version using the +GitLab package. + +We recommend performing upgrades between major and minor releases no more than once per +week, to allow time for background migrations to finish. Decrease the time required to +complete these migrations by increasing the number of +[Sidekiq workers](../../administration/operations/extra_sidekiq_processes.md) +that can process jobs in the `background_migration` queue. + +If you don't follow the steps in [zero downtime upgrades](../zero_downtime.md), +your GitLab application will not be available to users while an upgrade is in progress. +They either see a "Deploy in progress" message or a "502" error in their web browser. + +Prerequisites: + +- [Supported upgrade paths](../index.md#upgrade-paths) + has suggestions on when to upgrade. Upgrade paths are enforced for version upgrades by + default. This restricts performing direct upgrades that skip major versions (for + example 10.3 to 12.7 in one jump) that **can break GitLab + installations** due to multiple reasons like deprecated or removed configuration + settings, upgrade of internal tools and libraries, and so on. +- If you are upgrading from a non-Package installation to a GitLab Package installation, see + [Upgrading from a non-Package installation to a GitLab Package installation](https://docs.gitlab.com/omnibus/convert_to_omnibus.html). +- It's important to ensure that any + [background migrations](../index.md#checking-for-background-migrations-before-upgrading) + have been fully completed before upgrading to a new major version. Upgrading + before background migrations have finished may lead to data corruption. +- Gitaly servers must be upgraded to the newer version prior to upgrading the application server. + This prevents the gRPC client on the application server from sending RPCs that the old Gitaly version + does not support. + +You can upgrade the GitLab Package using one of the following methods: + +- [Using the official repositories](#upgrade-using-the-official-repositories). +- [Using a manually-downloaded package](#upgrade-using-a-manually-downloaded-package). + +Both automatically back up the GitLab database before installing a newer +GitLab version. You may skip this automatic database backup by creating an empty file +at `/etc/gitlab/skip-auto-backup`: + +```shell +sudo touch /etc/gitlab/skip-auto-backup +``` + +For safety reasons, you should maintain an up-to-date backup on your own if you plan to use this flag. + +## Version-specific changes + +Updating to major versions might need some manual intervention. For more information, +check the version your are upgrading to: + +- [GitLab 14](https://docs.gitlab.com/omnibus/gitlab_14_changes.html) +- [GitLab 13](https://docs.gitlab.com/omnibus/gitlab_13_changes.html) +- [GitLab 12](https://docs.gitlab.com/omnibus/gitlab_12_changes.html) +- [GitLab 11](https://docs.gitlab.com/omnibus/gitlab_11_changes.html) + +## Upgrade using the official repositories + +All GitLab packages are posted to the GitLab [package server](https://packages.gitlab.com/gitlab/). +Five repositories are maintained: + +- [GitLab EE](https://packages.gitlab.com/gitlab/gitlab-ee): for official + [Enterprise Edition](https://about.gitlab.com/pricing/) releases. +- [GitLab CE](https://packages.gitlab.com/gitlab/gitlab-ce): for official Community Edition releases. +- [Unstable](https://packages.gitlab.com/gitlab/unstable): for release candidates and other unstable versions. +- [Nighty Builds](https://packages.gitlab.com/gitlab/nightly-builds): for nightly builds. +- [Raspberry Pi](https://packages.gitlab.com/gitlab/raspberry-pi2): for official Community Edition releases built for [Raspberry Pi](https://www.raspberrypi.org) packages. + +If you have installed Omnibus GitLab [Community Edition](https://about.gitlab.com/install/?version=ce) +or [Enterprise Edition](https://about.gitlab.com/install/), then the +official GitLab repository should have already been set up for you. + +To upgrade to the newest GitLab version, run: + +- For GitLab [Enterprise Edition](https://about.gitlab.com/pricing/): + + ```shell + # Debian/Ubuntu + sudo apt-get update + sudo apt-get install gitlab-ee + + # Centos/RHEL + sudo yum install gitlab-ee + ``` + +- For GitLab Community Edition: + + ```shell + # Debian/Ubuntu + sudo apt-get update + sudo apt-get install gitlab-ce + + # Centos/RHEL + sudo yum install gitlab-ce + ``` + +### Upgrade to a specific version using the official repositories + +Linux package managers default to installing the latest available version of a +package for installation and upgrades. Upgrading directly to the latest major +version can be problematic for older GitLab versions that require a multi-stage +[upgrade path](../index.md#upgrade-paths). An upgrade path can span multiple +versions, so you must specify the specific GitLab package with each upgrade. + +To specify the intended GitLab version number in your package manager's install +or upgrade command: + +1. First, identify the GitLab version number in your package manager: + + ```shell + # Ubuntu/Debian + sudo apt-cache madison gitlab-ee + # RHEL/CentOS 6 and 7 + yum --showduplicates list gitlab-ee + # RHEL/CentOS 8 + dnf search gitlab-ee* + ``` + +1. Then install the specific GitLab package: + + ```shell + # Ubuntu/Debian + sudo apt install gitlab-ee=12.0.12-ee.0 + # RHEL/CentOS 6 and 7 + yum install gitlab-ee-12.0.12-ee.0.el7 + # RHEL/CentOS 8 + dnf install gitlab-ee-12.0.12-ee.0.el8 + # SUSE + zypper install gitlab-ee=12.0.12-ee.0 + ``` + +## Upgrade using a manually-downloaded package + +NOTE: +The [package repository](#upgrade-using-the-official-repositories) is recommended over +a manual installation. + +If for some reason you don't use the official repositories, you can +download the package and install it manually. This method can be used to either +install GitLab for the first time or update it. + +To download and install GitLab: + +1. Visit the [official repository](#upgrade-using-the-official-repositories) of your package. +1. Browse to the repository for the type of package you would like to see the + list of packages that are available. Multiple packages exist for a + single version, one for each supported distribution type. Next to the filename + is a label indicating the distribution, as the file names may be the same. +1. Find the package version you wish to install and click on it. +1. Click the **Download** button in the upper right corner to download the package. +1. After the GitLab package is downloaded, install it using the following commands: + + - For GitLab [Enterprise Edition](https://about.gitlab.com/pricing/): + + ```shell + # Debian/Ubuntu + dpkg -i gitlab-ee-<version>.deb + + # CentOS/RHEL + rpm -Uvh gitlab-ee-<version>.rpm + ``` + + - For GitLab Community Edition: + + ```shell + # GitLab Community Edition + # Debian/Ubuntu + dpkg -i gitlab-ce-<version>.deb + + # CentOS/RHEL + rpm -Uvh gitlab-ce-<version>.rpm + ``` + +## Troubleshooting + +### GitLab 13.7 and later unavailable on Amazon Linux 2 + +Amazon Linux 2 is not an [officially supported operating system](../../administration/package_information/deprecated_os.md#supported-operating-systems). +However, in past the [official package installation script](https://packages.gitlab.com/gitlab/gitlab-ee/install) +installed the `el/6` package repository if run on Amazon Linux. From GitLab 13.7, we no longer +provide `el/6` packages so administrators must run the [installation script](https://packages.gitlab.com/gitlab/gitlab-ee/install) +again to update the repository to `el/7`: + +```shell +curl --silent "https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.rpm.sh" | sudo bash +``` + +See the [epic on support for GitLab on Amazon Linux 2](https://gitlab.com/groups/gitlab-org/-/epics/2195) for the latest details on official Amazon Linux 2 support. + +### Get the status of a GitLab installation + +```shell +sudo gitlab-ctl status +sudo gitlab-rake gitlab:check SANITIZE=true +``` + +- Information on using `gitlab-ctl` to perform [maintenance tasks](https://docs.gitlab.com/omnibus/maintenance/index.html). +- Information on using `gitlab-rake` to [check the configuration](../../administration/raketasks/maintenance.md#check-gitlab-configuration). + +### RPM 'package is already installed' error + +If you are using RPM and you are upgrading from GitLab Community Edition to GitLab Enterprise Edition you may get an error like this: + +```shell +package gitlab-7.5.2_omnibus.5.2.1.ci-1.el7.x86_64 (which is newer than gitlab-7.5.2_ee.omnibus.5.2.1.ci-1.el7.x86_64) is already installed +``` + +You can override this version check with the `--oldpackage` option: + +```shell +sudo rpm -Uvh --oldpackage gitlab-7.5.2_ee.omnibus.5.2.1.ci-1.el7.x86_64.rpm +``` + +### Package obsoleted by installed package + +CE and EE packages are marked as obsoleting and replacing each other so that both aren't installed and running at the same time. + +If you are using local RPM files to switch from CE to EE or vice versa, use `rpm` for installing the package rather than `yum`. If you try to use yum, then you may get an error like this: + +```plaintext +Cannot install package gitlab-ee-11.8.3-ee.0.el6.x86_64. It is obsoleted by installed package gitlab-ce-11.8.3-ce.0.el6.x86_64 +``` + +To avoid this issue, either: + +- Use the same instructions provided in the + [Upgrade using a manually-downloaded package](#upgrade-using-a-manually-downloaded-package) section. +- Temporarily disable this checking in yum by adding `--setopt=obsoletes=0` to the options given to the command. + +### 500 error when accessing Project > Settings > Repository + +When GitLab is migrated from CE > EE > CE, and then back to EE, you +might get the following error when viewing a project's repository settings: + +```shell +Processing by Projects::Settings::RepositoryController#show as HTML + Parameters: {"namespace_id"=>"<namespace_id>", "project_id"=>"<project_id>"} +Completed 500 Internal Server Error in 62ms (ActiveRecord: 4.7ms | Elasticsearch: 0.0ms | Allocations: 14583) + +NoMethodError (undefined method `commit_message_negative_regex' for #<PushRule:0x00007fbddf4229b8> +Did you mean? commit_message_regex_change): +``` + +This error is caused by an EE feature being added to a CE instance on the initial move to EE. +After the instance is moved back to CE and then is upgraded to EE again, the +`push_rules` table already exists in the database. Therefore, a migration is +unable to add the `commit_message_regex_change` column. + +This results in the [backport migration of EE tables](https://gitlab.com/gitlab-org/gitlab/-/blob/cf00e431024018ddd82158f8a9210f113d0f4dbc/db/migrate/20190402150158_backport_enterprise_schema.rb#L1619) not working correctly. +The backport migration assumes that certain tables in the database do not exist when running CE. + +To fix this issue, manually add the missing `commit_message_negative_regex` column and restart GitLab: + +```shell +# Access psql +sudo gitlab-rails dbconsole + +# Add the missing column +ALTER TABLE push_rules ADD COLUMN commit_message_negative_regex VARCHAR; + +# Exit psql +\q + +# Restart GitLab +sudo gitlab-ctl restart +``` + +### Error `Failed to connect to the internal GitLab API` on a separate GitLab Pages server + +Please see [GitLab Pages troubleshooting](../../administration/pages/index.md#failed-to-connect-to-the-internal-gitlab-api). diff --git a/doc/update/patch_versions.md b/doc/update/patch_versions.md index 0a7057ffe97..d09f19d143b 100644 --- a/doc/update/patch_versions.md +++ b/doc/update/patch_versions.md @@ -103,7 +103,7 @@ sudo -u git -H make ### 8. Install/Update `gitlab-elasticsearch-indexer` **(PREMIUM SELF)** -Please follow the [install instruction](../integration/elasticsearch.md#installing-elasticsearch). +Please follow the [install instruction](../integration/elasticsearch.md#install-elasticsearch). ### 9. Start application diff --git a/doc/update/plan_your_upgrade.md b/doc/update/plan_your_upgrade.md new file mode 100644 index 00000000000..406f8322218 --- /dev/null +++ b/doc/update/plan_your_upgrade.md @@ -0,0 +1,180 @@ +--- +stage: Enablement +group: Distribution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Create a GitLab upgrade plan + +This document serves as a guide to create a strong plan to upgrade a self-managed +GitLab instance. + +General notes: + +- If possible, we recommend you test out the upgrade in a test environment before + updating your production instance. Ideally, your test environment should mimic + your production environment as closely as possible. +- If [working with Support](https://about.gitlab.com/support/scheduling-live-upgrade-assistance.html) + to create your plan, share details of your architecture, including: + - How is GitLab installed? + - What is the operating system of the node? + (check [OS versions that are no longer supported](../administration/package_information/deprecated_os.md) to confirm that later updates are available). + - Is it a single-node or a multi-node setup? If multi-node, share any architectural details about each node with us. + - Are you using [GitLab Geo](../administration/geo/index.md)? If so, share any architectural details about each secondary node. + - What else might be unique or interesting in your setup that might be important for us to understand? + - Are you running into any known issues with your current version of GitLab? + +## Pre-upgrade and post-upgrade checks + +Immediately before and after the upgrade, perform the pre-upgrade and post-upgrade checks +to ensure the major components of GitLab are working: + +1. [Check the general configuration](../administration/raketasks/maintenance.md#check-gitlab-configuration): + + ```shell + sudo gitlab-rake gitlab:check + ``` + +1. Confirm that encrypted database values [can be decrypted](../administration/raketasks/doctor.md#verify-database-values-can-be-decrypted-using-the-current-secrets): + + ```shell + sudo gitlab-rake gitlab:doctor:secrets + ``` + +1. In GitLab UI, check that: + - Users can log in. + - The project list is visible. + - Project issues and merge requests are accessible. + - Users can clone repositories from GitLab. + - Users can push commits to GitLab. + +1. For GitLab CI/CD, check that: + - Runners pick up jobs. + - Docker images can be pushed and pulled from the registry. + +1. If using Geo, run the relevant checks on the primary and each secondary: + + ```shell + sudo gitlab-rake gitlab:geo:check + ``` + +1. If using Elasticsearch, verify that searches are successful. + +If in any case something goes wrong, see [how to troubleshoot](#troubleshooting). + +## Rollback plan + +It's possible that something may go wrong during an upgrade, so it's critical +that a rollback plan be present for that scenario. A proper rollback plan +creates a clear path to bring the instance back to its last working state. It is +comprised of a way to back up the instance and a way to restore it. + +### Back up GitLab + +Create a backup of GitLab and all its data (database, repos, uploads, builds, +artifacts, LFS objects, registry, pages). This is vital for making it possible +to roll back GitLab to a working state if there's a problem with the upgrade: + +- Create a [GitLab backup](../raketasks/backup_restore.md#back-up-gitlab). + Make sure to follow the instructions based on your installation method. + Don't forget to back up the [secrets and configuration files](../raketasks/backup_restore.md#storing-configuration-files). +- Alternatively, create a snapshot of your instance. If this is a multi-node + installation, you must snapshot every node. + **This process is out of scope for GitLab Support.** + +### Restore GitLab + +To restore your GitLab backup: + +- Before restoring, make sure to read about the + [prerequisites](../raketasks/backup_restore.md#restore-gitlab), most importantly, + the versions of the backed up and the new GitLab instance must be the same. +- [Restore GitLab](../raketasks/backup_restore.md#restore-gitlab). + Make sure to follow the instructions based on your installation method. + Confirm that the [secrets and configuration files](../raketasks/backup_restore.md#storing-configuration-files) are also restored. +- If restoring from a snapshot, know the steps to do this. + **This process is out of scope for GitLab Support.** + +## Upgrade plan + +For the upgrade plan, start by creating an outline of a plan that best applies +to your instance and then upgrade it for any relevant features you're using. + +- Generate an upgrade plan by reading and understanding the relevant documentation: + - upgrade based on the installation method: + - [Linux package (Omnibus)](index.md#linux-packages-omnibus-gitlab) + - [Compiled from source](index.md#installation-from-source) + - [Docker](index.md#installation-using-docker) + - [Helm Charts](index.md#installation-using-helm) + - [Zero-downtime upgrades](zero_downtime.md) (if possible and desired) + - [Convert from GitLab Community Edition to Enterprise Edition](package/convert_to_ee.md) +- What version should you upgrade to: + - [Determine what upgrade path](index.md#upgrade-paths) to follow. + - Account for any [version-specific update instructions](index.md#version-specific-upgrading-instructions). + - Account for any [version-specific changes](package/index.md#version-specific-changes). + - Check the [OS compatibility with the target GitLab version](../administration/package_information/deprecated_os.md). +- Due to background migrations, plan to pause any further upgrades after upgrading + to a new major version. + [All migrations must finish running](index.md#checking-for-background-migrations-before-upgrading) + before the next upgrade. +- If available in your starting version, consider + [turning on maintenance mode](../administration/maintenance_mode/) during the + upgrade. +- About PostgreSQL: + - On the top bar, select **Menu > Admin**, and look for the version of + PostgreSQL you are using. + If [a PostgreSQL upgrade is needed](../administration/package_information/postgresql_versions.md), + account for the relevant + [packaged](https://docs.gitlab.com/omnibus/settings/database.html#upgrade-packaged-postgresql-server) + or [non-packaged](https://docs.gitlab.com/omnibus/settings/database.html#upgrade-a-non-packaged-postgresql-database) steps. + +### Additional features + +Apart from all the generic information above, you may have enabled some features +that require special planning. + +Feel free to ignore sections about features that are inapplicable to your setup, +such as Geo, external Gitaly, or Elasticsearch. + +#### External Gitaly + +If you're using an external Gitaly server, it must be upgraded to the newer +version prior to upgrading the application server. + +#### Geo + +If you're using Geo: + +- Review [Geo upgrade documentation](../administration/geo/replication/updating_the_geo_nodes.md). +- Read about the [Geo version-specific update instructions](../administration/geo/replication/version_specific_updates.md). +- Review Geo-specific steps when [updating the database](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). +- Create an upgrade and rollback plan for _each_ Geo node (primary and each secondary). + +#### Runners + +After updating GitLab, upgrade your runners to match +[your new GitLab version](https://docs.gitlab.com/runner/#gitlab-runner-versions). + +#### Elasticsearch + +After updating GitLab, you may have to upgrade +[Elasticsearch if the new version breaks compatibility](../integration/elasticsearch.md#version-requirements). +Updating Elasticsearch is **out of scope for GitLab Support**. + +## Troubleshooting + +If anything doesn't go as planned: + +- If time is of the essence, copy any errors and gather any logs to later analyze, + and then [roll back to the last working version](#rollback-plan). You can use + the following tools to help you gather data: + - [`gitlabsos`](https://gitlab.com/gitlab-com/support/toolbox/gitlabsos) if + you installed GitLab using the Linux package or Docker. + - [`kubesos`](https://gitlab.com/gitlab-com/support/toolbox/kubesos/) if + 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 [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/upgrading_from_ce_to_ee.md b/doc/update/upgrading_from_ce_to_ee.md index 93c9432f6d3..d91b3de6df1 100644 --- a/doc/update/upgrading_from_ce_to_ee.md +++ b/doc/update/upgrading_from_ce_to_ee.md @@ -88,7 +88,7 @@ sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production ### 4. Install `gitlab-elasticsearch-indexer` **(PREMIUM SELF)** -Please follow the [install instruction](../integration/elasticsearch.md#installing-elasticsearch). +Please follow the [install instruction](../integration/elasticsearch.md#install-elasticsearch). ### 5. Start application diff --git a/doc/update/upgrading_from_source.md b/doc/update/upgrading_from_source.md index dd7ef27feca..9abf993f0fe 100644 --- a/doc/update/upgrading_from_source.md +++ b/doc/update/upgrading_from_source.md @@ -69,9 +69,9 @@ Download Ruby and compile it: ```shell mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress "https://cache.ruby-lang.org/pub/ruby/2.7/ruby-2.7.2.tar.gz" -echo 'cb9731a17487e0ad84037490a6baf8bfa31a09e8 ruby-2.7.2.tar.gz' | shasum -c - && tar xzf ruby-2.7.2.tar.gz -cd ruby-2.7.2 +curl --remote-name --progress-bar "https://cache.ruby-lang.org/pub/ruby/2.7/ruby-2.7.4.tar.gz" +echo '3043099089608859fc8cce7f9fdccaa1f53a462457e3838ec3b25a7d609fbc5b ruby-2.7.4.tar.gz' | sha256sum -c - && tar xzf ruby-2.7.4.tar.gz +cd ruby-2.7.4 ./configure --disable-install-rdoc --enable-shared make @@ -107,11 +107,11 @@ Download and install Go (for Linux, 64-bit): # Remove former Go installation folder sudo rm -rf /usr/local/go -curl --remote-name --progress "https://dl.google.com/go/go1.13.5.linux-amd64.tar.gz" -echo '512103d7ad296467814a6e3f635631bd35574cab3369a97a323c9a585ccaa569 go1.13.5.linux-amd64.tar.gz' | shasum -a256 -c - && \ - sudo tar -C /usr/local -xzf go1.13.5.linux-amd64.tar.gz +curl --remote-name --progress-bar "https://dl.google.com/go/go1.15.12.linux-amd64.tar.gz" +echo 'bbdb935699e0b24d90e2451346da76121b2412d30930eabcd80907c230d098b7 go1.15.12.linux-amd64.tar.gz' | shasum -a256 -c - && \ + sudo tar -C /usr/local -xzf go1.15.12.linux-amd64.tar.gz sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ -rm go1.13.5.linux-amd64.tar.gz +rm go1.15.12.linux-amd64.tar.gz ``` diff --git a/doc/update/zero_downtime.md b/doc/update/zero_downtime.md new file mode 100644 index 00000000000..f0e6377f355 --- /dev/null +++ b/doc/update/zero_downtime.md @@ -0,0 +1,942 @@ +--- +stage: Enablement +group: Distribution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Zero downtime upgrades + +Starting with GitLab 9.1.0 it's possible to upgrade to a newer major, minor, or +patch version of GitLab without having to take your GitLab instance offline. +However, for this to work there are the following requirements: + +- You can only upgrade 1 minor release at a time. So from 9.1 to 9.2, not to + 9.3. If you skip releases, database modifications may be run in the wrong + sequence [and leave the database schema in a broken state](https://gitlab.com/gitlab-org/gitlab/-/issues/321542). +- You have to use [post-deployment migrations](../development/post_deployment_migrations.md). +- You are using PostgreSQL. Starting from GitLab 12.1, MySQL is not supported. +- Multi-node GitLab instance. Single-node instances may experience brief interruptions + [as services restart (Puma in particular)](#single-node-deployment). + +If you meet all the requirements above, follow these instructions in order. There are three sets of steps, depending on your deployment type: + +| Deployment type | Description | +| --------------------------------------------------------------- | ------------------------------------------------ | +| [Single-node](#single-node-deployment) | GitLab CE/EE on a single node | +| [Gitaly Cluster](#gitaly-cluster) | GitLab CE/EE using HA architecture for Gitaly Cluster | +| [Multi-node / PostgreSQL HA](#use-postgresql-ha) | GitLab CE/EE using HA architecture for PostgreSQL | +| [Multi-node / Redis HA](#use-redis-ha-using-sentinel) | GitLab CE/EE using HA architecture for Redis | +| [Geo](#geo-deployment) | GitLab EE with Geo enabled | +| [Multi-node / HA with Geo](#multi-node--ha-deployment-with-geo) | GitLab CE/EE on multiple nodes | + +Each type of deployment will require that you hot reload the `puma` and `sidekiq` processes on all nodes running these +services after you've upgraded. The reason for this is that those processes each load the GitLab Rails application which reads and loads +the database schema into memory when starting up. Each of these processes will need to be reloaded (or restarted in the case of `sidekiq`) +to re-read any database changes that have been made by post-deployment migrations. + +Most of the time you can safely upgrade from a patch release to the next minor +release if the patch release is not the latest. For example, upgrading from +9.1.1 to 9.2.0 should be safe even if 9.1.2 has been released. We do recommend +you check the release posts of any releases between your current and target +version just in case they include any migrations that may require you to upgrade +1 release at a time. + +Some releases may also include so called "background migrations". These +migrations are performed in the background by Sidekiq and are often used for +migrating data. Background migrations are only added in the monthly releases. + +Certain major/minor releases may require a set of background migrations to be +finished. To guarantee this, such a release processes any remaining jobs +before continuing the upgrading procedure. While this doesn't require downtime +(if the above conditions are met) we require that you [wait for background +migrations to complete](index.md#checking-for-background-migrations-before-upgrading) +between each major/minor release upgrade. +The time necessary to complete these migrations can be reduced by +increasing the number of Sidekiq workers that can process jobs in the +`background_migration` queue. To see the size of this queue, +[Check for background migrations before upgrading](index.md#checking-for-background-migrations-before-upgrading). + +As a rule of thumb, any database smaller than 10 GB doesn't take too much time to +upgrade; perhaps an hour at most per minor release. Larger databases however may +require more time, but this is highly dependent on the size of the database and +the migrations that are being performed. + +To help explain this, let's look at some examples: + +**Example 1:** You are running a large GitLab installation using version 9.4.2, +which is the latest patch release of 9.4. When GitLab 9.5.0 is released this +installation can be safely upgraded to 9.5.0 without requiring downtime if the +requirements mentioned above are met. You can also skip 9.5.0 and upgrade to +9.5.1 after it's released, but you **can not** upgrade straight to 9.6.0; you +_have_ to first upgrade to a 9.5.Z release. + +**Example 2:** You are running a large GitLab installation using version 9.4.2, +which is the latest patch release of 9.4. GitLab 9.5 includes some background +migrations, and 10.0 requires these to be completed (processing any +remaining jobs for you). Skipping 9.5 is not possible without downtime, and due +to the background migrations would require potentially hours of downtime +depending on how long it takes for the background migrations to complete. To +work around this you have to upgrade to 9.5.Z first, then wait at least a +week before upgrading to 10.0. + +**Example 3:** You use MySQL as the database for GitLab. Any upgrade to a new +major/minor release requires downtime. If a release includes any background +migrations this could potentially lead to hours of downtime, depending on the +size of your database. To work around this you must use PostgreSQL and +meet the other online upgrade requirements mentioned above. + +## Single-node deployment + +Before following these instructions, note the following **important** information: + +- You can only upgrade 1 minor release at a time. So from 13.6 to 13.7, not to 13.8. + If you attempt more than one minor release, the upgrade may fail. +- On single-node Omnibus deployments, updates with no downtime are not possible when + using Puma because Puma always requires a complete restart. This is because the + [phased restart](https://github.com/puma/puma/blob/master/README.md#clustered-mode) + feature of Puma does not work with the way it is configured in GitLab all-in-one + packages (cluster-mode with app preloading). +- While it is possible to minimize downtime on a single-node instance by following + these instructions, **it is not possible to always achieve true zero downtime + updates**. Users may see some connections timeout or be refused for a few minutes, + depending on which services need to restart. + +1. Create an empty file at `/etc/gitlab/skip-auto-reconfigure`. This prevents upgrades from running `gitlab-ctl reconfigure`, which by default automatically stops GitLab, runs all database migrations, and restarts GitLab. + + ```shell + sudo touch /etc/gitlab/skip-auto-reconfigure + ``` + +1. Update the GitLab package: + + - For GitLab Community Edition: + + ```shell + # Debian/Ubuntu + sudo apt-get update + sudo apt-get install gitlab-ce + + # Centos/RHEL + sudo yum install gitlab-ce + ``` + + - For GitLab [Enterprise Edition](https://about.gitlab.com/pricing/): + + ```shell + # Debian/Ubuntu + sudo apt-get update + sudo apt-get install gitlab-ee + + # Centos/RHEL + sudo yum install gitlab-ee + ``` + +1. To get the regular migrations and latest code in place, run + + ```shell + sudo SKIP_POST_DEPLOYMENT_MIGRATIONS=true gitlab-ctl reconfigure + ``` + +1. Once the node is updated and `reconfigure` finished successfully, run post-deployment migrations with + + ```shell + sudo gitlab-rake db:migrate + ``` + +1. Hot reload `puma` and `sidekiq` services + + ```shell + sudo gitlab-ctl hup puma + sudo gitlab-ctl restart sidekiq + ``` + +If you do not want to run zero downtime upgrades in the future, make +sure you remove `/etc/gitlab/skip-auto-reconfigure` after +you've completed these steps. + +## Multi-node / HA deployment + +You can only upgrade 1 minor release at a time. So from 13.6 to 13.7, not to 13.8. +If you attempt more than one minor release, the upgrade may fail. + +### Use a load balancer in front of web (Puma) nodes + +With Puma, single node zero-downtime updates are no longer possible. To achieve +HA with zero-downtime updates, at least two nodes are required to be used with a +load balancer which distributes the connections properly across both nodes. + +The load balancer in front of the application nodes must be configured to check +proper health check endpoints to check if the service is accepting traffic or +not. For Puma, the `/-/readiness` endpoint should be used, while +`/readiness` endpoint can be used for Sidekiq and other services. + +Upgrades on web (Puma) nodes must be done in a rolling manner, one after +another, ensuring at least one node is always up to serve traffic. This is +required to ensure zero-downtime. + +Puma will enter a blackout period as part of the upgrade, during which they +continue to accept connections but will mark their respective health check +endpoints to be unhealthy. On seeing this, the load balancer should disconnect +them gracefully. + +Puma will restart only after completing all the currently processing requests. +This ensures data and service integrity. Once they have restarted, the health +check end points will be marked healthy. + +The nodes must be updated in the following order to update an HA instance using +load balancer to latest GitLab version. + +1. Select one application node as a deploy node and complete the following steps + on it: + + 1. Create an empty file at `/etc/gitlab/skip-auto-reconfigure`. This prevents upgrades from running `gitlab-ctl reconfigure`, which by default automatically stops GitLab, runs all database migrations, and restarts GitLab: + + ```shell + sudo touch /etc/gitlab/skip-auto-reconfigure + ``` + + 1. Update the GitLab package: + + ```shell + # Debian/Ubuntu + sudo apt-get update && sudo apt-get install gitlab-ce + + # Centos/RHEL + sudo yum install gitlab-ce + ``` + + If you are an Enterprise Edition user, replace `gitlab-ce` with + `gitlab-ee` in the above command. + + 1. Get the regular migrations and latest code in place: + + ```shell + sudo SKIP_POST_DEPLOYMENT_MIGRATIONS=true gitlab-ctl reconfigure + ``` + + 1. Ensure services use the latest code: + + ```shell + sudo gitlab-ctl hup puma + sudo gitlab-ctl restart sidekiq + ``` + +1. Complete the following steps on the other Puma/Sidekiq nodes, one + after another. Always ensure at least one of such nodes is up and running, + and connected to the load balancer before proceeding to the next node. + + 1. Update the GitLab package and ensure a `reconfigure` is run as part of + it. If not (due to `/etc/gitlab/skip-auto-reconfigure` file being + present), run `sudo gitlab-ctl reconfigure` manually. + + 1. Ensure services use latest code: + + ```shell + sudo gitlab-ctl hup puma + sudo gitlab-ctl restart sidekiq + ``` + +1. On the deploy node, run the post-deployment migrations: + + ```shell + sudo gitlab-rake db:migrate + ``` + +### Gitaly Cluster + +[Gitaly Cluster](../administration/gitaly/praefect.md) is built using +Gitaly and the Praefect component. It has its own PostgreSQL database, independent of the rest of +the application. + +Before you update the main application you need to update Praefect. +Out of your Praefect nodes, pick one to be your Praefect deploy node. +This is where you will install the new Omnibus package first and run +database migrations. + +**Praefect deploy node** + +- Create an empty file at `/etc/gitlab/skip-auto-reconfigure`. This prevents upgrades from running `gitlab-ctl reconfigure`, which by default automatically stops GitLab, runs all database migrations, and restarts GitLab: + + ```shell + sudo touch /etc/gitlab/skip-auto-reconfigure + ``` + +- Ensure that `praefect['auto_migrate'] = true` is set in `/etc/gitlab/gitlab.rb` + +**All Praefect nodes _excluding_ the Praefect deploy node** + +- To prevent `reconfigure` from automatically running database migrations, ensure that `praefect['auto_migrate'] = false` is set in `/etc/gitlab/gitlab.rb`. + +**Praefect deploy node** + +- Update the GitLab package: + + ```shell + # Debian/Ubuntu + sudo apt-get update && sudo apt-get install gitlab-ce + + # Centos/RHEL + sudo yum install gitlab-ce + ``` + + If you are an Enterprise Edition user, replace `gitlab-ce` with `gitlab-ee` in the above command. + +- To apply the Praefect database migrations and restart Praefect, run: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +**All Praefect nodes _excluding_ the Praefect deploy node** + +- Update the GitLab package: + + ```shell + sudo apt-get update && sudo apt-get install gitlab-ce + ``` + + If you are an Enterprise Edition user, replace `gitlab-ce` with `gitlab-ee` in the above command. + +- Ensure nodes are running the latest code: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +### Use PostgreSQL HA + +Pick a node to be the `Deploy Node`. It can be any application node, but it must be the same +node throughout the process. + +**Deploy node** + +- Create an empty file at `/etc/gitlab/skip-auto-reconfigure`. This prevents upgrades from running `gitlab-ctl reconfigure`, which by default automatically stops GitLab, runs all database migrations, and restarts GitLab. + + ```shell + sudo touch /etc/gitlab/skip-auto-reconfigure + ``` + +**All nodes _including_ the Deploy node** + +- To prevent `reconfigure` from automatically running database migrations, ensure that `gitlab_rails['auto_migrate'] = false` is set in `/etc/gitlab/gitlab.rb`. + +**Gitaly only nodes** + +- Update the GitLab package + + ```shell + # Debian/Ubuntu + sudo apt-get update && sudo apt-get install gitlab-ce + + # Centos/RHEL + sudo yum install gitlab-ce + ``` + + If you are an Enterprise Edition user, replace `gitlab-ce` with `gitlab-ee` in the above command. + +- Ensure nodes are running the latest code + + ```shell + sudo gitlab-ctl reconfigure + ``` + +**Deploy node** + +- Update the GitLab package + + ```shell + # Debian/Ubuntu + sudo apt-get update && sudo apt-get install gitlab-ce + + # Centos/RHEL + sudo yum install gitlab-ce + ``` + + If you are an Enterprise Edition user, replace `gitlab-ce` with `gitlab-ee` in the above command. + +- If you're using PgBouncer: + + You'll need to bypass PgBouncer and connect directly to the database master + before running migrations. + + Rails uses an advisory lock when attempting to run a migration to prevent + concurrent migrations from running on the same database. These locks are + not shared across transactions, resulting in `ActiveRecord::ConcurrentMigrationError` + and other issues when running database migrations using PgBouncer in transaction + pooling mode. + + To find the master node, run the following on a database node: + + ```shell + sudo gitlab-ctl patroni members + ``` + + Then, in your `gitlab.rb` file on the deploy node, update + `gitlab_rails['db_host']` and `gitlab_rails['db_port']` with the database + master's host and port. + +- To get the regular database migrations and latest code in place, run + + ```shell + sudo gitlab-ctl reconfigure + sudo SKIP_POST_DEPLOYMENT_MIGRATIONS=true gitlab-rake db:migrate + ``` + +**All nodes _excluding_ the Deploy node** + +- Update the GitLab package + + ```shell + sudo apt-get update && sudo apt-get install gitlab-ce + ``` + + If you are an Enterprise Edition user, replace `gitlab-ce` with `gitlab-ee` in the above command. + +- Ensure nodes are running the latest code + + ```shell + sudo gitlab-ctl reconfigure + ``` + +**Deploy node** + +- Run post-deployment database migrations on deploy node to complete the migrations with + + ```shell + sudo gitlab-rake db:migrate + ``` + +**For nodes that run Puma or Sidekiq** + +- Hot reload `puma` and `sidekiq` services + + ```shell + sudo gitlab-ctl hup puma + sudo gitlab-ctl restart sidekiq + ``` + +- If you're using PgBouncer: + + Change your `gitlab.rb` to point back to PgBouncer and run: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +If you do not want to run zero downtime upgrades in the future, make +sure you remove `/etc/gitlab/skip-auto-reconfigure` and revert +setting `gitlab_rails['auto_migrate'] = false` in +`/etc/gitlab/gitlab.rb` after you've completed these steps. + +### Use Redis HA (using Sentinel) **(PREMIUM ONLY)** + +Package upgrades may involve version updates to the bundled Redis service. On +instances using [Redis for scaling](../administration/redis/index.md), +upgrades must follow a proper order to ensure minimum downtime, as specified +below. This doc assumes the official guides are being followed to setup Redis +HA. + +#### In the application node + +According to [official Redis docs](https://redis.io/topics/admin#upgrading-or-restarting-a-redis-instance-without-downtime), +the easiest way to update an HA instance using Sentinel is to upgrade the +secondaries one after the other, perform a manual failover from current +primary (running old version) to a recently upgraded secondary (running a new +version), and then upgrade the original primary. For this, we need to know +the address of the current Redis primary. + +- If your application node is running GitLab 12.7.0 or later, you can use the +following command to get address of current Redis primary + + ```shell + sudo gitlab-ctl get-redis-master + ``` + +- If your application node is running a version older than GitLab 12.7.0, you + will have to run the underlying `redis-cli` command (which `get-redis-master` + command uses) to fetch information about the primary. + + 1. Get the address of one of the sentinel nodes specified as + `gitlab_rails['redis_sentinels']` in `/etc/gitlab/gitlab.rb` + + 1. Get the Redis master name specified as `redis['master_name']` in + `/etc/gitlab/gitlab.rb` + + 1. Run the following command + + ```shell + sudo /opt/gitlab/embedded/bin/redis-cli -h <sentinel host> -p <sentinel port> SENTINEL get-master-addr-by-name <redis master name> + ``` + +#### In the Redis secondary nodes + +1. Install package for new version. + +1. Run `sudo gitlab-ctl reconfigure`, if a reconfigure is not run as part of + installation (due to `/etc/gitlab/skip-auto-reconfigure` file being present). + +1. If reconfigure warns about a pending Redis/Sentinel restart, restart the + corresponding service + + ```shell + sudo gitlab-ctl restart redis + sudo gitlab-ctl restart sentinel + ``` + +#### In the Redis primary node + +Before upgrading the Redis primary node, we need to perform a failover so that +one of the recently upgraded secondary nodes becomes the new primary. Once the +failover is complete, we can go ahead and upgrade the original primary node. + +1. Stop Redis service in Redis primary node so that it fails over to a secondary + node + + ```shell + sudo gitlab-ctl stop redis + ``` + +1. Wait for failover to be complete. You can verify it by periodically checking + details of the current Redis primary node (as mentioned above). If it starts + reporting a new IP, failover is complete. + +1. Start Redis again in that node, so that it starts following the current + primary node. + + ```shell + sudo gitlab-ctl start redis + ``` + +1. Install package corresponding to new version. + +1. Run `sudo gitlab-ctl reconfigure`, if a reconfigure is not run as part of + installation (due to `/etc/gitlab/skip-auto-reconfigure` file being present). + +1. If reconfigure warns about a pending Redis/Sentinel restart, restart the + corresponding service + + ```shell + sudo gitlab-ctl restart redis + sudo gitlab-ctl restart sentinel + ``` + +#### Update the application node + +Install the package for new version and follow regular package upgrade +procedure. + +## Geo deployment **(PREMIUM ONLY)** + +The order of steps is important. While following these steps, make +sure you follow them in the right order, on the correct node. + +Log in to your **primary** node, executing the following: + +1. Create an empty file at `/etc/gitlab/skip-auto-reconfigure`. This prevents upgrades from running `gitlab-ctl reconfigure`, which by default automatically stops GitLab, runs all database migrations, and restarts GitLab. + + ```shell + sudo touch /etc/gitlab/skip-auto-reconfigure + ``` + +1. Edit `/etc/gitlab/gitlab.rb` and ensure the following is present: + + ```ruby + gitlab_rails['auto_migrate'] = false + ``` + +1. Reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +1. Update the GitLab package + + ```shell + # Debian/Ubuntu + sudo apt-get update && sudo apt-get install gitlab-ee + + # Centos/RHEL + sudo yum install gitlab-ee + ``` + +1. To get the database migrations and latest code in place, run + + ```shell + sudo SKIP_POST_DEPLOYMENT_MIGRATIONS=true gitlab-ctl reconfigure + ``` + +1. Hot reload `puma` and `sidekiq` services + + ```shell + sudo gitlab-ctl hup puma + sudo gitlab-ctl restart sidekiq + ``` + +On each **secondary** node, executing the following: + +1. Create an empty file at `/etc/gitlab/skip-auto-reconfigure`. This prevents upgrades from running `gitlab-ctl reconfigure`, which by default automatically stops GitLab, runs all database migrations, and restarts GitLab. + + ```shell + sudo touch /etc/gitlab/skip-auto-reconfigure + ``` + +1. Edit `/etc/gitlab/gitlab.rb` and ensure the following is present: + + ```ruby + gitlab_rails['auto_migrate'] = false + ``` + +1. Reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +1. Update the GitLab package + + ```shell + # Debian/Ubuntu + sudo apt-get update && sudo apt-get install gitlab-ee + + # Centos/RHEL + sudo yum install gitlab-ee + ``` + +1. To get the database migrations and latest code in place, run + + ```shell + sudo SKIP_POST_DEPLOYMENT_MIGRATIONS=true gitlab-ctl reconfigure + ``` + +1. Hot reload `puma`, `sidekiq` and restart `geo-logcursor` services + + ```shell + sudo gitlab-ctl hup puma + sudo gitlab-ctl restart sidekiq + sudo gitlab-ctl restart geo-logcursor + ``` + +1. Run post-deployment database migrations, specific to the Geo database + + ```shell + sudo gitlab-rake geo:db:migrate + ``` + +After all **secondary** nodes are updated, finalize +the update on the **primary** node: + +- Run post-deployment database migrations + + ```shell + sudo gitlab-rake db:migrate + ``` + +After updating all nodes (both **primary** and all **secondaries**), check their status: + +- Verify Geo configuration and dependencies + + ```shell + sudo gitlab-rake gitlab:geo:check + ``` + +If you do not want to run zero downtime upgrades in the future, make +sure you remove `/etc/gitlab/skip-auto-reconfigure` and revert +setting `gitlab_rails['auto_migrate'] = false` in +`/etc/gitlab/gitlab.rb` after you've completed these steps. + +## Multi-node / HA deployment with Geo **(PREMIUM ONLY)** + +This section describes the steps required to upgrade a multi-node / HA +deployment with Geo. Some steps must be performed on a particular node. This +node will be known as the “deploy node” and is noted through the following +instructions. + +Updates must be performed in the following order: + +1. Update Geo **primary** multi-node deployment. +1. Update Geo **secondary** multi-node deployments. +1. Post-deployment migrations and checks. + +### Step 1: Choose a "deploy node" for each deployment + +You now need to choose: + +- One instance for use as the **primary** "deploy node" on the Geo **primary** multi-node deployment. +- One instance for use as the **secondary** "deploy node" on each Geo **secondary** multi-node deployment. + +Deploy nodes must be configured to be running Puma or Sidekiq or the `geo-logcursor` daemon. In order +to avoid any downtime, they must not be in use during the update: + +- If running Puma remove the deploy node from the load balancer. +- If running Sidekiq, ensure the deploy node is not processing jobs: + + ```shell + sudo gitlab-ctl stop sidekiq + ``` + +- If running `geo-logcursor` daemon, ensure the deploy node is not processing events: + + ```shell + sudo gitlab-ctl stop geo-logcursor + ``` + +For zero-downtime, Puma, Sidekiq, and `geo-logcursor` must be running on other nodes during the update. + +### Step 2: Update the Geo primary multi-node deployment + +**On all primary nodes _including_ the primary "deploy node"** + +1. Create an empty file at `/etc/gitlab/skip-auto-reconfigure`. This prevents upgrades from running `gitlab-ctl reconfigure`, which by default automatically stops GitLab, runs all database migrations, and restarts GitLab. + +```shell +sudo touch /etc/gitlab/skip-auto-reconfigure +``` + +1. To prevent `reconfigure` from automatically running database migrations, ensure that `gitlab_rails['auto_migrate'] = false` is set in `/etc/gitlab/gitlab.rb`. + +1. Ensure nodes are running the latest code + + ```shell + sudo gitlab-ctl reconfigure + ``` + +**On primary Gitaly only nodes** + +1. Update the GitLab package + + ```shell + # Debian/Ubuntu + sudo apt-get update && sudo apt-get install gitlab-ee + + # Centos/RHEL + sudo yum install gitlab-ee + ``` + +1. Ensure nodes are running the latest code + + ```shell + sudo gitlab-ctl reconfigure + ``` + +**On the primary "deploy node"** + +1. Update the GitLab package + + ```shell + # Debian/Ubuntu + sudo apt-get update && sudo apt-get install gitlab-ee + + # Centos/RHEL + sudo yum install gitlab-ee + ``` + +1. If you're using PgBouncer: + + You'll need to bypass PgBouncer and connect directly to the database master + before running migrations. + + Rails uses an advisory lock when attempting to run a migration to prevent + concurrent migrations from running on the same database. These locks are + not shared across transactions, resulting in `ActiveRecord::ConcurrentMigrationError` + and other issues when running database migrations using PgBouncer in transaction + pooling mode. + + To find the master node, run the following on a database node: + + ```shell + sudo gitlab-ctl patroni members + ``` + + Then, in your `gitlab.rb` file on the deploy node, update + `gitlab_rails['db_host']` and `gitlab_rails['db_port']` with the database + master's host and port. + +1. To get the regular database migrations and latest code in place, run + + ```shell + sudo gitlab-ctl 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, + then you may return it to service at this point. + + - To serve requests, add the deploy node to the load balancer. + - To process Sidekiq jobs again, start Sidekiq: + + ```shell + sudo gitlab-ctl start sidekiq + ``` + +**On all primary nodes _excluding_ the primary "deploy node"** + +1. Update the GitLab package + + ```shell + # Debian/Ubuntu + sudo apt-get update && sudo apt-get install gitlab-ee + + # Centos/RHEL + sudo yum install gitlab-ee + ``` + +1. Ensure nodes are running the latest code + + ```shell + sudo gitlab-ctl reconfigure + ``` + +**For all primary nodes that run Puma or Sidekiq _including_ the primary "deploy node"** + +Hot reload `puma` and `sidekiq` services: + +```shell +sudo gitlab-ctl hup puma +sudo gitlab-ctl restart sidekiq +``` + +### Step 3: Update each Geo secondary multi-node deployment + +Only proceed if you have successfully completed all steps on the Geo **primary** multi-node deployment. + +**On all secondary nodes _including_ the secondary "deploy node"** + +1. Create an empty file at `/etc/gitlab/skip-auto-reconfigure`. This prevents upgrades from running `gitlab-ctl reconfigure`, which by default automatically stops GitLab, runs all database migrations, and restarts GitLab. + +```shell +sudo touch /etc/gitlab/skip-auto-reconfigure +``` + +1. To prevent `reconfigure` from automatically running database migrations, ensure that `geo_secondary['auto_migrate'] = false` is set in `/etc/gitlab/gitlab.rb`. + +1. Ensure nodes are running the latest code + + ```shell + sudo gitlab-ctl reconfigure + ``` + +**On secondary Gitaly only nodes** + +1. Update the GitLab package + + ```shell + # Debian/Ubuntu + sudo apt-get update && sudo apt-get install gitlab-ee + + # Centos/RHEL + sudo yum install gitlab-ee + ``` + +1. Ensure nodes are running the latest code + + ```shell + sudo gitlab-ctl reconfigure + ``` + +**On the secondary "deploy node"** + +1. Update the GitLab package + + ```shell + # Debian/Ubuntu + sudo apt-get update && sudo apt-get install gitlab-ee + + # Centos/RHEL + sudo yum install gitlab-ee + ``` + +1. To get the regular database migrations and latest code in place, run + + ```shell + sudo gitlab-ctl reconfigure + sudo SKIP_POST_DEPLOYMENT_MIGRATIONS=true gitlab-rake geo:db:migrate + ``` + +1. If this deploy node is normally 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. + - To process Sidekiq jobs again, start Sidekiq: + + ```shell + sudo gitlab-ctl start sidekiq + ``` + + - To process Geo events again, start the `geo-logcursor` daemon: + + ```shell + sudo gitlab-ctl start geo-logcursor + ``` + +**On all secondary nodes _excluding_ the secondary "deploy node"** + +1. Update the GitLab package + + ```shell + # Debian/Ubuntu + sudo apt-get update && sudo apt-get install gitlab-ee + + # Centos/RHEL + sudo yum install gitlab-ee + ``` + +1. Ensure nodes are running the latest code + + ```shell + sudo gitlab-ctl reconfigure + ``` + +**For all secondary nodes that run Puma, Sidekiq, or the `geo-logcursor` daemon _including_ the secondary "deploy node"** + +Hot reload `puma`, `sidekiq` and ``geo-logcursor`` services: + +```shell +sudo gitlab-ctl hup puma +sudo gitlab-ctl restart sidekiq +sudo gitlab-ctl restart geo-logcursor +``` + +### Step 4: Run post-deployment migrations and checks + +**On the primary "deploy node"** + +1. Run post-deployment database migrations: + + ```shell + sudo gitlab-rake db:migrate + ``` + +1. Verify Geo configuration and dependencies + + ```shell + sudo gitlab-rake gitlab:geo:check + ``` + +1. If you're using PgBouncer: + + Change your `gitlab.rb` to point back to PgBouncer and run: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +**On all secondary "deploy nodes"** + +1. Run post-deployment database migrations, specific to the Geo database: + + ```shell + sudo gitlab-rake geo:db:migrate + ``` + +1. Verify Geo configuration and dependencies + + ```shell + sudo gitlab-rake gitlab:geo:check + ``` + +1. Verify Geo status + + ```shell + sudo gitlab-rake geo:status + ``` diff --git a/doc/user/admin_area/analytics/dev_ops_report.md b/doc/user/admin_area/analytics/dev_ops_report.md index f07ccc11c60..7ddddfc5e53 100644 --- a/doc/user/admin_area/analytics/dev_ops_report.md +++ b/doc/user/admin_area/analytics/dev_ops_report.md @@ -14,13 +14,13 @@ from planning to monitoring. To see DevOps Report: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Analytics > DevOps Report**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Analytics > DevOps Report**. ## DevOps Score NOTE: -To see the DevOps score, you must activate your GitLab instance's [Service Ping](../settings/usage_statistics.md#service-ping). +To see the DevOps score, you must activate your GitLab instance's [Service Ping](../settings/usage_statistics.md#service-ping). This is because DevOps Score is a comparative tool, so your score data must be centrally processed by GitLab Inc. first. You can use the DevOps score to compare your DevOps status to other organizations. @@ -45,6 +45,7 @@ feature is available. > - Fuzz Testing metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/330398) in GitLab 14.2. > - Dependency Scanning metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/328034) in GitLab 14.2. > - Multi-select [added](https://gitlab.com/gitlab-org/gitlab/-/issues/333586) in GitLab 14.2. +> - Overview table [added](https://gitlab.com/gitlab-org/gitlab/-/issues/335638) in GitLab 14.3. DevOps Adoption shows you which groups in your organization are using the most essential features of GitLab: diff --git a/doc/user/admin_area/analytics/img/admin_devops_adoption_v14_2.png b/doc/user/admin_area/analytics/img/admin_devops_adoption_v14_2.png Binary files differindex d4b3436f3ee..666e03f1d9d 100644 --- a/doc/user/admin_area/analytics/img/admin_devops_adoption_v14_2.png +++ b/doc/user/admin_area/analytics/img/admin_devops_adoption_v14_2.png diff --git a/doc/user/admin_area/analytics/index.md b/doc/user/admin_area/analytics/index.md index 465b26d516c..dd1efc913fa 100644 --- a/doc/user/admin_area/analytics/index.md +++ b/doc/user/admin_area/analytics/index.md @@ -10,8 +10,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w Administrators have access to instance-wide analytics: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Analytics**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Analytics**. There are several kinds of statistics: diff --git a/doc/user/admin_area/analytics/usage_trends.md b/doc/user/admin_area/analytics/usage_trends.md index 9c09b62f8af..06995069215 100644 --- a/doc/user/admin_area/analytics/usage_trends.md +++ b/doc/user/admin_area/analytics/usage_trends.md @@ -19,7 +19,7 @@ Usage Trends gives you an overview of how much data your instance contains, and To see Usage Trends: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Analytics > Usage Trends**. ## Total counts diff --git a/doc/user/admin_area/appearance.md b/doc/user/admin_area/appearance.md index d7f0b7e3854..0ffa8289d37 100644 --- a/doc/user/admin_area/appearance.md +++ b/doc/user/admin_area/appearance.md @@ -11,8 +11,8 @@ disqus_identifier: 'https://docs.gitlab.com/ee/customization/branded_login_page. There are several options for customizing the appearance of a self-managed instance of GitLab. To access these settings: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Appearance**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Appearance**. ## Navigation bar diff --git a/doc/user/admin_area/broadcast_messages.md b/doc/user/admin_area/broadcast_messages.md index 93e6aa9bb16..987d7444ae0 100644 --- a/doc/user/admin_area/broadcast_messages.md +++ b/doc/user/admin_area/broadcast_messages.md @@ -54,7 +54,7 @@ To display messages to users on your GitLab instance, add a broadcast message. To add a broadcast message: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Messages**. 1. Add the text for the message to the **Message** field. You can style a message's content using Markdown, emoji, and the `a` and `br` HTML tags. The `br` tag inserts a line break. The `a` HTML tag accepts `class` and `style` attributes with the following CSS properties: @@ -84,7 +84,7 @@ If you need to make changes to a broadcast message, you can edit it. To edit a broadcast message: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Messages**. 1. From the list of broadcast messages, select the edit button for the message. 1. After making the required changes, select **Update broadcast message**. @@ -98,7 +98,7 @@ You can delete a broadcast message while it's active. To delete a broadcast message: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Messages**. 1. From the list of broadcast messages, select the delete button for the message. diff --git a/doc/user/admin_area/credentials_inventory.md b/doc/user/admin_area/credentials_inventory.md index 8c5ae2dfb47..d79508e5b68 100644 --- a/doc/user/admin_area/credentials_inventory.md +++ b/doc/user/admin_area/credentials_inventory.md @@ -25,7 +25,7 @@ and [delete](#delete-a-users-ssh-key) and see: To access the Credentials inventory: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Credentials**. The following is an example of the Credentials inventory page: diff --git a/doc/user/admin_area/diff_limits.md b/doc/user/admin_area/diff_limits.md index 4be1ace10aa..b50748ca97e 100644 --- a/doc/user/admin_area/diff_limits.md +++ b/doc/user/admin_area/diff_limits.md @@ -33,8 +33,8 @@ set values are presented as **Too large** are cannot be expanded in the UI. To configure these values: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand **Diff limits**. 1. Enter a value for the diff limit. 1. Select **Save changes**. diff --git a/doc/user/admin_area/geo_nodes.md b/doc/user/admin_area/geo_nodes.md index 861d3644ab3..a2354e68d72 100644 --- a/doc/user/admin_area/geo_nodes.md +++ b/doc/user/admin_area/geo_nodes.md @@ -12,7 +12,7 @@ You can configure various settings for GitLab Geo sites. For more information, s On either the primary or secondary site: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Nodes**. ## Common settings @@ -65,7 +65,7 @@ which is used by users. Internal URL does not need to be a private address. Internal URL defaults to external URL, but you can also customize it: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Nodes**. 1. Select **Edit** on the site you want to customize. 1. Edit the internal URL. diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index 35afb9f376b..a5c3a2a7aeb 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -12,7 +12,7 @@ self-managed instances. If you are an Admin user, you can access the Admin Area by visiting `/admin` on your self-managed instance. You can also access it through the UI: -- GitLab versions 14.0 and later: on the top bar, select **Menu >** **{admin}** **Admin**. +- GitLab versions 14.0 and later: on the top bar, select **Menu > Admin**. - GitLab versions 13.12 and earlier: on the top bar, select the Admin Area icon (**{admin}**). NOTE: @@ -47,7 +47,7 @@ The Dashboard provides statistics and system information about the GitLab instan To access the Dashboard, either: -- On the top bar, select **Menu >** **{admin}** **Admin**. +- On the top bar, select **Menu > Admin**. - Visit `/admin` on your self-managed instance. The Dashboard is the default view of the Admin Area, and is made up of the following sections: @@ -71,8 +71,8 @@ You can administer all projects in the GitLab instance from the Admin Area's Pro To access the Projects page: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Overview > Projects**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Overview > Projects**. 1. Select the **All**, **Private**, **Internal**, or **Public** tab to list only projects of that criteria. @@ -111,8 +111,8 @@ You can combine the filter options. For example, to list only public projects wi You can administer all users in the GitLab instance from the Admin Area's Users page: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Overview > Users**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Overview > Users**. To list users matching a specific criteria, click on one of the following tabs on the **Users** page: @@ -156,8 +156,8 @@ This allows the administrator to "see what the user sees," and take actions on b You can impersonate a user in the following ways: - Through the UI: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. - 1. In the left sidebar, select **Overview > Users**. + 1. On the top bar, select **Menu > Admin**. + 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). @@ -199,6 +199,18 @@ The following totals are also included: GitLab billing is based on the number of [**Billable users**](../../subscriptions/self_managed/index.md#billable-users). +#### Add email to user + +You must be an administrator to manually add emails to users: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Overview > Users** (`/admin/users`). +1. Locate the user and select them. +1. Select **Edit**. +1. In **Email**, enter the new email address. This adds the new email address to the + user and sets the previous email address to be a secondary. +1. Select **Save changes**. + ### User cohorts The [Cohorts](user_cohorts.md) tab displays the monthly cohorts of new users and their activities over time. @@ -209,8 +221,8 @@ You can administer all groups in the GitLab instance from the Admin Area's Group To access the Groups page: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Overview > Groups**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Overview > Groups**. For each group, the page displays their name, description, size, number of projects in the group, number of members, and whether the group is private, internal, or public. To edit a group, click @@ -231,8 +243,8 @@ You can administer all jobs in the GitLab instance from the Admin Area's Jobs pa To access the Jobs page: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Overview > Jobs**. All jobs are listed, in descending order of job ID. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Overview > Jobs**. All jobs are listed, in descending order of job ID. 1. Click the **All** tab to list all jobs. Click the **Pending**, **Running**, or **Finished** tab to list only jobs of that status. @@ -257,8 +269,8 @@ You can administer all runners in the GitLab instance from the Admin Area's **Ru To access the **Runners** page: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Overview > Runners**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Overview > Runners**. The **Runners** page features: @@ -307,8 +319,8 @@ page. For more details, see [Gitaly](../../administration/gitaly/index.md). To access the **Gitaly Servers** page: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Overview > Gitaly Servers**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Overview > Gitaly Servers**. For each Gitaly server, the following details are listed: diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md index 0431b0d1628..4e97cb8e49c 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -116,7 +116,7 @@ before this occurs. To remove a license file from a self-managed instance: 1. From the top menu, select the Admin Area **{admin}**. -1. From the left sidebar, select **Subscription** +1. From the left sidebar, select **Subscription**. 1. Select **Remove license**. These steps may need to be repeated to completely remove all licenses, including those applied in the past. @@ -124,8 +124,10 @@ These steps may need to be repeated to completely remove all licenses, including ## License history You can upload and view more than one license, but only the latest license in the current date -range is used as the active license. When you upload a future-dated license, it -doesn't take effect until its applicable date. +range is used as the active license. + +When you upload a future-dated license, it doesn't take effect until its applicable date. +You can view all of your active subscriptions in the **Subscription history** table. NOTE: In GitLab 13.6 and earlier, a notification banner about an expiring license may continue to be displayed even after a new license has been uploaded. @@ -165,7 +167,7 @@ your license. However, if you have 111, you must purchase more users before you ### There is a connectivity issue -In GitLab 14.1 and later, to activate your subscription, your GitLab instance must be connected to the internet. +In GitLab 14.1 and later, to activate your subscription, your GitLab instance must be connected to the internet. If you have an offline or airgapped environment, you can [upload a license file](license.md#activate-gitlab-ee-with-a-license-file) instead. diff --git a/doc/user/admin_area/merge_requests_approvals.md b/doc/user/admin_area/merge_requests_approvals.md index 4f6419cdeb7..ffa08dee10d 100644 --- a/doc/user/admin_area/merge_requests_approvals.md +++ b/doc/user/admin_area/merge_requests_approvals.md @@ -15,8 +15,8 @@ project level. To enable merge request approval rules for an instance: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **{push-rules}** **Push Rules**, and expand **Merge request (MR) approvals**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **{push-rules}** **Push Rules**, and expand **Merge request (MR) approvals**. 1. Set the required rule. 1. Click **Save changes**. diff --git a/doc/user/admin_area/moderate_users.md b/doc/user/admin_area/moderate_users.md index 8211167895c..2655d927b87 100644 --- a/doc/user/admin_area/moderate_users.md +++ b/doc/user/admin_area/moderate_users.md @@ -13,11 +13,12 @@ users. ## Users pending approval A user in _pending approval_ state requires action by an administrator. A user sign up can be in a -pending approval state because an administrator has enabled either, or both, of the following -options: +pending approval state because an administrator has enabled any of the following options: - [Require admin 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#initial-omniauth-configuration) +- [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: @@ -39,7 +40,7 @@ sign in. To view user sign ups pending approval: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Select the **Pending approval** tab. @@ -49,7 +50,7 @@ A user sign up pending approval can be approved or rejected from the Admin Area. To approve or reject a user sign up: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Select the **Pending approval** tab. 1. (Optional) Select a user. @@ -74,7 +75,7 @@ administrators can choose to block the user. Users can be blocked [via an abuse report](review_abuse_reports.md#blocking-users), or directly from the Admin Area. To do this: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. (Optional) Select a user. 1. Select the **{settings}** **User administration** dropdown. @@ -97,7 +98,7 @@ Users can also be blocked using the [GitLab API](../../api/users.md#block-user). A blocked user can be unblocked from the Admin Area. To do this: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Select on the **Blocked** tab. 1. (Optional) Select a user. @@ -136,15 +137,19 @@ A deactivated user: Personal projects, and group and user history of the deactivated user are left intact. +NOTE: +Users are notified about account deactivation if +[user deactivation emails](settings/email.md#user-deactivation-emails) are enabled. + A user can be deactivated from the Admin Area. To do this: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. (Optional) Select a user. 1. Select the **{settings}** **User administration** dropdown. 1. Select **Deactivate**. -For the deactivation option to be visible to an admin, the user: +For the deactivation option to be visible to an administrator, the user: - Must be currently active. - Must not have signed in, or have any activity, in the last 90 days. @@ -159,7 +164,7 @@ Users can also be deactivated using the [GitLab API](../../api/users.md#deactiva Administrators can enable automatic deactivation of users who have not signed in, or have no activity in the last 90 days. To do this: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Account and limit** section. 1. Under **Dormant users**, check **Deactivate dormant users after 90 days of inactivity**. @@ -177,7 +182,7 @@ A deactivated user can be activated from the Admin Area. To do this: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Select the **Deactivated** tab. 1. (Optional) Select a user. @@ -193,9 +198,9 @@ Users can also be activated using the [GitLab API](../../api/users.md#activate-u ## Ban and unban users -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327353) in GitLab 14.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327353) in GitLab 14.2. -GitLab administrators can ban and unban users. Banned users are blocked, and their issues are hidden. +GitLab administrators can ban and unban users. Banned users are blocked, and their issues are hidden. The banned user's comments are still displayed. Hiding a banned user's comments is [tracked in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/327356). ### Ban a user @@ -204,7 +209,7 @@ To block a user and hide their contributions, administrators can ban the user. Users can be banned using the Admin Area. To do this: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. (Optional) Select a user. 1. Select the **{settings}** **User administration** dropdown. @@ -216,7 +221,7 @@ The banned user does not consume a [seat](../../subscriptions/self_managed/index A banned user can be unbanned using the Admin Area. To do this: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Select the **Banned** tab. 1. (Optional) Select a user. diff --git a/doc/user/admin_area/monitoring/health_check.md b/doc/user/admin_area/monitoring/health_check.md index a3e46ea6225..c5ffb032afd 100644 --- a/doc/user/admin_area/monitoring/health_check.md +++ b/doc/user/admin_area/monitoring/health_check.md @@ -146,8 +146,8 @@ Access token has been deprecated in GitLab 9.4 in favor of [IP whitelist](#ip-wh An access token needs to be provided while accessing the probe endpoints. You can find the current accepted token in the user interface: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Monitoring > Health Check**. (`admin/health_check`) +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Monitoring > Health Check**. (`admin/health_check`)  diff --git a/doc/user/admin_area/review_abuse_reports.md b/doc/user/admin_area/review_abuse_reports.md index 7816d0648b2..6494934c34d 100644 --- a/doc/user/admin_area/review_abuse_reports.md +++ b/doc/user/admin_area/review_abuse_reports.md @@ -16,7 +16,7 @@ reports in the Admin Area. To receive notifications of new abuse reports by email, follow these steps: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Reporting**. 1. Expand the **Abuse reports** section. 1. Provide an email address. @@ -33,7 +33,7 @@ documentation](../report_abuse.md). To access abuse reports: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Abuse Reports**. There are 3 ways to resolve an abuse report, with a button for each method: 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 71e05f44ef0..3549aa5323b 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -11,8 +11,8 @@ type: reference You can change the default maximum number of projects that users can create in their personal namespace: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**, then expand **Account and limit**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**, then expand **Account and limit**. 1. Increase or decrease that **Default projects limit** value. If you set **Default projects limit** to 0, users are not allowed to create projects @@ -22,8 +22,8 @@ in their users personal namespace. However, projects can still be created in a g You can change the maximum file size for attachments in comments and replies in GitLab: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**, then expand **Account and limit**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**, then expand **Account and limit**. 1. Increase or decrease by changing the value in **Maximum attachment size (MB)**. NOTE: @@ -35,8 +35,8 @@ details. You can change the maximum push size for your repository: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**, then expand **Account and limit**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**, then expand **Account and limit**. 1. Increase or decrease by changing the value in **Maximum push size (MB)**. NOTE: @@ -50,8 +50,8 @@ Use [Git LFS](../../../topics/git/lfs/index.md) to add large files to a reposito You can change the maximum file size for imports in GitLab: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**, then expand **Account and limit**. +1. On the top bar, select **Menu > Admin**. +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)**. NOTE: @@ -70,8 +70,8 @@ A prefix can help you identify PATs visually, as well as with automation tools. Only a GitLab administrator can set the prefix, which is a global setting applied to any PAT generated in the system by any user: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Account and limit** section. 1. Fill in the **Personal Access Token prefix** field. 1. Click **Save changes**. @@ -113,8 +113,8 @@ These settings can be found in: 1. Fill in the **Repository size limit (MB)** field in the **Naming, visibility** section. 1. Click **Save changes**. - GitLab global settings: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. - 1. In the left sidebar, select **Settings > General**. + 1. On the top bar, select **Menu > Admin**. + 1. On the left sidebar, select **Settings > General**. 1. Expand the **Account and limit** section. 1. Fill in the **Size limit per repository (MB)** field. 1. Click **Save changes**. @@ -154,19 +154,19 @@ nginx['client_max_body_size'] = "200m" > - It's deployed behind a feature flag, disabled by default. > - It's disabled on GitLab.com. > - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](../../../security/two_factor_authentication.md#enable-or-disable-two-factor-authentication-2fa-for-git-operations). +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](../../../security/two_factor_authentication.md#enable-or-disable-2fa-for-git-operations). NOTE: This feature is under development and not ready for production use. It is deployed behind a feature flag that is **disabled by default**. To use it in GitLab -self-managed instances, ask a GitLab administrator to [enable it](../../../security/two_factor_authentication.md#enable-or-disable-two-factor-authentication-2fa-for-git-operations). +self-managed instances, ask a GitLab administrator to [enable it](../../../security/two_factor_authentication.md#enable-or-disable-2fa-for-git-operations). GitLab administrators can choose to customize the session duration (in minutes) for Git operations when 2FA is enabled. The default is 15 and this can be set to a value between 1 and 10080. To set a limit on how long these sessions are valid: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Account and limit** section. 1. Fill in the **Session duration for Git operations when 2FA is enabled (minutes)** field. 1. Click **Save changes**. @@ -190,8 +190,8 @@ there are no restrictions. To set a lifetime on how long personal access tokens are valid: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Account and limit** section. 1. Fill in the **Maximum allowable lifetime for personal access tokens (days)** field. 1. Click **Save changes**. @@ -213,8 +213,8 @@ By default, expired SSH keys **are not usable**. To allow the use of expired SSH keys: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Account and limit** section. 1. Uncheck the **Enforce SSH key expiration** checkbox. @@ -229,8 +229,8 @@ By default, expired personal access tokens (PATs) **are not usable**. To allow the use of expired PATs: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Account and limit** section. 1. Uncheck the **Enforce personal access token expiration** checkbox. @@ -242,8 +242,8 @@ To maintain integrity of user details in [Audit Events](../../../administration/ To do this: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**, then expand **Account and limit**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**, then expand **Account and limit**. 1. Select the **Prevent users from changing their profile name** checkbox. NOTE: diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index 3b56318e711..178b117d06c 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -15,7 +15,7 @@ job artifacts. To enable (or disable) [Auto DevOps](../../../topics/autodevops/index.md) for all projects: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Check (or uncheck to disable) the box that says **Default to Auto DevOps pipeline for all projects**. 1. Optionally, set up the [Auto DevOps base domain](../../../topics/autodevops/requirements.md#auto-devops-base-domain) @@ -33,7 +33,7 @@ If you want to disable it for a specific project, you can do so in To display details about the instance's shared runners in all projects' runner settings: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **Continuous Integration and Deployment**. 1. Enter your shared runner details in the **Shared runner details** field. @@ -64,7 +64,7 @@ To change it at the: - Instance level: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Change the value of maximum artifacts size (in MB). 1. Click **Save changes** for the changes to take effect. @@ -91,7 +91,7 @@ can be set in the Admin Area of your GitLab instance. The syntax of duration is described in [`artifacts:expire_in`](../../../ci/yaml/index.md#artifactsexpire_in) and the default value is `30 days`. -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Change the value of default expiration time. 1. Click **Save changes** for the changes to take effect. @@ -122,7 +122,7 @@ If disabled at the instance level, you cannot enable this per-project. To disable the setting: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **Continuous Integration and Deployment**. 1. Clear the **Keep the latest artifacts for all jobs in the latest successful pipelines** checkbox. @@ -148,7 +148,7 @@ On GitLab.com, the quota is calculated based on your To change the pipelines minutes quota: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **Continuous Integration and Deployment**. 1. In the **Pipeline minutes quota** box, enter the maximum number of minutes. @@ -181,7 +181,7 @@ but persisting the traces and artifacts for auditing purposes. To set the duration for which the jobs are considered as old and expired: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand the **Continuous Integration and Deployment** section. 1. Set the value of **Archive jobs**. @@ -198,7 +198,7 @@ As of June 22, 2020 the [value is set](../../gitlab_com/index.md#gitlab-cicd) to To set all new [CI/CD variables](../../../ci/variables/index.md) as [protected](../../../ci/variables/index.md#protect-a-cicd-variable) by default: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Select **Protect CI/CD variables by default**. @@ -209,7 +209,7 @@ To set all new [CI/CD variables](../../../ci/variables/index.md) as The default CI/CD configuration file and path for new projects can be set in the Admin Area of your GitLab instance (`.gitlab-ci.yml` if not set): -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Input the new file and path in the **Default CI/CD configuration file** field. 1. Hit **Save changes** for the changes to take effect. @@ -245,7 +245,7 @@ in the pipeline editor. To select a CI/CD template for the required pipeline configuration: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand the **Required pipeline configuration** section. 1. Select a CI/CD template from the dropdown. @@ -259,7 +259,7 @@ GitLab administrators can disable the forwarding of npm requests to [npmjs.com]( To disable it: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand the **Package Registry** section. 1. Clear the checkbox **Forward npm package requests to the npm Registry if the packages are not found in the GitLab Package Registry**. @@ -271,7 +271,7 @@ GitLab administrators can disable the forwarding of PyPI requests to [pypi.org]( To disable it: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand the **Package Registry** section. 1. Clear the checkbox **Forward PyPI package requests to the PyPI Registry if the packages are not found in the GitLab Package Registry**. @@ -283,7 +283,7 @@ GitLab administrators can adjust the maximum allowed file size for each package To set the maximum file size: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand the **Package Registry** section. 1. Find the package type you would like to adjust. @@ -304,7 +304,7 @@ By default, all members of a project and group are able to register runners. To change this: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. Go to **Settings > CI/CD**. 1. Expand the **Runner registration** section. 1. Select the desired options. diff --git a/doc/user/admin_area/settings/email.md b/doc/user/admin_area/settings/email.md index 236b75797a2..c04a9a12912 100644 --- a/doc/user/admin_area/settings/email.md +++ b/doc/user/admin_area/settings/email.md @@ -21,7 +21,7 @@ address in the body of the email instead. To include the author's email address in the email body: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences** (`/admin/application_settings/preferences`). 1. Expand **Email**. 1. Select the **Include author name in email notification email body** checkbox. @@ -33,7 +33,7 @@ GitLab can send email in multipart format (HTML and plain text) or plain text on To enable multipart email: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences** (`/admin/application_settings/preferences`). 1. Expand **Email**. 1. Select **Enable multipart email**. @@ -48,7 +48,7 @@ This configuration option sets the email hostname for [private commit emails](.. To change the hostname used in private commit emails: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences** (`/admin/application_settings/preferences`). 1. Expand **Email**. 1. Enter the desired hostname in the **Custom hostname (for private commit emails)** field. @@ -66,12 +66,24 @@ can be used for legal, auditing, or compliance reasons, for example. To add additional text to emails: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **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** field. 1. Select **Save changes**. +## User deactivation emails **(FREE SELF)** + +GitLab sends email notifications to users when their account has been deactivated. + +To disable these notifications: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Preferences** (`/admin/application_settings/preferences`). +1. Expand **Email**. +1. Clear the **Enable user deactivation emails** checkbox. +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 205dd77c1bf..985f3c133d5 100644 --- a/doc/user/admin_area/settings/external_authorization.md +++ b/doc/user/admin_area/settings/external_authorization.md @@ -41,8 +41,8 @@ the [Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/logs The external authorization service can be enabled by an administrator: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**: +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**:  The available required properties are: diff --git a/doc/user/admin_area/settings/floc.md b/doc/user/admin_area/settings/floc.md index 0e9d4e5d0c1..17c390aef0e 100644 --- a/doc/user/admin_area/settings/floc.md +++ b/doc/user/admin_area/settings/floc.md @@ -22,8 +22,8 @@ Permissions-Policy: interest-cohort=() To enable it: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand **Federated Learning of Cohorts**. 1. Check the box. 1. Click **Save changes**. diff --git a/doc/user/admin_area/settings/git_lfs_rate_limits.md b/doc/user/admin_area/settings/git_lfs_rate_limits.md new file mode 100644 index 00000000000..8a0754374e2 --- /dev/null +++ b/doc/user/admin_area/settings/git_lfs_rate_limits.md @@ -0,0 +1,35 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: reference +--- + +# Git LFS Rate Limits **(FREE SELF)** + +[Git LFS (Large File Storage)](../../../topics/git/lfs/index.md) is a Git extension +for handling large files. If you use Git LFS in your repository, common Git operations +can generate many Git LFS requests. You can enforce +[general user and IP rate limits](user_and_ip_rate_limits.md), but you can also +override the general setting to enforce additional limits on Git LFS requests. This +override can improve the security and durability of your web application. Aside from +precedence, this configuration provides the same features as the general user and IP +rate limits. + +## Configure Git LFS rate limits + +Git LFS rate limits are disabled by default. If enabled and configured, these limits +supersede the [general user and IP rate limits](user_and_ip_rate_limits.md): + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Settings > Network**. +1. Expand **Git LFS Rate Limits**. +1. Select **Enable authenticated Git LFS request rate limit**. +1. Enter a value for **Max authenticated Git LFS requests per period per user**. +1. Enter a value for **Authenticated Git LFS rate limit period in seconds**. +1. Select **Save changes**. + +## Resources + +- [Rate limiting](../../../security/rate_limits.md) +- [User and IP rate limits](user_and_ip_rate_limits.md) diff --git a/doc/user/admin_area/settings/gitaly_timeouts.md b/doc/user/admin_area/settings/gitaly_timeouts.md index 04887906c91..1d4f45d1f04 100644 --- a/doc/user/admin_area/settings/gitaly_timeouts.md +++ b/doc/user/admin_area/settings/gitaly_timeouts.md @@ -12,7 +12,7 @@ configured to make sure that long-running Gitaly calls don't needlessly take up To access Gitaly timeout settings: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences**. 1. Expand the **Gitaly timeouts** section. diff --git a/doc/user/admin_area/settings/help_page.md b/doc/user/admin_area/settings/help_page.md index 01516430f4f..cf08b9b71db 100644 --- a/doc/user/admin_area/settings/help_page.md +++ b/doc/user/admin_area/settings/help_page.md @@ -16,7 +16,7 @@ the GitLab sign-in page. You can add a help message, which is shown at the top of the GitLab `/help` page (for example, <https://gitlab.com/help>): -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences**. 1. Expand **Sign-in and Help page**. 1. In **Additional text to show on the Help page**, enter the information you want to display on `/help`. @@ -34,7 +34,7 @@ is restricted, `/help` is visible only to signed-in users. You can add a help message, which is shown on the GitLab sign-in page. The message appears in a new section titled **Need Help?**, located below the sign-in page message: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences**. 1. Expand **Sign-in and Help page**. 1. In **Additional text to show on the sign-in page**, enter the information you want to @@ -47,7 +47,7 @@ You can now see the message on the sign-in page. GitLab marketing-related entries are occasionally shown on the Help page. To hide these entries: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences**. 1. Expand **Sign-in and Help page**. 1. Select the **Hide marketing-related entries from the Help page** checkbox. @@ -60,7 +60,7 @@ You can specify a custom URL to which users are directed when they: - Select **Support** from the Help dropdown. - Select **See our website for help** on the Help page. -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences**. 1. Expand **Sign-in and Help page**. 1. In the **Support page URL** field, enter the URL. @@ -68,8 +68,7 @@ You can specify a custom URL to which users are directed when they: ## Redirect `/help` pages -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/43157) in GitLab 13.5. -> - Enabled on GitLab.com and is ready for production use. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/43157) in GitLab 13.5. FLAG: On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to @@ -85,8 +84,8 @@ You can redirect these `/help` links to either: - The more navigable and searchable version published at [`docs.gitlab.com`](https://docs.gitlab.com). - A destination that meets [necessary requirements](#destination-requirements). -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Preferences**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Preferences**. 1. Expand **Sign-in and Help page**. 1. In the **Documentation pages URL** field, enter the URL. 1. Select **Save changes**. diff --git a/doc/user/admin_area/settings/img/domain_denylist_v14_1.png b/doc/user/admin_area/settings/img/domain_denylist_v14_1.png Binary files differindex c988afd75f6..e27997fc2c2 100644 --- a/doc/user/admin_area/settings/img/domain_denylist_v14_1.png +++ b/doc/user/admin_area/settings/img/domain_denylist_v14_1.png diff --git a/doc/user/admin_area/settings/img/import_export_rate_limits_v13_2.png b/doc/user/admin_area/settings/img/import_export_rate_limits_v13_2.png Binary files differdeleted file mode 100644 index 76015ce0ee3..00000000000 --- a/doc/user/admin_area/settings/img/import_export_rate_limits_v13_2.png +++ /dev/null diff --git a/doc/user/admin_area/settings/img/rate_limit_on_issues_creation_v14_2.png b/doc/user/admin_area/settings/img/rate_limit_on_issues_creation_v14_2.png Binary files differindex 63f4d5a4a1a..1a0a7548a91 100644 --- a/doc/user/admin_area/settings/img/rate_limit_on_issues_creation_v14_2.png +++ b/doc/user/admin_area/settings/img/rate_limit_on_issues_creation_v14_2.png diff --git a/doc/user/admin_area/settings/img/user_and_ip_rate_limits.png b/doc/user/admin_area/settings/img/user_and_ip_rate_limits.png Binary files differdeleted file mode 100644 index 5056e8354a9..00000000000 --- a/doc/user/admin_area/settings/img/user_and_ip_rate_limits.png +++ /dev/null diff --git a/doc/user/admin_area/settings/import_export_rate_limits.md b/doc/user/admin_area/settings/import_export_rate_limits.md index 12235bdb5ef..7d5a928eedf 100644 --- a/doc/user/admin_area/settings/import_export_rate_limits.md +++ b/doc/user/admin_area/settings/import_export_rate_limits.md @@ -5,28 +5,26 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Project/group import/export rate limits **(FREE SELF)** +# Rate limits for imports and exports of project and groups **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35728) in GitLab 13.2. -The following table includes configurable rate limits. The following table includes limits on a -per minute per user basis: +You can configure the rate limits for imports and exports of projects and groups: -| Limit | Default (per minute per user) | -|--------------------------|-------------------------------| -| Project Import | 6 | -| Project Export | 6 | -| Project Export Download | 1 | -| Group Import | 6 | -| Group Export | 6 | -| Group Export Download | 1 | +To change a rate limit: -All rate limits are: +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Network**, then expand **Import and export rate limits**. +1. Change the value of any rate limit. The rate limits are per minute per user, not per IP address. + Set to `0` to disable a rate limit. -- Configurable through the top bar at **Menu > Admin > Settings > Network > Import/Export Rate Limits** -- Applied per minute per user -- Not applied per IP address -- Active by default. To disable, set the option to `0` -- Logged to `auth.log` file if exceed rate limit +| Limit | Default | +|-------------------------|---------| +| Project Import | 6 | +| Project Export | 6 | +| Project Export Download | 1 | +| Group Import | 6 | +| Group Export | 6 | +| Group Export Download | 1 | - +When a user exceeds a rate limit, it is logged in `auth.log`. diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index 21ca1c573fe..ec5f3ca812f 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -17,8 +17,8 @@ documentation for all current settings and limits on the GitLab.com instance. To access the default page for Admin Area settings: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. | Option | Description | | ------ | ----------- | @@ -37,8 +37,9 @@ To access the default page for Admin Area settings: | Option | Description | | ------ | ----------- | -| [Elasticsearch](../../../integration/elasticsearch.md#enabling-advanced-search) | Elasticsearch integration. Elasticsearch AWS IAM. | +| [Elasticsearch](../../../integration/elasticsearch.md#enable-advanced-search) | Elasticsearch integration. Elasticsearch AWS IAM. | | [Kroki](../../../administration/integration/kroki.md#enable-kroki-in-gitlab) | Allow rendering of diagrams in AsciiDoc and Markdown documents using [kroki.io](https://kroki.io). | +| [Mailgun](../../../administration/integration/mailgun.md) | Enable your GitLab instance 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) **(FREE SAAS)** | 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). | | [Third party offers](third_party_offers.md) | Control the display of third party offers. | @@ -96,9 +97,10 @@ To access the default page for Admin Area settings: | Performance optimization | [Write to "authorized_keys" file](../../../administration/operations/fast_ssh_key_lookup.md#setting-up-fast-lookup-via-gitlab-shell) and [Push event activities limit and bulk push events](push_event_activities_limit.md). Various settings that affect GitLab performance. | | [User and IP rate limits](user_and_ip_rate_limits.md) | Configure limits for web and API requests. | | [Package Registry Rate Limits](package_registry_rate_limits.md) | Configure specific limits for Packages API requests that supersede the user and IP rate limits. | +| [Git LFS Rate Limits](git_lfs_rate_limits.md) | Configure specific limits for Git LFS requests that supersede the user and IP rate limits. | | [Outbound requests](../../../security/webhooks.md) | Allow requests to the local network from hooks and services. | | [Protected Paths](protected_paths.md) | Configure paths to be protected by Rack Attack. | -| [Incident Management](../../../operations/incident_management/index.md) Limits | Configure limits on the number of inbound alerts able to be sent to a project. | +| [Incident Management](../../../operations/incident_management/index.md) Limits | Limit the number of inbound alerts that can be sent to a project. | | [Notes creation limit](rate_limit_on_notes_creation.md)| Set a rate limit on the note creation requests. | ## Geo @@ -118,12 +120,13 @@ To access the default page for Admin Area settings: | [Polling interval multiplier](../../../administration/polling.md) | Configure how frequently the GitLab UI polls for updates. | | [Gitaly timeouts](gitaly_timeouts.md) | Configure Gitaly timeouts. | | Localization | [Default first day of the week](../../profile/preferences.md) and [Time tracking](../../project/time_tracking.md#limit-displayed-units-to-hours). | +| [Sidekiq Job Limits](sidekiq_job_limits.md) | Limit the size of Sidekiq jobs stored in Redis. | ### Default first day of the week You can change the [Default first day of the week](../../profile/preferences.md) for the entire GitLab instance: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Preferences**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Preferences**. 1. Scroll to the **Localization** section, and select your desired first day of the week. diff --git a/doc/user/admin_area/settings/instance_template_repository.md b/doc/user/admin_area/settings/instance_template_repository.md index 8a796435ef8..862bf3b1652 100644 --- a/doc/user/admin_area/settings/instance_template_repository.md +++ b/doc/user/admin_area/settings/instance_template_repository.md @@ -7,7 +7,7 @@ type: reference # Instance template repository **(PREMIUM SELF)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5986) in GitLab Premium 11.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5986) in GitLab Premium 11.3. In hosted systems, enterprises often have a need to share their own templates across teams. This feature allows an administrator to pick a project to be the @@ -19,8 +19,8 @@ while the project remains secure. To select a project to serve as the custom template repository: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Templates**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Templates**. 1. Select the project:  diff --git a/doc/user/admin_area/settings/package_registry_rate_limits.md b/doc/user/admin_area/settings/package_registry_rate_limits.md index 6e7b9b0da30..1aeb011d880 100644 --- a/doc/user/admin_area/settings/package_registry_rate_limits.md +++ b/doc/user/admin_area/settings/package_registry_rate_limits.md @@ -7,28 +7,47 @@ type: reference # Package Registry Rate Limits **(FREE SELF)** -Rate limiting is a common technique used to improve the security and durability of a web -application. For more details, see [Rate limits](../../../security/rate_limits.md). General user and -IP rate limits can be enforced from the top bar at -**Menu > Admin > Settings > Network > User and IP rate limits**. -For more details, see [User and IP rate limits](user_and_ip_rate_limits.md). - With the [GitLab Package Registry](../../packages/package_registry/index.md), you can use GitLab as a private or public registry for a variety of common package managers. You can publish and share packages, which others can consume as a dependency in downstream projects through the [Packages API](../../../api/packages.md). -When downloading such dependencies in downstream projects, many requests are made through the -Packages API. You may therefore reach enforced user and IP rate limits. To address this issue, you -can define specific rate limits for the Packages API in -**Menu > Admin > Settings > Network > Package Registry Rate Limits**: +If downstream projects frequently download such dependencies, many requests are made through the +Packages API. You may therefore reach enforced [user and IP rate limits](user_and_ip_rate_limits.md). +To address this issue, you can define specific rate limits for the Packages API: + +- [Unauthenticated requests (per IP)](#enable-unauthenticated-request-rate-limit-for-packages-api). +- [Authenticated API requests (per user)](#enable-authenticated-api-request-rate-limit-for-packages-api). + +These limits are disabled by default. + +When enabled, they supersede the general user and IP rate limits for requests to +the Packages API. You can therefore keep the general user and IP rate limits, and +increase the rate limits for the Packages API. Besides this precedence, there is +no difference in functionality compared to the general user and IP rate limits. + +## Enable unauthenticated request rate limit for packages API + +To enable the unauthenticated request rate limit: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Network**, and expand **Package registry rate limits**. +1. Select **Enable unauthenticated request rate limit**. + + - Optional. Update the **Maximum unauthenticated requests per rate limit period per IP** value. + Defaults to `800`. + - Optional. Update the **Unauthenticated rate limit period in seconds** value. + Defaults to `15`. + +## Enable authenticated API request rate limit for packages API -- Unauthenticated Packages API requests -- Authenticated Packages API requests +To enable the authenticated API request rate limit: -These limits are disabled by default. When enabled, they supersede the general user and IP rate -limits for requests to the Packages API. You can therefore keep the general user and IP rate limits, -and increase (if necessary) the rate limits for the Packages API. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Network**, and expand **Package registry rate limits**. +1. Select **Enable authenticated API request rate limit**. -Besides this precedence, there are no differences in functionality compared to the general user and -IP rate limits. For more details, see [User and IP rate limits](user_and_ip_rate_limits.md). + - Optional. Update the **Maximum authenticated API requests per rate limit period per user** value. + Defaults to `1000`. + - Optional. Update the **Authenticated API rate limit period in seconds** value. + Defaults to `15`. diff --git a/doc/user/admin_area/settings/project_integration_management.md b/doc/user/admin_area/settings/project_integration_management.md index 3b949b638d8..aadabe4d6ad 100644 --- a/doc/user/admin_area/settings/project_integration_management.md +++ b/doc/user/admin_area/settings/project_integration_management.md @@ -22,8 +22,8 @@ Only the complete settings for an integration can be inherited. Per-field inheri > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2137) in GitLab 13.3 for project-level integrations. > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2543) in GitLab 13.6 for group-level integrations. -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Integrations**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Integrations**. 1. Select an integration. 1. Enter configuration details and click **Save changes**. @@ -54,8 +54,8 @@ integration on all non-configured groups and projects by default. ### Remove an instance-level default setting -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Integrations**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Integrations**. 1. Select an integration. 1. Click **Reset** and confirm. @@ -68,8 +68,8 @@ Resetting an instance-level default setting removes the integration from all pro You can view which projects in your instance use custom settings that [override the instance-level default settings](#use-custom-settings-for-a-group-or-project-integration) for an integration. -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Integrations**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Integrations**. 1. Select an integration. 1. Select the **Projects using custom settings** tab. diff --git a/doc/user/admin_area/settings/push_event_activities_limit.md b/doc/user/admin_area/settings/push_event_activities_limit.md index 21e4f32ff8d..760ce96d987 100644 --- a/doc/user/admin_area/settings/push_event_activities_limit.md +++ b/doc/user/admin_area/settings/push_event_activities_limit.md @@ -26,8 +26,8 @@ the activity feed. To modify this setting: - In the Admin Area: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. - 1. In the left sidebar, select **Settings > Network**, then expand **Performance optimization**. + 1. On the top bar, select **Menu > Admin**. + 1. On the left sidebar, select **Settings > Network**, then expand **Performance optimization**. - Through the [Application settings API](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls) as `push_event_activities_limit`. 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 bba61a7b913..a2e8a875ebb 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 @@ -12,7 +12,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w This setting allows you to rate limit the requests to the issue and epic creation endpoints. To can change its value: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Network**. 1. Expand **Issues Rate Limits**. 1. Under **Max requests per minute per user**, enter the new value. diff --git a/doc/user/admin_area/settings/rate_limit_on_notes_creation.md b/doc/user/admin_area/settings/rate_limit_on_notes_creation.md index 7615ad6f81d..0a07cf095ee 100644 --- a/doc/user/admin_area/settings/rate_limit_on_notes_creation.md +++ b/doc/user/admin_area/settings/rate_limit_on_notes_creation.md @@ -9,15 +9,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53637) in GitLab 13.9. -This setting allows you to rate limit the requests to the note creation endpoint. +You can configure the per-user rate limit for requests to the note creation endpoint. To change the note creation rate limit: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Network**. -1. Expand **Notes Rate Limits**. -1. Under **Max requests per minute per user**, enter the new value. -1. Optional. Under **List of users to be excluded from the limit**, list users to be excluded from the limit. +1. Expand **Notes rate limit**. +1. In the **Maximum requests per minute** box, enter the new value. +1. Optional. In the **Users to exclude from the rate limit** box, list users allowed to exceed the limit. 1. Select **Save changes**. This limit is: diff --git a/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md b/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md index 24b69ba74c7..020d02b1635 100644 --- a/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md +++ b/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md @@ -11,8 +11,8 @@ type: reference This setting defaults to `300` requests per minute, and allows you to rate limit the requests to raw endpoints: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Network**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Network**. 1. Expand **Performance optimization**. For example, requests over `300` per minute to `https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/controllers/application_controller.rb` are blocked. Access to the raw file is released after 1 minute. diff --git a/doc/user/admin_area/settings/sidekiq_job_limits.md b/doc/user/admin_area/settings/sidekiq_job_limits.md new file mode 100644 index 00000000000..c6a783beb3f --- /dev/null +++ b/doc/user/admin_area/settings/sidekiq_job_limits.md @@ -0,0 +1,36 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: reference +--- + +# Sidekiq job size limits **(FREE SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68982) in GitLab 14.3. + +[Sidekiq](../../../administration/sidekiq.md) jobs get stored in +Redis. To avoid excessive memory for Redis, we: + +- Compress job arguments before storing them in Redis. +arguments before storing them in Redis, and rejecting jobs that exceed +- Reject jobs that exceed the specified threshold limit after compression. + +To access Sidekiq job size limits: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Settings > Preferences**. +1. Expand **Sidekiq job size limits**. +1. Adjust the compression threshold or size limit. The compression can + be disabled by selecting the **Track** mode. + +## Available settings + +| Setting | Default | Description | +|-------------------------------------------|------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Limiting mode | Compress | This mode compresses the jobs at the specified threshold and rejects them if they exceed the specified limit after compression. | +| Sidekiq job compression threshold (bytes) | 100 000 (100 KB) | When the size of arguments exceeds this threshold, they are compressed before being stored in Redis. | +| Sidekiq job size limit (bytes) | 0 | The jobs exceeding this size after compression are rejected. This avoids excessive memory usage in Redis leading to instability. Setting it to 0 prevents rejecting jobs. | + +After changing these values, [restart +Sidekiq](../../../administration/restart_gitlab.md). diff --git a/doc/user/admin_area/settings/sign_in_restrictions.md b/doc/user/admin_area/settings/sign_in_restrictions.md index 333e9465c31..223ffeebd44 100644 --- a/doc/user/admin_area/settings/sign_in_restrictions.md +++ b/doc/user/admin_area/settings/sign_in_restrictions.md @@ -13,8 +13,8 @@ You can use **Sign-in restrictions** to customize authentication restrictions fo To access sign-in restriction settings: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Sign-in restrictions** section. ## Password authentication enabled @@ -26,7 +26,7 @@ You can restrict the password authentication for web interface and Git over HTTP ## Admin Mode -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2158) in GitLab 13.10. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2158) in GitLab 13.10. When this feature is enabled, instance administrators are limited as regular users. During that period, they do not have access to all projects, groups, or the **Admin Area** menu. @@ -118,7 +118,7 @@ For example, if you include the following information in the noted text box: To access this text box: 1. On the top bar, select **Menu > Admin**. -1. In the left sidebar, select **Settings > General**, and expand the **Sign-in restrictions** section. +1. On the left sidebar, select **Settings > General**, and expand the **Sign-in restrictions** section. ``` Your users see the **Custom sign-in text** when they navigate to the sign-in screen for your diff --git a/doc/user/admin_area/settings/sign_up_restrictions.md b/doc/user/admin_area/settings/sign_up_restrictions.md index c774ae2eecc..dc09d6a5132 100644 --- a/doc/user/admin_area/settings/sign_up_restrictions.md +++ b/doc/user/admin_area/settings/sign_up_restrictions.md @@ -22,8 +22,8 @@ you do not expect public users to sign up for an account. To disable sign ups: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**, and expand **Sign-up restrictions**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**, and expand **Sign-up restrictions**. 1. Clear the **Sign-up enabled** checkbox, then select **Save changes**. ## Require administrator approval for new sign ups @@ -38,8 +38,8 @@ enabled by default for new GitLab instances. It is only applicable if sign ups a To require administrator approval for new sign ups: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**, and expand **Sign-up restrictions**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**, and expand **Sign-up restrictions**. 1. Select the **Require admin approval for new sign-ups** checkbox, then select **Save changes**. In [GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/273258), if an administrator disables this setting, the users in pending approval state are @@ -52,8 +52,8 @@ their email address before they are allowed to sign in. To enforce confirmation of the email address used for new sign ups: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**, and expand **Sign-up restrictions**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**, and expand **Sign-up restrictions**. 1. Select the **Enable email restrictions for sign ups** checkbox, then select **Save changes**. ## User cap **(FREE SELF)** @@ -70,8 +70,8 @@ user cap, the users in pending approval state are automatically approved in a ba ### Set the user cap number -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand **Sign-up restrictions**. 1. Enter a number in **User cap**. 1. Select **Save changes**. @@ -80,8 +80,8 @@ New user sign ups are subject to the user cap restriction. ## Remove the user cap -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand **Sign-up restrictions**. 1. Remove the number from **User cap**. 1. Select **Save changes**. @@ -122,15 +122,11 @@ email addresses to disallowed domains after sign up. ### Allowlist email domains -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/598) in GitLab 7.11.0 - You can restrict users only to sign up using email addresses matching the given domains list. ### Denylist email domains -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5259) in GitLab 8.10. - You can block users from signing up when using an email addresses of specific domains. This can reduce the risk of malicious users creating spam accounts with disposable email addresses. @@ -138,8 +134,8 @@ reduce the risk of malicious users creating spam accounts with disposable email To create an email domain allowlist or denylist: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**, and expand **Sign-up restrictions**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**, and expand **Sign-up restrictions**. 1. For the allowlist, you must enter the list manually. For the denylist, you can enter the list manually or upload a `.txt` file that contains list entries. diff --git a/doc/user/admin_area/settings/terms.md b/doc/user/admin_area/settings/terms.md index 21805ef771f..c7c41e665ec 100644 --- a/doc/user/admin_area/settings/terms.md +++ b/doc/user/admin_area/settings/terms.md @@ -17,8 +17,8 @@ for example `https://gitlab.example.com/-/users/terms`. To enforce acceptance of a Terms of Service and Privacy Policy: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Terms of Service and Privacy Policy** section. 1. Check the **All users must accept the Terms of Service and Privacy Policy to access GitLab** checkbox. 1. Input the text of the **Terms of Service and Privacy Policy**. You can use [Markdown](../../markdown.md) diff --git a/doc/user/admin_area/settings/third_party_offers.md b/doc/user/admin_area/settings/third_party_offers.md index 6f7cb081315..a9c8c5d2a76 100644 --- a/doc/user/admin_area/settings/third_party_offers.md +++ b/doc/user/admin_area/settings/third_party_offers.md @@ -15,7 +15,7 @@ for using [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/ To toggle the display of third-party offers: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings**, and expand **Third-party offers**. 1. Select **Do not display offers from third parties**. 1. Select **Save changes**. diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index 89c6be9608b..330a25087ef 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -73,9 +73,10 @@ If your GitLab instance is behind a proxy, set the appropriate To enable or disable Service Ping and version check: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Metrics and profiling**, and expand **Usage statistics**. -1. Select or clear the **Version check** and **Service ping** checkboxes. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Metrics and profiling**. +1. Expand **Usage statistics**. +1. Select or clear the **Enable version check** and **Enable service ping** checkboxes. 1. Select **Save changes**. <!-- ## Troubleshooting 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 fdeda0cf451..32f08801c76 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 @@ -13,30 +13,78 @@ of a web application. For more details, see The following limits are disabled by default: -- Unauthenticated requests -- Authenticated API requests -- Authenticated web requests +- [Unauthenticated API requests (per IP)](#enable-unauthenticated-api-request-rate-limit). +- [Unauthenticated web requests (per IP)](#enable-unauthenticated-web-request-rate-limit). +- [Authenticated API requests (per user)](#enable-authenticated-api-request-rate-limit). +- [Authenticated web requests (per user)](#enable-authenticated-web-request-rate-limit). -To enforce any or all of them: +NOTE: +By default, all Git operations are first tried unauthenticated. Because of this, HTTP Git operations +may trigger the rate limits configured for unauthenticated requests. -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Network**, and expand **User and IP rate limits**: -  +## Enable unauthenticated API request rate limit - NOTE: - By default, all Git operations are first tried unauthenticated. Because of this, HTTP Git operations - may trigger the rate limits configured for unauthenticated requests. +To enable the unauthenticated request rate limit: -## Response text +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Network**, and expand **User and IP rate limits**. +1. Select **Enable unauthenticated API request rate limit**. + + - Optional. Update the **Maximum unauthenticated API requests per rate limit period per IP** value. + Defaults to `3600`. + - Optional. Update the **Unauthenticated rate limit period in seconds** value. + Defaults to `3600`. + +## Enable unauthenticated web request rate limit + +To enable the unauthenticated request rate limit: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Network**, and expand **User and IP rate limits**. +1. Select **Enable unauthenticated web request rate limit**. + + - Optional. Update the **Maximum unauthenticated web requests per rate limit period per IP** value. + Defaults to `3600`. + - Optional. Update the **Unauthenticated rate limit period in seconds** value. + Defaults to `3600`. + +## Enable authenticated API request rate limit + +To enable the authenticated API request rate limit: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Network**, and expand **User and IP rate limits**. +1. Select **Enable authenticated API request rate limit**. + + - Optional. Update the **Maximum authenticated API requests per rate limit period per user** value. + Defaults to `7200`. + - Optional. Update the **Authenticated API rate limit period in seconds** value. + Defaults to `3600`. + +## Enable authenticated web request rate limit + +To enable the unauthenticated request rate limit: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Network**, and expand **User and IP rate limits**. +1. Select **Enable authenticated web request rate limit**. + + - Optional. Update the **Maximum authenticated web requests per rate limit period per user** value. + Defaults to `7200`. + - Optional. Update the **Authenticated web rate limit period in seconds** value. + Defaults to `3600`. + +## Use a custom rate limit response A request that exceeds a rate limit returns a 429 response code and a -plain-text body, which by default is: +plain-text body, which by default is `Retry later`. -```plaintext -Retry later -``` +To use a custom response: -It is possible to customize this response text in the Admin Area. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Network**, and expand **User and IP rate limits**. +1. In the **Plain-text response to send to clients that hit a rate limit** text box, + add the plain-text response message. ## Response headers @@ -129,6 +177,10 @@ a comma-separated list of throttle names. The possible names are: - `throttle_unauthenticated` + - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/335300) in GitLab 14.3. Use `throttle_unauthenticated_api` or `throttle_unauthenticated_web` instead. + `throttle_unauthenticated` is still supported and selects both of them. +- `throttle_unauthenticated_api` +- `throttle_unauthenticated_web` - `throttle_authenticated_api` - `throttle_authenticated_web` - `throttle_unauthenticated_protected_paths` @@ -136,6 +188,7 @@ The possible names are: - `throttle_authenticated_protected_paths_web` - `throttle_unauthenticated_packages_api` - `throttle_authenticated_packages_api` +- `throttle_authenticated_git_lfs` For example, to try out throttles for all authenticated requests to non-protected paths can be done by setting 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 c46aec76e57..7f3f4b32802 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -13,8 +13,8 @@ specific controls on branches, projects, snippets, groups, and more. To access the visibility and access control options: 1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. ## Protect default branches @@ -33,8 +33,8 @@ or configure [branch protection for groups](../../group/index.md#change-the-defa To change the default branch protection for the entire instance: 1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Select a **Default branch protection**: - **Not protected** - Both developers and maintainers can push new commits, @@ -59,8 +59,8 @@ can be overridden on a per-group basis by the group's owner. In disable this privilege for group owners, enforcing the instance-level protection rule: 1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Deselect the **Allow owners to manage default branch protection per group** checkbox. 1. Select **Save changes**. @@ -75,8 +75,8 @@ Instance-level protections for project creation define which roles can on the instance. To alter which roles have permission to create projects: 1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. For **Default project creation protection**, select the desired roles: - No one. @@ -90,23 +90,23 @@ Anyone with the **Owner** role, either at the project or group level, can delete a project. To allow only users with the Administrator role to delete projects: 1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Scroll to **Default project deletion protection**, and select **Only admins can delete project**. 1. Select **Save changes**. ## Default delayed project deletion **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/255449) in GitLab 14.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/255449) in GitLab 14.2 for groups created after August 12, 2021. -Projects in a group (but not a personal namespace) can be deleted after a delayed period, by -[configuring in Group Settings](../../group/index.md#enable-delayed-project-removal). +Projects in a group (but not a personal namespace) can be deleted after a delayed period. +You can [configure it in group settings](../../group/index.md#enable-delayed-project-removal). To enable delayed project deletion by default in new groups: 1. Check the **Default delayed project deletion** checkbox. -1. Click **Save changes**. +1. Select **Save changes**. ## Default deletion delay **(PREMIUM SELF)** @@ -142,8 +142,8 @@ Alternatively, projects that are marked for removal can be deleted immediately. To set the default [visibility levels for new projects](../../../public_access/public_access.md): 1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Select the desired default project visibility: - **Private** - Project access must be granted explicitly to each user. If this @@ -157,8 +157,8 @@ To set the default [visibility levels for new projects](../../../public_access/p To set the default visibility levels for new [snippets](../../snippets.md): 1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Select the desired default snippet visibility. 1. Select **Save changes**. @@ -171,8 +171,8 @@ For more details on snippet visibility, read To set the default visibility levels for new groups: 1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Select the desired default group visibility: - **Private** - The group and its projects can only be viewed by members. @@ -188,8 +188,8 @@ For more details on group visibility, see To restrict visibility levels for projects, snippets, and selected pages: 1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **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. 1. Select **Save changes**. @@ -202,8 +202,8 @@ For more details on project visibility, see You can specify from which hosting sites users can [import their projects](../../project/import/index.md): 1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Select each of **Import sources** to allow. 1. Select **Save changes**. @@ -214,8 +214,8 @@ To enable the export of [projects and their data](../../../user/project/settings/import_export.md#export-a-project-and-its-data): 1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Select **Project export enabled**. 1. Select **Save changes**. @@ -230,8 +230,8 @@ The GitLab restrictions apply at the application level. To specify the enabled Git access protocols: 1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Select the desired Git access protocols: - Both SSH and HTTP(S) diff --git a/doc/user/admin_area/user_cohorts.md b/doc/user/admin_area/user_cohorts.md index e96ce969b3a..89026e56a27 100644 --- a/doc/user/admin_area/user_cohorts.md +++ b/doc/user/admin_area/user_cohorts.md @@ -10,8 +10,8 @@ You can analyze your users' GitLab activities over time. To view user cohorts: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Overview > Users**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Overview > Users**. 1. Select the **Cohorts** tab. ## Overview diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index 7cb5db4379a..5b7e6e39187 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -75,12 +75,12 @@ in one place. [Learn more about instance-level analytics](../admin_area/analytics/index.md). -## Group-level analytics **(PREMIUM)** +## Group-level analytics > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195979) in GitLab 12.8. > - Moved to GitLab Premium in 13.9. -The following analytics features are available at the group level: +GitLab provides several analytics features at the group level. Some of these features require you to use a higher tier than GitLab Free. - [Application Security](../application_security/security_dashboard/#group-security-dashboard) - [Contribution](../group/contribution_analytics/index.md) @@ -93,7 +93,7 @@ The following analytics features are available at the group level: ## Project-level analytics -The following analytics features are available at the project level: +You can use GitLab to review analytics at the project level. Some of these features require you to use a higher tier than GitLab Free. - [Application Security](../application_security/security_dashboard/#project-security-dashboard) - [CI/CD](ci_cd_analytics.md) @@ -105,8 +105,10 @@ The following analytics features are available at the project level: - [Repository](repository_analytics.md) - [Value Stream](value_stream_analytics.md) -## User-configurable analytics **(ULTIMATE)** +## User-configurable analytics The following analytics features are available for users to create personalized views: - [Application Security](../application_security/security_dashboard/#security-center) + +Be sure to review the documentation page for this feature for GitLab tier requirements. diff --git a/doc/user/analytics/issue_analytics.md b/doc/user/analytics/issue_analytics.md index b77a25a9d62..44b8c87ee27 100644 --- a/doc/user/analytics/issue_analytics.md +++ b/doc/user/analytics/issue_analytics.md @@ -7,13 +7,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Issue Analytics **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196561) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196561) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9. Issue Analytics is a bar graph which illustrates the number of issues created each month. The default time span is 13 months, which includes the current month, and the 12 months prior. -To access the chart, navigate to your project sidebar and select **Analytics > Issue**. +To access the chart: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Analytics > Issue**. Hover over each bar to see the total number of issues. diff --git a/doc/user/analytics/merge_request_analytics.md b/doc/user/analytics/merge_request_analytics.md index 321e2f0fc24..44e4cd8b371 100644 --- a/doc/user/analytics/merge_request_analytics.md +++ b/doc/user/analytics/merge_request_analytics.md @@ -20,7 +20,10 @@ The Throughput chart shows the number of merge requests merged, by month. Merge a common measure of productivity in software engineering. Although imperfect, the average throughput can be a meaningful benchmark of your team's overall productivity. -To access Merge Request Analytics, from your project's menu, go to **Analytics > Merge Request**. +To access Merge Request Analytics: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Analytics > Merge request**. ## Use cases @@ -93,10 +96,10 @@ You can filter the data that is presented on the page based on the following par To filter results: -1. Click on the filter bar. +1. Select the filter bar. 1. Select a parameter to filter by. 1. Select a value from the autocompleted results, or enter search text to refine the results. -1. Hit the "Return" key. +1. Press Enter. ## Date range diff --git a/doc/user/analytics/productivity_analytics.md b/doc/user/analytics/productivity_analytics.md index a06d94caf69..391ec5c04d9 100644 --- a/doc/user/analytics/productivity_analytics.md +++ b/doc/user/analytics/productivity_analytics.md @@ -50,11 +50,11 @@ The following metrics and visualizations are available on a project or group lev > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13188) in GitLab 12.4. -GitLab has the ability to filter analytics based on a date range. To filter results: +You can filter analytics based on a date range. To filter results: 1. Select a group. -1. Optionally select a project. -1. Select a date range using the available date pickers. +1. Optional. Select a project. +1. Select a date range by using the available date pickers. ## Permissions diff --git a/doc/user/analytics/value_stream_analytics.md b/doc/user/analytics/value_stream_analytics.md index 9a1aed9c39f..7057d069e95 100644 --- a/doc/user/analytics/value_stream_analytics.md +++ b/doc/user/analytics/value_stream_analytics.md @@ -64,7 +64,7 @@ Items aren't included in the stage time calculation if they have not reached the | Stage | Description | |---------|---------------| -| Issue | Measures the median time between creating an issue and taking action to solve it, by either labeling it or adding it to a milestone, whichever comes first. The label is tracked only if it already includes an [Issue Board list](../project/issue_board.md) created for it. | +| Issue | Measures the median time between creating an issue and taking action to solve it, by either labeling it or adding it to a milestone, whichever comes first. The label is tracked only if it already includes an [issue board list](../project/issue_board.md) created for it. | | Plan | Measures the median time between the action you took for the previous stage, and pushing the first commit to the branch. That first branch commit triggers the separation between **Plan** and **Code**, and at least one of the commits in the branch must include the related issue number (such as `#42`). If the issue number is *not* included in a commit, that data is not included in the measurement time of the stage. | | Code | Measures the median time between pushing a first commit (previous stage) and creating a merge request (MR). The process is tracked with the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) in the description of the merge request. For example, if the issue is closed with `Closes #xxx`, it's assumed that `xxx` is issue number for the merge request). If there is no closing pattern, the start time is set to the create time of the first commit. | | Test | Essentially the start to finish time for all pipelines. Measures the median time to run the entire pipeline for that project. Related to the time required by GitLab CI/CD to run every job for the commits pushed to that merge request, as defined in the previous stage. | @@ -85,7 +85,7 @@ How this works: In short, the Value Stream Analytics dashboard tracks data related to [GitLab flow](../../topics/gitlab_flow.md). It does not include data for: - Merge requests that do not close an issue. -- Issues that do not include labels present in the Issue Board +- Issues that do not include labels present in the issue board. - Issues without a milestone. - Staging stages, in projects without a [production environment](#how-the-production-environment-is-identified). diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 7ed36572be4..e32989c2915 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -85,7 +85,7 @@ In GitLab 14.0 and later, API fuzzing configuration files must be in your reposi ### Web API fuzzing configuration form -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299234) in GitLab 13.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299234) in GitLab 13.10. WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -98,17 +98,16 @@ a YAML snippet that you can paste in your GitLab CI/CD configuration. To generate an API Fuzzing configuration snippet: -1. From your project's home page, go to **Security & Compliance > Configuration** in the left - sidebar. -1. Select **Configure** in the **API Fuzzing** row. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Configuration**. +1. In the **API Fuzzing** row, select **Configure**. 1. Complete the form as needed. Read below for more information on available configuration options. 1. Select **Generate code snippet**. A modal opens with the YAML snippet corresponding to the options you've selected in the form. 1. Choose one of the following actions: - 1. Select **Copy code and open `.gitlab-ci.yml` file** to copy the snippet to your clipboard and - be redirected to your project's `.gitlab-ci.yml` file where you can paste the YAML - configuration. - 1. Select **Copy code only** to copy the snippet to your clipboard and close the modal. + 1. To copy the snippet to your clipboard and be redirected to your project's `.gitlab-ci.yml` file, + where you can paste the YAML configuration, select **Copy code and open `.gitlab-ci.yml` file**. + 1. To copy the snippet to your clipboard and close the modal, select **Copy code only**. ### OpenAPI Specification @@ -995,7 +994,7 @@ Follow these steps to view details of a fuzzing fault: **API Fuzzing detected N potential vulnerabilities**. Click the title to display the fault details. -1. Click the fault's title to display the fault's details. The table below describes these details. +1. Select the fault's title to display the fault's details. The table below describes these details. | Field | Description | |:--------------------|:----------------------------------------------------------------------------------------| diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index 664fcd9b72f..98e241ba3bd 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -13,61 +13,56 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - A simplified version was made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/294076) in GitLab 13.10. > - [Redesigned](https://gitlab.com/gitlab-org/gitlab/-/issues/326926) in 14.2. -The Security Configuration page displays what security scans are available, links to documentation and also simple enablement tools for the current project. +The Security Configuration page lists the following for the security testing and compliance tools: -To view a project's security configuration, go to the project's home page, -then in the left sidebar go to **Security & Compliance > Configuration**. - -For each security control the page displays: - -- Its name, description and a documentation link. +- Name, description, and a documentation link. - Whether or not it is available. - A configuration button or a link to its configuration guide. +The status of each security control is determined by the project's latest default branch +[CI pipeline](../../../ci/pipelines/index.md). +If a job with the expected security report artifact exists in the pipeline, the feature's status is +_enabled_. + +If the latest pipeline used [Auto DevOps](../../../topics/autodevops/index.md), +all security features are configured by default. + +To view a project's security configuration: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Configuration**. + +Select **Configuration history** to see the `.gitlab-ci.yml` file's history. + ## Security testing You can configure the following security controls: -- Auto DevOps - - Click **Enable Auto DevOps** on the alert to enable it for the current project. For more details, see [Auto DevOps](../../../topics/autodevops/index.md). -- SAST - - Click **Enable SAST** to use SAST for the current project. For more details, see [Configure SAST in the UI](../sast/index.md#configure-sast-in-the-ui). -- DAST **(ULTIMATE)** - - Click **Enable DAST** to use DAST for the current Project. To manage the available DAST profiles used for on-demand scans Click **Manage Scans**. For more details, see [DAST on-demand scans](../dast/index.md#on-demand-scans). +- Static Application Security Testing (SAST) + - Select **Enable SAST** to configure SAST for the current project. + For more details, read [Configure SAST in the UI](../sast/index.md#configure-sast-in-the-ui). +- Dynamic Application Security Testing (DAST) **(ULTIMATE)** + - Select **Enable DAST** to configure DAST for the current project. + - Select **Manage scans** to manage the saved DAST scans, site profiles, and scanner profiles. + For more details, read [DAST on-demand scans](../dast/index.md#on-demand-scans). - Dependency Scanning **(ULTIMATE)** - Select **Configure via Merge Request** to create a merge request with the changes required to enable Dependency Scanning. For more details, see [Enable Dependency Scanning via an automatic merge request](../dependency_scanning/index.md#enable-dependency-scanning-via-an-automatic-merge-request). - - Container Scanning **(ULTIMATE)** - - Can be configured via `.gitlab-ci.yml`. For more details, see [Container Scanning](../../../user/application_security/container_scanning/index.md#configuration). + - Can be configured with `.gitlab-ci.yml`. For more details, read [Container Scanning](../../../user/application_security/container_scanning/index.md#configuration). - Cluster Image Scanning **(ULTIMATE)** - - Can be configured via `.gitlab-ci.yml`. For more details, see [Cluster Image Scanning](../../../user/application_security/cluster_image_scanning/#configuration). + - Can be configured with `.gitlab-ci.yml`. For more details, read [Cluster Image Scanning](../../../user/application_security/cluster_image_scanning/#configuration). - Secret Detection - Select **Configure via Merge Request** to create a merge request with the changes required to - enable Secret Detection. For more details, see [Enable Secret Detection via an automatic merge request](../secret_detection/index.md#enable-secret-detection-via-an-automatic-merge-request). - + enable Secret Detection. For more details, read [Enable Secret Detection via an automatic merge request](../secret_detection/index.md#enable-secret-detection-via-an-automatic-merge-request). - API Fuzzing **(ULTIMATE)** - - Click **Enable API Fuzzing** to use API Fuzzing for the current Project. For more details, see [API Fuzzing](../../../user/application_security/api_fuzzing/index.md#enable-web-api-fuzzing). + - Select **Enable API Fuzzing** to use API Fuzzing for the current project. For more details, read [API Fuzzing](../../../user/application_security/api_fuzzing/index.md#enable-web-api-fuzzing). - Coverage Fuzzing **(ULTIMATE)** - - Can be configured via `.gitlab-ci.yml`. For more details, see [Coverage Fuzzing](../../../user/application_security/coverage_fuzzing/index.md#configuration). - -## Status **(ULTIMATE)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20711) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. - -The status of each security control is determined by the project's latest default branch -[CI pipeline](../../../ci/pipelines/index.md). -If a job with the expected security report artifact exists in the pipeline, the feature's status is -_enabled_. - -If the latest pipeline used [Auto DevOps](../../../topics/autodevops/index.md), -all security features are configured by default. - -Click **View history** to see the `.gitlab-ci.yml` file's history. + - Can be configured with `.gitlab-ci.yml`. For more details, read [Coverage Fuzzing](../../../user/application_security/coverage_fuzzing/index.md#configuration). ## Compliance **(ULTIMATE)** You can configure the following security controls: - License Compliance **(ULTIMATE)** - - Can be configured via `.gitlab-ci.yml`. For more details, see [License Compliance](../../../user/compliance/license_compliance/index.md#configuration). + - Can be configured with `.gitlab-ci.yml`. For more details, read [License Compliance](../../../user/compliance/license_compliance/index.md#configuration). diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 5791351a067..2b3d4dbfc0a 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -9,14 +9,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3672) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. -WARNING: -Versions of GitLab prior to 14.0 used Clair as the default container scanning engine. GitLab 14.0 -removes Clair from the product and replaces it with two new scanners. If you -run container scanning with the default settings, GitLab switches you seamlessly and automatically -to Trivy in GitLab 14.0. However, if you customized the variables in your container scanning job, -you should review the [migration guide](#change-scanners) -and make any necessary updates. - Your application's Docker image may itself be based on Docker images that contain known vulnerabilities. By including an extra job in your pipeline that scans for those vulnerabilities and displays them in a merge request, you can use GitLab to audit your Docker-based apps. @@ -57,37 +49,9 @@ To enable container scanning in your pipeline, you need the following: ## Configuration -How you enable container scanning depends on your GitLab version: - -- GitLab 11.9 and later: [Include](../../../ci/yaml/index.md#includetemplate) the - [`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml) - that comes with your GitLab installation. -- GitLab versions earlier than 11.9: Copy and use the job from the - [`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml). - -Other changes: - -- GitLab 13.6 [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263482) better support for - [FIPS](https://csrc.nist.gov/publications/detail/fips/140/2/final) by upgrading the - `CS_MAJOR_VERSION` from `2` to `3`. Version `3` of the `container_scanning` Docker image uses - [`centos:centos8`](https://hub.docker.com/_/centos) - as the new base. It also removes the use of the [start.sh](https://gitlab.com/gitlab-org/security-products/analyzers/klar/-/merge_requests/77) - script and instead executes the analyzer by default. Any customizations made to the - `container_scanning` job's [`before_script`](../../../ci/yaml/index.md#before_script) - and [`after_script`](../../../ci/yaml/index.md#after_script) - blocks may not work with the new version. To roll back to the previous [`alpine:3.11.3`](https://hub.docker.com/_/alpine)-based - Docker image, you can specify the major version through the [`CS_MAJOR_VERSION`](#available-cicd-variables) - variable. -- GitLab 13.9 [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322656) integration with - [Trivy](https://github.com/aquasecurity/trivy) by upgrading `CS_MAJOR_VERSION` from `3` to `4`. -- GitLab 14.0 [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61850) - an integration with [Trivy](https://github.com/aquasecurity/trivy) - as the default for container scanning, and also [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326279) - an integration with [Grype](https://github.com/anchore/grype) - as an alternative scanner. - -To include the `Container-Scanning.gitlab-ci.yml` template (GitLab 11.9 and later), add the -following to your `.gitlab-ci.yml` file: +To enable container scanning, add the +[`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml) +to your `.gitlab-ci.yml` file: ```yaml include: @@ -157,7 +121,7 @@ You can [configure](#customizing-the-container-scanning-settings) analyzers by u | `CI_APPLICATION_TAG` | `$CI_COMMIT_SHA` | Docker repository tag for the image to be scanned. | All | | `CS_ANALYZER_IMAGE` | `registry.gitlab.com/security-products/container-scanning:4` | Docker image of the analyzer. | All | | `CS_DOCKER_INSECURE` | `"false"` | Allow access to secure Docker registries using HTTPS without validating the certificates. | All | -| `CS_REGISTRY_INSECURE` | `"false"` | Allow access to insecure registries (HTTP only). Should only be set to `true` when testing the image locally. | Trivy. The registry must listen on port `80/tcp`. | +| `CS_REGISTRY_INSECURE` | `"false"` | Allow access to insecure registries (HTTP only). Should only be set to `true` when testing the image locally. Works with all scanners, but the registry must listen on port `80/tcp` for Trivy to work. | All | | `CS_SEVERITY_THRESHOLD` | `UNKNOWN` | Severity level threshold. The scanner outputs vulnerabilities with severity level higher than or equal to this threshold. Supported levels are Unknown, Low, Medium, High, and Critical. | Trivy | | `DOCKER_IMAGE` | `$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG` | The Docker image to be scanned. If set, this variable overrides the `$CI_APPLICATION_REPOSITORY` and `$CI_APPLICATION_TAG` variables. | All | | `DOCKER_PASSWORD` | `$CI_REGISTRY_PASSWORD` | Password for accessing a Docker registry requiring authentication. The default is only set if `$DOCKER_IMAGE` resides at [`$CI_REGISTRY`](../../../ci/variables/predefined_variables.md). | All | @@ -625,3 +589,29 @@ To prevent the error, ensure the Docker version that the runner is using is ### Getting warning message `gl-container-scanning-report.json: no matching files` For information on this, see the [general Application Security troubleshooting section](../../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload). + +## Changes + +- GitLab 13.6 [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263482) better support for + [FIPS](https://csrc.nist.gov/publications/detail/fips/140/2/final) by upgrading the + `CS_MAJOR_VERSION` from `2` to `3`. Version `3` of the `container_scanning` Docker image uses + [`centos:centos8`](https://hub.docker.com/_/centos) + as the new base. It also removes the use of the [start.sh](https://gitlab.com/gitlab-org/security-products/analyzers/klar/-/merge_requests/77) + script and instead executes the analyzer by default. Any customizations made to the + `container_scanning` job's [`before_script`](../../../ci/yaml/index.md#before_script) + and [`after_script`](../../../ci/yaml/index.md#after_script) + blocks may not work with the new version. To roll back to the previous [`alpine:3.11.3`](https://hub.docker.com/_/alpine)-based + Docker image, you can specify the major version through the [`CS_MAJOR_VERSION`](#available-cicd-variables) + variable. +- GitLab 13.9 [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322656) integration with + [Trivy](https://github.com/aquasecurity/trivy) by upgrading `CS_MAJOR_VERSION` from `3` to `4`. +- GitLab 13.9 [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/321451) the integration with + [Clair](https://github.com/quay/clair/). +- GitLab 14.0 [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61850) + an integration with [Trivy](https://github.com/aquasecurity/trivy) + as the default for container scanning, and also [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326279) + an integration with [Grype](https://github.com/anchore/grype) + as an alternative scanner. + +Other changes to the container scanning analyzer can be found in the project's +[changelog](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning/-/blob/master/CHANGELOG.md). diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 679d20a6394..0d5eb2b6d50 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Coverage Guided Fuzz Testing **(ULTIMATE)** +# Coverage-guided fuzz testing **(ULTIMATE)** GitLab allows you to add coverage-guided fuzz testing to your pipelines. This helps you discover bugs and potential security issues that other QA processes may miss. Coverage-guided fuzzing sends @@ -82,7 +82,7 @@ The `my_fuzz_target` job (the separate job for your fuzz target) does the follow - Runs on a fuzz stage that usually comes after a test stage. The `gitlab-cov-fuzz` is a command-line tool that runs the instrumented application. It parses and -analyzes the exception information that the fuzzer outputs. It also downloads the [corpus](#glossary) +analyzes the exception information that the fuzzer outputs. It also downloads the [corpus](../terminology/index.md#corpus) and crash events from previous pipelines automatically. This helps your fuzz targets build on the progress of previous fuzzing jobs. The parsed crash events and data are written to `gl-coverage-fuzzing-report.json`. @@ -97,7 +97,7 @@ Each fuzzing step outputs these artifacts: - `crashes`: Holds all crash events the current job encountered as well as those not fixed in previous jobs. -### Types of Fuzzing Jobs +### Types of fuzzing jobs There are two types of jobs: @@ -127,7 +127,7 @@ any option available in the underlying fuzzing engine. | `COVFUZZ_SEED_CORPUS` | Path to a seed corpus directory. The default is empty. | | `COVFUZZ_URL_PREFIX` | Path to the `gitlab-cov-fuzz` repository cloned for use with an offline environment. You should only change this when using an offline environment. The default value is `https://gitlab.com/gitlab-org/security-products/analyzers/gitlab-cov-fuzz/-/raw`. | -The files in the seed corpus (`COVFUZZ_SEED_CORPUS`), if provided, aren't updated unless you commit new +The files in the [seed corpus](../terminology/index.md#seed-corpus) (`COVFUZZ_SEED_CORPUS`), if provided, aren't updated unless you commit new files to your Git repository. There's usually no need to frequently update the seed corpus. As part of the GitLab artifacts system, GitLab saves in a corpus directory the new test cases that every run generates. In any subsequent runs, GitLab also reuses the generated corpus together with the seed @@ -172,13 +172,13 @@ Here's an example coverage fuzzing report: } ``` -### Additional Configuration +### Additional configuration The `gitlab-cov-fuzz` command passes all arguments it receives to the underlying fuzzing engine. You can therefore use all the options available in that fuzzing engine. For more information on these options, see the underlying fuzzing engine's documentation. -### Offline Environment +### Offline environment To use coverage fuzzing in an offline environment, follow these steps: @@ -262,12 +262,3 @@ vulnerability: - Scanner: The scanner that detected the vulnerability (for example, Coverage Fuzzing). - Scanner Provider: The engine that did the scan. For Coverage Fuzzing, this can be any of the engines listed in [Supported fuzzing engines and languages](#supported-fuzzing-engines-and-languages). - -### Glossary - -- Seed corpus: The set of test cases given as initial input to the fuzz target. This usually speeds - up the fuzz target substantially. This can be either manually created test cases or auto-generated - with the fuzz target itself from previous runs. -- Corpus: The set of meaningful test cases that are generated while the fuzzer is running. Each - meaningful test case produces new coverage in the tested program. It's advised to re-use the - corpus and pass it to subsequent runs. diff --git a/doc/user/application_security/dast/browser_based.md b/doc/user/application_security/dast/browser_based.md index e8fbc17327c..5094ccd2196 100644 --- a/doc/user/application_security/dast/browser_based.md +++ b/doc/user/application_security/dast/browser_based.md @@ -19,7 +19,7 @@ The browser-based crawler works by loading the target application into a special such as clicking on a link or filling in a form. For each action found, the crawler will execute it, take a new snapshot and determine what in the page changed from the previous snapshot. Crawling continues by taking more snapshots and finding subsequent actions. -The benefit of crawling by following user actions in a browser is that the crawler can interact with the target application much like a real user would, identifying complex flows that traditional web crawlers don’t understand. This results in better coverage of the website. +The benefit of crawling by following user actions in a browser is that the crawler can interact with the target application much like a real user would, identifying complex flows that traditional web crawlers don't understand. This results in better coverage of the website. Using the browser-based crawler should provide greater coverage for most web applications, compared with the current DAST AJAX crawler. The new crawler replaces the AJAX crawler and is specifically designed to maximize crawl coverage in modern web applications. While both crawlers are currently used in conjunction with the existing DAST scanner, the combination of the browser-based crawler with the current DAST scanner is much more effective at finding and testing every page in an application. diff --git a/doc/user/application_security/dast/dast_troubleshooting.md b/doc/user/application_security/dast/dast_troubleshooting.md index 725fab85789..f771bc82d58 100644 --- a/doc/user/application_security/dast/dast_troubleshooting.md +++ b/doc/user/application_security/dast/dast_troubleshooting.md @@ -88,3 +88,7 @@ stages: include: - template: DAST.latest.gitlab-ci.yml ``` + +## Lack of IPv6 support + +Due to the underlying [ZAProxy engine not supporting IPv6](https://github.com/zaproxy/zaproxy/issues/3705), DAST is unable to scan or crawl IPv6-based applications. diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 7455915761c..0d60701b030 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -74,7 +74,7 @@ If your application utilizes Docker containers you have another option for deplo After your Docker build job completes and your image is added to your container registry, you can use the image as a [service](../../../ci/services/index.md). -By using service definitions in your `gitlab-ci.yml`, you can scan services with the DAST analyzer. +By using service definitions in your `.gitlab-ci.yml`, you can scan services with the DAST analyzer. ```yaml stages: @@ -328,6 +328,8 @@ Vulnerability rules in an API scan are different than those in a normal website A new DAST API scanning engine is available in GitLab 13.12 and later. For more details, see [DAST API scanning engine](../dast_api). The new scanning engine supports REST, SOAP, GraphQL, and generic APIs using forms, XML, and JSON. Testing can be performed using OpenAPI, Postman Collections, and HTTP Archive (HAR) documents. +The target API instance’s base URL is provided by using the `DAST_API_TARGET_URL` variable or an `environment_url.txt` file. + #### Specification format API scans support OpenAPI V2 and OpenAPI V3 specifications. You can define these specifications using `JSON` or `YAML`. @@ -339,7 +341,7 @@ The specification does not have to be hosted on the same host as the API being t ```yaml include: - - template: DAST.gitlab-ci.yml + - template: DAST-API.gitlab-ci.yml variables: DAST_API_OPENAPI: http://my.api/api-specification.yml @@ -390,7 +392,7 @@ the following DAST configuration can be used: ```yaml include: - - template: DAST.gitlab-ci.yml + - template: DAST-API.gitlab-ci.yml variables: DAST_API_OPENAPI: http://api-test.host.com/api-specification.yml @@ -405,7 +407,7 @@ Headers are applied to every request DAST makes. ```yaml include: - - template: DAST.gitlab-ci.yml + - template: DAST-API.gitlab-ci.yml variables: DAST_API_OPENAPI: http://api-test.api.com/api-specification.yml @@ -554,6 +556,9 @@ By default, several rules are disabled because they either take a long time to run or frequently generate false positives. The complete list of disabled rules can be found in [exclude_rules.yml](https://gitlab.com/gitlab-org/security-products/dast/-/blob/main/src/config/exclude_rules.yml). +The lists for `DAST_EXCLUDE_RULES` and `DAST_ONLY_INCLUDE_RULES` **must** be enclosed in double +quotes (`"`), otherwise they are interpreted as numeric values. + ### Hide sensitive information > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36332) in GitLab 13.1. @@ -742,7 +747,7 @@ dast: when: always ``` -### Available CI/CD variables +## Available CI/CD variables These CI/CD variables are specific to DAST. They can be used to customize the behavior of DAST to your requirements. @@ -762,7 +767,7 @@ These CI/CD variables are specific to DAST. They can be used to customize the be | `DAST_AUTO_UPDATE_ADDONS` | boolean | ZAP add-ons are pinned to specific versions in the DAST Docker image. Set to `true` to download the latest versions when the scan starts. Default: `false`. | | `DAST_BROWSER_PATH_TO_LOGIN_FORM` <sup>1,2</sup> | selector | Comma-separated list of selectors that will be clicked on prior to attempting to enter `DAST_USERNAME` and `DAST_PASSWORD` into the login form. Example: `"css:.navigation-menu,css:.login-menu-item"`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326633) in GitLab 14.1. | | `DAST_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_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. The whole list **must** be enclosed in double quotes (`"`). Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). For example, `HTTP Parameter Override` has a rule ID of `10026`. Cannot be used when `DAST_ONLY_INCLUDE_RULES` is set. **Note:** In earlier versions of GitLab the excluded rules were executed but vulnerabilities they generated were suppressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | | `DAST_EXCLUDE_URLS` <sup>1,2</sup> | URLs | The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. Not supported for API scans. Example, `http://example.com/sign-out`. | | `DAST_FIRST_SUBMIT_FIELD` <sup>2</sup> | string | The `id` or `name` of the element that when clicked submits the username form of a multi-page login process. For example, `css:button[type='user-submit']`. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | | `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` | boolean | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293595)** in GitLab 14.0. Set to `true` to require domain validation when running DAST full scans. Not supported for API scans. Default: `false` | @@ -772,7 +777,7 @@ These CI/CD variables are specific to DAST. They can be used to customize the be | `DAST_MARKDOWN_REPORT` | string | The filename of the Markdown report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | | `DAST_MASK_HTTP_HEADERS` | string | Comma-separated list of request and response headers to be masked (GitLab 13.1). Must contain **all** headers to be masked. Refer to [list of headers that are masked by default](#hide-sensitive-information). | | `DAST_MAX_URLS_PER_VULNERABILITY` | number | The maximum number of URLs reported for a single vulnerability. `DAST_MAX_URLS_PER_VULNERABILITY` is set to `50` by default. To list all the URLs set to `0`. [Introduced](https://gitlab.com/gitlab-org/security-products/dast/-/merge_requests/433) in GitLab 13.12. | -| `DAST_ONLY_INCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to configure the scan to run only them. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). Cannot be used when `DAST_EXCLUDE_RULES` is set. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250651) in GitLab 13.12. | +| `DAST_ONLY_INCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to configure the scan to run only them. The whole list **must** be enclosed in double quotes (`"`). Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). Cannot be used when `DAST_EXCLUDE_RULES` is set. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250651) in GitLab 13.12. | | `DAST_PASSWORD` <sup>1,2</sup> | string | The password to authenticate to in the website. Example: `P@55w0rd!` | | `DAST_PASSWORD_FIELD` <sup>1,2</sup> | string | The selector of password field at the sign-in HTML form. Example: `id:password` | | `DAST_PATHS` | string | Set to a comma-separated list of URLs for DAST to scan. For example, `/page1.html,/category1/page3.html,/page2.html`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in GitLab 13.4. | @@ -795,7 +800,7 @@ These CI/CD variables are specific to DAST. They can be used to customize the be 1. Available to an on-demand DAST scan. 1. Used for authentication. -#### Selectors +### Selectors Selectors are used by CI/CD variables to specify the location of an element displayed on a page in a browser. Selectors have the format `type`:`search string`. The crawler will search for the selector using the search string based on the type. @@ -808,7 +813,7 @@ Selectors have the format `type`:`search string`. The crawler will search for th | `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. | | None provided | `a.click-me` | Defaults to searching using a CSS selector. | -##### Find selectors with Google Chrome +#### Find selectors with Google Chrome Chrome DevTools element selector tool is an effective way to find a selector. @@ -824,7 +829,7 @@ Chrome DevTools element selector tool is an effective way to find a selector. In this example, the `id="user_login"` appears to be a good candidate. You can use this as a selector as the DAST username field by setting `DAST_USERNAME_FIELD: "id:user_login"`. -##### Choose the right selector +#### Choose the right selector Judicious choice of selector leads to a scan that is resilient to the application changing. @@ -919,7 +924,7 @@ The DAST job does not require the project's repository to be present when runnin > - Auditing for DAST profile management was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217872) in GitLab 14.1. An on-demand DAST scan runs outside the DevOps life cycle. Changes in your repository don't trigger -the scan. You must start it manually. +the scan. You must either start it manually, or schedule it to run. An on-demand DAST scan: @@ -928,8 +933,6 @@ An on-demand DAST scan: - Is associated with your project's default branch. - Is saved on creation so it can be run later. -In GitLab 13.10 and later, you can select to run an on-demand scan against a specific branch. - ### On-demand scan modes An on-demand scan can be run in active or passive mode: @@ -941,23 +944,34 @@ An on-demand scan can be run in active or passive mode: ### Run an on-demand DAST scan -NOTE: -You must have permission to run an on-demand DAST scan against a protected branch. -The default branch is automatically protected. For more information, see -[Pipeline security on protected branches](../../../ci/pipelines/index.md#pipeline-security-on-protected-branches). - Prerequisites: +- You must have permission to run an on-demand DAST scan against a protected branch. The default + branch is automatically protected. For more information, read + [Pipeline security on protected branches](../../../ci/pipelines/index.md#pipeline-security-on-protected-branches). - A [scanner profile](#create-a-scanner-profile). - A [site profile](#create-a-site-profile). -- If you are running an active scan the site profile must be [validated](#validate-a-site-profile). +- If you are running an active scan the site profile must have been [validated](#validate-a-site-profile). + +You can run an on-demand scan immediately, once at a scheduled date and time or at a specified +frequency: + +- Every day +- Every week +- Every month +- Every 3 months +- Every 6 months +- Every year -To run an on-demand scan, either: +To run an on-demand scan immediately, either: -- [Create and run an on-demand scan](#create-and-run-an-on-demand-scan). +- [Create and run an on-demand scan immediately](#create-and-run-an-on-demand-scan-immediately). - [Run a previously saved on-demand scan](#run-a-saved-on-demand-scan). -#### Create and run an on-demand scan +To run an on-demand scan either at a scheduled date or frequency, read +[Schedule an on-demand scan](#schedule-an-on-demand-scan). + +#### Create and run an on-demand scan immediately 1. From your project's home page, go to **Security & Compliance > On-demand Scans** in the left sidebar. @@ -965,44 +979,70 @@ To run an on-demand scan, either: 1. In GitLab 13.10 and later, select the desired branch from the **Branch** dropdown. 1. In **Scanner profile**, select a scanner profile from the dropdown. 1. In **Site profile**, select a site profile from the dropdown. -1. To run the on-demand scan now, select **Save and run scan**. Otherwise select **Save scan** to - [run](#run-a-saved-on-demand-scan) it later. +1. To run the on-demand scan immediately, select **Save and run scan**. Otherwise, select + **Save scan** to [run](#run-a-saved-on-demand-scan) it later. The on-demand DAST scan runs and the project's dashboard shows the results. -### List saved on-demand scans +#### Run a saved on-demand scan -To list saved on-demand scans: +To run a saved on-demand scan: -1. From your project's home page, go to **Security & Compliance > Configuration**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Configuration**. +1. Select **Manage DAST scans**. +1. In the **DAST Profiles** row, select **Manage**. 1. Select the **Saved Scans** tab. +1. In the scan's row, select **Run scan**. + + If the branch saved in the scan no longer exists, you must first + [edit the scan](#edit-an-on-demand-scan), select a new branch, and save the edited scan. -### View details of an on-demand scan +The on-demand DAST scan runs, and the project's dashboard shows the results. -To view details of an on-demand scan: +#### Schedule an on-demand scan + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.3. [Deployed behind the `dast_on_demand_scans_scheduler` flag](../../../administration/feature_flags.md), disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per user, +ask an administrator to [disable the `dast_on_demand_scans_scheduler` flag](../../../administration/feature_flags.md). +The feature is not ready for production use. + +To schedule a scan: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > On-demand Scans**. +1. Complete the **Scan name** and **Description** text boxes. +1. In GitLab 13.10 and later, from the **Branch** dropdown list, select the desired branch. +1. In the **Scanner profile** section, from the dropdown list, select a scanner profile. +1. In the **Site profile** section, from the dropdown list, select a site profile. +1. Select **Schedule scan**. +1. In the **Start time** section, select a time zone, date, and time. +1. From the **Repeats** dropdown list, select your desired frequency: + - To run the scan once, select **Never**. + - For a recurring scan, select any other option. +1. To run the on-demand scan immediately, select **Save and run scan**. To [run](#run-a-saved-on-demand-scan) it according to the schedule you set, select + **Save scan**. + +#### List saved on-demand scans + +To list saved on-demand scans: 1. From your project's home page, go to **Security & Compliance > Configuration**. -1. Select **Manage DAST scans**. -1. Select **Manage** in the **DAST Profiles** row. 1. Select the **Saved Scans** tab. -1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Edit**. -### Run a saved on-demand scan +#### View details of an on-demand scan -To run a saved on-demand scan: +To view details of an on-demand scan: 1. From your project's home page, go to **Security & Compliance > Configuration**. 1. Select **Manage DAST scans**. 1. Select **Manage** in the **DAST Profiles** row. 1. Select the **Saved Scans** tab. -1. In the scan's row select **Run scan**. - - If the branch saved in the scan no longer exists, you must first - [edit the scan](#edit-an-on-demand-scan), select a new branch, and save the edited scan. - -The on-demand DAST scan runs and the project's dashboard shows the results. +1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Edit**. -### Edit an on-demand scan +#### Edit an on-demand scan To edit an on-demand scan: @@ -1014,7 +1054,7 @@ To edit an on-demand scan: 1. Edit the form. 1. Select **Save scan**. -### Delete an on-demand scan +#### Delete an on-demand scan To delete an on-demand scan: @@ -1049,11 +1089,7 @@ When an API site type is selected, a [host override](#host-override) is used to #### Site profile validation > - Site profile validation [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233020) in GitLab 13.8. -> - Meta tag validation [enabled on GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/6460) in GitLab 14.2 and is ready for production use. -> - Meta tag validation [enabled with `dast_meta_tag_validation flag` flag](https://gitlab.com/gitlab-org/gitlab/-/issues/337711) for self-managed GitLab in GitLab 14.2 and is ready for production use. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the `dast_meta_tag_validation` flag](../../../administration/feature_flags.md). On GitLab.com, this feature is available but can be configured by GitLab.com administrators only. +> - Meta tag validation [introduced](https://gitlab.com/groups/gitlab-org/-/epics/6460) in GitLab 14.2. Site profile validation reduces the risk of running an active scan against the wrong website. A site must be validated before an active scan can run against it. The site validation methods are as @@ -1096,7 +1132,7 @@ To edit an existing site profile: 1. Edit the fields then select **Save profile**. If a site profile is linked to a security policy, a user cannot edit the profile from this page. See -[Scan Policies](../policies/index.md) +[Scan Execution Policies](../policies/index.md#scan-execution-policy-editor) for more information. #### Delete a site profile @@ -1110,7 +1146,7 @@ To delete an existing site profile: 1. Select **Delete** to confirm the deletion. If a site profile is linked to a security policy, a user cannot delete the profile from this page. -See [Scan Policies](../policies/index.md) +See [Scan Execution Policies](../policies/index.md#scan-execution-policy-editor) for more information. #### Validate a site profile @@ -1147,6 +1183,21 @@ The site is validated and an active scan can run against it. If a validated site profile's target URL is edited, the site's validation status is revoked. +#### Retry a failed validation + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322609) in GitLab 14.3. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, ask an +administrator to [disable the `dast_failed_site_validations` flag](../../../administration/feature_flags.md). + +If a site profile's validation fails, you can retry it by selecting the **Retry validation** button +in the profiles list. + +When loading the DAST profiles library, past failed validations are listed above the profiles +list. You can also retry the validation from there by selecting the **Retry validation** link in +the alert. You can also dismiss the alert to revoke failed validations. + #### Revoke a site profile's validation status Note that all site profiles with the same URL have their validation status revoked. @@ -1240,7 +1291,7 @@ To edit a scanner profile: 1. Select **Save profile**. If a scanner profile is linked to a security policy, a user cannot edit the profile from this page. -See [Scan Policies](../policies/index.md) +See [Scan Execution Policies](../policies/index.md#scan-execution-policy-editor) for more information. #### Delete a scanner profile @@ -1254,7 +1305,7 @@ To delete a scanner profile: 1. Select **Delete**. If a scanner profile is linked to a security policy, a user cannot delete the profile from this -page. See [Scan Policies](../policies/index.md) +page. See [Scan Execution Policies](../policies/index.md#scan-execution-policy-editor) for more information. ### Auditing @@ -1311,9 +1362,9 @@ dast: 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 in previous jobs, we recommend you don't download artifacts. To avoid downloading -artifacts, add the following to your `gitlab-ci.yml` file: +artifacts, add the following to your `.gitlab-ci.yml` file: -```json +```yaml dast: dependencies: [] ``` diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index 48a784e0d03..055a2ceb161 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -897,7 +897,7 @@ variables: ### Exclude Paths -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211892) in GitLab 14.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211892) in GitLab 14.0. When testing an API it can be useful to exclude certain paths. For example, you might exclude testing of an authentication service or an older version of the API. To exclude paths, use the `FUZZAPI_EXCLUDE_PATHS` CI/CD variable . This variable is specified in your `.gitlab-ci.yml` file. To exclude multiple paths, separate entries using the `;` character. In the provided paths you can use a single character wildcard `?` and `*` for a multiple character wildcard. diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index 1cb21d34853..edfd0333d54 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10075) in GitLab Ultimate 12.0. Use the dependency list to review your project's dependencies and key -details about those dependencies, including their known vulnerabilities. It is a collection of dependencies in your project, including existing and new findings. +details about those dependencies, including their known vulnerabilities. It is a collection of dependencies in your project, including existing and new findings. To see the dependency list, go to your project and select **Security & Compliance > Dependency List**. @@ -49,7 +49,7 @@ can also be sorted by name or by the packager that installed them. If a dependency has known vulnerabilities, view them by clicking the arrow next to the dependency's name or the badge that indicates how many known vulnerabilities exist. For each vulnerability, its severity and description appears below it. To view more details of a vulnerability, -select the vulnerability’s description. The [vulnerability's details](../vulnerabilities) page is opened. +select the vulnerability's description. The [vulnerability's details](../vulnerabilities) page is opened. ### Dependency paths @@ -78,8 +78,8 @@ 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. Note that the dependency list only shows the results of the last successful pipeline to run on the default branch. ### Using the API -You can download your project’s list of dependencies [using the API](../../../api/dependencies.md#list-project-dependencies). Note this only provides the dependencies identified by the gemnasium family of analyzers and [not any other of the GitLab dependency analyzers](../dependency_scanning/analyzers.md). +You can download your project's list of dependencies [using the API](../../../api/dependencies.md#list-project-dependencies). Note this only provides the dependencies identified by the gemnasium family of analyzers and [not any other of the GitLab dependency analyzers](../dependency_scanning/analyzers.md). diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 565b9c29934..d903ce58982 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -57,8 +57,8 @@ However, you can override the selection using the variable `DS_EXCLUDED_ANALYZER The language detection relies on CI job [`rules`](../../../ci/yaml/index.md#rules) and searches a maximum of two directory levels from the repository's root. For example, the -`gemnasium-dependency_scanning` job is enabled if a repository contains either a `Gemfile` or -`api/Gemfile` file, but not if the only supported dependency file is `api/client/Gemfile`. +`gemnasium-dependency_scanning` job is enabled if a repository contains either `Gemfile`, +`api/Gemfile`, or `api/client/Gemfile`, but not if the only supported dependency file is `api/v1/client/Gemfile`. The following languages and dependency managers are supported: @@ -147,7 +147,7 @@ table.supported-languages ul { </tr> <tr> <td rowspan="2">Java</td> - <td><a href="https://gradle.org/">Gradle</a></td> + <td><a href="https://gradle.org/">Gradle</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers">1</a></b></sup></td> <td>Any</td> <td> <ul> @@ -228,7 +228,7 @@ table.supported-languages ul { <td> <ul> <li><a href="https://pipenv.pypa.io/en/latest/basics/#example-pipfile-pipfile-lock"><code>Pipfile</code></a></li> - <li><a href="https://pipenv.pypa.io/en/latest/basics/#example-pipfile-pipfile-lock"><code>Pipfile.lock</code></a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers">1</a></b></sup></li> + <li><a href="https://pipenv.pypa.io/en/latest/basics/#example-pipfile-pipfile-lock"><code>Pipfile.lock</code></a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers">2</a></b></sup></li> </ul> </td> <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> @@ -236,7 +236,7 @@ table.supported-languages ul { </tr> <tr> <td>Scala</td> - <td><a href="https://www.scala-sbt.org/">sbt</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers">2</a></b></sup></td> + <td><a href="https://www.scala-sbt.org/">sbt</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers">3</a></b></sup></td> <td>Any</td> <td><code>build.sbt</code></td> <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> @@ -247,6 +247,8 @@ table.supported-languages ul { ### Notes regarding supported languages and package managers +1. Although Gradle with Java 8 is supported, there are other issues such that Android project builds are not supported at this time. Please see the backlog issue [Android support for Dependency Scanning (gemnasium-maven)](https://gitlab.com/gitlab-org/gitlab/-/issues/336866) for more details. + 1. The presence of a `Pipfile.lock` file alone will _not_ trigger the analyzer; the presence of a `Pipfile` is still required in order for the analyzer to be executed. However, if a `Pipfile.lock` file is found, it will be used by `Gemnasium` to scan the exact package versions listed in this file. @@ -262,7 +264,7 @@ GitLab relies on [`rules:exists`](../../../ci/yaml/index.md#rulesexists) to star `Supported files` in the repository as shown in the [table above](#supported-languages-and-package-managers). The current detection logic limits the maximum search depth to two levels. For example, the `gemnasium-dependency_scanning` job is enabled if -a repository contains either a `Gemfile.lock` or `api/Gemfile.lock` file, but not if the only supported dependency file is `api/client/Gemfile.lock`. +a repository contains either a `Gemfile.lock`, `api/Gemfile.lock`, or `api/client/Gemfile.lock`, but not if the only supported dependency file is `api/v1/client/Gemfile.lock`. ### How multiple files are processed @@ -287,13 +289,13 @@ We execute both analyzers because they use different sources of vulnerability da #### Python -We only execute one build in the directory where a requirements file has been detected, such as `requirements.txt` or any +We only execute one installation in the directory where a requirements file has been detected, such as `requirements.txt` or any variation of this file (for example, `requirements.pip` or `requires.txt`). #### Java and Scala We only execute one build in the directory where a build file has been detected, such as `build.sbt` or `build.gradle`. -Please note, we support the following types of Java project stuctures: +Please note, we support the following types of Java project structures: - [multi-project sbt builds](https://www.scala-sbt.org/1.x/docs/Multi-Project.html) - [multi-project gradle builds](https://docs.gradle.org/current/userguide/intro_multi_project_builds.html) @@ -908,3 +910,19 @@ with a dependency on this version of Python should use `retire.js` version 2.10. ### Error: `dependency_scanning is used for configuration only, and its script should not be executed` For information on this, see the [GitLab Secure troubleshooting section](../index.md#error-job-is-used-for-configuration-only-and-its-script-should-not-be-executed). + +### Import multiple certificates for Java-based projects + +The `gemnasium-maven` analyzer reads the contents of the `ADDITIONAL_CA_CERT_BUNDLE` variable using `keytool`, which imports either a single certificate or a certificate chain. Multiple unrelated certificates are ignored and only the first one is imported by `keytool`. + +To add multiple unrelated certificates to the analyzer, you can declare a `before_script` such as this in the definition of the `gemnasium-maven-dependency_scanning` job: + +```yaml +gemnasium-maven-dependency_scanning: + before_script: + - . $HOME/.bashrc # make the java tools available to the script + - OIFS="$IFS"; IFS=""; echo $ADDITIONAL_CA_CERT_BUNDLE > multi.pem; IFS="$OIFS" # write ADDITIONAL_CA_CERT_BUNDLE variable to a PEM file + - csplit -z --digits=2 --prefix=cert multi.pem "/-----END CERTIFICATE-----/+1" "{*}" # split the file into individual certificates + - for i in `ls cert*`; do keytool -v -importcert -alias "custom-cert-$i" -file $i -trustcacerts -noprompt -storepass changeit -keystore /opt/asdf/installs/java/adoptopenjdk-11.0.7+10.1/lib/security/cacerts 1>/dev/null 2>&1 || true; done # import each certificate using keytool (note the keystore location is related to the Java version being used and should be changed accordingly for other versions) + - unset ADDITIONAL_CA_CERT_BUNDLE # unset the variable so that the analyzer doesn't duplicate the import +``` diff --git a/doc/user/application_security/img/mr_security_scanning_results_v14_3.png b/doc/user/application_security/img/mr_security_scanning_results_v14_3.png Binary files differnew file mode 100644 index 00000000000..3e0113dfb46 --- /dev/null +++ b/doc/user/application_security/img/mr_security_scanning_results_v14_3.png diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 50fd727b892..7b95769a81f 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -159,7 +159,9 @@ We recommended you run a scan of the `default` branch before enabling feature br 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. -From the merge request security widget, select **Expand** to unfold the widget, displaying any new and no longer detected (removed) findings by scan type. Select **View Full Report** to go directly to the **Security** tab in the latest branch pipeline. +From the merge request security widget, select **Expand** to unfold the widget, displaying any new and no longer detected (removed) findings by scan type. Select **View full report** to go directly to the **Security** tab in the latest branch pipeline. + + ## View security scan information in the pipeline Security tab @@ -221,7 +223,8 @@ For this approval group, you must set the number of approvals required to greate Follow these steps to enable `Vulnerability-Check`: -1. Go to your project and select **Settings > General**. +1. On the top bar, select **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. Set the **Security scanners** that the rule applies to. @@ -269,7 +272,7 @@ under your project's settings: ## DAST On-Demand Scans -If you don’t want scans running in your normal DevOps process you can use on-demand scans instead. For more details, see [on-demand scans](dast/index.md#on-demand-scans). This feature is only available for DAST. If you run an on-demand scan against the default branch, it is reported as a "successful pipeline" and these results are included in the security dashboard and vulnerability report. +If you don't want scans running in your normal DevOps process you can use on-demand scans instead. For more details, see [on-demand scans](dast/index.md#on-demand-scans). This feature is only available for DAST. If you run an on-demand scan against the default branch, it is reported as a "successful pipeline" and these results are included in the security dashboard and vulnerability report. ## Security report validation @@ -337,6 +340,16 @@ For more details about which findings or vulnerabilities you can view in each of ## Troubleshooting +### Secure job failing with exit code 1 + +If a Secure job is failing and it's unclear why, add `SECURE_LOG_LEVEL: "debug"` as a global CI/CD variable for +more verbose output that is helpful for troubleshooting. + +```yaml +variables: + SECURE_LOG_LEVEL: "debug" +``` + ### Outdated security reports When a security report generated for a merge request becomes outdated, the merge request shows a warning diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index 3bf9d85cd0b..cdf54070d69 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -111,7 +111,7 @@ example of such a transfer: GitLab provides a [vendored template](../../../ci/yaml/index.md#includetemplate) to ease this process. -This template should be used in a new, empty project, with a `gitlab-ci.yml` file containing: +This template should be used in a new, empty project, with a `.gitlab-ci.yml` file containing: ```yaml include: diff --git a/doc/user/application_security/policies/img/container_policy_rule_mode_v14_3.png b/doc/user/application_security/policies/img/container_policy_rule_mode_v14_3.png Binary files differnew file mode 100644 index 00000000000..b21d0330b2f --- /dev/null +++ b/doc/user/application_security/policies/img/container_policy_rule_mode_v14_3.png diff --git a/doc/user/application_security/policies/img/container_policy_yaml_mode_v14_3.png b/doc/user/application_security/policies/img/container_policy_yaml_mode_v14_3.png Binary files differnew file mode 100644 index 00000000000..31d5eb57228 --- /dev/null +++ b/doc/user/application_security/policies/img/container_policy_yaml_mode_v14_3.png diff --git a/doc/user/application_security/policies/img/policies_list_v14_3.png b/doc/user/application_security/policies/img/policies_list_v14_3.png Binary files differnew file mode 100644 index 00000000000..7a24860d4a7 --- /dev/null +++ b/doc/user/application_security/policies/img/policies_list_v14_3.png diff --git a/doc/user/application_security/policies/img/scan_execution_policy_yaml_mode_v14_3.png b/doc/user/application_security/policies/img/scan_execution_policy_yaml_mode_v14_3.png Binary files differnew file mode 100644 index 00000000000..d04905eda59 --- /dev/null +++ b/doc/user/application_security/policies/img/scan_execution_policy_yaml_mode_v14_3.png diff --git a/doc/user/application_security/policies/img/security_policy_project_v14_3.png b/doc/user/application_security/policies/img/security_policy_project_v14_3.png Binary files differnew file mode 100644 index 00000000000..5e3aefaeb81 --- /dev/null +++ b/doc/user/application_security/policies/img/security_policy_project_v14_3.png diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md index 3d0135678b7..bd143d8608a 100644 --- a/doc/user/application_security/policies/index.md +++ b/doc/user/application_security/policies/index.md @@ -4,57 +4,189 @@ group: Container Security info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Scan Policies **(ULTIMATE)** +# Policies **(ULTIMATE)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5329) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.10. -> - Deployed behind a feature flag, disabled by default. -> - Disabled on GitLab.com. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5329) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.10. Deployed behind a feature flag, disabled by default. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/321258) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 14.3. -Scan Policies in GitLab provide security teams a way to require scans of their choice to be run +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, +ask an administrator to [disable the `security_orchestration_policies_configuration` flag](../../../administration/feature_flags.md). +On GitLab.com, this feature is available. + +Policies in GitLab provide security teams a way to require scans of their choice to be run whenever a project pipeline runs according to the configuration specified. Security teams can therefore be confident that the scans they set up have not been changed, altered, or disabled. You -can access these by navigating to your project's **Security & Compliance > Scan Policies** page. +can access these by navigating to your project's **Security & Compliance > Policies** page. GitLab supports the following security policies: +- [Container Network Policy](#container-network-policy) - [Scan Execution Policy](#scan-execution-policy-schema) -WARNING: -Scan Policies is under development and is not ready for production use. It's deployed behind a -feature flag that's disabled by default. +## Policy management -NOTE: -We recommend using the [Security Policies project](#security-policies-project) -exclusively for managing policies for the project. Do not add your application's source code to such -projects. +The Policies page displays deployed +policies for all available environments. You can check a +policy's information (for example description, enforcement +status, etc.), and create and edit deployed policies: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Policies**. + + + +Network policies are fetched directly from the selected environment's +deployment platform while other policies are fetched from the project's +security policy project. Changes performed outside of this tab are +reflected upon refresh. + +By default, the policy list contains predefined network policies in a +disabled state. Once enabled, a predefined policy deploys to the +selected environment's deployment platform and you can manage it like +the regular policies. + +Note that if you're using [Auto DevOps](../../../topics/autodevops/index.md) +and change a policy in this section, your `auto-deploy-values.yaml` file doesn't update. Auto DevOps +users must make changes by following the +[Container Network Policy documentation](../../../topics/autodevops/stages.md#network-policy). + +## Policy editor + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3403) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4. + +You can use the policy editor to create, edit, and delete policies: + +1. On the top bar, select **Menu > Projects** and find your group. +1. On the left sidebar, select **Security & Compliance > Policies**. + - To create a new policy, select **New policy** which is located in the **Policies** page's header. + - To edit an existing policy, select **Edit policy** in the selected policy drawer. + +The policy editor has two modes: + +- The visual _Rule_ mode allows you to construct and preview policy + rules using rule blocks and related controls. + +  + +- YAML mode allows you to enter a policy definition in `.yaml` format + and is aimed at expert users and cases that the Rule mode doesn't + support. + +  + +You can use both modes interchangeably and switch between them at any +time. If a YAML resource is incorrect or contains data not supported +by the Rule mode, Rule mode is automatically +disabled. If the YAML is incorrect, you must use YAML +mode to fix your policy before Rule mode is available again. -## Enable or disable scan policies +## Container Network Policy -Scan Policies is under development and is not ready for production use. It's deployed behind a -feature flag that's disabled by default. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can enable it for your instance. Scan Policies can be enabled or disabled per-project. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32365) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. -To enable it: +The **Container Network Policy** section provides packet flow metrics for +your application's Kubernetes namespace. This section has the following +prerequisites: -```ruby -# Instance-wide -Feature.enable(:security_orchestration_policies_configuration) -# or by project -Feature.enable(:security_orchestration_policies_configuration, Project.find(<project ID>)) +- Your project contains at least one [environment](../../../ci/environments/index.md). +- You've [installed Cilium](../../project/clusters/protect/container_network_security/quick_start_guide.md#use-the-cluster-management-template-to-install-cilium). +- You've configured the [Prometheus service](../../project/integrations/prometheus.md#enabling-prometheus-integration). + +If you're using custom Helm values for Cilium, you must enable Hubble +with flow metrics for each namespace by adding the following lines to +your [Cilium values](../../project/clusters/protect/container_network_security/quick_start_guide.md#use-the-cluster-management-template-to-install-cilium): + +```yaml +hubble: + enabled: true + metrics: + enabled: + - 'flow:sourceContext=namespace;destinationContext=namespace' ``` -To disable it: +The **Container Network Policy** section displays the following information +about your packet flow: + +- The total amount of the inbound and outbound packets +- The proportion of packets dropped according to the configured + policies +- The per-second average rate of the forwarded and dropped packets + accumulated over time window for the requested time interval -```ruby -# Instance-wide -Feature.disable(:security_orchestration_policies_configuration) -# or by project -Feature.disable(:security_orchestration_policies_configuration, Project.find(<project ID>)) +If a significant percentage of packets is dropped, you should +investigate it for potential threats by +examining the Cilium logs: + +```shell +kubectl -n gitlab-managed-apps logs -l k8s-app=cilium -c cilium-monitor ``` +### Change the enforcement status + +To change a network policy's enforcement status: + +- Select the network policy you want to update. +- Select **Edit policy**. +- Select the **Policy status** toggle to update the selected policy. +- Select **Save changes** to deploy network policy changes. + +Disabled network policies have the `network-policy.gitlab.com/disabled_by: gitlab` selector inside +the `podSelector` block. This narrows the scope of such a policy and as a result it doesn't affect +any pods. The policy itself is still deployed to the corresponding deployment namespace. + +### Container Network Policy editor + +The policy editor only supports the [CiliumNetworkPolicy](https://docs.cilium.io/en/v1.8/policy/) +specification. Regular Kubernetes [NetworkPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#networkpolicy-v1-networking-k8s-io) +resources aren't supported. + +Rule mode supports the following rule types: + +- [Labels](https://docs.cilium.io/en/v1.8/policy/language/#labels-based). +- [Entities](https://docs.cilium.io/en/v1.8/policy/language/#entities-based). +- [IP/CIDR](https://docs.cilium.io/en/v1.8/policy/language/#ip-cidr-based). Only + the `toCIDR` block without `except` is supported. +- [DNS](https://docs.cilium.io/en/v1.8/policy/language/#dns-based). +- [Level 4](https://docs.cilium.io/en/v1.8/policy/language/#layer-4-examples) + can be added to all other rules. + +Once your policy is complete, save it by selecting **Save policy** +at the bottom of the editor. Existing policies can also be +removed from the editor interface by selecting **Delete policy** +at the bottom of the editor. + +### Configure a Network Policy Alert + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3438) and [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/287676) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.9. +> - The feature flag was removed and the Threat Monitoring Alerts Project was [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/287676) in GitLab 14.0. + +You can use policy alerts to track your policy's impact. Alerts are only available if you've +[installed](../../clusters/agent/repository.md) +and [configured](../../clusters/agent/index.md#create-an-agent-record-in-gitlab) +a Kubernetes Agent for this project. + +There are two ways to create policy alerts: + +- In the [policy editor UI](#container-network-policy-editor), + by clicking **Add alert**. +- In the policy editor's YAML mode, through the `metadata.annotations` property: + + ```yaml + metadata: + annotations: + app.gitlab.com/alert: 'true' + ``` + +Once added, the UI updates and displays a warning about the dangers of too many alerts. + ## Security Policies project +NOTE: +We recommend using the [Security Policies project](#security-policies-project) +exclusively for managing policies for the project. Do not add your application's source code to such +projects. + The Security Policies feature is a repository to store policies. All security policies are stored as the `.gitlab/security-policies/policy.yml` YAML file with this format: @@ -85,6 +217,40 @@ scan_execution_policy: site_profile: Site Profile D ``` +## Security Policy project selection + +NOTE: +Only project Owners have the [permissions](../../permissions.md#project-members-permissions) +to select Security Policy Project. + +When the Security Policy project is created and policies are created within that repository, you +must create an association between that project and the project you want to apply policies to: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Policies**. +1. Select **Edit Policy Project**, and search for and select the + project you would like to link from the dropdown menu. +1. Select **Save**. + +  + +### Scan Execution Policy editor + +NOTE: +Only project Owners have the [permissions](../../permissions.md#project-members-permissions) +to select Security Policy Project. + +Once your policy is complete, save it by selecting **Create merge request** +at the bottom of the editor. You will be redirected to the merge request on the project's +configured security policy project. If one does not link to your project, a security +policy project will be automatically created. Existing policies can also be +removed from the editor interface by selecting **Delete policy** +at the bottom of the editor. + + + +The policy editor currently only supports the YAML mode. The Rule mode is tracked in the [Allow Users to Edit Rule-mode Scan Execution Policies in the Policy UI](https://gitlab.com/groups/gitlab-org/-/epics/5363) epic. + ### Scan Execution Policies Schema The YAML file with Scan Execution Policies consists of an array of objects matching Scan Execution Policy Schema nested under the `scan_execution_policy` key. You can configure a maximum of 5 policies under the `scan_execution_policy` key. @@ -121,6 +287,16 @@ This rule enforces the defined actions and schedules a scan on the provided date | `type` | `string` | `schedule` | The rule's type. | | `branches` | `array` of `string` | `*` or the branch's name | The branch the given policy applies to (supports wildcard). | | `cadence` | `string` | CRON expression (for example, `0 0 * * *`) | A whitespace-separated string containing five fields that represents the scheduled time. | +| `clusters` | `object` | | The cluster where the given policy will enforce running selected scans (only for `container_scanning`/`cluster_image_scanning` scans). The key of the object is the name of the Kubernetes cluster configured for your project in GitLab. In the optionally provided value of the object, you can precisely select Kubernetes resources that will be scanned. | + +#### `cluster` schema + +| Field | Type | Possible values | Description | +|--------------|---------------------|--------------------------|-------------| +| `containers` | `array` of `string` | | The container name that will be scanned (only the first value is currently supported). | +| `resources` | `array` of `string` | | The resource name that will be scanned (only the first value is currently supported). | +| `namespaces` | `array` of `string` | | The namespace that will be scanned (only the first value is currently supported). | +| `kinds` | `array` of `string` | `deployment`/`daemonset` | The resource kind that should be scanned (only the first value is currently supported). | ### `scan` action type @@ -149,6 +325,9 @@ Note the following: - A secret detection scan runs in `normal` mode when executed as part of a pipeline, and in [`historic`](../secret_detection/index.md#full-history-secret-scan) mode when executed as part of a scheduled scan. +- A container scanning and cluster image scanning scans configured for the `pipeline` rule type will ignore the cluster defined in the `clusters` object. + They will use predefined CI/CD variables defined for your project. Cluster selection with the `clusters` object is supported for the `schedule` rule type. + Cluster with name provided in `clusters` object must be created and configured for the project. To be able to successfully perform the `container_scanning`/`cluster_image_scanning` scans for the cluster you must follow instructions for the [Cluster Image Scanning feature](../cluster_image_scanning/index.md#prerequisites). Here's an example: @@ -179,8 +358,8 @@ scan_execution_policy: scanner_profile: Scanner Profile C site_profile: Site Profile D - scan: secret_detection -- name: Enforce Secret Detection in every default branch pipeline - description: This policy enforces pipeline configuration to have a job with Secret Detection scan for the default branch +- name: Enforce Secret Detection and Container Scanning in every default branch pipeline + description: This policy enforces pipeline configuration to have a job with Secret Detection and Container Scanning scans for the default branch enabled: true rules: - type: pipeline @@ -188,6 +367,25 @@ scan_execution_policy: - main actions: - scan: secret_detection + - scan: container_scanning +- name: Enforce Cluster Image Scanning on production-cluster every 24h + description: This policy enforces Cluster Image Scanning scan to run every 24 hours + enabled: true + rules: + - type: schedule + cadence: '15 3 * * *' + clusters: + production-cluster: + containers: + - database + resources: + - production-application + namespaces: + - production-namespace + kinds: + - deployment + actions: + - scan: cluster_image_scanning ``` In this example: @@ -196,22 +394,9 @@ In this example: `release/v1.2.1`), DAST scans run with `Scanner Profile A` and `Site Profile B`. - DAST and secret detection scans run every 10 minutes. The DAST scan runs with `Scanner Profile C` and `Site Profile D`. -- Secret detection scans run for every pipeline executed on the `main` branch. - -## Security Policy project selection - -When the Security Policy project is created and policies are created within that repository, you -must create an association between that project and the project you want to apply policies to. To do -this, navigate to your project's **Security & Compliance > Policies**, select -**Security policy project** from the dropdown menu, then select the **Create policy** button to save -changes. - -You can always change the **Security policy project** by navigating to your project's -**Security & Compliance > Policies** and modifying the selected project. - -NOTE: -Only project Owners have the [permissions](../../permissions.md#project-members-permissions) -to select Security Policy Project. +- Secret detection and container scanning scans run for every pipeline executed on the `main` branch. +- Cluster Image Scanning scan runs every 24h. The scan runs on the `production-cluster` cluster and fetches vulnerabilities + from the container with the name `database` configured for deployment with the name `production-application` in the `production-namespace` namespace. ## Roadmap diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index 661a4ee8e82..d399dcaf4a9 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -65,8 +65,8 @@ Any custom change to the official analyzers can be achieved by using a You can switch to a custom Docker registry that provides the official analyzer images under a different prefix. For instance, the following instructs -SAST to pull `my-docker-registry/gl-images/bandit` -instead of `registry.gitlab.com/gitlab-org/security-products/analyzers/bandit`. +SAST to pull `my-docker-registry/gl-images/sast/bandit` +instead of `registry.gitlab.com/security-products/sast/bandit`. In `.gitlab-ci.yml` define: ```yaml diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 6e88f38d900..3caa1771a5b 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -361,6 +361,9 @@ To create a custom ruleset: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292686) in GitLab 14.2. +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the `vulnerability_flags` flag](../../../administration/feature_flags.md). On GitLab.com, this feature is available. + Vulnerabilities that have been detected and are false positives will be flagged as false positives in the security dashboard. ### Using CI/CD variables to pass credentials for private repositories @@ -669,19 +672,19 @@ import the following default SAST analyzer images from `registry.gitlab.com` int [local Docker container registry](../../packages/container_registry/index.md): ```plaintext -registry.gitlab.com/gitlab-org/security-products/analyzers/bandit:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/brakeman:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/eslint:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/flawfinder:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/gosec:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/kubesec:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/pmd-apex:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/security-code-scan:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/semgrep:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/sobelow:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/spotbugs:2 +registry.gitlab.com/security-products/sast/bandit:2 +registry.gitlab.com/security-products/sast/brakeman:2 +registry.gitlab.com/security-products/sast/eslint:2 +registry.gitlab.com/security-products/sast/flawfinder:2 +registry.gitlab.com/security-products/sast/gosec:3 +registry.gitlab.com/security-products/sast/kubesec:2 +registry.gitlab.com/security-products/sast/nodejs-scan:2 +registry.gitlab.com/security-products/sast/phpcs-security-audit:2 +registry.gitlab.com/security-products/sast/pmd-apex:2 +registry.gitlab.com/security-products/sast/security-code-scan:2 +registry.gitlab.com/security-products/sast/semgrep:2 +registry.gitlab.com/security-products/sast/sobelow:2 +registry.gitlab.com/security-products/sast/spotbugs:2 ``` The process for importing Docker images into a local offline Docker registry depends on diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index b6ff68c861b..cd1014d36a6 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -35,7 +35,7 @@ GitLab displays identified secrets visibly in a few places: Secret Detection detects a variety of common secrets by default. You can also customize the secret detection patterns using [custom rulesets](#custom-rulesets). -The [default ruleset provided by Gitleaks](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/blob/master/gitleaks.toml) includes the following key types: +The [default ruleset provided by TruffleHog and Gitleaks](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/blob/master/gitleaks.toml) includes the following key types: - Cloud services: - Amazon Web Services (AWS) @@ -89,12 +89,13 @@ However not all features are available on every tier. See the breakdown below fo Different features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), as shown in the following table: -| Capability | In Free | In Ultimate | +| Capability | In Free & Premium | In Ultimate | |:----------------------------------------------------------------|:--------------------|:-------------------| | [Configure Secret Detection Scanners](#configuration) | **{check-circle}** | **{check-circle}** | | [Customize Secret Detection Settings](#customizing-settings) | **{check-circle}** | **{check-circle}** | | View [JSON Report](../sast/index.md#reports-json-format) | **{check-circle}** | **{check-circle}** | | Presentation of JSON Report in Merge Request | **{dotted-circle}** | **{check-circle}** | +| View identified secrets in the pipelines' **Security** tab | **{dotted-circle}** | **{check-circle}** | | [Interaction with Vulnerabilities](../vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | | [Access to Security Dashboard](../security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | @@ -330,7 +331,7 @@ Import the following default Secret Detection analyzer images from `registry.git [local Docker container registry](../../packages/container_registry/index.md): ```plaintext -registry.gitlab.com/gitlab-org/security-products/analyzers/secrets:3 +registry.gitlab.com/security-products/secret-detection:3 ``` The process for importing Docker images into a local offline Docker registry depends on diff --git a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_2.png b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_2.png Binary files differindex 3a195a5ce8d..52249cef343 100644 --- a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_2.png +++ b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_2.png diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index b799177ec5a..c78179e9693 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -46,7 +46,7 @@ The security dashboard and vulnerability report displays information about vulne ## Pipeline Security -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13496) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13496) in GitLab 12.3. At the pipeline level, the Security section displays the vulnerabilities present in the branch of the project the pipeline ran against. @@ -64,7 +64,7 @@ the analyzer outputs an ### Scan details -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3728) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.10. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3728) in GitLab 13.10. The **Scan details** section lists the scans run in the pipeline and the total number of vulnerabilities per scan. For the DAST scan, select **Download scanned resources** to download a @@ -104,7 +104,7 @@ To download an SVG image of the chart, select **Save chart to an image** (**{dow ## Group Security Dashboard -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6709) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6709) in GitLab 11.5. The group Security Dashboard gives an overview of the vulnerabilities found in the default branches of the projects in a group and its subgroups. Access it by navigating to **Security > Security Dashboard** @@ -139,7 +139,7 @@ Navigate to the group's [vulnerability report](../vulnerability_report/index.md) ## Security Center -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3426) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3426) in GitLab 13.4. The Security Center is personal space where you manage vulnerabilities across all your projects. It displays the vulnerabilities present in the default branches of all the projects you configure. It includes @@ -166,22 +166,17 @@ To add projects to the Security Center: After you add projects, the security dashboard and vulnerability report display the vulnerabilities found in those projects' default branches. -## Keeping the dashboards up to date +## Keep dashboards up to date -The Security Dashboard displays information from the results of the most recent -security scan on the [default branch](../../project/repository/branches/default.md), -which means that security scans are performed every time the branch is updated. - -If the default branch is updated infrequently, scans are run infrequently and the -information on the Security Dashboard can become outdated as new vulnerabilities -are discovered. +The Security Dashboard displays results of the most recent security scan on the +[default branch](../../project/repository/branches/default.md). By default, security scans are run +only when the default branch is updated. Information on the Security Dashboard may not reflect +newly-discovered vulnerabilities. To ensure the information on the Security Dashboard is regularly updated, -[configure a scheduled pipeline](../../../ci/pipelines/schedules.md) to run a -daily security scan. This updates the information displayed on the Security -Dashboard regardless of how often the default branch is updated. - -That way, reports are created even if no code change happens. +[configure a scheduled pipeline](../../../ci/pipelines/schedules.md) to run a daily security scan. +This updates the information displayed on the Security Dashboard regardless of how often the default +branch is updated. WARNING: Running Dependency Scanning from a scheduled pipeline might result in false negatives if your @@ -191,12 +186,6 @@ can occur because the dependency version resolved during the scan might differ f resolved when your project was built and released, in a previous pipeline. Java projects can't have lock files. Python projects can have lock files, but GitLab Secure tools don't support them. -## Security scans using Auto DevOps - -When using [Auto DevOps](../../../topics/autodevops/index.md), use -[special environment variables](../../../topics/autodevops/customize.md#cicd-variables) -to configure daily security scans. - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/application_security/terminology/index.md b/doc/user/application_security/terminology/index.md index c96497e9233..8277c30b81f 100644 --- a/doc/user/application_security/terminology/index.md +++ b/doc/user/application_security/terminology/index.md @@ -38,6 +38,12 @@ The different places in an application that are vulnerable to attack. Secure pro search the attack surface during scans. Each product defines the attack surface differently. For example, SAST uses files and line numbers, and DAST uses URLs. +### Corpus + +The set of meaningful test cases that are generated while the fuzzer is running. Each meaningful +test case produces new coverage in the tested program. It's advised to re-use the corpus and pass it +to subsequent runs. + ### CVE Common Vulnerabilities and Exposures (CVE®) is a list of common identifiers for publicly known @@ -142,6 +148,12 @@ A standard report format that Secure products comply with when creating JSON rep Provides an overview of all the vulnerabilities for a project, group, or GitLab instance. Vulnerabilities are only created from findings discovered on the project's default branch. +### Seed corpus + +The set of test cases given as initial input to the fuzz target. This usually speeds up the fuzz +target substantially. This can be either manually created test cases or auto-generated with the fuzz +target itself from previous runs. + ### Vendor The party maintaining an analyzer. As such, a vendor is responsible for integrating a scanner into diff --git a/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_12.png b/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_12.png Binary files differdeleted file mode 100644 index e165c7e6ceb..00000000000 --- a/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_12.png +++ /dev/null diff --git a/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v14_3.png b/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v14_3.png Binary files differnew file mode 100644 index 00000000000..a11a7fafc4a --- /dev/null +++ b/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v14_3.png diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md index 8cecb9c5929..79f202a6edb 100644 --- a/doc/user/application_security/threat_monitoring/index.md +++ b/doc/user/application_security/threat_monitoring/index.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14707) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. -The **Threat Monitoring** page provides metrics and policy management +The **Threat Monitoring** page provides alerts and metrics for the GitLab application runtime security features. You can access these by navigating to your project's **Security & Compliance > Threat Monitoring** page. @@ -18,153 +18,7 @@ GitLab supports statistics for the following security features: - [Container Network Policies](../../../topics/autodevops/stages.md#network-policy) -## Container Network Policy - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32365) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. - -The **Container Network Policy** section provides packet flow metrics for -your application's Kubernetes namespace. This section has the following -prerequisites: - -- Your project contains at least one [environment](../../../ci/environments/index.md) -- You've [installed Cilium](../../project/clusters/protect/container_network_security/quick_start_guide.md#use-the-cluster-management-template-to-install-cilium) -- You've configured the [Prometheus service](../../project/integrations/prometheus.md#enabling-prometheus-integration) - -If you're using custom Helm values for Cilium, you must enable Hubble -with flow metrics for each namespace by adding the following lines to -your [Cilium values](../../project/clusters/protect/container_network_security/quick_start_guide.md#use-the-cluster-management-template-to-install-cilium): - -```yaml -hubble: - enabled: true - metrics: - enabled: - - 'flow:sourceContext=namespace;destinationContext=namespace' -``` - -The **Container Network Policy** section displays the following information -about your packet flow: - -- The total amount of the inbound and outbound packets -- The proportion of packets dropped according to the configured - policies -- The per-second average rate of the forwarded and dropped packets - accumulated over time window for the requested time interval - -If a significant percentage of packets is dropped, you should -investigate it for potential threats by -examining the Cilium logs: - -```shell -kubectl -n gitlab-managed-apps logs -l k8s-app=cilium -c cilium-monitor -``` - -## Container Network Policy management - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3328) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. - -The **Threat Monitoring** page's **Policy** tab displays deployed -network policies for all available environments. You can check a -network policy's `yaml` manifest, its enforcement -status, and create and edit deployed policies. This section has the -following prerequisites: - -- Your project contains at least one [environment](../../../ci/environments/index.md) -- You've [installed Cilium](../../project/clusters/protect/container_network_security/quick_start_guide.md#use-the-cluster-management-template-to-install-cilium) - -Network policies are fetched directly from the selected environment's -deployment platform. Changes performed outside of this tab are -reflected upon refresh. - -By default, the network policy list contains predefined policies in a -disabled state. Once enabled, a predefined policy deploys to the -selected environment's deployment platform and you can manage it like -the regular policies. - -Note that if you're using [Auto DevOps](../../../topics/autodevops/index.md) -and change a policy in this section, your `auto-deploy-values.yaml` file doesn't update. Auto DevOps -users must make changes by following the -[Container Network Policy documentation](../../../topics/autodevops/stages.md#network-policy). - -### Changing enforcement status - -To change a network policy's enforcement status: - -- Click the network policy you want to update. -- Click the **Edit policy** button. -- Click the **Policy status** toggle to update the selected policy. -- Click the **Save changes** button to deploy network policy changes. - -Disabled network policies have the `network-policy.gitlab.com/disabled_by: gitlab` selector inside -the `podSelector` block. This narrows the scope of such a policy and as a result it doesn't affect -any pods. The policy itself is still deployed to the corresponding deployment namespace. - -### Container Network Policy editor - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3403) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4. - -You can use the policy editor to create, edit, and delete policies. - -- To create a new policy, click the **New policy** button located in the **Policy** tab's header. -- To edit an existing policy, click **Edit policy** in the selected policy drawer. - -The policy editor only supports the [CiliumNetworkPolicy](https://docs.cilium.io/en/v1.8/policy/) -specification. Regular Kubernetes [NetworkPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#networkpolicy-v1-networking-k8s-io) -resources aren't supported. - -The policy editor has two modes: - -- The visual _Rule_ mode allows you to construct and preview policy - rules using rule blocks and related controls. -- YAML mode allows you to enter a policy definition in `.yaml` format - and is aimed at expert users and cases that the Rule mode doesn't - support. - -You can use both modes interchangeably and switch between them at any -time. If a YAML resource is incorrect, Rule mode is automatically -disabled. You must use YAML mode to fix your policy before Rule mode -is available again. - -Rule mode supports the following rule types: - -- [Labels](https://docs.cilium.io/en/v1.8/policy/language/#labels-based). -- [Entities](https://docs.cilium.io/en/v1.8/policy/language/#entities-based). -- [IP/CIDR](https://docs.cilium.io/en/v1.8/policy/language/#ip-cidr-based). Only - the `toCIDR` block without `except` is supported. -- [DNS](https://docs.cilium.io/en/v1.8/policy/language/#dns-based). -- [Level 4](https://docs.cilium.io/en/v1.8/policy/language/#layer-4-examples) - can be added to all other rules. - -Once your policy is complete, save it by pressing the **Save policy** -button at the bottom of the editor. Existing policies can also be -removed from the editor interface by clicking the **Delete policy** -button at the bottom of the editor. - -### Configuring Network Policy Alerts - -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3438) and [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/287676) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.9. -> - The feature flag was removed and the Threat Monitoring Alerts Project was [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/287676) in GitLab 14.0. - -You can use policy alerts to track your policy's impact. Alerts are only available if you've -[installed](../../clusters/agent/repository.md) -and [configured](../../clusters/agent/index.md#create-an-agent-record-in-gitlab) -a Kubernetes Agent for this project. - -There are two ways to create policy alerts: - -- In the [policy editor UI](#container-network-policy-editor), - by clicking **Add alert**. -- In the policy editor's YAML mode, through the `metadata.annotations` property: - - ```yaml - metadata: - annotations: - app.gitlab.com/alert: 'true' - ``` - -Once added, the UI updates and displays a warning about the dangers of too many alerts. - -### Container Network Policy Alert list +## Container Network Policy Alert list > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3438) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.9. @@ -184,7 +38,7 @@ the selector menu in the **Status** column to set the status for each alert: By default, the list doesn't display resolved or dismissed alerts. - + Clicking an alert's row opens the alert drawer, which shows more information about the alert. A user can also create an incident from the alert and update the alert status in the alert drawer. diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index a727dc88ffc..9ebecc67704 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -37,7 +37,9 @@ A vulnerability's status can be one of the following: | Detected | The default state for a newly discovered vulnerability. | | Confirmed | A user has seen this vulnerability and confirmed it to be accurate. | | Dismissed | A user has seen this vulnerability and dismissed it because it is not accurate or otherwise not to be resolved. | -| Resolved | The vulnerability has been fixed and is no longer valid. | +| Resolved | The vulnerability has been fixed or is no longer present. | + +Dismissed vulnerabilities are ignored if detected in subsequent scans. Resolved vulnerabilities that are reintroduced and detected by subsequent scans have a _new_ vulnerability record created. When an existing vulnerability is no longer detected in a project's `default` branch, you should change its status to Resolved. This ensures that if it is accidentally reintroduced in a future merge, it will be visible again as a new record. You can use the [Activity filter](../vulnerability_report/#activity-filter) to select all vulnerabilities that are no longer detected, and [change their status](../vulnerability_report#change-status-of-multiple-vulnerabilities). ## Change vulnerability status diff --git a/doc/user/application_security/vulnerability_report/img/group_vulnerability_report_v14_2.png b/doc/user/application_security/vulnerability_report/img/group_vulnerability_report_v14_2.png Binary files differindex 193efe9c386..44c689eda3e 100644 --- a/doc/user/application_security/vulnerability_report/img/group_vulnerability_report_v14_2.png +++ b/doc/user/application_security/vulnerability_report/img/group_vulnerability_report_v14_2.png diff --git a/doc/user/application_security/vulnerability_report/img/project_security_dashboard_status_change_v14_2.png b/doc/user/application_security/vulnerability_report/img/project_security_dashboard_status_change_v14_2.png Binary files differindex 056e051363d..a43340544ca 100644 --- a/doc/user/application_security/vulnerability_report/img/project_security_dashboard_status_change_v14_2.png +++ b/doc/user/application_security/vulnerability_report/img/project_security_dashboard_status_change_v14_2.png diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index c2c2e7459ba..8b811c62ec3 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -145,6 +145,17 @@ To change the status of vulnerabilities in the table:  +### Change status of multiple vulnerabilities + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35816) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. + +You can change the status of multiple vulnerabilities at once: + +1. In the list of vulnerabilities, select the checkbox for each vulnerability you want to update. + To select all, select the checkbox in the table header. +1. Above the table, select a new status. +1. Click **Change status** to save. + ## Export vulnerability details > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213014) in the Security Center (previously known as the Instance Security Dashboard) and project-level Vulnerability Report (previously known as the Project Security Dashboard) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0. @@ -191,14 +202,3 @@ You can dismiss a vulnerability for the entire project: 1. Optional. Add a reason for the dismissal and select **Save comment**. To undo this action, select a different status from the same menu. - -### Dismiss multiple vulnerabilities - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35816) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. - -You can dismiss multiple vulnerabilities at once: - -1. In the list of vulnerabilities, select the checkbox for each vulnerability you want to dismiss. - To select all, select the checkbox in the table header. -1. Above the table, select a dismissal reason. -1. Select **Dismiss Selected**. diff --git a/doc/user/clusters/agent/ci_cd_tunnel.md b/doc/user/clusters/agent/ci_cd_tunnel.md index 09123fdd472..1ea5168f30c 100644 --- a/doc/user/clusters/agent/ci_cd_tunnel.md +++ b/doc/user/clusters/agent/ci_cd_tunnel.md @@ -4,40 +4,52 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# CI/CD Tunnel +# CI/CD Tunnel **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327409) in GitLab 14.1. -> - Pre-configured `KUBECONFIG` [added](https://gitlab.com/gitlab-org/gitlab/-/issues/324275) in GitLab 14.2. +> - The pre-configured `KUBECONFIG` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/324275) in GitLab 14.2. +> - The ability to authorize groups was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. The CI/CD Tunnel enables users to access Kubernetes clusters from GitLab CI/CD jobs even if there is no network connectivity between GitLab Runner and a cluster. GitLab Runner does not have to be running in the same cluster. Only CI/CD jobs set in the configuration project can access one of the configured agents. -Prerequisites: +## Prerequisites - A running [`kas` instance](index.md#set-up-the-kubernetes-agent-server). - A [configuration repository](index.md#define-a-configuration-repository) with an Agent config file installed (`.gitlab/agents/<agent-name>/config.yaml`). - An [Agent record](index.md#create-an-agent-record-in-gitlab). -- The agent is [installed in the cluster](index.md#install-the-agent-into-the-cluster). +- The Agent [installed in the cluster](index.md#install-the-agent-into-the-cluster). -If your project has one or more Agent records, a `KUBECONFIG` variable that is compatible with `kubectl` is provided to your CI/CD jobs. A separate context (`kubecontext`) is available for each configured Agent. By default, no context is selected. +## Use the CI/CD Tunnel to run Kubernetes commands from GitLab CI/CD +If your project has access to one or more Agent records available, its CI/CD +jobs provide a `KUBECONFIG` variable compatible with `kubectl`. + +Also, each Agent has a separate context (`kubecontext`). By default, +there isn't any context selected. Contexts are named in the following format: `<agent-configuration-project-path>:<agent-name>`. +To get the list of available contexts, run `kubectl config get-contexts`. + +## Example for a `kubectl` command using the CI/CD Tunnel -To access your cluster from a CI/CD job through the tunnel: +The following example shows a CI/CD job that runs a `kubectl` command using the CI/CD Tunnel. +You can run any Kubernetes-specific commands similarly, such as `kubectl`, `helm`, +`kpt`, and so on. To do so: -1. In your `.gitlab-ci.yml` select the context for the agent you wish to use: +1. Set your Agent's context in the first command with the format `<agent-configuration-project-path>:<agent-name>`. +1. Run Kubernetes commands. - ```yaml - deploy: - image: - name: bitnami/kubectl:latest - entrypoint: [""] - script: - - kubectl config use-context path/to/agent-configuration-project:your-agent-name - - kubectl get pods - ``` +For example: -1. Execute `kubectl` commands directly against your cluster with this CI/CD job you just created. +```yaml + deploy: + image: + name: bitnami/kubectl:latest + entrypoint: [""] + script: + - kubectl config use-context path/to/agent-configuration-project:your-agent-name + - kubectl get pods +``` diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index c59d2a1f61c..d2dc57c0849 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -20,7 +20,7 @@ tasks in a secure and cloud-native way. It enables: - Pull-based GitOps deployments. - [Inventory object](../../infrastructure/clusters/deploy/inventory_object.md) to keep track of objects applied to your cluster. - Real-time access to API endpoints in a cluster. -- Alert generation based on [Container network policy](../../application_security/threat_monitoring/index.md#container-network-policy). +- Alert generation based on [Container network policy](../../application_security/policies/index.md#container-network-policy). - [CI/CD Tunnel](ci_cd_tunnel.md) that enables users to access Kubernetes clusters from GitLab CI/CD jobs even if there is no network connectivity between GitLab Runner and a cluster. Many more features are planned. Please review [our roadmap](https://gitlab.com/groups/gitlab-org/-/epics/3329) @@ -77,6 +77,8 @@ The setup process involves a few steps to enable GitOps deployments: 1. [Install the Agent into the cluster](#install-the-agent-into-the-cluster). 1. [Create manifest files](#create-manifest-files). +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a GitLab 14.2 [walking-through video](https://www.youtube.com/watch?v=XuBpKtsgGkE) with this process. + ### Upgrades and version compatibility As the GitLab Kubernetes Agent is a new product, we are constantly adding new features @@ -104,7 +106,8 @@ To use the KAS: ### Define a configuration repository -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7, the Agent manifest configuration can be added to multiple directories (or subdirectories) of its repository. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7, the Agent manifest configuration can be added to multiple directories (or subdirectories) of its repository. +> - Group authorization was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. To configure an Agent, you need: @@ -123,6 +126,7 @@ In your repository, add the Agent configuration file under: Your `config.yaml` file specifies all configurations of the Agent, such as: - The manifest projects to synchronize. +- The groups that can access this Agent via the [CI/CD Tunnel](ci_cd_tunnel.md). - The address of the `hubble-relay` for the Network Security policy integrations. As an example, a minimal Agent configuration that sets up only the manifest @@ -174,17 +178,14 @@ To perform a one-liner installation, run the command below. Make sure to replace - `your-agent-token` with the token received from the previous step (identified as `secret` in the JSON output). - `gitlab-kubernetes-agent` with the namespace you defined in the previous step. - `wss://kas.gitlab.example.com` with the configured access of the Kubernetes Agent Server (KAS). For GitLab.com users, the KAS is available under `wss://kas.gitlab.com`. +- `--agent-version=vX.Y.Z` with the latest released patch version matching your GitLab installation's major and minor versions. For example, for GitLab v13.9.0, use `--agent-version=v13.9.1`. You can find your GitLab version under the "Help/Help" menu. ```shell -docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --agent-token=your-agent-token --kas-address=wss://kas.gitlab.example.com --agent-version stable --namespace gitlab-kubernetes-agent | kubectl apply -f - +docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --agent-token=your-agent-token --kas-address=wss://kas.gitlab.example.com --agent-version=vX.Y.Z --namespace gitlab-kubernetes-agent | kubectl apply -f - ``` -Set `--agent-version` to the latest released patch version matching your -GitLab installation's major and minor versions. For example, if you have -GitLab v13.9.0, set `--agent-version=v13.9.1`. - WARNING: -Version `stable` can be used to refer to the latest stable release at the time when the command runs. It's fine for +`--agent-version stable` can be used to refer to the latest stable release at the time when the command runs. It's fine for testing purposes but for production please make sure to specify a matching version explicitly. To find out the various options the above Docker container supports, run: @@ -287,7 +288,7 @@ spec: containers: - name: agent # Make sure to specify a matching version for production - image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:stable" + image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:vX.Y.Z args: - --token-file=/config/token - --kas-address @@ -383,29 +384,16 @@ Each time you push a change to a monitored manifest repository, the Agent logs t #### Example manifest file -This file creates an NGINX deployment. +This file creates a minimal `ConfigMap`: ```yaml -apiVersion: apps/v1 -kind: Deployment +apiVersion: v1 +kind: ConfigMap metadata: - name: nginx-deployment + name: demo-map namespace: gitlab-kubernetes-agent # Can be any namespace managed by you that the agent has access to. -spec: - selector: - matchLabels: - app: nginx - replicas: 2 - template: - metadata: - labels: - app: nginx - spec: - containers: - - name: nginx - image: nginx:1.14.2 - ports: - - containerPort: 80 +data: + key: value ``` ## Example projects @@ -433,8 +421,8 @@ There are several components that work in concert for the Agent to generate the - Enablement of [hubble-relay](https://docs.cilium.io/en/v1.8/concepts/overview/#hubble) on an existing installation. - One or more network policies through any of these options: - - Use the [Container Network Policy editor](../../application_security/threat_monitoring/index.md#container-network-policy-editor) to create and manage policies. - - Use an [AutoDevOps](../../application_security/threat_monitoring/index.md#container-network-policy-management) configuration. + - Use the [Container Network Policy editor](../../application_security/policies/index.md#container-network-policy-editor) to create and manage policies. + - Use an [AutoDevOps](../../application_security/policies/index.md#container-network-policy) configuration. - Add the required labels and annotations to existing network policies. - A configuration repository with [Cilium configured in `config.yaml`](repository.md#surface-network-security-alerts-from-cluster-to-gitlab) diff --git a/doc/user/clusters/agent/repository.md b/doc/user/clusters/agent/repository.md index a3a3e4c29b0..ea57ded3320 100644 --- a/doc/user/clusters/agent/repository.md +++ b/doc/user/clusters/agent/repository.md @@ -9,6 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7. > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in GitLab 13.11, the Kubernetes Agent became available on GitLab.com. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0, the `resource_inclusions` and `resource_exclusions` attributes were removed and `reconcile_timeout`, `dry_run_strategy`, `prune`, `prune_timeout`, `prune_propagation_policy`, and `inventory_policy` attributes were added. +> - The `ci_access` attribute was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -147,6 +148,40 @@ gitops: - glob: '/**/*.yaml' ``` +## Authorize groups to use an Agent + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. + +If you use the same cluster across multiple projects, you can set up the CI/CD Tunnel +to grant the Agent access to one or more groups. This way, all the projects that belong +to the authorized groups can access the same Agent. This enables you to save resources and +have a scalable setup. + +When you authorize a group, the agent's Kubernetes context is automatically injected +into every project of the authorized group, and users can select the connection as +described in the [CI/CD Tunnel documentation](ci_cd_tunnel.md). +To authorize a group to access the Agent through the [CI/CD Tunnel](ci_cd_tunnel.md), +use the `ci_access` attribute in your `config.yaml` configuration file. + +An Agent can only authorize groups in the same group hierarchy as the Agent's configuration project. At most +100 groups can be authorized per Agent. + +To authorize a group: + +1. Edit your `.config.yaml` file under the `.gitlab/agents/<agent name>` directory. +1. Add the `ci_access` attribute. +1. Add the `groups` attribute into `ci_access`. +1. Add the group `id` into `groups`, identifying the authorized group through its path. + +For example: + +```yaml +ci_access: + # This agent is accessible from CI jobs in projects in these groups + groups: + - id: group/subgroup +``` + ## Surface network security alerts from cluster to GitLab The GitLab Agent provides an [integration with Cilium](index.md#kubernetes-network-security-alerts). diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index 5d247f04d3b..2da8396cfd7 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -285,10 +285,10 @@ postgresql: ``` Support for installing the Sentry managed application is provided by the -GitLab Health group. If you run into unknown issues, +GitLab Monitor group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Health group](https://about.gitlab.com/handbook/product/categories/#health-group). +[Monitor group](https://about.gitlab.com/handbook/product/categories/#monitor-group). ### Install PostHog using GitLab CI/CD @@ -366,9 +366,9 @@ project. Refer to the of the Prometheus chart's README for the available configuration options. Support for installing the Prometheus managed application is provided by the -GitLab APM group. If you run into unknown issues, +GitLab Monitor group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at -least 2 people from the [APM group](https://about.gitlab.com/handbook/product/categories/#apm-group). +least 2 people from the [Monitor group](https://about.gitlab.com/handbook/product/categories/#monitor-group). ### Install GitLab Runner using GitLab CI/CD @@ -819,9 +819,9 @@ management project. Refer to the available configuration options. Support for installing the Elastic Stack managed application is provided by the -GitLab APM group. If you run into unknown issues, +GitLab Monitor group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at -least 2 people from the [APM group](https://about.gitlab.com/handbook/product/categories/#apm-group). +least 2 people from the [Monitor group](https://about.gitlab.com/handbook/product/categories/#monitor-group). ### Install Crossplane using GitLab CI/CD diff --git a/doc/user/clusters/environments.md b/doc/user/clusters/environments.md index cb721115e76..cad55f0cf0b 100644 --- a/doc/user/clusters/environments.md +++ b/doc/user/clusters/environments.md @@ -36,7 +36,7 @@ In order to: [deploy to a Kubernetes cluster](../project/clusters/index.md#deploying-to-a-kubernetes-cluster) successfully. - Show pod usage correctly, you must - [enable Deploy Boards](../project/deploy_boards.md#enabling-deploy-boards). + [enable deploy boards](../project/deploy_boards.md#enabling-deploy-boards). After you have successful deployments to your group-level or instance-level cluster: diff --git a/doc/user/clusters/img/advanced-settings-cluster-management-project-v12_5.png b/doc/user/clusters/img/advanced-settings-cluster-management-project-v12_5.png Binary files differdeleted file mode 100644 index 5fd1bac5e05..00000000000 --- a/doc/user/clusters/img/advanced-settings-cluster-management-project-v12_5.png +++ /dev/null diff --git a/doc/user/clusters/integrations.md b/doc/user/clusters/integrations.md index 5e6843144fc..70f940c775b 100644 --- a/doc/user/clusters/integrations.md +++ b/doc/user/clusters/integrations.md @@ -33,9 +33,6 @@ You can integrate your Kubernetes cluster with [Prometheus](https://prometheus.io/) for monitoring key metrics of your apps directly from the GitLab UI. -[Alerts](../../operations/metrics/alerts.md) can be configured the same way as -for [external Prometheus instances](../../operations/metrics/alerts.md#external-prometheus-instances). - Once enabled, you can see metrics from services available in the [metrics library](../project/integrations/prometheus_library/index.md). diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md index 204afa9fc89..ca6843f6fde 100644 --- a/doc/user/clusters/management_project.md +++ b/doc/user/clusters/management_project.md @@ -32,28 +32,30 @@ Management projects are restricted to the following: group (or descendants) as the cluster's group. - For instance-level clusters, there are no such restrictions. -## Usage +## How to create and configure a cluster management project -To use a cluster management project for a cluster: +To use a cluster management project to manage your cluster: -1. Select the project. -1. Configure your pipelines. -1. Set an environment scope. +1. Create a new project to serve as the cluster management project +for your cluster. We recommend that you +[create this project based on the Cluster Management project template](management_project_template.md#create-a-new-project-based-on-the-cluster-management-template). +1. [Associate the cluster with the management project](#associate-the-cluster-management-project-with-the-cluster). +1. [Configure your cluster's pipelines](#configuring-your-pipeline). +1. [Set the environment scope](#setting-the-environment-scope). -### Selecting a cluster management project +### Associate the cluster management project with the cluster -To select a cluster management project to use: +To associate a cluster management project with your cluster: 1. Navigate to the appropriate configuration page. For a: - [Project-level cluster](../project/clusters/index.md), go to your project's **Infrastructure > Kubernetes clusters** page. - [Group-level cluster](../group/clusters/index.md), go to your group's **Kubernetes** page. - - [Instance-level cluster](../instance/clusters/index.md), go to **Menu >** **{admin}** **Admin > Kubernetes** page. -1. Select the project using **Cluster management project field** in the **Advanced settings** - section. - - + - [Instance-level cluster](../instance/clusters/index.md), on the top bar, select **Menu > Admin > Kubernetes**. +1. Expand **Advanced settings**. +1. From the **Cluster management project** dropdown, select the cluster management project +you created in the previous step. ### Configuring your pipeline diff --git a/doc/user/clusters/management_project_template.md b/doc/user/clusters/management_project_template.md index 1de17396bf4..9e2b00a0f54 100644 --- a/doc/user/clusters/management_project_template.md +++ b/doc/user/clusters/management_project_template.md @@ -4,35 +4,68 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Cluster Management Project Template **(FREE)** +# Cluster Management project template **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25318) in GitLab 12.10 with Helmfile support via Helm v2. -> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63577) in GitLab 14.0 with Helmfile support via Helm v3 instead, and a much more flexible usage of Helmfile. This introduces breaking changes that are detailed below. +> - Helm v2 support was [dropped](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63577) in GitLab 14.0. Use Helm v3 instead. -This [GitLab built-in project template](../project/working_with_projects.md#built-in-templates) -provides a quicker start for users interested in managing cluster -applications via [Helm v3](https://helm.sh/) charts. More specifically, taking advantage of the -[Helmfile](https://github.com/roboll/helmfile) utility client. The template consists of some pre-configured apps that -should help you get started quickly using various GitLab features. Still, you have all the flexibility to remove the ones you do not -need, or even add new ones that are not built-in. +With a [cluster management project](management_project.md) you can manage +your cluster's deployment and applications through a repository in GitLab. -## How to use this template +The Custer Management project template provides you a baseline to get +started and flexibility to customize your project to your cluster's needs. +For instance, you can: -1. Create a new project, choosing "GitLab Cluster Management" from the list of [built-in project templates](../project/working_with_projects.md#built-in-templates). -1. Make this project a [cluster management project](management_project.md). -1. If you used the [GitLab Managed Apps](applications.md), refer to - [Migrating from GitLab Managed Apps](migrating_from_gma_to_project_template.md). +- Extend the CI/CD configuration. +- Configure the built-in cluster applications. +- Remove the built-in cluster applications you don't need. +- Add other cluster applications using the same structure as the ones already available. -### Components +The template contains the following [components](#available-components): -In the repository of the newly-created project, you will find: +- A pre-configured GitLab CI/CD file so that you can configure deployment pipelines. +- A pre-configured [Helmfile](https://github.com/roboll/helmfile) so that +you can manage cluster applications with [Helm v3](https://helm.sh/). +- An `applications` directory with a `helmfile.yaml` configured for each +application available in the template. -- A predefined [`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/blob/master/.gitlab-ci.yml) - file, with a CI pipeline already configured. -- A main [`helmfile.yaml`](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/blob/master/helmfile.yaml) to toggle which applications you would like to manage. -- An `applications` directory with a `helmfile.yaml` configured for each application GitLab provides. +WARNING: +If you used [GitLab Managed Apps](applications.md) to manage your +cluster from GitLab, see how to [migrate from GitLab Managed Apps](migrating_from_gma_to_project_template.md) to the Cluster Management +project. -#### The `.gitlab-ci.yml` file +## Set up the management project from the Cluster Management project template + +To set up your cluster's management project off of the Cluster Management project template: + +1. [Create a new project based on the Cluster Management template](#create-a-new-project-based-on-the-cluster-management-template). +1. [Associate the cluster management project with your cluster](management_project.md#associate-the-cluster-management-project-with-the-cluster). +1. Use the [available components](#available-components) to manage your cluster. + +### Create a new project based on the Cluster Management template + +To get started, create a new project based on the Cluster Management +project template to use as a cluster management project. + +You can either create the [new project](../project/working_with_projects.md#create-a-project) +from the template or import the project from the URL. Importing +the project is useful if you are using a GitLab self-managed +instance that may not have the latest version of the template. + +To create the new project: + +- From the template: select the **GitLab Cluster Management** project template. +- Importing from the URL: use `https://gitlab.com/gitlab-org/project-templates/cluster-management.git`. + +## Available components + +Use the available components to configure your cluster: + +- [A `.gitlab-ci.yml` file](#the-gitlab-ciyml-file). +- [A main `helmfile.yml` file](#the-main-helmfileyml-file). +- [A directory with built-in applications](#built-in-applications). + +### The `.gitlab-ci.yml` file The base image used in your pipeline is built by the [cluster-applications](https://gitlab.com/gitlab-org/cluster-integration/cluster-applications) project. This image consists of a set of Bash utility scripts to support [Helm v3 releases](https://helm.sh/docs/intro/using_helm/#three-big-concepts): @@ -48,23 +81,21 @@ project. This image consists of a set of Bash utility scripts to support [Helm v facilitate the GitLab Managed Apps adoption. - `gl-helmfile {arguments}`: A thin wrapper that triggers the [Helmfile](https://github.com/roboll/helmfile) command. -#### The main `helmfile.yml` file +### The main `helmfile.yml` file This file has a list of paths to other Helmfiles for each app. They're all commented out by default, so you must uncomment -the paths for the apps that you would like to manage. +the paths for the apps that you would like to use in your cluster. -By default, each `helmfile.yaml` in these sub-paths have the attribute `installed: true`. This signifies that every time +By default, each `helmfile.yaml` in these sub-paths has the attribute `installed: true`. This means that every time the pipeline runs, Helmfile tries to either install or update your apps according to the current state of your cluster and Helm releases. If you change this attribute to `installed: false`, Helmfile tries try to uninstall this app from your cluster. [Read more](https://github.com/roboll/helmfile) about how Helmfile works. -Furthermore, each app has an `applications/{app}/values.yaml` file. This is the -place where you can define some default values for your app's Helm chart. Some apps already have defaults +Furthermore, each app has an `applications/{app}/values.yaml` file (`applicaton/{app}/values.yaml.gotmpl` in case of GitLab Runner). This is the +place where you can define default values for your app's Helm chart. Some apps already have defaults pre-defined by GitLab. -#### Built-in applications - -The built-in applications are intended to provide an easy way to get started with various Kubernetes oriented GitLab features. +### Built-in applications The [built-in supported applications](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/tree/master/applications) are: @@ -79,8 +110,3 @@ The [built-in supported applications](https://gitlab.com/gitlab-org/project-temp - [Prometheus](../infrastructure/clusters/manage/management_project_applications/prometheus.md) - [Sentry](../infrastructure/clusters/manage/management_project_applications/sentry.md) - [Vault](../infrastructure/clusters/manage/management_project_applications/vault.md) - -### Migrate from GitLab Managed Apps - -If you had GitLab Managed Apps, either One-Click or CI/CD install, read the docs on how to -[migrate from GitLab Managed Apps to project template](migrating_from_gma_to_project_template.md) 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 dc16cf5cc45..2da058fb5bc 100644 --- a/doc/user/clusters/migrating_from_gma_to_project_template.md +++ b/doc/user/clusters/migrating_from_gma_to_project_template.md @@ -4,13 +4,24 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Migrating from GitLab Managed Apps to a management project template +# Migrate from GitLab Managed Apps to Cluster Management Projects -The [GitLab Managed Apps](applications.md) are deprecated in GitLab 14.0. To migrate to the new way of managing them: +The [GitLab Managed Apps](applications.md) were deprecated in GitLab 14.0 +in favor of [Cluster Management Projects](management_project.md). +Managing your cluster applications through a project enables you a +lot more flexibility to manage your cluster than through the late GitLab Managed Apps. +To migrate to the cluster management project you need +[GitLab Runners](../../ci/runners/index.md) +available and be familiar with [Helm](https://helm.sh/). -1. Read how the [management project template](management_project_template.md) works, and - create a new project based on the "GitLab Cluster Management" template. -1. Create a new project as explained in the [management project template](management_project_template.md). +## Migrate to a Cluster Management Project + +To migrate from GitLab Managed Apps to a Cluster Management Project, +follow the steps below. +See also [video walk-throughs](#video-walk-throughs) with examples. + +1. Create a new project based on the [Cluster Management Project template](management_project_template.md#create-a-new-project-based-on-the-cluster-management-template). +1. [Associate your new Cluster Management Project with your cluster](management_project.md#associate-the-cluster-management-project-with-the-cluster). 1. Detect apps deployed through Helm v2 releases by using the pre-configured [`.gitlab-ci.yml`](management_project_template.md#the-gitlab-ciyml-file) file: - In case you had overwritten the default GitLab Managed Apps namespace, edit `.gitlab-ci.yml`, and make sure the script is receiving the correct namespace as an argument: @@ -80,6 +91,16 @@ The [GitLab Managed Apps](applications.md) are deprecated in GitLab 14.0. To mig used in Helm v3. So, the only way to integrate it with this Cluster Management Project is to actually uninstall this app and accept the chart version proposed in `applications/vault/values.yaml`. + - Cert-manager: + - For users on Kubernetes version 1.20 or above, the deprecated cert-manager v0.10 is no longer valid and + and the upgrade includes a breaking change. So we suggest that you [backup and uninstall cert-manager v0.10](#backup-and-uninstall-cert-manager-v010) + , and install cert-manager v1.4 instead. To install this version, uncomment the `applications/cert-manager-1-4/helmfile.yaml` + from the [`./helmfile.yaml`](management_project_template.md#the-main-helmfileyml-file). + This triggers a pipeline to install the new version. + - For users on Kubernetes versions lower than 1.20, you can stick to v0.10 by uncommenting + `applications/cert-manager/helmfile.yaml` + in your project's main Helmfile ([`./helmfile.yaml`](management_project_template.md#the-main-helmfileyml-file)). + 1. After following all the previous steps, [run a pipeline manually](../../ci/pipelines/index.md#run-a-pipeline-manually) and watch the `apply` job logs to see if any of your applications were successfully detected, installed, and whether they got any unexpected updates. @@ -93,3 +114,21 @@ The [GitLab Managed Apps](applications.md) are deprecated in GitLab 14.0. To mig After getting a successful pipeline, repeat these steps for any other deployed apps you want to manage with the Cluster Management Project. + +## Backup and uninstall cert-manager v0.10 + +1. Follow the [official docs](https://docs.cert-manager.io/en/release-0.10/tasks/backup-restore-crds.html) on how to + backup your cert-manager v0.10 data. +1. Uninstall cert-manager by editing the setting all the occurrences of `installed: true` to `installed: false` in the + `applications/cert-manager/helmfile.yaml` file. +1. Search for any left-over resources by executing the following command `kubectl get Issuers,ClusterIssuers,Certificates,CertificateRequests,Orders,Challenges,Secrets,ConfigMaps -n gitlab-managed-apps | grep certmanager`. +1. For each of the resources found in the previous step, delete them with `kubectl delete -n gitlab-managed-apps {ResourceType} {ResourceName}`. + For example, if you found a resource of type `ConfigMap` named `cert-manager-controller`, delete it by executing: + `kubectl delete configmap -n gitlab-managed-apps cert-manager-controller`. + +## Video walk-throughs + +You can watch these videos with examples on how to migrate from GMA to a Cluster Management project: + +- [Migrating from scratch using a brand new cluster management project](https://youtu.be/jCUFGWT0jS0). Also covers Helm v2 apps migration. +- [Migrating from an existing GitLab managed apps CI/CD project](https://youtu.be/U2lbBGZjZmc). diff --git a/doc/user/compliance/compliance_report/index.md b/doc/user/compliance/compliance_report/index.md index c51636e33f5..d30cedfb3cd 100644 --- a/doc/user/compliance/compliance_report/index.md +++ b/doc/user/compliance/compliance_report/index.md @@ -14,17 +14,32 @@ Compliance report gives you the ability to see a group's merge request activity. high-level view for all projects in the group. For example, code approved for merging into production. -To access compliance report for a group, go to **{shield}** **Security & Compliance > Compliance** -on the group's menu. +You can use the report to: + +- Get an overview of the latest merge request for each project. +- See if merge requests were approved and by whom. +- See merge request authors. +- See the latest [CI/CD pipeline](../../../ci/pipelines/index.md) result for each merge request. + +## View the compliance report for a group + +Prerequisites: + +- You must be an administrator or have the Owner role for the group. + +To view the compliance report: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Security & Compliance > Compliance**. NOTE: -Compliance report shows only the latest merge request on each project. +The compliance report shows only the latest merge request on each project. ## Merge request drawer > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299357) in GitLab 14.1. -When you click on a row, a drawer is shown that provides further details about the merge +When you select a row, a drawer is shown that provides further details about the merge request: - Project name and [compliance framework label](../../project/settings/index.md#compliance-frameworks), @@ -36,22 +51,6 @@ request: - A list of users that approved the merge request. - The user that merged the merge request. -## Use cases - -This feature is for people who care about the compliance status of projects within their group. - -You can use the report to: - -- Get an overview of the latest merge request for each project. -- See if merge requests were approved and by whom. -- See merge request authors. -- See the latest [CI Pipeline](../../../ci/pipelines/index.md) result for each merge request. - -## Permissions - -- On [GitLab Ultimate](https://about.gitlab.com/pricing/) tier. -- By **Administrators** and **Group Owners**. - ## Approval status and separation of duties > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217939) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3. @@ -85,14 +84,23 @@ The data provides a comprehensive view with respect to merge commits. It include merge request author, merge request ID, merge user, 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. -To download the Chain of Custody report, navigate to **{shield}** **Security & Compliance > Compliance** on the group's menu and click **List of all merge commits** +To download the Chain of Custody report: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Security & Compliance > Compliance**. +1. Select **List of all merge commits**. ### Commit-specific Chain of Custody Report **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267629) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.6. -You can generate a commit-specific Chain of Custody report for a given commit SHA. To do so, select -the dropdown next to the **List of all merge commits** button at the top of the compliance report. +You can generate a commit-specific Chain of Custody report for a given commit SHA. + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Security & Compliance > Compliance**. +1. At the top of the compliance report, to the right of **List of all merge commits**, select the down arrow (**{angle-down}**). +1. Enter the merge commit SHA, and then select **Export commit custody report**. + SHA and then select **Export commit custody report**. NOTE: The Chain of Custody report download is a CSV file, with a maximum size of 15 MB. diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index e39a3f7111b..165150a58a1 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -40,7 +40,7 @@ compliance report is shown properly.  -You can click on a license to see more information. +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). @@ -49,11 +49,20 @@ When GitLab detects a **Denied** license, you can view it in the [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/appendix-IV-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), +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). + ## Supported languages and package managers The following languages and package managers are supported. -Java 8 and Gradle 1.x projects are not supported. The minimum supported version of Maven is 3.2.5. +Gradle 1.x projects are not supported. The minimum supported version of Maven is 3.2.5. | Language | Package managers | Notes | |------------|----------------------------------------------------------------------------------------------|-------| @@ -140,12 +149,12 @@ License Compliance can be configured using CI/CD variables. | `ADDITIONAL_CA_CERT_BUNDLE` | no | Bundle of trusted CA certificates (currently supported in Pip, Pipenv, Maven, Gradle, Yarn, and npm projects). | | `ASDF_JAVA_VERSION` | no | Version of Java to use for the scan. | | `ASDF_NODEJS_VERSION` | no | Version of Node.js to use for the scan. | -| `ASDF_PYTHON_VERSION` | no | Version of Python to use for the scan. | +| `ASDF_PYTHON_VERSION` | no | Version of Python to use for the scan. [Configuration](#selecting-the-version-of-python) | | `ASDF_RUBY_VERSION` | no | Version of Ruby to use for the scan. | | `GRADLE_CLI_OPTS` | no | Additional arguments for the Gradle executable. If not supplied, defaults to `--exclude-task=test`. | | `LICENSE_FINDER_CLI_OPTS` | no | Additional arguments for the `license_finder` executable. For example, if you have multiple projects in nested directories, you can update your `.gitlab-ci-yml` template to specify a recursive scan, like `LICENSE_FINDER_CLI_OPTS: '--recursive'`. | -| `LM_JAVA_VERSION` | no | Version of Java. If set to `11`, Maven and Gradle use Java 11 instead of Java 8. | -| `LM_PYTHON_VERSION` | no | Version of Python. If set to `3`, dependencies are installed using Python 3 instead of Python 2.7. | +| `LM_JAVA_VERSION` | no | Version of Java. If set to `11`, Maven and Gradle use Java 11 instead of Java 8. [Configuration](#selecting-the-version-of-java) | +| `LM_PYTHON_VERSION` | no | Version of Python. If set to `3`, dependencies are installed using Python 3 instead of Python 2.7. [Configuration](#selecting-the-version-of-python) | | `MAVEN_CLI_OPTS` | no | Additional arguments for the `mvn` executable. If not supplied, defaults to `-DskipTests`. | | `PIP_INDEX_URL` | no | Base URL of Python Package Index (default: `https://pypi.org/simple/`). | | `SECURE_ANALYZERS_PREFIX` | no | Set the Docker registry base address to download the analyzer from. | @@ -245,6 +254,12 @@ Alternatively, you can use a Java key store to verify the TLS connection. For in generate a key store file, see the [Maven Guide to Remote repository access through authenticated HTTPS](http://maven.apache.org/guides/mini/guide-repository-ssl.html). +### Selecting the version of Java + +License Compliance uses Java 8 by default. You can specify a different Java version using `LM_JAVA_VERSION`. + +`LM_JAVA_VERSION` only accepts versions: 8, 11, 14, 15. + ### Selecting the version of Python > - [Introduced](https://gitlab.com/gitlab-org/security-products/license-management/-/merge_requests/36) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. @@ -264,6 +279,8 @@ license_scanning: LM_PYTHON_VERSION: 2 ``` +`LM_PYTHON_VERSION` or `ASDF_PYTHON_VERSION` can be used to specify the desired version of Python. When both variables are specified `LM_PYTHON_VERSION` takes precedence. + ### Custom root certificates for Python You can supply a custom root certificate to complete TLS verification by using the @@ -693,15 +710,16 @@ instance's administrator can manually update it with a [Rake task](../../../rake The License list allows you to see your project's licenses and key details about them. -In order for the licenses to appear under the license list, the following +For the licenses to appear under the license list, the following requirements must be met: 1. The License Compliance CI job must be [configured](#configuration) for your project. 1. Your project must use at least one of the [supported languages and package managers](#supported-languages-and-package-managers). -Once everything is set, navigate to **Security & Compliance > License Compliance** -in your project's sidebar, and the licenses are displayed, where: +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. @@ -741,8 +759,10 @@ license. You can enable `License-Check` one of two ways: -1. Navigate to your project's **Settings > General** and expand **Merge request approvals**. -1. Click **Enable** or **Edit**. +1. On the top bar, select **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).  @@ -802,11 +822,11 @@ or using the appropriate [`ASDF_<tool>_VERSION`](https://asdf-vm.com/#/core-conf activate the appropriate version. For example, the following `.tool-versions` file activates version `12.16.3` of [Node.js](https://nodejs.org/) -and version `2.7.2` of [Ruby](https://www.ruby-lang.org/). +and version `2.7.4` of [Ruby](https://www.ruby-lang.org/). ```plaintext nodejs 12.16.3 -ruby 2.7.2 +ruby 2.7.4 ``` The next example shows how to activate the same versions of the tools mentioned above by using CI/CD variables defined in your @@ -819,7 +839,7 @@ include: license_scanning: variables: ASDF_NODEJS_VERSION: '12.16.3' - ASDF_RUBY_VERSION: '2.7.2' + ASDF_RUBY_VERSION: '2.7.4' ``` A full list of variables can be found in [CI/CD variables](#available-cicd-variables). diff --git a/doc/user/discussions/img/btn_new_issue_for_all_threads.png b/doc/user/discussions/img/btn_new_issue_for_all_threads.png Binary files differdeleted file mode 100644 index b07267a011a..00000000000 --- a/doc/user/discussions/img/btn_new_issue_for_all_threads.png +++ /dev/null diff --git a/doc/user/discussions/img/create-new-issue_v14_3.png b/doc/user/discussions/img/create-new-issue_v14_3.png Binary files differnew file mode 100644 index 00000000000..d76fed6cb42 --- /dev/null +++ b/doc/user/discussions/img/create-new-issue_v14_3.png diff --git a/doc/user/discussions/img/new-issue-one-thread_v14_3.png b/doc/user/discussions/img/new-issue-one-thread_v14_3.png Binary files differnew file mode 100644 index 00000000000..34d3a3be0a7 --- /dev/null +++ b/doc/user/discussions/img/new-issue-one-thread_v14_3.png diff --git a/doc/user/discussions/img/new_issue_for_thread.png b/doc/user/discussions/img/new_issue_for_thread.png Binary files differdeleted file mode 100644 index c7f0fd76844..00000000000 --- a/doc/user/discussions/img/new_issue_for_thread.png +++ /dev/null diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index a1d8863710c..aa4e3ce6f49 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -13,7 +13,7 @@ GitLab encourages communication through comments, threads, and There are two types of comments: - A standard comment. -- A comment in a thread, which has to be resolved. +- A comment in a thread, which can be [resolved](#resolve-a-thread). In a comment, you can enter [Markdown](../markdown.md) and use [quick actions](../project/quick_actions.md). @@ -46,9 +46,9 @@ To add a commit diff comment: 1. To select a specific commit, on the merge request, select the **Commits** tab, select the commit message. To view the latest commit, select the **Changes** tab. -1. By the line you want to comment on, hover over the line number and select **{comment}**. - You can select multiple lines by dragging the **{comment}** icon. -1. Type your comment and select **Start a review** or **Add comment now**. +1. By the line you want to comment on, hover over the line number and select **Comment** (**{comment}**). + You can select multiple lines by dragging the **Comment** (**{comment}**) icon. +1. Enter your comment and select **Start a review** or **Add comment now**. The comment is displayed on the merge request's **Discussions** tab. @@ -164,12 +164,10 @@ from any device you're logged into. You can assign an issue to a user who made a comment. -1. In the comment, select the **More Actions** menu. -1. Select **Assign to commenting user**. - - - -Select the button again to unassign the commenter. +1. In the comment, select the **More Actions** (**{ellipsis_v}**) menu. +1. Select **Assign to commenting user**: +  +1. To unassign the commenter, select the button again. ## Create a thread by replying to a standard comment @@ -184,13 +182,13 @@ Prerequisites: To create a thread by replying to a comment: -1. On the top right of the comment, select **{comment}** (**Reply to comment**). +1. On the top right of the comment, select **Reply to comment** (**{comment}**).  The reply area is displayed. -1. Type your reply. +1. Enter your reply. 1. Select **Comment** or **Add comment now** (depending on where in the UI you are replying). The top comment is converted to a thread. @@ -206,7 +204,7 @@ Prerequisites: To create a thread: -1. Type a comment. +1. Enter a comment. 1. Below the comment, to the right of the **Comment** button, select the down arrow (**{chevron-down}**). 1. From the list, select **Start thread**. 1. Select **Start thread** again. @@ -218,16 +216,16 @@ A threaded comment is created. ## Resolve a thread > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5022) in GitLab 8.11. -> - Resolvable threads can be added only to merge request diffs. > - Resolving comments individually was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/28750) in GitLab 13.6. -You can resolve a thread when you want to finish a conversation. +In a merge request, you can resolve a thread when you want to finish a conversation. Prerequisites: - You must have at least the [Developer role](../permissions.md#project-members-permissions) or be the author of the change being reviewed. -- You must be in an issue, merge request, commit, or snippet. +- Resolvable threads can be added only to merge requests. It doesn't work + for comments in issues, commits, or snippets. To resolve a thread: @@ -237,33 +235,30 @@ To resolve a thread: - 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**. -At the top of the page, the number of unresolved threads is updated. +At the top of the page, the number of unresolved threads is updated:  ### Move all unresolved threads in a merge request to an issue If you have multiple unresolved threads in a merge request, you can -create an issue to resolve them separately. +create an issue to resolve them separately. In the merge request, at the top of the page, +select **Create issue to resolve all threads** (**{issue-new}**): -- In the merge request, at the top of the page, select **Resolve all threads in new issue**. + -  - -All threads are marked as resolved and a link is added from the merge request to +All threads are marked as resolved, and a link is added from the merge request to the newly created issue. ### Move one unresolved thread in a merge request to an issue If you have one specific unresolved thread in a merge request, you can -create an issue to resolve it separately. - -- In the merge request, under the last reply to the thread, next to the - **Resolve thread** button, select **Resolve this thread in a new issue**. +create an issue to resolve it separately. In the merge request, under the last reply +to the thread, next to **Resolve thread**, select **Create issue to resolve thread** (**{issue-new}**): -  + -The thread is marked as resolved and a link is added from the merge request to +The thread is marked as resolved, and a link is added from the merge request to the newly created issue. ### Prevent merge unless all threads are resolved diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 024ab86a1b7..23765de8f46 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -9,6 +9,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w This page contains information about the settings that are used on GitLab.com, available to [GitLab SaaS](https://about.gitlab.com/pricing/) customers. +## Password requirements + +GitLab.com has the following requirements for passwords on new accounts and password changes: + +- Minimum character length 8 characters. +- Maximum character length 128 characters. +- All characters are accepted. For example, `~`, `!`, `@`, `#`, `$`, `%`, `^`, `&`, `*`, `()`, + `[]`, `_`, `+`, `=`, and `-`. + +## SSH key restrictions + +GitLab.com uses the default [SSH key restrictions](../../security/ssh_keys_restrictions.md). + ## SSH host keys fingerprints Below are the fingerprints for SSH host keys on GitLab.com. The first time you @@ -123,6 +136,7 @@ the related documentation. | [Max jobs in active pipelines](../../administration/instance_limits.md#number-of-jobs-in-active-pipelines) | `500` for Free tier, unlimited otherwise | Unlimited | | [Max CI/CD subscriptions to a project](../../administration/instance_limits.md#number-of-cicd-subscriptions-to-a-project) | `2` | Unlimited | | [Max pipeline schedules in projects](../../administration/instance_limits.md#number-of-pipeline-schedules) | `10` for Free tier, `50` for all paid tiers | Unlimited | +| [Max pipelines per schedule](../../administration/instance_limits.md#limit-the-number-of-pipelines-created-by-a-pipeline-schedule-per-day) | `24` for Free tier, `288` for all paid tiers | Unlimited | | [Scheduled Job Archival](../../user/admin_area/settings/continuous_integration.md#archive-jobs) | 3 months | Never | | Max test cases per [unit test report](../../ci/unit_test_reports.md) | `500_000` | Unlimited | | [Max registered runners](../../administration/instance_limits.md#number-of-registered-runners-per-scope) | `50` per-project and per-group for Free tier,<br/>`1_000` per-group for all paid tiers / `1_000` per-project for all paid tiers | `1_000` per-group / `1_000` per-project | @@ -292,7 +306,7 @@ endpoints](../../user/admin_area/settings/rate_limits_on_raw_endpoints.md). For information on rate limiting responses, see: - [List of headers on responses to blocked requests](../admin_area/settings/user_and_ip_rate_limits.md#response-headers). -- [Customizable response text](../admin_area/settings/user_and_ip_rate_limits.md#response-text). +- [Customizable response text](../admin_area/settings/user_and_ip_rate_limits.md#use-a-custom-rate-limit-response). ### Protected paths throttle @@ -349,7 +363,7 @@ doesn't return the following headers: ### Visibility settings If created before GitLab 12.2 (July 2019), these items have the -[Internal visibility](../../public_access/public_access.md#internal-projects) +[Internal visibility](../../public_access/public_access.md#internal-projects-and-groups) setting [disabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/12388): - Projects diff --git a/doc/user/group/devops_adoption/img/group_devops_adoption_v14_2.png b/doc/user/group/devops_adoption/img/group_devops_adoption_v14_2.png Binary files differindex 073e747153f..21e38907a10 100644 --- a/doc/user/group/devops_adoption/img/group_devops_adoption_v14_2.png +++ b/doc/user/group/devops_adoption/img/group_devops_adoption_v14_2.png diff --git a/doc/user/group/devops_adoption/index.md b/doc/user/group/devops_adoption/index.md index 5c84a343da9..554d01039ad 100644 --- a/doc/user/group/devops_adoption/index.md +++ b/doc/user/group/devops_adoption/index.md @@ -13,6 +13,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Fuzz Testing metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/330398) in GitLab 14.2. > - Dependency Scanning metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/328034) in GitLab 14.2. > - Multiselect [added](https://gitlab.com/gitlab-org/gitlab/-/issues/333586) in GitLab 14.2. +> - Overview table [added](https://gitlab.com/gitlab-org/gitlab/-/issues/335638) in GitLab 14.3. Prerequisites: diff --git a/doc/user/group/epics/epic_boards.md b/doc/user/group/epics/epic_boards.md index 34eebfb9e3b..d184030718a 100644 --- a/doc/user/group/epics/epic_boards.md +++ b/doc/user/group/epics/epic_boards.md @@ -4,7 +4,7 @@ group: Product Planning info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Epic Boards **(PREMIUM)** +# Epic boards **(PREMIUM)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5067) in GitLab 13.10. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/290039) in GitLab 14.1. @@ -54,7 +54,7 @@ Prerequisites: To delete the active epic board: -1. Select the dropdown with the current board name in the upper left corner of the Epic Boards page. +1. Select the dropdown with the current board name in the upper left corner of the epic boards page. 1. Select **Delete board**. 1. Select **Delete**. diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index 24c78d169c4..68df71d1c5d 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -64,7 +64,7 @@ You can also consult the [group permissions table](../../permissions.md#group-me ## Related topics - [Manage epics](manage_epics.md) and multi-level child epics. -- Create workflows with [Epic Boards](epic_boards.md). +- Create workflows with [epic boards](epic_boards.md). - [Turn on notifications](../../profile/notifications.md) for about epic events. - [Award an emoji](../../award_emojis.md) to an epic or its comments. - Collaborate on an epic by posting comments in a [thread](../../discussions/index.md). diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index 721afa219d0..31c3a8e774e 100644 --- a/doc/user/group/import/index.md +++ b/doc/user/group/import/index.md @@ -77,7 +77,7 @@ Any other items are **not** migrated. ## Enable or disable GitLab Group Migration -GitLab Migration is deployed behind a feature flag that is **disabled by default**. +GitLab Migration is deployed behind a feature flag that is **enabled by default**. [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) can enable it. To enable it: diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 948f9cab659..caf874cfe28 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -82,6 +82,10 @@ To create a group: - Underscores - Dashes and dots (it cannot start with dashes or end in a dot) 1. Choose the [visibility level](../../public_access/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? 1. Invite GitLab members or other users to join the group. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> @@ -263,7 +267,7 @@ These Group Activity Analytics can be enabled with the `group_activity_analytics ### View group activity -You can view the most recent actions taken in a group. +You can view the most recent actions taken in a group, either in your browser or in an RSS feed: 1. On the top bar, select **Menu > Groups**. 1. Select **Your Groups**. @@ -312,7 +316,7 @@ In GitLab 13.11, you can optionally replace the sharing form with a modal window To share a group after enabling this feature: 1. Go to your group's page. -1. In the left sidebar, go to **Group information > Members**, and then select **Invite a group**. +1. On the left sidebar, go to **Group information > Members**, and then select **Invite a group**. 1. Select a group, and select a **Max role**. 1. (Optional) Select an **Access expiration date**. 1. Select **Invite**. @@ -664,16 +668,16 @@ Projects can be configured to be deleted either: - Immediately. - After a delayed interval. During this interval period, the projects are in a read-only state - and can be restored, if required. The default interval period is seven days but + and can be restored. The default interval period is seven days but [is configurable](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). -On: +On self-managed GitLab, projects are deleted immediately by default. +In GitLab 14.2 and later, an administrator can +[change the default setting](../admin_area/settings/visibility_and_access_controls.md#default-delayed-project-deletion) +for projects in newly-created groups. -- GitLab self-managed instances, projects are deleted immediately by default. In GitLab - 14.2 and later, an administrator can - [change the default setting](../admin_area/settings/visibility_and_access_controls.md#default-delayed-project-deletion) for projects in newly-created groups. -- GitLab.com, see [GitLab.com settings page](../gitlab_com/index.md#delayed-project-deletion) for - the default setting. +On GitLab.com, see the [GitLab.com settings page](../gitlab_com/index.md#delayed-project-deletion) for +the default setting. To enable delayed deletion of projects in a group: @@ -750,7 +754,7 @@ The group's new subgroups have push rules set for them based on either: - [Transfer a project into a group](../project/settings/index.md#transferring-an-existing-project-into-another-namespace). - [Share a project with a group](../project/members/share_project_with_groups.md): Give all group members access to the project at once. - [Lock the sharing with group feature](#prevent-a-project-from-being-shared-with-groups). -- [Enforce two-factor authentication (2FA)](../../security/two_factor_authentication.md#enforcing-2fa-for-all-users-in-a-group): Enforce 2FA +- [Enforce two-factor authentication (2FA)](../../security/two_factor_authentication.md#enforce-2fa-for-all-users-in-a-group): Enforce 2FA for all group members. - Namespaces [API](../../api/namespaces.md) and [Rake tasks](../../raketasks/features.md).. diff --git a/doc/user/group/issues_analytics/index.md b/doc/user/group/issues_analytics/index.md index 9240828db0a..3d28ef5306d 100644 --- a/doc/user/group/issues_analytics/index.md +++ b/doc/user/group/issues_analytics/index.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Issue Analytics **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7478) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7478) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.5. Issue Analytics is a bar graph which illustrates the number of issues created each month. The default time span is 13 months, which includes the current month, and the 12 months diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md index 5c4e66a4539..70fa3ba639d 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -110,7 +110,17 @@ Prerequisites: - You must have at least the [Developer role](../../permissions.md) for a group. -To edit an iteration, select the three-dot menu (**{ellipsis_v}**) > **Edit iteration**. +To edit an iteration, select the three-dot menu (**{ellipsis_v}**) > **Edit**. + +## Delete an iteration + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292268) in GitLab 14.3. + +Prerequisites: + +- You must have at least the [Developer role](../../permissions.md) for a group. + +To delete an iteration, select the three-dot menu (**{ellipsis_v}**) > **Delete**. ## Add an issue to an iteration diff --git a/doc/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md index 054c6ab7a6b..685c4601ac4 100644 --- a/doc/user/group/repositories_analytics/index.md +++ b/doc/user/group/repositories_analytics/index.md @@ -16,7 +16,7 @@ This feature might not be available to you. Check the **version history** note a ## Current group code coverage -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263478) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263478) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7. The **Analytics > Repositories** group page displays the overall test coverage of all your projects in your group. In the **Overall activity** section, you can see: @@ -27,13 +27,13 @@ In the **Overall activity** section, you can see: ## Average group test coverage from the last 30 days -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215140) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215140) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.9. The **Analytics > Repositories** group page displays the average test coverage of all your projects in your group in a graph for the last 30 days. ## Latest project test coverage list -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267624) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267624) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. To see the latest code coverage for each project in your group: diff --git a/doc/user/group/roadmap/img/epics_state_dropdown_v12_10.png b/doc/user/group/roadmap/img/epics_state_dropdown_v12_10.png Binary files differdeleted file mode 100644 index c6d0b17455f..00000000000 --- a/doc/user/group/roadmap/img/epics_state_dropdown_v12_10.png +++ /dev/null diff --git a/doc/user/group/roadmap/img/epics_state_dropdown_v14_3.png b/doc/user/group/roadmap/img/epics_state_dropdown_v14_3.png Binary files differnew file mode 100644 index 00000000000..171876e34a9 --- /dev/null +++ b/doc/user/group/roadmap/img/epics_state_dropdown_v14_3.png diff --git a/doc/user/group/roadmap/img/roadmap_view_v13_2.png b/doc/user/group/roadmap/img/roadmap_view_v13_2.png Binary files differdeleted file mode 100644 index 94cf2258569..00000000000 --- a/doc/user/group/roadmap/img/roadmap_view_v13_2.png +++ /dev/null diff --git a/doc/user/group/roadmap/img/roadmap_view_v14_3.png b/doc/user/group/roadmap/img/roadmap_view_v14_3.png Binary files differnew file mode 100644 index 00000000000..ca4b87b9fdd --- /dev/null +++ b/doc/user/group/roadmap/img/roadmap_view_v14_3.png diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md index 811297c6eda..656c40d1915 100644 --- a/doc/user/group/roadmap/index.md +++ b/doc/user/group/roadmap/index.md @@ -32,7 +32,7 @@ When you hover over a milestone bar or title, a popover appears with its title, date. You can also click the chevron (**{chevron-down}**) next to the **Milestones** heading to toggle the list of the milestone bars. - + ## Sort and filter the Roadmap @@ -52,7 +52,7 @@ filtering them by what's important for you. A dropdown menu lets you show only open or closed epics. By default, all epics are shown. - + You can sort epics in the Roadmap view by: @@ -101,18 +101,38 @@ Feature.disable(:async_filtering) > - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. > - In [GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/198062), Timelines were moved to the Premium tier. -Roadmap supports the following date ranges: +### Date range presets -- Quarters -- Months (default) -- Weeks +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/204994) in GitLab 14.3. [Deployed behind the `roadmap_daterange_filter` flag](../../../administration/feature_flags.md), disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/323917) in GitLab 14.3. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per group, +ask an administrator to [enable the `roadmap_daterange_filter` flag](../../../administration/feature_flags.md). +On GitLab.com, this feature is available. +The feature is ready for production use. + +Roadmap provides three date range options, each with predetermined timeline duration: + +- **This quarter**: includes weeks present in current quarter. +- **This year**: includes weeks or months present in current year. +- **Within 3 years**: includes weeks, months, or quarters present in the previous 18 months and + upcoming 18 months (that is, three years in total). + +### Layout presets + +Depending on selected [date range preset](#date-range-presets), Roadmap supports the following layout presets: + +- **Quarters**: only available when the "Within 3 years" date range is selected. +- **Months**: available when either "This year" or "Within 3 years" date range is selected. +- **Weeks** (default): available for all the date range presets. ### Quarters  In the **Quarters** preset, roadmap shows epics and milestones which have start or due dates -**falling within** or **going through** past quarter, current quarter, and the next four quarters, +**falling within** currently selected date range preset, where **today** is shown by the vertical red line in the timeline. The sub-headers underneath the quarter name on the timeline header represent the month of the quarter. @@ -123,7 +143,7 @@ the timeline header represent the month of the quarter. In the **Months** preset, roadmap shows epics and milestones which have start or due dates **falling within** or -**going through** the past month, current month, and the next five months, where **today** +**going through** currently selected date range preset, where **today** is shown by the vertical red line in the timeline. The sub-headers underneath the month name on the timeline header represent the date on starting day (Sunday) of the week. This preset is selected by default. @@ -133,7 +153,7 @@ selected by default.  In the **Weeks** preset, roadmap shows epics and milestones which have start or due dates **falling -within** or **going through** the past week, current week and the next four weeks, where **today** +within** or **going through** currently selected date range preset, where **today** is shown by the vertical red line in the timeline. The sub-headers underneath the week name on the timeline header represent the days of the week. diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index a627f04fa46..8f6b3e7244a 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -57,6 +57,7 @@ Once users have signed into GitLab using the SSO SAML setup, changing the `NameI #### NameID Format We recommend setting the NameID format to `Persistent` unless using a field (such as email) that requires a different format. +Most NameID formats can be used, except `Transient` due to the temporary nature of this format. ### Assertions @@ -120,6 +121,14 @@ SSO has the following effects when enabled: - Users must be signed-in through SSO before they can pull images using the [Dependency Proxy](../../packages/dependency_proxy/index.md). <!-- Add bullet for API activity when https://gitlab.com/gitlab-org/gitlab/-/issues/9152 is complete --> +When SSO is enforced, users are not immediately revoked. If the user: + +- 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. + +When SCIM updates, the user's access is immediately revoked. + ## Providers The SAML standard means that a wide range of identity providers will work with GitLab. Your identity provider may have relevant documentation. It may be generic SAML documentation, or specifically targeted for GitLab. @@ -140,13 +149,13 @@ Follow the Azure documentation on [configuring single sign-on to applications](h 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). The video is outdated in regard to objectID mapping and the [SCIM documentation should be followed](scim_setup.md#azure-configuration-steps). -| GitLab Setting | Azure Field | -|--------------|----------------| -| Identifier | Identifier (Entity ID) | -| Assertion consumer service URL | Reply URL (Assertion Consumer Service URL) | -| GitLab single sign-on URL | Sign on URL | -| Identity provider single sign-on URL | Login URL | -| Certificate fingerprint | Thumbprint | +| GitLab Setting | Azure Field | +| ------------------------------------ | ------------------------------------------ | +| Identifier | Identifier (Entity ID) | +| Assertion consumer service URL | Reply URL (Assertion Consumer Service URL) | +| GitLab single sign-on URL | Sign on URL | +| Identity provider single sign-on URL | Login URL | +| Certificate fingerprint | Thumbprint | We recommend: @@ -164,12 +173,12 @@ Please follow the Okta documentation on [setting up a SAML application in 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 | +| 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 | Under Okta's **Single sign-on URL** field, check the option **Use this for Recipient URL and Destination URL**. @@ -186,14 +195,14 @@ application. 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: -| GitLab Setting | OneLogin Field | -|--------------|----------------| -| Identifier | Audience | -| Assertion consumer service URL | Recipient | -| Assertion consumer service URL | ACS (Consumer) URL | +| 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 single sign-on URL | Login URL | +| Identity provider single sign-on URL | SAML 2.0 Endpoint | Recommended `NameID` value: `OneLogin ID`. @@ -281,10 +290,7 @@ If a user is already a member of the group, linking the SAML identity does not c ### Blocking access -To rescind access to the group, perform the following steps, in order: - -1. Remove the user from the user data store on the identity provider or the list of users on the specific app. -1. Remove the user from the GitLab.com group. +Please refer to [Blocking access via SCIM](scim_setup.md#blocking-access). ### Unlinking accounts @@ -305,7 +311,7 @@ For example, to unlink the `MyOrg` account: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Account**. +1. On the left sidebar, select **Account**. 1. In the **Social sign-in** section, select **Disconnect** next to the connected account.  @@ -331,7 +337,7 @@ Ensure your SAML identity provider sends an attribute statement named `Groups` o NOTE: To inspect the SAML response, you can use one of these [SAML debugging tools](#saml-debugging-tools). -Also note that the value for `Groups` or `groups` in the SAML reponse can be either the group name or +Also note that the value for `Groups` or `groups` in the SAML response can be either the group name or the group ID depending what the IdP sends to GitLab. When SAML SSO is enabled for the top-level group, `Maintainer` and `Owner` level users @@ -352,10 +358,88 @@ the user gets the highest access level from the groups. For example, if one grou is linked as `Guest` and another `Maintainer`, a user in both groups gets `Maintainer` access. -Users who are not members of any mapped SAML groups are removed from the GitLab group. +### Automatic member removal + +After a group sync, users who are not members of a mapped SAML group are removed from +the GitLab group. + +For example, in the following diagram: -You can prevent accidental member removal. For example, if you have a SAML group link for `Owner` level access -in a top-level group, you should also set up a group link for all other members. +- Alex Garcia signs into GitLab and is removed from GitLab Group C because they don't belong + to SAML Group C. +- Sidney Jones belongs to SAML Group C, but is not added to GitLab Group C because they have + not yet signed in. + +```mermaid +graph TB + subgraph SAML users + SAMLUserA[Sidney Jones] + SAMLUserB[Zhang Wei] + SAMLUserC[Alex Garcia] + SAMLUserD[Charlie Smith] + end + + subgraph SAML groups + SAMLGroupA["Group A"] --> SAMLGroupB["Group B"] + SAMLGroupA --> SAMLGroupC["Group C"] + SAMLGroupA --> SAMLGroupD["Group D"] + end + + SAMLGroupB --> |Member|SAMLUserA + SAMLGroupB --> |Member|SAMLUserB + + SAMLGroupC --> |Member|SAMLUserA + SAMLGroupC --> |Member|SAMLUserB + + SAMLGroupD --> |Member|SAMLUserD + SAMLGroupD --> |Member|SAMLUserC +``` + +```mermaid +graph TB + subgraph GitLab users + GitLabUserA[Sidney Jones] + GitLabUserB[Zhang Wei] + GitLabUserC[Alex Garcia] + GitLabUserD[Charlie Smith] + end + + subgraph GitLab groups + GitLabGroupA["Group A (SAML configured)"] --> GitLabGroupB["Group B (SAML Group Link not configured)"] + GitLabGroupA --> GitLabGroupC["Group C (SAML Group Link configured)"] + GitLabGroupA --> GitLabGroupD["Group D (SAML Group Link configured)"] + end + + GitLabGroupB --> |Member|GitLabUserA + + GitLabGroupC --> |Member|GitLabUserB + GitLabGroupC --> |Member|GitLabUserC + + GitLabGroupD --> |Member|GitLabUserC + GitLabGroupD --> |Member|GitLabUserD +``` + +```mermaid +graph TB + subgraph GitLab users + GitLabUserA[Sidney Jones] + GitLabUserB[Zhang Wei] + GitLabUserC[Alex Garcia] + GitLabUserD[Charlie Smith] + end + + subgraph GitLab groups after Alex Garcia signs in + GitLabGroupA[Group A] + GitLabGroupA["Group A (SAML configured)"] --> GitLabGroupB["Group B (SAML Group Link not configured)"] + GitLabGroupA --> GitLabGroupC["Group C (SAML Group Link configured)"] + GitLabGroupA --> GitLabGroupD["Group D (SAML Group Link configured)"] + end + + GitLabGroupB --> |Member|GitLabUserA + GitLabGroupC --> |Member|GitLabUserB + GitLabGroupD --> |Member|GitLabUserC + GitLabGroupD --> |Member|GitLabUserD +``` ## Passwords for users created via SAML SSO for Groups @@ -392,6 +476,9 @@ This can then be compared to the [NameID](#nameid) being sent by the identity pr ### Users receive a 404 +If you receive a `404` during setup when using "verify configuration", make sure you have used the correct +[SHA-1 generated fingerprint](../../../integration/saml.md#notes-on-configuring-your-identity-provider). + If a user is trying to sign in for the first time and the GitLab single sign-on URL has not [been configured](#configuring-your-identity-provider), they may see a 404. As outlined in the [user access section](#linking-saml-to-your-existing-gitlabcom-account), a group Owner will need to provide the URL to users. @@ -403,17 +490,18 @@ If you do not wish to use that GitLab user with the SAML login, you can [unlink ### Message: "SAML authentication failed: User has already been taken" -The user that you're signed in with already has SAML linked to a different identity. +The user that you're signed in with already has SAML linked to a different identity, or the NameID value has changed. Here are possible causes and solutions: -| Cause | Solution | -|------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Cause | Solution | +| ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | You've tried to link multiple SAML identities to the same user, for a given identity provider. | Change the identity that you sign in with. To do so, [unlink the previous SAML identity](#unlinking-accounts) from this GitLab account before attempting to sign in again. | +| The NameID changes everytime the user requests SSO identification | Check the NameID is not set with `Transient` format, or the NameID is not changing on subsequent requests.| ### Message: "SAML authentication failed: Email has already been taken" | Cause | Solution | -|------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------| +| ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | When a user account with the email address already exists in GitLab, but the user does not have the SAML identity tied to their account. | The user will need to [link their account](#user-access-and-management). | ### Message: "SAML authentication failed: Extern UID has already been taken, User has already been taken" @@ -439,8 +527,8 @@ Alternatively, when users need to [link SAML to their existing GitLab.com accoun ### The NameID has changed -| Cause | Solution | -|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Cause | Solution | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | As mentioned in the [NameID](#nameid) section, if the NameID changes for any user, the user can be locked out. This is a common problem when an email address is used as the identifier. | Follow the steps outlined in the ["SAML authentication failed: User has already been taken"](#message-saml-authentication-failed-user-has-already-been-taken) section. | ### I need to change my SAML app diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index a0c281971fc..5e90501d487 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -58,7 +58,10 @@ During this configuration, note the following: - The `Tenant URL` and `secret token` are the ones retrieved in the [previous step](#gitlab-configuration). - It is recommended to set a notification email and check the **Send an email notification when a failure occurs** checkbox. -- For mappings, we will only leave `Synchronize Azure Active Directory Users to AppName` enabled. +- For mappings, we only leave `Synchronize Azure Active Directory Users to AppName` enabled. + `Synchronize Azure Active Directory Groups to AppName` is usually disabled. However, this + does not mean Azure AD users cannot be provisioned in groups. Leaving it enabled does not break + the SCIM user provisioning, but causes errors in Azure AD that may be confusing and misleading. You can then test the connection by clicking on **Test Connection**. If the connection is successful, be sure to save your configuration before moving on. See below for [troubleshooting](#troubleshooting). @@ -69,13 +72,13 @@ Follow [Azure documentation to configure the attribute mapping](https://docs.mic The following table below provides an attribute mapping known to work with GitLab. If your SAML configuration differs from [the recommended SAML settings](index.md#azure-setup-notes), modify the corresponding `customappsso` settings accordingly. If a mapping is not listed in the -table, use the Azure defaults. +table, use the Azure defaults. For a list of required attributes, refer to the [SCIM API documentation](../../../api/scim.md). -| Azure Active Directory Attribute | `customappsso` Attribute | Matching precedence | -| -------------------------------- | ---------------------- | -------------------- | -| `objectId` | `externalId` | 1 | -| `userPrincipalName` | `emails[type eq "work"].value` | | -| `mailNickname` | `userName` | | +| Azure Active Directory Attribute | `customappsso` Attribute | Matching precedence | +| -------------------------------- | ------------------------------ | ------------------- | +| `objectId` | `externalId` | 1 | +| `userPrincipalName` | `emails[type eq "work"].value` | | +| `mailNickname` | `userName` | | For guidance, you can view [an example configuration in the troubleshooting reference](../../../administration/troubleshooting/group_saml_scim.md#azure-active-directory). @@ -162,6 +165,12 @@ graph TD B -->|Yes| D[GitLab sends message back 'Email exists'] ``` +During provisioning: + +- Both primary and secondary emails are considered when checking whether a GitLab user account exists. +- Duplicate usernames are also handled, by adding suffix `1` upon user creation. For example, + due to already existing `test_user` username, `test_user1` is used. + As long as [Group SAML](index.md) has been configured, existing GitLab.com users can link to their accounts in one of the following ways: - By updating their *primary* email address in their GitLab.com user account to match their identity provider's user profile email address. @@ -183,13 +192,12 @@ For role information, please see the [Group SAML page](index.md#user-access-and- ### Blocking access -To rescind access to the group, remove the user from the identity -provider or users list for the specific app. - -Upon the next sync, the user is deprovisioned, which means that the user is removed from the group. +To rescind access to the top-level group, all sub-groups, and projects, remove or deactivate the user +on the identity provider. SCIM providers generally update GitLab with the changes on demand, which +is minutes at most. The user's membership is revoked and they immediately lose access. NOTE: -Deprovisioning does not delete the user account. +Deprovisioning does not delete the GitLab user account. ```mermaid graph TD @@ -260,9 +268,9 @@ Alternatively, users can be removed from the SCIM app which de-links all removed Changing the SAML or SCIM configuration or provider can cause the following problems: -| Problem | Solution | -|------------------------------------------------------------------------------|--------------------| -| SAML and SCIM identity mismatch. | First [verify that the user's SAML NameId matches the SCIM externalId](#how-do-i-verify-users-saml-nameid-matches-the-scim-externalid) and then [update or fix the mismatched SCIM externalId and SAML NameId](#update-or-fix-mismatched-scim-externalid-and-saml-nameid). | +| Problem | Solution | +| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| SAML and SCIM identity mismatch. | First [verify that the user's SAML NameId matches the SCIM externalId](#how-do-i-verify-users-saml-nameid-matches-the-scim-externalid) and then [update or fix the mismatched SCIM externalId and SAML NameId](#update-or-fix-mismatched-scim-externalid-and-saml-nameid). | | SCIM identity mismatch between GitLab and the Identify Provider SCIM app. | You can confirm whether you're hitting the error because of your SCIM identity mismatch between your SCIM app and GitLab.com by using [SCIM API](../../../api/scim.md#update-a-single-scim-provisioned-user) which shows up in the `id` key and compares it with the user `externalId` in the SCIM app. You can use the same [SCIM API](../../../api/scim.md#update-a-single-scim-provisioned-user) to update the SCIM `id` for the user on GitLab.com. | ### Azure diff --git a/doc/user/group/settings/import_export.md b/doc/user/group/settings/import_export.md index a0930867b2a..516f3504a98 100644 --- a/doc/user/group/settings/import_export.md +++ b/doc/user/group/settings/import_export.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w --- # Group import/export **(FREE)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2888) in GitLab 13.0 as an experimental feature. May change in future releases. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2888) in GitLab 13.0 as an experimental feature. May change in future releases. Existing groups running on any GitLab instance or GitLab.com can be exported with all their related data and moved to a new GitLab instance. @@ -22,7 +22,7 @@ See also: Users with the [Owner role](../../permissions.md) for a group can enable import and export for that group: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General > Visibility and access controls**. 1. Scroll to **Import sources**. 1. Enable the desired **Import sources**. @@ -69,7 +69,7 @@ Users with the [Owner role](../../permissions.md) for a group can export the contents of that group: 1. On the top bar, select **Menu >** **Groups** and find your group. -1. In the left sidebar, select **Settings**. +1. On the left sidebar, select **Settings**. 1. Scroll to the **Advanced** section, and select **Export Group**. 1. After the export is generated, you should receive an email with a link to the [exported contents](#exported-contents) in a compressed tar archive, with contents in NDJSON format. diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 7d674b5deac..aaff0574ef0 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -88,7 +88,7 @@ The setting can be changed for any group by: 1. On the left sidebar, select **Settings > General**. 1. Expand the **Permissions, LFS, 2FA** section. - An administrator: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Groups**. 1. Select the group, and select **Edit**. diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index 4d254279a3d..68ae5e0df2d 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Value Stream Analytics **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196455) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9 at the group level. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196455) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9 for groups. Value Stream Analytics measures the time spent to go from an [idea to production](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab) @@ -79,6 +79,9 @@ Data is shown for workflow items created during the selected date range. To filt ## How metrics are measured +> DORA API-based deployment metrics [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/337256) +> to Premium in GitLab 14.3 for group-level Value Stream Analytics. + The "Time" metrics near the top of the page are measured as follows: - **Lead time**: median time from issue created to issue closed. @@ -113,7 +116,7 @@ Each stage of Value Stream Analytics is further described in the table below. | **Stage** | **Description** | | --------- | --------------- | -| Issue | Measures the median time between creating an issue and taking action to solve it, by either labeling it or adding it to a milestone, whatever comes first. The label is tracked only if it already has an [Issue Board list](../../project/issue_board.md) created for it. | +| Issue | Measures the median time between creating an issue and taking action to solve it, by either labeling it or adding it to a milestone, whatever comes first. The label is tracked only if it already has an [issue board list](../../project/issue_board.md) created for it. | | Plan | Measures the median time between the action you took for the previous stage, and pushing the first commit to the branch. The very first commit of the branch is the one that triggers the separation between **Plan** and **Code**, and at least one of the commits in the branch needs to contain the related issue number (for example, `#42`). If none of the commits in the branch mention the related issue number, it is not considered to the measurement time of the stage. | | Code | Measures the median time between pushing a first commit (previous stage) and creating a merge request (MR) related to that commit. The key to keep the process tracked is to include the [issue closing pattern](../../project/issues/managing_issues.md#closing-issues-automatically) to the description of the merge request (for example, `Closes #xxx`, where `xxx` is the number of the issue related to this merge request). If the closing pattern is not present, then the calculation takes the creation time of the first commit in the merge request as the start time. | | Test | Measures the median time to run the entire pipeline for that project. It's related to the time GitLab CI/CD takes to run every job for the commits pushed to that merge request defined in the previous stage. It is basically the start->finish time for all pipelines. | @@ -136,7 +139,7 @@ To sum up, anything that doesn't follow [GitLab flow](../../../topics/gitlab_flo Value Stream Analytics dashboard does not present any data for: - Merge requests that do not close an issue. -- Issues not labeled with a label present in the Issue Board or for issues not assigned a milestone. +- Issues not labeled with a label present in the issue board or for issues not assigned a milestone. - Staging stage, if the project has no [production environment](#how-the-production-environment-is-identified). ## How the production environment is identified diff --git a/doc/user/index.md b/doc/user/index.md index 8fc91ec95ea..d6eaad469c1 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -43,7 +43,7 @@ GitLab is a Git-based platform that integrates a great number of essential tools - Hosting code in repositories with version control. - Tracking proposals for new implementations, bug reports, and feedback with a fully featured [Issue tracker](project/issues/index.md). -- Organizing and prioritizing with [Issue Boards](project/issue_board.md). +- Organizing and prioritizing with [issue boards](project/issue_board.md). - Reviewing code in [Merge Requests](project/merge_requests/index.md) with live-preview changes per branch with [Review Apps](../ci/review_apps/index.md). - Building, testing, and deploying with built-in [Continuous Integration](../ci/index.md). @@ -58,7 +58,7 @@ With GitLab Enterprise Edition, you can also: - Improve collaboration with: - [Merge Request Approvals](project/merge_requests/approvals/index.md). - [Multiple Assignees for Issues](project/issues/multiple_assignees_for_issues.md). - - [Multiple Issue Boards](project/issue_board.md#multiple-issue-boards). + - [Multiple issue boards](project/issue_board.md#multiple-issue-boards). - Create formal relationships between issues with [linked issues](project/issues/related_issues.md). - Use [Burndown Charts](project/milestones/burndown_and_burnup_charts.md) to track progress during a sprint or while working on a new version of their software. - Leverage [Elasticsearch](../integration/elasticsearch.md) with [Advanced Search](search/advanced_search.md) for faster, more advanced code search across your entire GitLab instance. @@ -66,7 +66,7 @@ With GitLab Enterprise Edition, you can also: - [Mirror a repository](project/repository/repository_mirroring.md) from elsewhere on your local server. - View your entire CI/CD pipeline involving more than one project with [Multiple-Project Pipelines](../ci/pipelines/multi_project_pipelines.md). - [Lock files](project/file_lock.md) to prevent conflicts. -- View the current health and status of each CI environment running on Kubernetes with [Deploy Boards](project/deploy_boards.md). +- View the current health and status of each CI environment running on Kubernetes with [deploy boards](project/deploy_boards.md). - Leverage continuous delivery method with [Canary Deployments](project/canary_deployments.md). - Scan your code for vulnerabilities and [display them in merge requests](application_security/sast/index.md). diff --git a/doc/user/infrastructure/clusters/connect/index.md b/doc/user/infrastructure/clusters/connect/index.md new file mode 100644 index 00000000000..ada278292a9 --- /dev/null +++ b/doc/user/infrastructure/clusters/connect/index.md @@ -0,0 +1,126 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Connect a cluster to GitLab **(FREE)** + +You can create new or connect existing clusters to GitLab through different [levels](#cluster-levels), +using different [methods](#methods-to-connect-a-cluster-to-gitlab). + +Before getting started: + +1. Check the [supported Kubernetes cluster versions](#supported-cluster-versions). +1. Define the [cluster level](#cluster-levels) according to your case. + +After that: + +1. Choose the [method](#methods-to-connect-a-cluster-to-gitlab) +to connect your cluster according to your case. +1. [View your clusters](#view-your-clusters) connected to GitLab. + +## Methods to connect a cluster to GitLab + +GitLab offers three methods to connect existing and create new clusters: + +- **GitLab Kubernetes Agent**: the best solution to +[connect existing clusters](#connect-existing-clusters-to-gitlab). +- **Infrastructure as Code**: it's a broader infrastructure management +toolset that includes managing your cluster. It's the recommended +solution to [create a new cluster](#create-new-clusters-from-gitlab) +from GitLab. +- **Certificate-based method**: our first and legacy solution uses +cluster certificates to connect your cluster to GitLab. It is no longer +recommended for [security implications](#security-implications-for-clusters-connected-with-certificates). + +### Connect existing clusters to GitLab + +To safely connect and configure an existing cluster on the **project level**, +we **recommend** using the [GitLab Kubernetes Agent](../../../clusters/agent/index.md). +We are working to support [the Agent for connecting a cluster at the group level](https://gitlab.com/groups/gitlab-org/-/epics/5784). + +Alternatively, you can use [cluster certificates](../../../project/clusters/add_existing_cluster.md) +to connect clusters in all levels (projects, group, instance). However, +for [security implications](#security-implications-for-clusters-connected-with-certificates), +we don't recommend using this method. + +### Create new clusters from GitLab + +To safely create new clusters from GitLab, use +[Infrastructure as Code](../../iac/index.md#create-a-new-cluster-through-iac). + +The [certificate-based method to create a new cluster](../../../project/clusters/add_remove_clusters.md) +is still available through the GitLab UI but was **deprecated** in GitLab 14.0. +If possible, we don't recommend using this method. + +### Connect multiple clusters to a single project + +To connect multiple clusters to a single project in GitLab, +we **recommend** using the [GitLab Kubernetes Agent](../../../clusters/agent/index.md). + +You can also use the [certificate-based method](../../../project/clusters/multiple_kubernetes_clusters.md), +but, for [security implications](#security-implications-for-clusters-connected-with-certificates), +we don't recommend using this method. + +## Cluster levels + +Choose your cluster's level according to its purpose: + +| Level | Purpose | +|--|--| +| [Project level](../../../project/clusters/index.md) | Use your cluster for a single project. | +| [Group level](../../../group/clusters/index.md) | Use the same cluster across multiple projects within your group. | +| [Instance level](../../../instance/clusters/index.md) **(FREE SELF)** | Use the same cluster across groups and projects within your instance. | + +## Supported cluster versions + +GitLab is committed to support at least two production-ready Kubernetes minor +versions at any given time. We regularly review the versions we support, and +provide a three-month deprecation period before we remove support of a specific +version. The range of supported versions is based on the evaluation of: + +- The versions supported by major managed Kubernetes providers. +- The versions [supported by the Kubernetes community](https://kubernetes.io/releases/version-skew-policy/#supported-versions). + +GitLab supports the following Kubernetes versions, and you can upgrade your +Kubernetes version to any supported version at any time: + +- 1.19 (support ends on February 22, 2022) +- 1.18 (support ends on November 22, 2021) +- 1.17 (support ends on September 22, 2021) + +Some GitLab features may support versions outside the range provided here. + +## View your clusters + +To view the Kubernetes clusters connected to your project, +group, or instance, open the cluster's page according to the +[level](#cluster-levels) of your cluster. + +**Project-level clusters:** + +1. Go to your project's homepage. +1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. + +**Group-level clusters:** + +1. Go to your group's homepage. +1. On the left sidebar, select **Kubernetes**. + +**Instance-level clusters:** **(FREE SELF)** + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Kubernetes**. + +## Security implications for clusters connected with certificates + +WARNING: +The whole cluster security is based on a model where [developers](../../../permissions.md) +are trusted, so **only trusted users should be allowed to control your clusters**. + +The use of cluster certificates to connect your cluster grants +access to a wide set of functionalities needed to successfully +build and deploy a containerized application. Bear in mind that +the same credentials are used for all the applications running +on the cluster. diff --git a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md index 35af316d7ac..90044fa74e1 100644 --- a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md @@ -48,7 +48,7 @@ so that your credentials are not exposed through the code. To do so, follow the 1. On your computer, encode the JSON file to `base64` (replace `/path/to/sa-key.json` to the path to your key): ```shell - base64 /path/to/sa-key.json | tr -d \\n` + base64 /path/to/sa-key.json | tr -d \\n ``` 1. Use the output of this command as the `BASE64_GOOGLE_CREDENTIALS` environment variable in the next step. diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md b/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md index 3bf79ea90c7..9ef7bd0f3ff 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md @@ -6,16 +6,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Install cert-manager with a cluster management project -> [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. +> - [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. +> - Support for cert-manager v1.4 was [introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/69405) in GitLab 14.3. Assuming you already have a [Cluster management project](../../../../../user/clusters/management_project.md) created from a [management project template](../../../../../user/clusters/management_project_template.md), to install cert-manager you should uncomment this line from your `helmfile.yaml`: ```yaml - - path: applications/cert-manager/helmfile.yaml + - path: applications/cert-manager-1-4/helmfile.yaml ``` +NOTE: +We kept the `- path: applications/cert-manager/helmfile.yaml` with cert-manager v0.10 to facilitate +the [migration from GitLab Managed Apps to a cluster management project](../../../../clusters/migrating_from_gma_to_project_template.md). + cert-manager: - Is installed by default into the `gitlab-managed-apps` namespace of your cluster. @@ -24,7 +29,7 @@ cert-manager: email address to be specified. The email address is used by Let's Encrypt to contact you about expiring certificates and issues related to your account. -The following configuration in your `applications/cert-manager/helmfile.yaml` is required to install cert-manager: +To install cert-manager in your cluster, configure your `applications/cert-manager-1-4/helmfile.yaml` to: ```yaml certManager: @@ -48,9 +53,3 @@ You can customize the installation of cert-manager by defining a management project. Refer to the [chart](https://github.com/jetstack/cert-manager) for the available configuration options. - -Support for installing the Cert Manager managed application is provided by the -GitLab Configure group. If you run into unknown issues, -[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at -least 2 people from the -[Configure group](https://about.gitlab.com/handbook/product/categories/#configure-group). diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/cilium.md b/doc/user/infrastructure/clusters/manage/management_project_applications/cilium.md index 4e84f2c5ef4..c19bfbfb1b1 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/cilium.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/cilium.md @@ -120,9 +120,3 @@ global: enabled: - 'flow:sourceContext=namespace;destinationContext=namespace' ``` - -Support for installing the Cilium managed application is provided by the -GitLab Container Security group. If you run into unknown issues, -[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at -least 2 people from the -[Container Security group](https://about.gitlab.com/handbook/product/categories/#container-security-group). diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/elasticstack.md b/doc/user/infrastructure/clusters/manage/management_project_applications/elasticstack.md index 3d2b3caf0af..dbde9bd90b0 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/elasticstack.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/elasticstack.md @@ -27,8 +27,3 @@ You can customize the installation of Elastic Stack by updating the management project. Refer to the [chart](https://gitlab.com/gitlab-org/charts/elastic-stack) for all available configuration options. - -Support for installing the Elastic Stack managed application is provided by the -GitLab APM group. If you run into unknown issues, -[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at -least 2 people from the [APM group](https://about.gitlab.com/handbook/product/categories/#apm-group). diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/falco.md b/doc/user/infrastructure/clusters/manage/management_project_applications/falco.md index dff0c3bd7bc..7bd2a4a5133 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/falco.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/falco.md @@ -93,9 +93,3 @@ You can check these logs with the following command: ```shell kubectl -n gitlab-managed-apps logs -l app=falco ``` - -Support for installing the Falco managed application is provided by the -GitLab Container Security group. If you run into unknown issues, -[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at -least 2 people from the -[Container Security group](https://about.gitlab.com/handbook/product/categories/#container-security-group). diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/fluentd.md b/doc/user/infrastructure/clusters/manage/management_project_applications/fluentd.md index bf05f8f87d8..c5de0511c2f 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/fluentd.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/fluentd.md @@ -28,9 +28,3 @@ for the current development release of Fluentd for all available configuration o The configuration chart link points to the current development release, which may differ from the version you have installed. To ensure compatibility, switch to the specific branch or tag you are using. - -Support for installing the Fluentd managed application is provided by the -GitLab Container Security group. If you run into unknown issues, -[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at -least 2 people from the -[Container Security group](https://about.gitlab.com/handbook/product/categories/#container-security-group). diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md b/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md index 4f17dbab11b..5ee26db754e 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md @@ -24,8 +24,3 @@ You can customize the installation of Ingress by updating the management project. Refer to the [chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress) for the available configuration options. - -Support for installing the Ingress managed application is provided by the GitLab Configure group. -If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), -and ping at least 2 people from the -[Configure group](https://about.gitlab.com/handbook/product/categories/#configure-group). diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/prometheus.md b/doc/user/infrastructure/clusters/manage/management_project_applications/prometheus.md index 19e6c76d133..3420f340c94 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/prometheus.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/prometheus.md @@ -25,8 +25,3 @@ You can customize the installation of Prometheus by updating the management project. Refer to the [Configuration section](https://github.com/helm/charts/tree/master/stable/prometheus#configuration) of the Prometheus chart's README for the available configuration options. - -Support for installing the Prometheus managed application is provided by the -GitLab APM group. If you run into unknown issues, -[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at -least 2 people from the [APM group](https://about.gitlab.com/handbook/product/categories/#apm-group). diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md b/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md index 56e01be68cb..841f2af7863 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md @@ -18,6 +18,8 @@ uncomment this line from your `helmfile.yaml`: GitLab Runner is installed by default into the `gitlab-managed-apps` namespace of your cluster. +## Required variables + For GitLab Runner to function, you _must_ specify the following in your `applications/gitlab-runner/values.yaml.gotmpl` file: @@ -28,10 +30,10 @@ For GitLab Runner to function, you _must_ specify the following in your These values can be specified using [CI/CD variables](../../../../../ci/variables/index.md): -- `GITLAB_RUNNER_GITLAB_URL` is used for `gitlabUrl`. +- `CI_SERVER_URL` is used for `gitlabUrl`. If you are using GitLab.com, you don't need to set this variable. - `GITLAB_RUNNER_REGISTRATION_TOKEN` is used for `runnerRegistrationToken` -The methods of specifying these values are mutually exclusive. Either specify variables `GITLAB_RUNNER_REGISTRATION_TOKEN` and `GITLAB_RUNNER_TOKEN` as CI variables (recommended) or provide values for `runnerRegistrationToken:` and `runnerToken:` in `applications/gitlab-runner/values.yaml.gotmpl`. +The methods of specifying these values are mutually exclusive. Either specify variables `GITLAB_RUNNER_REGISTRATION_TOKEN` and `CI_SERVER_URL` as CI variables (recommended) or provide values for `runnerRegistrationToken:` and `gitlabUrl:` in `applications/gitlab-runner/values.yaml.gotmpl`. The runner registration token allows connection to a project by a runner and therefore should be treated as a secret to prevent malicious use and code exfiltration through a runner. For this reason, we recommend that you specify the runner registration token as a [protected variable](../../../../../ci/variables/index.md#protect-a-cicd-variable) and [masked variable](../../../../../ci/variables/index.md#mask-a-cicd-variable) and do not commit them to the Git repository in the `values.yaml.gotmpl` file. @@ -40,9 +42,3 @@ You can customize the installation of GitLab Runner by defining management project. Refer to the [chart](https://gitlab.com/gitlab-org/charts/gitlab-runner) for the available configuration options. - -Support for installing the GitLab Runner managed application is provided by the -GitLab Runner group. If you run into unknown issues, -[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at -least 2 people from the -[Runner group](https://about.gitlab.com/handbook/product/categories/#runner-group). diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/sentry.md b/doc/user/infrastructure/clusters/manage/management_project_applications/sentry.md index 4d82fe389d2..300350010af 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/sentry.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/sentry.md @@ -68,9 +68,3 @@ ingress: postgresql: postgresqlPassword: example-postgresql-password ``` - -Support for installing the Sentry managed application is provided by the -GitLab Health group. If you run into unknown issues, -[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at -least 2 people from the -[Health group](https://about.gitlab.com/handbook/product/categories/#health-group). diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md b/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md index 291321963d0..d6b4eb5c157 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md @@ -100,9 +100,3 @@ kubectl -n gitlab-managed-apps exec -it vault-0 sh This should give you your unseal keys and initial root token. Make sure to note these down and keep these safe, as they're required to unseal the Vault throughout its lifecycle. - -Support for installing the Vault managed application is provided by the -GitLab Release Management group. If you run into unknown issues, -[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at -least 2 people from the -[Release Management group](https://about.gitlab.com/handbook/product/categories/#release-management-group). diff --git a/doc/user/infrastructure/img/terraform_list_view_v13_8.png b/doc/user/infrastructure/iac/img/terraform_list_view_v13_8.png Binary files differindex 6eb85285e81..6eb85285e81 100644 --- a/doc/user/infrastructure/img/terraform_list_view_v13_8.png +++ b/doc/user/infrastructure/iac/img/terraform_list_view_v13_8.png diff --git a/doc/user/infrastructure/img/terraform_plan_log_v13_0.png b/doc/user/infrastructure/iac/img/terraform_plan_log_v13_0.png Binary files differindex c3c6f6b2f8b..c3c6f6b2f8b 100644 --- a/doc/user/infrastructure/img/terraform_plan_log_v13_0.png +++ b/doc/user/infrastructure/iac/img/terraform_plan_log_v13_0.png diff --git a/doc/user/infrastructure/img/terraform_plan_widget_v13_2.png b/doc/user/infrastructure/iac/img/terraform_plan_widget_v13_2.png Binary files differindex 564835a5dbe..564835a5dbe 100644 --- a/doc/user/infrastructure/img/terraform_plan_widget_v13_2.png +++ b/doc/user/infrastructure/iac/img/terraform_plan_widget_v13_2.png diff --git a/doc/user/infrastructure/iac/index.md b/doc/user/infrastructure/iac/index.md index 5b44490f78d..89df9c1d18f 100644 --- a/doc/user/infrastructure/iac/index.md +++ b/doc/user/infrastructure/iac/index.md @@ -65,7 +65,7 @@ Amazon S3 or Google Cloud Storage. Its features include: - Locking and unlocking state. - Remote Terraform plan and apply execution. -Read more on setting up and [using GitLab Managed Terraform states](../terraform_state.md) +Read more on setting up and [using GitLab Managed Terraform states](terraform_state.md). ## Terraform module registry @@ -81,7 +81,7 @@ solution to help collaboration around Terraform code changes and their expected effects using the Merge Request pages. This way users don't have to build custom tools or rely on 3rd party solutions to streamline their IaC workflows. -Read more on setting up and [using the merge request integrations](../mr_integration.md). +Read more on setting up and [using the merge request integrations](mr_integration.md). ## The GitLab Terraform provider diff --git a/doc/user/infrastructure/iac/mr_integration.md b/doc/user/infrastructure/iac/mr_integration.md new file mode 100644 index 00000000000..853a39a59a8 --- /dev/null +++ b/doc/user/infrastructure/iac/mr_integration.md @@ -0,0 +1,210 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Terraform integration in Merge Requests **(FREE)** + +Collaborating around Infrastructure as Code (IaC) changes requires both code changes and expected infrastructure changes to be checked and approved. GitLab provides a solution to help collaboration around Terraform code changes and their expected effects using the Merge Request pages. This way users don't have to build custom tools or rely on 3rd party solutions to streamline their IaC workflows. + +## Output Terraform Plan information into a merge request + +Using the [GitLab Terraform Report artifact](../../../ci/yaml/index.md#artifactsreportsterraform), +you can expose details from `terraform plan` runs directly into a merge request widget, +enabling you to see statistics about the resources that Terraform creates, +modifies, or destroys. + +WARNING: +Like any other job artifact, Terraform Plan data is [viewable by anyone with Guest access](../../permissions.md) to the repository. +Neither Terraform nor GitLab encrypts the plan file by default. If your Terraform Plan +includes sensitive data such as passwords, access tokens, or certificates, we strongly +recommend encrypting plan output or modifying the project visibility settings. + +## Configure Terraform report artifacts + +GitLab ships with a [pre-built CI template](index.md#quick-start) that uses GitLab Managed Terraform state and integrates Terraform changes into merge requests. We recommend customizing the pre-built image and relying on the `gitlab-terraform` helper provided within for a quick setup. + +To manually configure a GitLab Terraform Report artifact: + +1. For simplicity, let's define a few reusable variables to allow us to + refer to these files multiple times: + + ```yaml + variables: + PLAN: plan.cache + PLAN_JSON: plan.json + ``` + +1. Install `jq`, a + [lightweight and flexible command-line JSON processor](https://stedolan.github.io/jq/). +1. Create an alias for a specific `jq` command that parses out the information we + want to extract from the `terraform plan` output: + + ```yaml + before_script: + - apk --no-cache add jq + - alias convert_report="jq -r '([.resource_changes[]?.change.actions?]|flatten)|{\"create\":(map(select(.==\"create\"))|length),\"update\":(map(select(.==\"update\"))|length),\"delete\":(map(select(.==\"delete\"))|length)}'" + ``` + + NOTE: + In distributions that use Bash (for example, Ubuntu), `alias` statements are not + expanded in non-interactive mode. If your pipelines fail with the error + `convert_report: command not found`, alias expansion can be activated explicitly + by adding a `shopt` command to your script: + + ```yaml + before_script: + - shopt -s expand_aliases + - alias convert_report="jq -r '([.resource_changes[]?.change.actions?]|flatten)|{\"create\":(map(select(.==\"create\"))|length),\"update\":(map(select(.==\"update\"))|length),\"delete\":(map(select(.==\"delete\"))|length)}'" + ``` + +1. Define a `script` that runs `terraform plan` and `terraform show`. These commands + pipe the output and convert the relevant bits into a store variable `PLAN_JSON`. + This JSON is used to create a + [GitLab Terraform Report artifact](../../../ci/yaml/index.md#artifactsreportsterraform). + The Terraform report obtains a Terraform `tfplan.json` file. The collected + Terraform plan report is uploaded to GitLab as an artifact, and is shown in merge requests. + + ```yaml + plan: + stage: build + script: + - terraform plan -out=$PLAN + - terraform show --json $PLAN | convert_report > $PLAN_JSON + artifacts: + reports: + terraform: $PLAN_JSON + ``` + + For a full example using the pre-built image, see [Example `.gitlab-ci.yml` + file](#example-gitlab-ciyml-file). + + For an example displaying multiple reports, see [`.gitlab-ci.yml` multiple reports file](#multiple-terraform-plan-reports). + +1. Running the pipeline displays the widget in the merge request, like this: + +  + +1. Clicking the **View Full Log** button in the widget takes you directly to the + plan output present in the pipeline logs: + +  + +### Example `.gitlab-ci.yml` file + +```yaml +default: + image: registry.gitlab.com/gitlab-org/terraform-images/stable:latest + + cache: + key: example-production + paths: + - ${TF_ROOT}/.terraform + +variables: + TF_ROOT: ${CI_PROJECT_DIR}/environments/example/production + TF_ADDRESS: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/example-production + +before_script: + - cd ${TF_ROOT} + +stages: + - prepare + - validate + - build + - deploy + +init: + stage: prepare + script: + - gitlab-terraform init + +validate: + stage: validate + script: + - gitlab-terraform validate + +plan: + stage: build + script: + - gitlab-terraform plan + - gitlab-terraform plan-json + artifacts: + name: plan + paths: + - ${TF_ROOT}/plan.cache + reports: + terraform: ${TF_ROOT}/plan.json + +apply: + stage: deploy + environment: + name: production + script: + - gitlab-terraform apply + dependencies: + - plan + when: manual + only: + - master +``` + +### Multiple Terraform Plan reports + +Starting with GitLab version 13.2, you can display multiple reports on the Merge Request +page. The reports also display the `artifacts: name:`. See example below for a suggested setup. + +```yaml +default: + image: + name: registry.gitlab.com/gitlab-org/gitlab-build-images:terraform + entrypoint: + - '/usr/bin/env' + - 'PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin' + + cache: + paths: + - .terraform + +stages: + - build + +.terraform-plan-generation: + stage: build + variables: + PLAN: plan.tfplan + JSON_PLAN_FILE: tfplan.json + before_script: + - cd ${TERRAFORM_DIRECTORY} + - terraform --version + - terraform init + - apk --no-cache add jq + script: + - terraform validate + - terraform plan -out=${PLAN} + - terraform show --json ${PLAN} | jq -r '([.resource_changes[]?.change.actions?]|flatten)|{"create":(map(select(.=="create"))|length),"update":(map(select(.=="update"))|length),"delete":(map(select(.=="delete"))|length)}' > ${JSON_PLAN_FILE} + artifacts: + reports: + terraform: ${TERRAFORM_DIRECTORY}/${JSON_PLAN_FILE} + +review_plan: + extends: .terraform-plan-generation + variables: + TERRAFORM_DIRECTORY: "review/" + # Review will not include an artifact name + +staging_plan: + extends: .terraform-plan-generation + variables: + TERRAFORM_DIRECTORY: "staging/" + artifacts: + name: Staging + +production_plan: + extends: .terraform-plan-generation + variables: + TERRAFORM_DIRECTORY: "production/" + artifacts: + name: Production +``` diff --git a/doc/user/infrastructure/iac/terraform_state.md b/doc/user/infrastructure/iac/terraform_state.md new file mode 100644 index 00000000000..fb051c7fa14 --- /dev/null +++ b/doc/user/infrastructure/iac/terraform_state.md @@ -0,0 +1,446 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# GitLab managed Terraform State **(FREE)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2673) in GitLab 13.0. + +[Terraform remote backends](https://www.terraform.io/docs/language/settings/backends/index.html) +enable you to store the state file in a remote, shared store. GitLab uses the +[Terraform HTTP backend](https://www.terraform.io/docs/language/settings/backends/http.html) +to securely store the state files in local storage (the default) or +[the remote store of your choice](../../../administration/terraform_state.md). + +WARNING: +Using local storage (the default) on clustered deployments of GitLab will result in +a split state across nodes, making subsequent executions of Terraform inconsistent. +You are highly advised to use a remote storage in that case. + +The GitLab managed Terraform state backend can store your Terraform state easily and +securely, and spares you from setting up additional remote resources like +Amazon S3 or Google Cloud Storage. Its features include: + +- Versioning of Terraform state files. +- Supporting encryption of the state file both in transit and at rest. +- Locking and unlocking state. +- Remote Terraform plan and apply execution. + +A GitLab **administrator** must [setup the Terraform state storage configuration](../../../administration/terraform_state.md) +before using this feature. + +## Permissions for using Terraform + +In GitLab version 13.1, the [Maintainer role](../../permissions.md) was required to use a +GitLab managed Terraform state backend. In GitLab versions 13.2 and greater, the +[Maintainer role](../../permissions.md) is required to lock, unlock, and write to the state +(using `terraform apply`), while the [Developer role](../../permissions.md) is required to read +the state (using `terraform plan -lock=false`). + +## Set up GitLab-managed Terraform state + +To get started with a GitLab-managed Terraform state, there are two different options: + +- [Use a local machine](#get-started-using-local-development). +- [Use GitLab CI](#get-started-using-gitlab-ci). + +Terraform States can be found by navigating to a Project's +**{cloud-gear}** **Infrastructure > Terraform** page. + +### Get started using local development + +If you plan to only run `terraform plan` and `terraform apply` commands from your +local machine, this is a simple way to get started: + +1. Create your project on your GitLab instance. +1. Navigate to **Settings > General** and note your **Project name** + and **Project ID**. +1. Define the Terraform backend in your Terraform project to be: + + ```hcl + terraform { + backend "http" { + } + } + ``` + +1. Create a [Personal Access Token](../../profile/personal_access_tokens.md) with + the `api` scope. + +1. On your local machine, run `terraform init`, passing in the following options, + replacing `<YOUR-STATE-NAME>`, `<YOUR-PROJECT-ID>`, `<YOUR-USERNAME>` and + `<YOUR-ACCESS-TOKEN>` with the relevant values. This command initializes your + Terraform state, and stores that state in your GitLab project. The name of + your state can contain only uppercase and lowercase letters, decimal digits, + hyphens, and underscores. This example uses `gitlab.com`: + + ```shell + terraform init \ + -backend-config="address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-STATE-NAME>" \ + -backend-config="lock_address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-STATE-NAME>/lock" \ + -backend-config="unlock_address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-STATE-NAME>/lock" \ + -backend-config="username=<YOUR-USERNAME>" \ + -backend-config="password=<YOUR-ACCESS-TOKEN>" \ + -backend-config="lock_method=POST" \ + -backend-config="unlock_method=DELETE" \ + -backend-config="retry_wait_min=5" + ``` + +If you already have a GitLab-managed Terraform state, you can use the `terraform init` command +with the prepopulated parameters values: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Infrastructure > Terraform**. +1. Next to the environment you want to use, select the [Actions menu](#managing-state-files) + **{ellipsis_v}** and select **Copy Terraform init command**. + +You can now run `terraform plan` and `terraform apply` as you normally would. + +### Get started using GitLab CI + +If you don't want to start with local development, you can also use GitLab CI to +run your `terraform plan` and `terraform apply` commands. + +Next, [configure the backend](#configure-the-backend). + +#### Configure the backend + +After executing the `terraform init` command, you must configure the Terraform backend +and the CI YAML file: + +1. In your Terraform project, define the [HTTP backend](https://www.terraform.io/docs/language/settings/backends/http.html) + by adding the following code block in a `.tf` file (such as `backend.tf`) to + define the remote backend: + + ```hcl + terraform { + backend "http" { + } + } + ``` + +1. In the root directory of your project repository, configure a + `.gitlab-ci.yml` file. This example uses a pre-built image which includes a + `gitlab-terraform` helper. For supported Terraform versions, see the [GitLab + Terraform Images project](https://gitlab.com/gitlab-org/terraform-images). + + ```yaml + image: registry.gitlab.com/gitlab-org/terraform-images/stable:latest + ``` + +1. In the `.gitlab-ci.yml` file, define some CI/CD variables to ease + development. In this example, `TF_ROOT` is the directory where the Terraform + commands must be executed, `TF_ADDRESS` is the URL to the state on the GitLab + instance where this pipeline runs, and the final path segment in `TF_ADDRESS` + is the name of the Terraform state. Projects may have multiple states, and + this name is arbitrary, so in this example we set it to `example-production` + which corresponds with the directory we're using as our `TF_ROOT`, and we + ensure that the `.terraform` directory is cached between jobs in the pipeline + using a cache key based on the state name (`example-production`): + + ```yaml + variables: + TF_ROOT: ${CI_PROJECT_DIR}/environments/example/production + TF_ADDRESS: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/example-production + + cache: + key: example-production + paths: + - ${TF_ROOT}/.terraform + ``` + +1. In a `before_script`, change to your `TF_ROOT`: + + ```yaml + before_script: + - cd ${TF_ROOT} + + stages: + - prepare + - validate + - build + - deploy + + init: + stage: prepare + script: + - gitlab-terraform init + + validate: + stage: validate + script: + - gitlab-terraform validate + + plan: + stage: build + script: + - gitlab-terraform plan + - gitlab-terraform plan-json + artifacts: + name: plan + paths: + - ${TF_ROOT}/plan.cache + reports: + terraform: ${TF_ROOT}/plan.json + + apply: + stage: deploy + environment: + name: production + script: + - gitlab-terraform apply + dependencies: + - plan + when: manual + only: + - master + ``` + +1. Push your project to GitLab, which triggers a CI job pipeline. This pipeline + runs the `gitlab-terraform init`, `gitlab-terraform validate`, and + `gitlab-terraform plan` commands. + +The output from the above `terraform` commands should be viewable in the job logs. + +WARNING: +Like any other job artifact, Terraform plan data is [viewable by anyone with Guest access](../../permissions.md) to the repository. +Neither Terraform nor GitLab encrypts the plan file by default. If your Terraform plan +includes sensitive data such as passwords, access tokens, or certificates, GitLab strongly +recommends encrypting plan output or modifying the project visibility settings. + +### Example project + +See [this reference project](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-aws) using GitLab and Terraform to deploy a basic AWS EC2 in a custom VPC. + +## Using a GitLab managed Terraform state backend as a remote data source + +You can use a GitLab-managed Terraform state as a +[Terraform data source](https://www.terraform.io/docs/language/state/remote-state-data.html). +To use your existing Terraform state backend as a data source, provide the following details +as [Terraform input variables](https://www.terraform.io/docs/language/values/variables.html): + +- **address**: The URL of the remote state backend you want to use as a data source. + For example, `https://gitlab.com/api/v4/projects/<TARGET-PROJECT-ID>/terraform/state/<TARGET-STATE-NAME>`. +- **username**: The username to authenticate with the data source. If you are using a [Personal Access Token](../../profile/personal_access_tokens.md) for + authentication, this is your GitLab username. If you are using GitLab CI, this is `'gitlab-ci-token'`. +- **password**: The password to authenticate with the data source. If you are using a Personal Access Token for + authentication, this is the token value. If you are using GitLab CI, it is the contents of the `${CI_JOB_TOKEN}` CI/CD variable. + +An example setup is shown below: + +1. Create a file named `example.auto.tfvars` with the following contents: + + ```plaintext + example_remote_state_address=https://gitlab.com/api/v4/projects/<TARGET-PROJECT-ID>/terraform/state/<TARGET-STATE-NAME> + example_username=<GitLab username> + example_access_token=<GitLab Personal Access Token> + ``` + +1. Define the data source by adding the following code block in a `.tf` file (such as `data.tf`): + + ```hcl + data "terraform_remote_state" "example" { + backend = "http" + + config = { + address = var.example_remote_state_address + username = var.example_username + password = var.example_access_token + } + } + ``` + +Outputs from the data source can now be referenced in your Terraform resources +using `data.terraform_remote_state.example.outputs.<OUTPUT-NAME>`. + +You need at least the [Developer role](../../permissions.md) in the target project +to read the Terraform state. + +## Migrating to GitLab Managed Terraform state + +Terraform supports copying the state when the backend is changed or +reconfigured. This can be useful if you need to migrate from another backend to +GitLab managed Terraform state. Using a local terminal is recommended to run the commands needed for migrating to GitLab Managed Terraform state. + +The following example demonstrates how to change the state name, the same workflow is needed to migrate to GitLab Managed Terraform state from a different state storage backend. + +### Setting up the initial backend + +```shell +PROJECT_ID="<gitlab-project-id>" +TF_USERNAME="<gitlab-username>" +TF_PASSWORD="<gitlab-personal-access-token>" +TF_ADDRESS="https://gitlab.com/api/v4/projects/${PROJECT_ID}/terraform/state/old-state-name" + +terraform init \ + -backend-config=address=${TF_ADDRESS} \ + -backend-config=lock_address=${TF_ADDRESS}/lock \ + -backend-config=unlock_address=${TF_ADDRESS}/lock \ + -backend-config=username=${TF_USERNAME} \ + -backend-config=password=${TF_PASSWORD} \ + -backend-config=lock_method=POST \ + -backend-config=unlock_method=DELETE \ + -backend-config=retry_wait_min=5 +``` + +```plaintext +Initializing the backend... + +Successfully configured the backend "http"! Terraform will automatically +use this backend unless the backend configuration changes. + +Initializing provider plugins... + +Terraform has been successfully initialized! + +You may now begin working with Terraform. Try running "terraform plan" to see +any changes that are required for your infrastructure. All Terraform commands +should now work. + +If you ever set or change modules or backend configuration for Terraform, +rerun this command to reinitialize your working directory. If you forget, other +commands will detect it and remind you to do so if necessary. +``` + +### Changing the backend + +Now that `terraform init` has created a `.terraform/` directory that knows where +the old state is, you can tell it about the new location: + +```shell +TF_ADDRESS="https://gitlab.com/api/v4/projects/${PROJECT_ID}/terraform/state/new-state-name" + +terraform init \ + -backend-config=address=${TF_ADDRESS} \ + -backend-config=lock_address=${TF_ADDRESS}/lock \ + -backend-config=unlock_address=${TF_ADDRESS}/lock \ + -backend-config=username=${TF_USERNAME} \ + -backend-config=password=${TF_PASSWORD} \ + -backend-config=lock_method=POST \ + -backend-config=unlock_method=DELETE \ + -backend-config=retry_wait_min=5 +``` + +```plaintext +Initializing the backend... +Backend configuration changed! + +Terraform has detected that the configuration specified for the backend +has changed. Terraform will now check for existing state in the backends. + + +Acquiring state lock. This may take a few moments... +Do you want to copy existing state to the new backend? + Pre-existing state was found while migrating the previous "http" backend to the + newly configured "http" backend. No existing state was found in the newly + configured "http" backend. Do you want to copy this state to the new "http" + backend? Enter "yes" to copy and "no" to start with an empty state. + + Enter a value: yes + + +Successfully configured the backend "http"! Terraform will automatically +use this backend unless the backend configuration changes. + +Initializing provider plugins... + +Terraform has been successfully initialized! + +You may now begin working with Terraform. Try running "terraform plan" to see +any changes that are required for your infrastructure. All Terraform commands +should now work. + +If you ever set or change modules or backend configuration for Terraform, +rerun this command to reinitialize your working directory. If you forget, other +commands will detect it and remind you to do so if necessary. +``` + +If you type `yes`, it copies your state from the old location to the new +location. You can then go back to running it in GitLab CI/CD. + +## Managing state files + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/273592) in GitLab 13.8. + +Users with Developer and greater [permissions](../../permissions.md) can view the +state files attached to a project at **Infrastructure > Terraform**. Users with the +Maintainer role can perform commands on the state files. The user interface +contains these fields: + + + +- **Name**: The name of the environment, with a locked (**{lock}**) icon if the + state file is locked. +- **Pipeline**: A link to the most recent pipeline and its status. +- **Details**: Information about when the state file was created or changed. +- **Actions**: Actions you can take on the state file, including copying the `terraform init` command, + downloading, locking, unlocking, or [removing](#remove-a-state-file) the state file and versions. + +NOTE: +Additional improvements to the +[graphical interface for managing state files](https://gitlab.com/groups/gitlab-org/-/epics/4563) +are planned. + +## Remove a state file + +Users with Maintainer and greater [permissions](../../permissions.md) can use the +following options to remove a state file: + +- **GitLab UI**: Go to **Infrastructure > Terraform**. In the **Actions** column, + click the vertical ellipsis (**{ellipsis_v}**) button and select + **Remove state file and versions**. +- **GitLab REST API**: You can remove a state file by making a request to the + REST API. For example: + + ```shell + curl --header "Private-Token: <your_access_token>" --request DELETE "https://gitlab.example.com/api/v4/projects/<your_project_id>/terraform/state/<your_state_name>" + ``` + +- [GitLab GraphQL API](#remove-a-state-file-with-the-gitlab-graphql-api). + +### Remove a state file with the GitLab GraphQL API + +You can remove a state file by making a GraphQL API request. For example: + +```shell +mutation deleteState { + terraformStateDelete(input: { id: "<global_id_for_the_state>" }) { + errors + } +} +``` + +You can obtain the `<global_id_for_the_state>` by querying the list of states: + +```shell +query ProjectTerraformStates { + project(fullPath: "<your_project_path>") { + terraformStates { + nodes { + id + name + } + } + } +} +``` + +For those new to the GitLab GraphQL API, read +[Getting started with GitLab GraphQL API](../../../api/graphql/getting_started.md). + +## Troubleshooting + +### Unable to lock Terraform state files in CI jobs for `terraform apply` using a plan created in a previous job + +When passing `-backend-config=` to `terraform init`, Terraform persists these values inside the plan +cache file. This includes the `password` value. + +As a result, to create a plan and later use the same plan in another CI job, you might get the error +`Error: Error acquiring the state lock` errors when using `-backend-config=password=$CI_JOB_TOKEN`. +This happens because the value of `$CI_JOB_TOKEN` is only valid for the duration of the current job. + +As a workaround, use [http backend configuration variables](https://www.terraform.io/docs/language/settings/backends/http.html#configuration-variables) in your CI job, +which is what happens behind the scenes when following the +[Get started using GitLab CI](#get-started-using-gitlab-ci) instructions. diff --git a/doc/user/infrastructure/index.md b/doc/user/infrastructure/index.md index b2d75a22615..9f28a40474e 100644 --- a/doc/user/infrastructure/index.md +++ b/doc/user/infrastructure/index.md @@ -6,9 +6,40 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Infrastructure management **(FREE)** -GitLab provides you with great solutions to help you manage your -infrastructure: +With the rise of DevOps and SRE approaches, infrastructure management becomes codified, +automatable, and software development best practices gain their place around infrastructure +management too. On one hand, the daily tasks of classical operations people changed +and are more similar to traditional software development. On the other hand, software engineers +are more likely to control their whole DevOps lifecycle, including deployments and delivery. -- [Infrastructure as Code and GitOps](iac/index.md) -- [Kubernetes clusters](../project/clusters/index.md) -- [Runbooks](../project/clusters/runbooks/index.md) +GitLab offers various features to speed up and simplify your infrastructure management practices. + +## Infrastructure as Code + +GitLab has deep integrations with Terraform to run Infrastructure as Code pipelines +and support various processes. Terraform is considered the standard in cloud infrastructure provisioning. +The various GitLab integrations help you: + +- Get started quickly without any setup. +- Collaborate around infrastructure changes in merge requests the same as you might + with code changes. +- Scale using a module registry. + +Learn more about how GitLab can help you run [Infrastructure as Code](iac/index.md). + +## Integrated Kubernetes management + +GitLab has special integrations with Kubernetes to help you deploy, manage and troubleshoot +third-party or custom applications in Kubernetes clusters. Auto DevOps provides a full +DevSecOps pipeline by default targeted at Kubernetes based deployments. To support +all the GitLab features, GitLab offers a cluster management project for easy onboarding. +The deploy boards provide quick insights into your cluster, including pod logs tailing. + +Learn more about the [GitLab integration with Kubernetes](../project/clusters/index.md). + +## Runbooks in GitLab + +Runbooks are a collection of documented procedures that explain how to carry out a task, +such as starting, stopping, debugging, or troubleshooting a system. + +Read more about [how executable runbooks work in GitLab](../project/clusters/runbooks/index.md). diff --git a/doc/user/infrastructure/mr_integration.md b/doc/user/infrastructure/mr_integration.md index 29bf218b109..81e8f7cbd33 100644 --- a/doc/user/infrastructure/mr_integration.md +++ b/doc/user/infrastructure/mr_integration.md @@ -1,210 +1,9 @@ --- -stage: Configure -group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: 'iac/mr_integration.md' +remove_date: '2021-11-26' --- -# Terraform integration in Merge Requests **(FREE)** +This document was moved to [another location](iac/mr_integration.md). -Collaborating around Infrastructure as Code (IaC) changes requires both code changes and expected infrastructure changes to be checked and approved. GitLab provides a solution to help collaboration around Terraform code changes and their expected effects using the Merge Request pages. This way users don't have to build custom tools or rely on 3rd party solutions to streamline their IaC workflows. - -## Output Terraform Plan information into a merge request - -Using the [GitLab Terraform Report artifact](../../ci/yaml/index.md#artifactsreportsterraform), -you can expose details from `terraform plan` runs directly into a merge request widget, -enabling you to see statistics about the resources that Terraform creates, -modifies, or destroys. - -WARNING: -Like any other job artifact, Terraform Plan data is [viewable by anyone with Guest access](../permissions.md) to the repository. -Neither Terraform nor GitLab encrypts the plan file by default. If your Terraform Plan -includes sensitive data such as passwords, access tokens, or certificates, we strongly -recommend encrypting plan output or modifying the project visibility settings. - -## Configure Terraform report artifacts - -GitLab ships with a [pre-built CI template](iac/index.md#quick-start) that uses GitLab Managed Terraform state and integrates Terraform changes into merge requests. We recommend customizing the pre-built image and relying on the `gitlab-terraform` helper provided within for a quick setup. - -To manually configure a GitLab Terraform Report artifact: - -1. For simplicity, let's define a few reusable variables to allow us to - refer to these files multiple times: - - ```yaml - variables: - PLAN: plan.cache - PLAN_JSON: plan.json - ``` - -1. Install `jq`, a - [lightweight and flexible command-line JSON processor](https://stedolan.github.io/jq/). -1. Create an alias for a specific `jq` command that parses out the information we - want to extract from the `terraform plan` output: - - ```yaml - before_script: - - apk --no-cache add jq - - alias convert_report="jq -r '([.resource_changes[]?.change.actions?]|flatten)|{\"create\":(map(select(.==\"create\"))|length),\"update\":(map(select(.==\"update\"))|length),\"delete\":(map(select(.==\"delete\"))|length)}'" - ``` - - NOTE: - In distributions that use Bash (for example, Ubuntu), `alias` statements are not - expanded in non-interactive mode. If your pipelines fail with the error - `convert_report: command not found`, alias expansion can be activated explicitly - by adding a `shopt` command to your script: - - ```yaml - before_script: - - shopt -s expand_aliases - - alias convert_report="jq -r '([.resource_changes[]?.change.actions?]|flatten)|{\"create\":(map(select(.==\"create\"))|length),\"update\":(map(select(.==\"update\"))|length),\"delete\":(map(select(.==\"delete\"))|length)}'" - ``` - -1. Define a `script` that runs `terraform plan` and `terraform show`. These commands - pipe the output and convert the relevant bits into a store variable `PLAN_JSON`. - This JSON is used to create a - [GitLab Terraform Report artifact](../../ci/yaml/index.md#artifactsreportsterraform). - The Terraform report obtains a Terraform `tfplan.json` file. The collected - Terraform plan report is uploaded to GitLab as an artifact, and is shown in merge requests. - - ```yaml - plan: - stage: build - script: - - terraform plan -out=$PLAN - - terraform show --json $PLAN | convert_report > $PLAN_JSON - artifacts: - reports: - terraform: $PLAN_JSON - ``` - - For a full example using the pre-built image, see [Example `.gitlab-ci.yml` - file](#example-gitlab-ciyml-file). - - For an example displaying multiple reports, see [`.gitlab-ci.yml` multiple reports file](#multiple-terraform-plan-reports). - -1. Running the pipeline displays the widget in the merge request, like this: - -  - -1. Clicking the **View Full Log** button in the widget takes you directly to the - plan output present in the pipeline logs: - -  - -### Example `.gitlab-ci.yml` file - -```yaml -default: - image: registry.gitlab.com/gitlab-org/terraform-images/stable:latest - - cache: - key: example-production - paths: - - ${TF_ROOT}/.terraform - -variables: - TF_ROOT: ${CI_PROJECT_DIR}/environments/example/production - TF_ADDRESS: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/example-production - -before_script: - - cd ${TF_ROOT} - -stages: - - prepare - - validate - - build - - deploy - -init: - stage: prepare - script: - - gitlab-terraform init - -validate: - stage: validate - script: - - gitlab-terraform validate - -plan: - stage: build - script: - - gitlab-terraform plan - - gitlab-terraform plan-json - artifacts: - name: plan - paths: - - ${TF_ROOT}/plan.cache - reports: - terraform: ${TF_ROOT}/plan.json - -apply: - stage: deploy - environment: - name: production - script: - - gitlab-terraform apply - dependencies: - - plan - when: manual - only: - - master -``` - -### Multiple Terraform Plan reports - -Starting with GitLab version 13.2, you can display multiple reports on the Merge Request -page. The reports also display the `artifacts: name:`. See example below for a suggested setup. - -```yaml -default: - image: - name: registry.gitlab.com/gitlab-org/gitlab-build-images:terraform - entrypoint: - - '/usr/bin/env' - - 'PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin' - - cache: - paths: - - .terraform - -stages: - - build - -.terraform-plan-generation: - stage: build - variables: - PLAN: plan.tfplan - JSON_PLAN_FILE: tfplan.json - before_script: - - cd ${TERRAFORM_DIRECTORY} - - terraform --version - - terraform init - - apk --no-cache add jq - script: - - terraform validate - - terraform plan -out=${PLAN} - - terraform show --json ${PLAN} | jq -r '([.resource_changes[]?.change.actions?]|flatten)|{"create":(map(select(.=="create"))|length),"update":(map(select(.=="update"))|length),"delete":(map(select(.=="delete"))|length)}' > ${JSON_PLAN_FILE} - artifacts: - reports: - terraform: ${TERRAFORM_DIRECTORY}/${JSON_PLAN_FILE} - -review_plan: - extends: .terraform-plan-generation - variables: - TERRAFORM_DIRECTORY: "review/" - # Review will not include an artifact name - -staging_plan: - extends: .terraform-plan-generation - variables: - TERRAFORM_DIRECTORY: "staging/" - artifacts: - name: Staging - -production_plan: - extends: .terraform-plan-generation - variables: - TERRAFORM_DIRECTORY: "production/" - artifacts: - name: Production -``` +<!-- This redirect file can be deleted after <2021-11-26>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/infrastructure/terraform_state.md b/doc/user/infrastructure/terraform_state.md index 179f9677b96..e71291d502e 100644 --- a/doc/user/infrastructure/terraform_state.md +++ b/doc/user/infrastructure/terraform_state.md @@ -1,431 +1,9 @@ --- -stage: Configure -group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: 'iac/terraform_state.md' +remove_date: '2021-11-26' --- -# GitLab managed Terraform State **(FREE)** +This document was moved to [another location](iac/terraform_state.md). -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2673) in GitLab 13.0. - -[Terraform remote backends](https://www.terraform.io/docs/language/settings/backends/index.html) -enable you to store the state file in a remote, shared store. GitLab uses the -[Terraform HTTP backend](https://www.terraform.io/docs/language/settings/backends/http.html) -to securely store the state files in local storage (the default) or -[the remote store of your choice](../../administration/terraform_state.md). - -WARNING: -Using local storage (the default) on clustered deployments of GitLab will result in -a split state across nodes, making subsequent executions of Terraform inconsistent. -You are highly advised to use a remote storage in that case. - -The GitLab managed Terraform state backend can store your Terraform state easily and -securely, and spares you from setting up additional remote resources like -Amazon S3 or Google Cloud Storage. Its features include: - -- Versioning of Terraform state files. -- Supporting encryption of the state file both in transit and at rest. -- Locking and unlocking state. -- Remote Terraform plan and apply execution. - -A GitLab **administrator** must [setup the Terraform state storage configuration](../../administration/terraform_state.md) -before using this feature. - -## Permissions for using Terraform - -In GitLab version 13.1, the [Maintainer role](../permissions.md) was required to use a -GitLab managed Terraform state backend. In GitLab versions 13.2 and greater, the -[Maintainer role](../permissions.md) is required to lock, unlock, and write to the state -(using `terraform apply`), while the [Developer role](../permissions.md) is required to read -the state (using `terraform plan -lock=false`). - -## Set up GitLab-managed Terraform state - -To get started with a GitLab-managed Terraform state, there are two different options: - -- [Use a local machine](#get-started-using-local-development). -- [Use GitLab CI](#get-started-using-gitlab-ci). - -Terraform States can be found by navigating to a Project's -**{cloud-gear}** **Infrastructure > Terraform** page. - -### Get started using local development - -If you plan to only run `terraform plan` and `terraform apply` commands from your -local machine, this is a simple way to get started: - -1. Create your project on your GitLab instance. -1. Navigate to **Settings > General** and note your **Project name** - and **Project ID**. -1. Define the Terraform backend in your Terraform project to be: - - ```hcl - terraform { - backend "http" { - } - } - ``` - -1. Create a [Personal Access Token](../profile/personal_access_tokens.md) with - the `api` scope. - -1. On your local machine, run `terraform init`, passing in the following options, - replacing `<YOUR-STATE-NAME>`, `<YOUR-PROJECT-ID>`, `<YOUR-USERNAME>` and - `<YOUR-ACCESS-TOKEN>` with the relevant values. This command initializes your - Terraform state, and stores that state in your GitLab project. The name of - your state can contain only uppercase and lowercase letters, decimal digits, - hyphens, and underscores. This example uses `gitlab.com`: - - ```shell - terraform init \ - -backend-config="address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-STATE-NAME>" \ - -backend-config="lock_address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-STATE-NAME>/lock" \ - -backend-config="unlock_address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-STATE-NAME>/lock" \ - -backend-config="username=<YOUR-USERNAME>" \ - -backend-config="password=<YOUR-ACCESS-TOKEN>" \ - -backend-config="lock_method=POST" \ - -backend-config="unlock_method=DELETE" \ - -backend-config="retry_wait_min=5" - ``` - -If you already have a GitLab-managed Terraform state, you can use the `terraform init` command -with the prepopulated parameters values: - -1. On the top bar, select **Menu > Projects** and find your project. -1. On the left sidebar, select **Infrastructure > Terraform**. -1. Next to the environment you want to use, select the [Actions menu](#managing-state-files) - **{ellipsis_v}** and select **Copy Terraform init command**. - -You can now run `terraform plan` and `terraform apply` as you normally would. - -### Get started using GitLab CI - -If you don't want to start with local development, you can also use GitLab CI to -run your `terraform plan` and `terraform apply` commands. - -Next, [configure the backend](#configure-the-backend). - -#### Configure the backend - -After executing the `terraform init` command, you must configure the Terraform backend -and the CI YAML file: - -1. In your Terraform project, define the [HTTP backend](https://www.terraform.io/docs/language/settings/backends/http.html) - by adding the following code block in a `.tf` file (such as `backend.tf`) to - define the remote backend: - - ```hcl - terraform { - backend "http" { - } - } - ``` - -1. In the root directory of your project repository, configure a - `.gitlab-ci.yml` file. This example uses a pre-built image which includes a - `gitlab-terraform` helper. For supported Terraform versions, see the [GitLab - Terraform Images project](https://gitlab.com/gitlab-org/terraform-images). - - ```yaml - image: registry.gitlab.com/gitlab-org/terraform-images/stable:latest - ``` - -1. In the `.gitlab-ci.yml` file, define some CI/CD variables to ease - development. In this example, `TF_ROOT` is the directory where the Terraform - commands must be executed, `TF_ADDRESS` is the URL to the state on the GitLab - instance where this pipeline runs, and the final path segment in `TF_ADDRESS` - is the name of the Terraform state. Projects may have multiple states, and - this name is arbitrary, so in this example we set it to `example-production` - which corresponds with the directory we're using as our `TF_ROOT`, and we - ensure that the `.terraform` directory is cached between jobs in the pipeline - using a cache key based on the state name (`example-production`): - - ```yaml - variables: - TF_ROOT: ${CI_PROJECT_DIR}/environments/example/production - TF_ADDRESS: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/example-production - - cache: - key: example-production - paths: - - ${TF_ROOT}/.terraform - ``` - -1. In a `before_script`, change to your `TF_ROOT`: - - ```yaml - before_script: - - cd ${TF_ROOT} - - stages: - - prepare - - validate - - build - - deploy - - init: - stage: prepare - script: - - gitlab-terraform init - - validate: - stage: validate - script: - - gitlab-terraform validate - - plan: - stage: build - script: - - gitlab-terraform plan - - gitlab-terraform plan-json - artifacts: - name: plan - paths: - - ${TF_ROOT}/plan.cache - reports: - terraform: ${TF_ROOT}/plan.json - - apply: - stage: deploy - environment: - name: production - script: - - gitlab-terraform apply - dependencies: - - plan - when: manual - only: - - master - ``` - -1. Push your project to GitLab, which triggers a CI job pipeline. This pipeline - runs the `gitlab-terraform init`, `gitlab-terraform validate`, and - `gitlab-terraform plan` commands. - -The output from the above `terraform` commands should be viewable in the job logs. - -WARNING: -Like any other job artifact, Terraform plan data is [viewable by anyone with Guest access](../permissions.md) to the repository. -Neither Terraform nor GitLab encrypts the plan file by default. If your Terraform plan -includes sensitive data such as passwords, access tokens, or certificates, GitLab strongly -recommends encrypting plan output or modifying the project visibility settings. - -### Example project - -See [this reference project](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-aws) using GitLab and Terraform to deploy a basic AWS EC2 in a custom VPC. - -## Using a GitLab managed Terraform state backend as a remote data source - -You can use a GitLab-managed Terraform state as a -[Terraform data source](https://www.terraform.io/docs/language/state/remote-state-data.html). -To use your existing Terraform state backend as a data source, provide the following details -as [Terraform input variables](https://www.terraform.io/docs/language/values/variables.html): - -- **address**: The URL of the remote state backend you want to use as a data source. - For example, `https://gitlab.com/api/v4/projects/<TARGET-PROJECT-ID>/terraform/state/<TARGET-STATE-NAME>`. -- **username**: The username to authenticate with the data source. If you are using a [Personal Access Token](../profile/personal_access_tokens.md) for - authentication, this is your GitLab username. If you are using GitLab CI, this is `'gitlab-ci-token'`. -- **password**: The password to authenticate with the data source. If you are using a Personal Access Token for - authentication, this is the token value. If you are using GitLab CI, it is the contents of the `${CI_JOB_TOKEN}` CI/CD variable. - -An example setup is shown below: - -1. Create a file named `example.auto.tfvars` with the following contents: - - ```plaintext - example_remote_state_address=https://gitlab.com/api/v4/projects/<TARGET-PROJECT-ID>/terraform/state/<TARGET-STATE-NAME> - example_username=<GitLab username> - example_access_token=<GitLab Personal Access Token> - ``` - -1. Define the data source by adding the following code block in a `.tf` file (such as `data.tf`): - - ```hcl - data "terraform_remote_state" "example" { - backend = "http" - - config = { - address = var.example_remote_state_address - username = var.example_username - password = var.example_access_token - } - } - ``` - -Outputs from the data source can now be referenced in your Terraform resources -using `data.terraform_remote_state.example.outputs.<OUTPUT-NAME>`. - -You need at least the [Developer role](../permissions.md) in the target project -to read the Terraform state. - -## Migrating to GitLab Managed Terraform state - -Terraform supports copying the state when the backend is changed or -reconfigured. This can be useful if you need to migrate from another backend to -GitLab managed Terraform state. Using a local terminal is recommended to run the commands needed for migrating to GitLab Managed Terraform state. - -The following example demonstrates how to change the state name, the same workflow is needed to migrate to GitLab Managed Terraform state from a different state storage backend. - -### Setting up the initial backend - -```shell -PROJECT_ID="<gitlab-project-id>" -TF_USERNAME="<gitlab-username>" -TF_PASSWORD="<gitlab-personal-access-token>" -TF_ADDRESS="https://gitlab.com/api/v4/projects/${PROJECT_ID}/terraform/state/old-state-name" - -terraform init \ - -backend-config=address=${TF_ADDRESS} \ - -backend-config=lock_address=${TF_ADDRESS}/lock \ - -backend-config=unlock_address=${TF_ADDRESS}/lock \ - -backend-config=username=${TF_USERNAME} \ - -backend-config=password=${TF_PASSWORD} \ - -backend-config=lock_method=POST \ - -backend-config=unlock_method=DELETE \ - -backend-config=retry_wait_min=5 -``` - -```plaintext -Initializing the backend... - -Successfully configured the backend "http"! Terraform will automatically -use this backend unless the backend configuration changes. - -Initializing provider plugins... - -Terraform has been successfully initialized! - -You may now begin working with Terraform. Try running "terraform plan" to see -any changes that are required for your infrastructure. All Terraform commands -should now work. - -If you ever set or change modules or backend configuration for Terraform, -rerun this command to reinitialize your working directory. If you forget, other -commands will detect it and remind you to do so if necessary. -``` - -### Changing the backend - -Now that `terraform init` has created a `.terraform/` directory that knows where -the old state is, you can tell it about the new location: - -```shell -TF_ADDRESS="https://gitlab.com/api/v4/projects/${PROJECT_ID}/terraform/state/new-state-name" - -terraform init \ - -backend-config=address=${TF_ADDRESS} \ - -backend-config=lock_address=${TF_ADDRESS}/lock \ - -backend-config=unlock_address=${TF_ADDRESS}/lock \ - -backend-config=username=${TF_USERNAME} \ - -backend-config=password=${TF_PASSWORD} \ - -backend-config=lock_method=POST \ - -backend-config=unlock_method=DELETE \ - -backend-config=retry_wait_min=5 -``` - -```plaintext -Initializing the backend... -Backend configuration changed! - -Terraform has detected that the configuration specified for the backend -has changed. Terraform will now check for existing state in the backends. - - -Acquiring state lock. This may take a few moments... -Do you want to copy existing state to the new backend? - Pre-existing state was found while migrating the previous "http" backend to the - newly configured "http" backend. No existing state was found in the newly - configured "http" backend. Do you want to copy this state to the new "http" - backend? Enter "yes" to copy and "no" to start with an empty state. - - Enter a value: yes - - -Successfully configured the backend "http"! Terraform will automatically -use this backend unless the backend configuration changes. - -Initializing provider plugins... - -Terraform has been successfully initialized! - -You may now begin working with Terraform. Try running "terraform plan" to see -any changes that are required for your infrastructure. All Terraform commands -should now work. - -If you ever set or change modules or backend configuration for Terraform, -rerun this command to reinitialize your working directory. If you forget, other -commands will detect it and remind you to do so if necessary. -``` - -If you type `yes`, it copies your state from the old location to the new -location. You can then go back to running it in GitLab CI/CD. - -## Managing state files - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/273592) in GitLab 13.8. - -Users with Developer and greater [permissions](../permissions.md) can view the -state files attached to a project at **Infrastructure > Terraform**. Users with the -Maintainer role can perform commands on the state files. The user interface -contains these fields: - - - -- **Name**: The name of the environment, with a locked (**{lock}**) icon if the - state file is locked. -- **Pipeline**: A link to the most recent pipeline and its status. -- **Details**: Information about when the state file was created or changed. -- **Actions**: Actions you can take on the state file, including copying the `terraform init` command, - downloading, locking, unlocking, or [removing](#remove-a-state-file) the state file and versions. - -NOTE: -Additional improvements to the -[graphical interface for managing state files](https://gitlab.com/groups/gitlab-org/-/epics/4563) -are planned. - -## Remove a state file - -Users with Maintainer and greater [permissions](../permissions.md) can use the -following options to remove a state file: - -- **GitLab UI**: Go to **Infrastructure > Terraform**. In the **Actions** column, - click the vertical ellipsis (**{ellipsis_v}**) button and select - **Remove state file and versions**. -- **GitLab REST API**: You can remove a state file by making a request to the - REST API. For example: - - ```shell - curl --header "Private-Token: <your_access_token>" --request DELETE "https://gitlab.example.com/api/v4/projects/<your_project_id>/terraform/state/<your_state_name>" - ``` - -- [GitLab GraphQL API](#remove-a-state-file-with-the-gitlab-graphql-api). - -### Remove a state file with the GitLab GraphQL API - -You can remove a state file by making a GraphQL API request. For example: - -```shell -mutation deleteState { - terraformStateDelete(input: { id: "<global_id_for_the_state>" }) { - errors - } -} -``` - -You can obtain the `<global_id_for_the_state>` by querying the list of states: - -```shell -query ProjectTerraformStates { - project(fullPath: "<your_project_path>") { - terraformStates { - nodes { - id - name - } - } - } -} -``` - -For those new to the GitLab GraphQL API, read -[Getting started with GitLab GraphQL API](../../api/graphql/getting_started.md). +<!-- This redirect file can be deleted after <2021-11-26>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/instance/clusters/index.md b/doc/user/instance/clusters/index.md index 5f51286cf7f..20cd30b6110 100644 --- a/doc/user/instance/clusters/index.md +++ b/doc/user/instance/clusters/index.md @@ -16,8 +16,8 @@ projects. To view the instance level Kubernetes clusters: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Kubernetes**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Kubernetes**. ## Cluster precedence diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index d3e913edfda..dc08baaf731 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -297,9 +297,6 @@ dependency. You can install a package from the scope of your instance or your pr If multiple packages have the same recipe, when you install a package, the most recently-published package is retrieved. -WARNING: -Project-level packages [cannot be downloaded currently](https://gitlab.com/gitlab-org/gitlab/-/issues/270129). - Conan packages are often installed as dependencies by using the `conanfile.txt` file. diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index 18b86c4a357..1db2165cd5d 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -154,7 +154,7 @@ To use CI/CD to authenticate, you can use: docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY ``` -- A [CI job token](../../../ci/triggers/index.md#ci-job-token). +- A [CI job token](../../../ci/jobs/ci_job_token.md). ```shell docker login -u $CI_JOB_USER -p $CI_JOB_TOKEN $CI_REGISTRY @@ -747,6 +747,8 @@ The **Packages & Registries > Container Registry** entry is removed from the pro ## Change visibility of the Container Registry +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18792) in GitLab 14.2. + By default, the Container Registry is visible to everyone with access to the project. You can, however, change the visibility of the Container Registry for a project. @@ -863,6 +865,18 @@ these steps: 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 ``` + If you have Rails console access, you can enter the following commands to retrieve a list of tags limited by date: + + ```shell + output = File.open( "/tmp/list_o_tags.out","w" ) + Project.find(<Project_id>).container_repositories.find(<container_repo_id>).tags.each do |tag| + output << tag.name + "\n" if tag.created_at < 1.month.ago + end;nil + output.close + ``` + + This set of commands creates a `/tmp/list_o_tags.out` file listing all tags with a `created_at` date of older than one month. + 1. Remove from the `list_o_tags.out` file any tags that you want to keep. Here are some example `sed` commands for this. Note that these commands are simply examples. You may change them to best suit your needs: diff --git a/doc/user/packages/debian_repository/index.md b/doc/user/packages/debian_repository/index.md index 789902c03e3..29641380753 100644 --- a/doc/user/packages/debian_repository/index.md +++ b/doc/user/packages/debian_repository/index.md @@ -67,7 +67,7 @@ To create a distribution, publish a package, or install a private package, you n following: - [Personal access token](../../../api/index.md#personalproject-access-tokens) -- [CI/CD job token](../../../api/index.md#gitlab-cicd-job-token) +- [CI/CD job token](../../../ci/jobs/ci_job_token.md) - [Deploy token](../../project/deploy_tokens/index.md) ## Create a Distribution @@ -78,7 +78,7 @@ packages on the group level, create a distribution with the same `codename`. To create a project-level distribution: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<project_id>/debian_distributions?codename=unstable +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<project_id>/debian_distributions?codename=unstable" ``` Example response: diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index c76b0a6810f..ad25ec7edbf 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -94,8 +94,11 @@ Proxy. > - The prefix for group names containing uppercase letters was [fixed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/54559) in GitLab 13.10. Runners log in to the Dependency Proxy automatically. To pull through -the Dependency Proxy, use the `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` -[predefined CI/CD variable](../../../ci/variables/predefined_variables.md): +the Dependency Proxy, use one of the [predefined variables](../../../ci/variables/predefined_variables.md): + +- `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` pulls through the top-level group. +- `CI_DEPENDENCY_PROXY_DIRECT_GROUP_IMAGE_PREFIX` pulls through the subgroup, or direct group the + project exists in. Example pulling the latest alpine image: @@ -109,7 +112,10 @@ There are other additional predefined CI/CD variables you can also use: - `CI_DEPENDENCY_PROXY_USER`: A CI/CD user for logging in to the Dependency Proxy. - `CI_DEPENDENCY_PROXY_PASSWORD`: A CI/CD password for logging in to the Dependency Proxy. - `CI_DEPENDENCY_PROXY_SERVER`: The server for logging in to the Dependency Proxy. -- `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX`: The image prefix for pulling images through the Dependency Proxy. +- `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX`: the image prefix for pulling images through the + dependency proxy from the top-level group. +- `CI_DEPENDENCY_PROXY_DIRECT_GROUP_IMAGE_PREFIX`: the image prefix for pulling images through the + dependency proxy from the direct group or subgroup that the project belongs to. `CI_DEPENDENCY_PROXY_SERVER` and `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` include the server port. If you explicitly include the Dependency Proxy diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index aa6373b66cb..6d35273ae6f 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/index.md @@ -21,13 +21,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#personalproject-access-tokens), -[CI/CD job token](../../../api/index.md#gitlab-cicd-job-token), or [deploy token](../../project/deploy_tokens/index.md). +[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#personalproject-access-tokens), -a [CI/CD job token](../../../api/index.md#gitlab-cicd-job-token), or a [deploy token](../../project/deploy_tokens/index.md). +a [CI/CD job token](../../../ci/jobs/ci_job_token.md), or a [deploy token](../../project/deploy_tokens/index.md). ## Publish a package file @@ -125,7 +125,7 @@ Example request that uses HTTP Basic authentication: ```shell curl --user "user:<your_access_token>" \ - https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt + "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt" ``` ## Publish a generic package by using CI/CD diff --git a/doc/user/packages/helm_repository/index.md b/doc/user/packages/helm_repository/index.md index f98fc352ab5..2d984d76b97 100644 --- a/doc/user/packages/helm_repository/index.md +++ b/doc/user/packages/helm_repository/index.md @@ -25,9 +25,9 @@ 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#personalproject-access-tokens). -- A [deploy token](../../project/deploy_tokens/index.md). -- A [CI/CD job token](../../../api/index.md#gitlab-cicd-job-token). +- A [personal access token](../../../api/index.md#personalproject-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). ## Publish a package @@ -35,24 +35,35 @@ NOTE: You can publish Helm charts with duplicate names or versions. If duplicates exist, GitLab always returns the chart with the latest version. -Once built, a chart can be uploaded to the `stable` channel with `curl` or `helm-push`: +Once built, a chart can be uploaded to the desired channel with `curl` or `helm-push`: - With `curl`: ```shell curl --request POST \ --form 'chart=@mychart-0.1.0.tgz' \ - --user <username>:<personal_access_token> \ - https://gitlab.example.com/api/v4/projects/1/packages/helm/api/stable/charts + --user <username>:<access_token> \ + https://gitlab.example.com/api/v4/projects/<project_id>/packages/helm/api/<channel>/charts ``` + - `<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`). + - `<channel>`: the name of the channel (like `stable`). + - With the [`helm-push`](https://github.com/chartmuseum/helm-push/#readme) plugin: ```shell - helm repo add --username <username> --password <personal_access_token> project-1 https://gitlab.example.com/api/v4/projects/1/packages/helm/stable + helm repo add --username <username> --password <access_token> project-1 https://gitlab.example.com/api/v4/projects/<project_id>/packages/helm/<channel> helm push mychart-0.1.0.tgz project-1 ``` + - `<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`). + - `<channel>`: the name of the channel (like `stable`). + ## Use CI/CD to publish a Helm package To publish a Helm package automated through [GitLab CI/CD](../../../ci/index.md), you can use @@ -69,18 +80,31 @@ stages: upload: stage: upload script: - - 'curl --request POST --user gitlab-ci-token:$CI_JOB_TOKEN --form "chart=@mychart-0.1.0.tgz" "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/helm/api/stable/charts"' + - 'curl --request POST --user gitlab-ci-token:$CI_JOB_TOKEN --form "chart=@mychart-0.1.0.tgz" "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/helm/api/<channel>/charts"' ``` +- `<username>`: the GitLab username or the deploy token username. +- `<access_token>`: the personal access token or the deploy token. +- `<channel>`: the name of the channel (like `stable`). + ## Install a package +NOTE: +When requesting a package, GitLab considers only the 300 most recent packages created. +For each package, only the most recent package file is returned. + To install the latest version of a chart, use the following command: ```shell -helm repo add --username <username> --password <personal_access_token> project-1 https://gitlab.example.com/api/v4/projects/1/packages/helm/stable +helm repo add --username <username> --password <access_token> project-1 https://gitlab.example.com/api/v4/projects/<project_id>/packages/helm/<channel> helm install my-release project-1/mychart ``` +- `<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`). +- `<channel>`: the name of the channel (like `stable`). + If the repo has previously been added, you may need to run: ```shell diff --git a/doc/user/packages/terraform_module_registry/index.md b/doc/user/packages/terraform_module_registry/index.md index e3b9563a143..7f101adccad 100644 --- a/doc/user/packages/terraform_module_registry/index.md +++ b/doc/user/packages/terraform_module_registry/index.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Terraform module registry **(FREE)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3221) in GitLab 14.0. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3221) in GitLab 14.0. Publish Terraform modules in your project's Infrastructure Registry, then reference them using GitLab as a Terraform module registry. @@ -16,7 +16,7 @@ as a Terraform module registry. To authenticate to the Terraform module registry, you need either: - A [personal access token](../../../api/index.md#personalproject-access-tokens) with at least `read_api` rights. -- A [CI/CD job token](../../../api/index.md#gitlab-cicd-job-token). +- A [CI/CD job token](../../../ci/jobs/ci_job_token.md). ## Publish a Terraform Module @@ -41,6 +41,10 @@ PUT /projects/:id/packages/terraform/modules/:module_name/:module_system/:module Provide the file content in the request body. +Note that, in the following example, the request must end with `/file`. +If you send a request ending with something else, it results in a 404 +error `{"error":"404 Not Found"}`. + Example request using a personal access token: ```shell diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 81681ec1303..f240a9fd407 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -41,23 +41,23 @@ For more information, see [projects members documentation](project/members/index The following table lists project permissions available for each role: -<!-- Keep this table sorted: first, by minimum role, then alphabetically. --> +<!-- Keep this table sorted: By topic first, then by minimum role, then alphabetically. --> | Action | Guest | Reporter | Developer | Maintainer | Owner | |-------------------------------------------------------------------------------------------------------------------------|----------|----------|-----------|------------|-------| | [Analytics](analytics/index.md):<br>View issue analytics **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Analytics](analytics/index.md):<br>View [merge request analytics](analytics/merge_request_analytics.md) **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View [merge request analytics](analytics/merge_request_analytics.md) **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | | [Analytics](analytics/index.md):<br>View value stream analytics | ✓ | ✓ | ✓ | ✓ | ✓ | | [Analytics](analytics/index.md):<br>View [DORA metrics](analytics/ci_cd_analytics.md) | | ✓ | ✓ | ✓ | ✓ | | [Analytics](analytics/index.md):<br>View [CI/CD analytics](analytics/ci_cd_analytics.md) | | ✓ | ✓ | ✓ | ✓ | -| [Analytics](analytics/index.md):<br>View [code review analytics](analytics/code_review_analytics.md) **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | -| [Analytics](analytics/index.md):<br>View [repository analytics](analytics/repository_analytics.md) | | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View [code review analytics](analytics/code_review_analytics.md) **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View [repository analytics](analytics/repository_analytics.md) | | ✓ | ✓ | ✓ | ✓ | | [Application security](application_security/index.md):<br>View licenses in [dependency list](application_security/dependency_list/index.md) **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | | [Application security](application_security/index.md):<br>Create and run [on-demand DAST scans](application_security/dast/index.md#on-demand-scans) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | | [Application security](application_security/index.md):<br>Manage [security policy](application_security/policies/index.md) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | | [Application security](application_security/index.md):<br>View [dependency list](application_security/dependency_list/index.md) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | | [Application security](application_security/index.md):<br>View [threats list](application_security/threat_monitoring/index.md#threat-monitoring) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Application security](application_security/index.md):<br>Create a [CVE ID Request](application_security/cve_id_request.md) **(FREE SAAS)** | | | | ✓ | ✓ | +| [Application security](application_security/index.md):<br>Create a [CVE ID Request](application_security/cve_id_request.md) **(FREE SAAS)** | | | | ✓ | ✓ | | [Application security](application_security/index.md):<br>Create or assign [security policy project](application_security/policies/index.md) **(ULTIMATE)** | | | | | ✓ | | [CI/CD](../ci/README.md):<br>Download and browse job artifacts | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | | [CI/CD](../ci/README.md):<br>View a job log | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | @@ -74,13 +74,22 @@ The following table lists project permissions available for each role: | [CI/CD](../ci/README.md):<br>Run Web IDE's Interactive Web Terminals **(ULTIMATE ONLY)** | | | | ✓ | ✓ | | [CI/CD](../ci/README.md):<br>Use [environment terminals](../ci/environments/index.md#web-terminals) | | | | ✓ | ✓ | | [CI/CD](../ci/README.md):<br>Delete pipelines | | | | | ✓ | +| [Clusters](project/clusters/index.md):<br>View pod logs | | | ✓ | ✓ | ✓ | +| [Clusters](project/clusters/index.md):<br>Manage clusters | | | | ✓ | ✓ | +| [Container Registry](packages/container_registry/index.md):<br>Create, edit, delete cleanup policies | | | ✓ | ✓ | ✓ | +| [Container Registry](packages/container_registry/index.md):<br>Remove a container registry image | | | ✓ | ✓ | ✓ | +| [Container Registry](packages/container_registry/index.md):<br>Update container registry | | | ✓ | ✓ | ✓ | +| [GitLab Pages](project/pages/index.md):<br>View Pages protected by [access control](project/pages/introduction.md#gitlab-pages-access-control) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [GitLab Pages](project/pages/index.md):<br>Manage | | | | ✓ | ✓ | +| [GitLab Pages](project/pages/index.md):<br>Manage GitLab Pages domains and certificates | | | | ✓ | ✓ | +| [GitLab Pages](project/pages/index.md):<br>Remove GitLab Pages | | | | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Add Labels | ✓ (*16*) | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Assign | ✓ (*16*) | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Create | ✓ | ✓ | ✓ | ✓ | ✓ | | [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 | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Set weight | ✓ (*16*) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Set weight | ✓ (*16*) | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>View [confidential issues](project/issues/confidential_issues.md) | (*2*) | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Lock threads | | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Manage related issues | | ✓ | ✓ | ✓ | ✓ | @@ -89,6 +98,10 @@ The following table lists project permissions available for each role: | [Issues](project/issues/index.md):<br>Set issue [time tracking](project/time_tracking.md) estimate and time spent | | ✓ | ✓ | ✓ | ✓ | | [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 **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [License Compliance](compliance/license_compliance/index.md):<br>View License Compliance reports **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [License Compliance](compliance/license_compliance/index.md):<br>View License list **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | +| [License Compliance](compliance/license_compliance/index.md):<br>Manage license policy **(ULTIMATE)** | | | | ✓ | ✓ | | [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 | | | ✓ | ✓ | ✓ | @@ -97,26 +110,38 @@ The following table lists project permissions available for each role: | [Merge requests](project/merge_requests/index.md):<br>Create | | | ✓ | ✓ | ✓ | | [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>Manage or accept | | | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Manage merge approval rules (project settings) | | | | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Delete | | | | | ✓ | +| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>Manage user-starred metrics dashboards (*7*) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [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 package | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Package registry](packages/index.md):<br>Publish package | | | ✓ | ✓ | ✓ | +| [Package registry](packages/index.md):<br>Delete 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) **(PREMIUM)** | | | ✓ | ✓ | ✓ | +| [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>Leave comments | ✓ | ✓ | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>Reposition comments on images (posted by any user) | ✓ (*10*) | ✓ (*10*) | ✓ (*10*) | ✓ | ✓ | | [Projects](project/index.md):<br>View Insights **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View [releases](project/releases/index.md) | ✓ (*6*) | ✓ | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>View Requirements **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | | [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 statistics | | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View project statistics | | ✓ | ✓ | ✓ | ✓ | | [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) | | | ✓ (*13*) | ✓ (*13*) | ✓ (*13*) | | [Projects](project/index.md):<br>Create, edit [wiki](project/wiki/index.md) pages | | | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>Enable Review Apps | | | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>View project [Audit Events](../administration/audit_events.md) | | | ✓ (*11*) | ✓ | ✓ | | [Projects](project/index.md):<br>Add deploy keys | | | | ✓ | ✓ | | [Projects](project/index.md):<br>Add new team members | | | | ✓ | ✓ | | [Projects](project/index.md):<br>Change [project features visibility](../public_access/public_access.md) level | | | | ✓ (14) | ✓ | +| [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 | | | | ✓ | ✓ | @@ -133,6 +158,27 @@ The following table lists project permissions available for each role: | [Projects](project/index.md):<br>Disable notification emails | | | | | ✓ | | [Projects](project/index.md):<br>Rename project | | | | | ✓ | | [Projects](project/index.md):<br>Transfer project to another namespace | | | | | ✓ | +| [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>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 | | | ✓ (*5*) | ✓ | ✓ | +| [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 | | | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Rewrite or remove Git tags | | | ✓ | ✓ | ✓ | +| [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](../push_rules/push_rules.md) | | | | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Push to protected branches | | | | ✓ | ✓ | +| [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 (*4*) | | | | | | +| [Repository](project/repository/index.md):<br>Remove protected branches (*4*) | | | | | | +| [Requirements Management](project/requirements/index.md):<br>Archive / reopen **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | +| [Requirements Management](project/requirements/index.md):<br>Create / edit **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | +| [Requirements Management](project/requirements/index.md):<br>Import / export **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | | [Security dashboard](application_security/security_dashboard/index.md):<br>View Security reports **(ULTIMATE)** | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | | [Security dashboard](application_security/security_dashboard/index.md):<br>Create issue from vulnerability finding **(ULTIMATE)** | | | ✓ | ✓ | ✓ | | [Security dashboard](application_security/security_dashboard/index.md):<br>Create vulnerability from vulnerability finding **(ULTIMATE)** | | | ✓ | ✓ | ✓ | @@ -143,60 +189,17 @@ The following table lists project permissions available for each role: | [Security dashboard](application_security/security_dashboard/index.md):<br>Use security dashboard **(ULTIMATE)** | | | ✓ | ✓ | ✓ | | [Security dashboard](application_security/security_dashboard/index.md):<br>View vulnerability **(ULTIMATE)** | | | ✓ | ✓ | ✓ | | [Security dashboard](application_security/security_dashboard/index.md):<br>View vulnerability findings in [dependency list](application_security/dependency_list/index.md) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| Manage user-starred metrics dashboards (*7*) | ✓ | ✓ | ✓ | ✓ | ✓ | -| Pull project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| View [Releases](project/releases/index.md) | ✓ (*6*) | ✓ | ✓ | ✓ | ✓ | -| View allowed and denied licenses **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| View GitLab Pages protected by [access control](project/pages/introduction.md#gitlab-pages-access-control) | ✓ | ✓ | ✓ | ✓ | ✓ | -| View License Compliance reports **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| View project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| Archive [test case](../ci/test_cases/index.md) | | ✓ | ✓ | ✓ | ✓ | -| Archive/reopen requirements **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | -| Create new [test case](../ci/test_cases/index.md) | | ✓ | ✓ | ✓ | ✓ | -| Create/edit requirements **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | -| Import/export requirements **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | -| Move [test case](../ci/test_cases/index.md) | | ✓ | ✓ | ✓ | ✓ | -| Pull [packages](packages/index.md) | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| Reopen [test case](../ci/test_cases/index.md) | | ✓ | ✓ | ✓ | ✓ | -| See a commit status | | ✓ | ✓ | ✓ | ✓ | -| View Error Tracking list | | ✓ | ✓ | ✓ | ✓ | -| View License list **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | -| View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | -| Add tags | | | ✓ | ✓ | ✓ | -| Create new branches | | | ✓ | ✓ | ✓ | -| Create or update commit status | | | ✓ (*5*) | ✓ | ✓ | -| Create/edit/delete [releases](project/releases/index.md)| | | ✓ (*13*) | ✓ (*13*) | ✓ (*13*) | -| Create/edit/delete a Cleanup policy | | | ✓ | ✓ | ✓ | -| Create/edit/delete metrics dashboard annotations | | | ✓ | ✓ | ✓ | -| Force push to non-protected branches | | | ✓ | ✓ | ✓ | -| Manage Feature Flags **(PREMIUM)** | | | ✓ | ✓ | ✓ | -| Publish [packages](packages/index.md) | | | ✓ | ✓ | ✓ | -| Push to non-protected branches | | | ✓ | ✓ | ✓ | -| Read Terraform state | | | ✓ | ✓ | ✓ | -| Remove a container registry image | | | ✓ | ✓ | ✓ | -| Remove non-protected branches | | | ✓ | ✓ | ✓ | -| Rewrite/remove Git tags | | | ✓ | ✓ | ✓ | -| Update a container registry | | | ✓ | ✓ | ✓ | -| View Pods logs | | | ✓ | ✓ | ✓ | -| Configure project hooks | | | | ✓ | ✓ | -| Delete [packages](packages/index.md) | | | | ✓ | ✓ | -| Enable/disable branch protection | | | | ✓ | ✓ | -| Enable/disable tag protections | | | | ✓ | ✓ | -| Manage [push rules](../push_rules/push_rules.md) | | | | ✓ | ✓ | -| Manage clusters | | | | ✓ | ✓ | -| Manage Error Tracking | | | | ✓ | ✓ | -| Manage GitLab Pages | | | | ✓ | ✓ | -| Manage GitLab Pages domains and certificates | | | | ✓ | ✓ | -| Manage license policy **(ULTIMATE)** | | | | ✓ | ✓ | -| Manage Terraform state | | | | ✓ | ✓ | -| Push to protected branches | | | | ✓ | ✓ | -| Remove GitLab Pages | | | | ✓ | ✓ | -| Turn on/off protected branch push for developers | | | | ✓ | ✓ | -| Remove fork relationship | | | | | ✓ | -| Force push to protected branches (*4*) | | | | | | -| Remove protected branches (*4*) | | | | | | - -1. Guest users are able to perform this action on public and internal projects, but not private projects. This doesn't apply to [external users](#external-users) where explicit access must be given even if the project is internal. +| [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 | | ✓ | ✓ | ✓ | ✓ | +| [Test cases](../ci/test_cases/index.md):<br>Create | | ✓ | ✓ | ✓ | ✓ | +| [Test cases](../ci/test_cases/index.md):<br>Move | | ✓ | ✓ | ✓ | ✓ | +| [Test cases](../ci/test_cases/index.md):<br>Reopen | | ✓ | ✓ | ✓ | ✓ | + +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](#external-users) + must be given explicit access even if the project is internal. For GitLab.com, see the + [GitLab.com visibility settings](gitlab_com/index.md#visibility-settings). 1. Guest users can only view the [confidential issues](project/issues/confidential_issues.md) they created themselves. 1. If **Public pipelines** is enabled in **Project Settings > CI/CD**. 1. Not allowed for Guest, Reporter, Developer, Maintainer, or Owner. See [protected branches](project/protected_branches.md). @@ -242,10 +245,10 @@ to learn more. Find the current permissions on the Value Stream Analytics dashboard, as described in [related documentation](analytics/value_stream_analytics.md#permissions). -### Issue Board permissions +### Issue board permissions -Find the current permissions for interacting with the Issue Board feature in the -[Issue Boards permissions page](project/issue_board.md#permissions). +Find the current permissions for interacting with the issue board feature in the +[issue boards permissions page](project/issue_board.md#permissions). ### File Locking permissions **(PREMIUM)** @@ -280,6 +283,7 @@ The following table lists group permissions available for each role: |--------------------------------------------------------|-------|----------|-----------|------------|-------| | Browse group | ✓ | ✓ | ✓ | ✓ | ✓ | | Edit SAML SSO Billing **(PREMIUM SAAS)** | ✓ | ✓ | ✓ | ✓ | ✓ (4) | +| Pull a container image using the dependency proxy | ✓ | ✓ | ✓ | ✓ | ✓ | | View Contribution analytics | ✓ | ✓ | ✓ | ✓ | ✓ | | View group epic **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | | View group wiki pages **(PREMIUM)** | ✓ (6) | ✓ | ✓ | ✓ | ✓ | @@ -301,7 +305,6 @@ The following table lists group permissions available for each role: | Create/edit/delete iterations | | | ✓ | ✓ | ✓ | | Create/edit/delete metrics dashboard annotations | | | ✓ | ✓ | ✓ | | Enable/disable a dependency proxy | | | ✓ | ✓ | ✓ | -| Pull a container image using the dependency proxy | ✓ | ✓ | ✓ | ✓ | ✓ | | Purge the dependency proxy for a group | | | | | ✓ | | Publish [packages](packages/index.md) | | | ✓ | ✓ | ✓ | | Use security dashboard **(ULTIMATE)** | | | ✓ | ✓ | ✓ | @@ -314,6 +317,7 @@ The following table lists group permissions available for each role: | View/manage group-level Kubernetes cluster | | | | ✓ | ✓ | | Administer project compliance frameworks | | | | | ✓ | | Create/Delete group deploy tokens | | | | | ✓ | +| Change group visibility level | | | | | ✓ | | Delete group | | | | | ✓ | | Delete group epic **(PREMIUM)** | | | | | ✓ | | Disable notification emails | | | | | ✓ | @@ -381,7 +385,7 @@ An administrator can flag a user as external by either of the following methods: - [Through the API](../api/users.md#user-modification). - Using the GitLab UI: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users** to create a new user or edit an existing one. There, you can find the option to flag the user as external. @@ -393,7 +397,7 @@ and [LDAP groups](../administration/auth/ldap/index.md#external-groups). By default, new users are not set as external users. This behavior can be changed by an administrator: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Account and limit** section. diff --git a/doc/user/profile/account/create_accounts.md b/doc/user/profile/account/create_accounts.md index 972414dbf0b..3cc56cc47e6 100644 --- a/doc/user/profile/account/create_accounts.md +++ b/doc/user/profile/account/create_accounts.md @@ -26,7 +26,7 @@ their own accounts by either: As an Admin user, you can manually create users: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users** (`/admin/users`). 1. Select **New user**. diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index f6af373e295..41b4e508c38 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -21,14 +21,14 @@ As a user, to delete your own account: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Account**. +1. On the left sidebar, select **Account**. 1. Select **Delete account**. ## As an administrator As an administrator, to delete a user account: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Select a user. 1. Under the **Account** tab, select: diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index 597170540ab..14e6f4dad3a 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -35,8 +35,19 @@ still access your account if you lose your U2F / WebAuthn device. ## Enabling 2FA -There are multiple ways to enable two-factor authentication: by using a one-time -password authenticator or a U2F / WebAuthn device. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35102) in GitLab 14.3, account email confirmation required. + +There are multiple ways to enable two-factor authentication (2FA): + +- Using a one-time password authenticator. +- Using a U2F / WebAuthn device. + +In GitLab 14.3 and later, your account email must be confirmed to enable two-factor authentication. + +FLAG: +On self-managed GitLab, account email confirmation requirement is enabled. To disable this +restriction, ask an administrator to +[disable the `ensure_verified_primary_email_for_2fa` flag](../../../administration/feature_flags.md). ### One-time password @@ -377,7 +388,7 @@ have lost your code generation device) you can: - [Use a saved recovery code](#use-a-saved-recovery-code). - [Generate new recovery codes using SSH](#generate-new-recovery-codes-using-ssh). - [Regenerate 2FA recovery codes](#regenerate-2fa-recovery-codes). -- [Ask a GitLab administrator to disable two-factor authentication on your account](#ask-a-gitlab-administrator-to-disable-two-factor-authentication-on-your-account). +- [Have 2FA disabled on your account](#have-2fa-disabled-on-your-account). ### Use a saved recovery code @@ -454,12 +465,9 @@ To regenerate 2FA recovery codes, you need access to a desktop browser: NOTE: If you regenerate 2FA recovery codes, save them. You can't use any previously created 2FA codes. -### Ask a GitLab administrator to disable two-factor authentication on your account +### Have 2FA disabled on your account -If you cannot use a saved recovery code or generate new recovery codes, ask a -GitLab global administrator to disable two-factor authentication for your -account. This temporarily leaves your account in a less secure state. -Sign in and re-enable two-factor authentication as soon as possible. +If you cannot use a saved recovery code or generate new recovery codes then please submit a [support ticket](https://support.gitlab.com/hc/en-us/requests/new) requesting that a GitLab global administrator disables two-factor authentication for your account. Please note that only the actual owner of the account can make this request and that disabling this setting will temporarily leave your account in a less secure state. You should therefore sign in and re-enable two-factor authentication as soon as possible. ## Note to GitLab administrators @@ -516,7 +524,7 @@ To avoid the time sync issue, enable time synchronization in the device that gen 1. Go to Settings. 1. Select General. 1. Select Date & Time. - 1. Enable Set Automatically. If it’s already enabled, disable it, wait a few seconds, and re-enable. + 1. Enable Set Automatically. If it's already enabled, disable it, wait a few seconds, and re-enable. <!-- ## Troubleshooting diff --git a/doc/user/profile/active_sessions.md b/doc/user/profile/active_sessions.md index e55b92378bd..25f349d9272 100644 --- a/doc/user/profile/active_sessions.md +++ b/doc/user/profile/active_sessions.md @@ -18,7 +18,7 @@ To list all active sessions: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Active Sessions**. +1. On the left sidebar, select **Active Sessions**.  @@ -35,7 +35,7 @@ To revoke an active session: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Active Sessions**. +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. NOTE: diff --git a/doc/user/profile/img/notification_group_settings_v12_8.png b/doc/user/profile/img/notification_group_settings_v12_8.png Binary files differdeleted file mode 100644 index 4aa4c32a260..00000000000 --- a/doc/user/profile/img/notification_group_settings_v12_8.png +++ /dev/null diff --git a/doc/user/profile/img/notification_project_settings_v12_8.png b/doc/user/profile/img/notification_project_settings_v12_8.png Binary files differdeleted file mode 100644 index 9b8837a4ef4..00000000000 --- a/doc/user/profile/img/notification_project_settings_v12_8.png +++ /dev/null diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index 2c76b46249e..24006e6f875 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -31,7 +31,7 @@ To change your password: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Password**. +1. On the left sidebar, select **Password**. 1. In the **Current password** field, enter your current password. 1. In the **New password** and **Password confirmation** field, enter your new password. 1. Select **Save password**. @@ -55,10 +55,21 @@ To change your username: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Account**. +1. On the left sidebar, select **Account**. 1. In the **Change username** section, enter a new username as the path. 1. Select **Update username**. +## Add emails to your user profile + +To add new email to your account: + +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. On the left sidebar, select **Emails**. +1. In the **Email** box, enter the new email. +1. Select **Add email address**. +1. Verify your email address with the verification email received. + ## Make your user profile page private You can make your user profile visible to only you and GitLab administrators. @@ -219,6 +230,7 @@ To set your time zone: A commit email is an email address displayed in every Git-related action carried out through the GitLab interface. Any of your own verified email addresses can be used as the commit email. +Your primary email is used by default. To change your commit email: diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index 17b4251662e..aaa311a4097 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -5,57 +5,72 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab Notification Emails **(FREE)** +# Notification emails **(FREE)** -GitLab Notifications allow you to stay informed about what's happening in GitLab. With notifications -enabled, you can receive updates about activity in issues, merge requests, epics, and designs. -Notifications are sent via email. +Stay informed about what's happening in GitLab with email notifications. +You can receive updates about activity in issues, merge requests, epics, and designs. -For the tool that enables GitLab administrators to send messages to users, read +For the tool that GitLab administrators can use to send messages to users, read [Email from GitLab](../../tools/email.md). -## Receiving notifications +## Receive notifications You receive notifications for one of the following reasons: -- You participate in an issue, merge request, epic, or design. In this context, _participate_ means comment, or edit. -- You [enable notifications in an issue, merge request, or epic](#notifications-on-issues-merge-requests-and-epics). +- You participate in an issue, merge request, epic, or design. In this context, _participate_ means + comment or edit. +- You've [enabled notifications in an issue, merge request, or epic](#notifications-on-issues-merge-requests-and-epics). - You configured notifications at the [project](#project-notifications) and/or [group](#group-notifications) level. While notifications are enabled, you receive notification of actions occurring in that issue, merge request, or epic. NOTE: -Notifications can be blocked by an administrator, preventing them from being sent. +Administrators can block notifications, preventing them from being sent. -## Tuning your notifications +## Tune your notifications -The number of notifications can be overwhelming. GitLab allows you to tune the notifications you receive. +Getting many notifications can be overwhelming. You can tune the notifications you receive. For example, you might want to be notified about all activity in a specific project. -For other projects, you only need to be notified when you are mentioned by name. +For other projects, you only want to be notified when you are mentioned by name. -You can tune the notifications you receive by combining your notification settings: +You can tune the notifications you receive by changing your notification settings: - [Global notification settings](#global-notification-settings) - [Notification scope](#notification-scope) - [Notification levels](#notification-levels) -## Editing notification settings +## Edit notification settings + +These notification settings apply only to you. They do not affect the notifications received by +anyone else in the same project or group. To edit your notification settings: 1. In the top-right corner, select your avatar. 1. Select **Preferences**. -1. In the left sidebar, select **Notifications**. +1. On the left sidebar, select **Notifications**. 1. Edit the desired notification settings. Edited settings are automatically saved and enabled. -These notification settings apply only to you. They do not affect the notifications received by anyone else in the same project or group. +## Notification scope + +You can tune the scope of your notifications by selecting different notification levels for each project and group. -## Global notification settings +Notification scope is applied from the broadest to most specific levels: + +- **Global (default)**: Your global, or _default_, notification level applies if you + have not selected a notification level for the project or group in which the activity occurred. +- **Group**: For each group, you can select a notification level. Your group setting + overrides your default setting. +- **Project**: For each project, you can select a notification level. Your project + setting overrides the group setting. + +### Global notification settings Your **Global notification settings** are the default settings unless you select different values for a project or a group. - **Notification email**: the email address your notifications are sent to. + Defaults to your primary email address. - **Receive product marketing emails**: select this checkbox to receive [periodic emails](#product-marketing-emails) about GitLab features. - **Global notification level**: the default [notification level](#notification-levels) @@ -65,95 +80,78 @@ different values for a project or a group.  -### Notification scope - -You can tune the scope of your notifications by selecting different notification levels for each project and group. +### Group notifications -Notification scope is applied in order of precedence (highest to lowest): - -- **Project**: For each project, you can select a notification level. Your project - setting overrides the group setting. -- **Group**: For each group, you can select a notification level. Your group setting - overrides your default setting. -- **Global (default)**: Your global, or _default_, notification level applies if you - have not selected a notification level for the project or group in which the activity occurred. - -#### Project notifications - -You can select a notification level for each project to help you closely monitor activity in select projects. +You can select a notification level and email address for each group. - +#### Group notification level -To select a notification level for a project, use either of these methods: +To select a notification level for a group, use either of these methods: 1. In the top-right corner, select your avatar. 1. Select **Preferences**. -1. In the left sidebar, select **Notifications**. -1. Locate the project in the **Projects** section. +1. On the left sidebar, select **Notifications**. +1. Locate the project in the **Groups** section. 1. Select the desired [notification level](#notification-levels). Or: -1. Go to your project. -1. Select the notification dropdown, marked with a bell icon (**{notifications}**). +1. On the top bar, select **Menu > Groups** and find your group. +1. Select the notification dropdown, next to the bell icon (**{notifications}**). 1. Select the desired [notification level](#notification-levels). -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For a demonstration of how to be notified when a new release is available, see [Notification for releases](https://www.youtube.com/watch?v=qyeNkGgqmH4). +#### Group notification email address -#### Group notifications +> Introduced in GitLab 12.0 -You can select a notification level and email address for each group. +You can select an email address to receive notifications for each group you belong to. This could be useful, 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. Select **Preferences**. +1. On the left sidebar, select **Notifications**. +1. Locate the project in the **Groups** section. +1. Select the desired email address. -##### Group notification level +### Project notifications -To select a notification level for a group, use either of these methods: +You can select a notification level for each project to help you closely monitor activity in select projects. + +To select a notification level for a project, use either of these methods: 1. In the top-right corner, select your avatar. 1. Select **Preferences**. -1. In the left sidebar, select **Notifications**. -1. Locate the project in the **Groups** section. +1. On the left sidebar, select **Notifications**. +1. Locate the project in the **Projects** section. 1. Select the desired [notification level](#notification-levels). ---- +Or: -1. Go to your group. -1. Select the notification dropdown, marked with a bell icon (**{notifications}**). +1. On the top bar, select **Menu > Projects** and find your project. +1. Select the notification dropdown, next to the bell icon (**{notifications}**). 1. Select the desired [notification level](#notification-levels). -##### Group notification email address - -> Introduced in GitLab 12.0 - -You can select an email address to receive notifications for each group you belong to. This could be useful, 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. Select **Preferences**. -1. In the left sidebar, select **Notifications**. -1. Locate the project in the **Groups** section. -1. Select the desired email address. +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +To learn how to be notified when a new release is available, see [Notification for releases](https://www.youtube.com/watch?v=qyeNkGgqmH4). ### Notification levels For each project and group you can select one of the following levels: -| Level | Description | -|:------------|:------------| -| Global | Your global settings apply. | -| Watch | Receive notifications for any activity. | +| Level | Description | +| ----------- | ----------------------------------------------------------- | +| Global | Your global settings apply. | +| Watch | Receive notifications for any activity. | | On mention | Receive notifications when [mentioned](../project/issues/issue_data_and_actions.md#mentions) in a comment. | | Participate | Receive notifications for threads you have participated in. | -| Disabled | Turns off notifications. | -| Custom | Receive notifications for custom selected events. | +| Disabled | Turns off notifications. | +| Custom | Receive notifications for custom selected events. | ### Product marketing emails You can receive emails that teach you about various GitLab features. This is enabled by default. -To opt out, [edit your notification settings](#editing-notification-settings) and clear the +To opt out, [edit your notification settings](#edit-notification-settings) and clear the **Receive product marketing emails** checkbox. Disabling these emails does not disable all emails. @@ -173,51 +171,56 @@ for all users. Users are notified of the following events: +<!-- The table is sorted first by recipient, then alphabetically. --> + | Event | Sent to | Settings level | |------------------------------|---------------------|------------------------------| -| New SSH key added | User | Security email, always sent. | -| SSH key has expired | User | Security email, always sent. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322637) in GitLab 13.12 | -| New email added | User | Security email, always sent. | +| New release | Project members | Custom notification | +| Project moved | Project members (1) | (1) not disabled | | Email changed | User | Security email, always sent. | +| Group access level changed | User | Sent when user group access level is changed | +| New email added | User | Security email, always sent. | +| New SAML/SCIM user provisioned | User | Sent when a user is provisioned through SAML/SCIM. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276018) in GitLab 13.8 | +| New SSH key added | User | Security email, always sent. | +| New user created | User | Sent on user creation, except for OmniAuth (LDAP)| | Password changed | User | Security email, always sent when user changes their own password | | Password changed by administrator | User | Security email, always sent when an administrator changes the password of another user | -| Two-factor authentication disabled | User | Security email, always sent. | -| New user created | User | Sent on user creation, except for OmniAuth (LDAP)| -| New SAML/SCIM user provisioned | User | Sent when a user is provisioned through SAML/SCIM. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276018) in GitLab 13.8 | -| User added to project | User | Sent when user is added to project | +| Personal access tokens expiring soon <!-- Do not delete or lint this instance of future tense --> | User | Security email, always sent. | +| Personal access tokens have expired | User | Security email, always sent. | | Project access level changed | User | Sent when user project access level is changed | +| SSH key has expired | User | Security email, always sent. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322637) in GitLab 13.12 | +| Two-factor authentication disabled | User | Security email, always sent. | | User added to group | User | Sent when user is added to group | -| Group access level changed | User | Sent when user group access level is changed | -| Personal Access Tokens expiring soon <!-- Do not delete or lint this instance of future tense --> | User | Security email, always sent. | -| Personal Access Tokens have expired | User | Security email, always sent. | -| Project moved | Project members (1) | (1) not disabled | -| New release | Project members | Custom notification | +| User added to project | User | Sent when user is added to project | ## Notifications on issues, merge requests, and epics -To enable notifications on one specific issue, merge request or epic, you need to enable the **Notifications** toggle in the right sidebar. +To enable notifications on a specific issue, merge request, or epic, you must turn on the +**Notifications** toggle in the right sidebar. -- **Enable**: If you are not a participant in the discussion on that issue, but - want to receive notifications on each update, subscribe to it. -- **Disable**: If you are receiving notifications for updates to that issue but no - longer want to receive them, unsubscribe from it. +- To subscribe, **turn on** if you are not a participant in the discussion, but want to receive + notifications on each update. +- To unsubscribe, **turn off** if you are receiving notifications for updates but no longer want to + receive them, unsubscribe from it. -Disabling this toggle only unsubscribes you from updates related to this issue, merge request, or epic. +Turning this toggle off only unsubscribes you from updates related to this issue, merge request, or epic. Learn how to [opt out of all emails from GitLab](#opt-out-of-all-gitlab-emails). -Enabling this notification on an epic doesn't automatically subscribe you to the issues linked +Turning notifications on in an epic doesn't automatically subscribe you to the issues linked to the epic. For most events, the notification is sent to: - Participants: - The author and assignee of the issue/merge request. - - Authors of comments on the issue/merge request. - - Anyone mentioned by `@username` in the title or description of the issue, merge request or epic. - - Anyone with notification level "Participating" or higher that is mentioned by `@username` in any of the comments on the issue, merge request, or epic. + - Authors of comments. + - Anyone [mentioned](../project/issues/issue_data_and_actions.md#mentions) by username in the title + or description of the issue, merge request or epic. + - Anyone with notification level "Participating" or higher that is mentioned by their username in + any of the comments on the issue, merge request, or epic. - Watchers: users with notification level "Watch". - Subscribers: anyone who manually subscribed to the issue, merge request, or epic. -- Custom: Users with notification level "custom" who turned on notifications for any of the events present in the table below. +- Custom: Users with notification level "custom" who turned on notifications for any of the events in the following table. NOTE: To minimize the number of notifications that do not require any action, in @@ -259,16 +262,17 @@ If the title or description of an issue or merge request is changed, notifications are sent to any **new** mentions by `@username` as if they had been mentioned in the original text. -You don't receive notifications for issues, merge requests or milestones created -by yourself (except when an issue is due). You only receive automatic -notifications when somebody else comments or adds changes to the ones that -you've created or mentions you. +By default, you don't receive notifications for issues, merge requests, or epics created +by yourself. You only receive notifications when somebody else comments or adds changes to the ones +that you've created or mentions you, or when an issue is due soon. +To always receive notifications on your own issues and so on, you must turn on +[notifications about your own activity](#global-notification-settings). If an open merge request becomes unmergeable due to conflict, its author is notified about the cause. -If a user has also set the merge request to automatically merge once pipeline succeeds, +If a user has also set the merge request to automatically merge when pipeline succeeds, then that user is also notified. -## Design email notifications +## Notifications on designs > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217095) in GitLab 13.6. @@ -284,7 +288,7 @@ The participants are: If you no longer wish to receive any email notifications: -1. [Go to the Notifications settings page.](#editing-notification-settings) +1. [Go to the Notifications settings page.](#edit-notification-settings) 1. Clear the **Receive product marketing emails** checkbox. 1. Set your **Global notification level** to **Disabled**. 1. Clear the **Receive notifications about your own activity** checkbox. @@ -295,7 +299,7 @@ On self-managed installations, even after doing this, your instance administrato [can still email you](../../tools/email.md). To unsubscribe, select the unsubscribe link in one of these emails. -## Filtering email +## Filter email Notification email messages include GitLab-specific headers. You can filter the notification emails based on the content of these headers to better manage your notifications. For example, you could filter all emails for a specific project where you are being assigned either a merge request or issue. diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index c534a630480..bdd49b00a15 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -12,11 +12,26 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Introduced in GitLab 13.3: [Additional notifications for expiring tokens](https://gitlab.com/gitlab-org/gitlab/-/issues/214721). > - Introduced in GitLab 14.1: [Prefill token name and scopes](https://gitlab.com/gitlab-org/gitlab/-/issues/334664). -If you're unable to use [OAuth2](../../api/oauth2.md), you can use a personal access token to authenticate with the [GitLab API](../../api/index.md#personalproject-access-tokens). You can also use a personal access token with Git to authenticate over HTTP. +Personal access tokens can be an alternative to [OAuth2](../../api/oauth2.md) and used to: + +- Authenticate with the [GitLab API](../../api/index.md#personalproject-access-tokens). +- Authenticate with Git using HTTP Basic Authentication. In both cases, you authenticate with a personal access token in place of your password. -Personal access tokens are required when [Two-Factor Authentication (2FA)](account/two_factor_authentication.md) is enabled. +Personal access tokens are: + +- Required when [two-factor authentication (2FA)](account/two_factor_authentication.md) is enabled. +- Used with a GitLab username to authenticate with GitLab features that require usernames. For example, + [GitLab managed Terraform state backend](../infrastructure/iac/terraform_state.md#using-a-gitlab-managed-terraform-state-backend-as-a-remote-data-source) + and [Docker container registry](../packages/container_registry/index.md#authenticate-with-the-container-registry), +- Similar to [project access tokens](../project/settings/project_access_tokens.md), but are attached + to a user rather than a project. + +NOTE: +Though required, GitLab usernames are ignored when authenticating with a personal access token. +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#personalproject-access-tokens). @@ -29,7 +44,7 @@ You can create as many personal access tokens as you like. 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Access Tokens**. +1. On the left sidebar, select **Access Tokens**. 1. Enter a name and optional expiry date for the token. 1. Select the [desired scopes](#personal-access-token-scopes). 1. Select **Create personal access token**. @@ -53,7 +68,7 @@ At any time, you can revoke a personal access token. 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Access Tokens**. +1. On the left sidebar, select **Access Tokens**. 1. In the **Active personal access tokens** area, next to the key, select **Revoke**. ## View the last time a token was used @@ -65,7 +80,7 @@ To view the last time a token was used: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Access Tokens**. +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. ## Personal access token scopes diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index cac283f6f18..b4723294438 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -26,7 +26,7 @@ percentage of users are affected and the change can either be fixed or quickly reverted. Leveraging [Kubernetes' Canary deployments](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#canary-deployments), visualize your canary -deployments right inside the [Deploy Board](deploy_boards.md), without the need to leave GitLab. +deployments right inside the [deploy board](deploy_boards.md), without the need to leave GitLab. ## Use cases @@ -47,9 +47,9 @@ this document. ## Enabling Canary Deployments -Canary deployments require that you properly configure Deploy Boards: +Canary deployments require that you properly configure deploy boards: -1. Follow the steps to [enable Deploy Boards](deploy_boards.md#enabling-deploy-boards). +1. Follow the steps to [enable deploy boards](deploy_boards.md#enabling-deploy-boards). 1. To track canary deployments you need to label your Kubernetes deployments and pods with `track: canary`. To get started quickly, you can use the [Auto Deploy](../../topics/autodevops/stages.md#auto-deploy) template for canary deployments that GitLab provides. @@ -61,13 +61,13 @@ This allows GitLab to discover whether a deployment is stable or canary (tempora Once all of the above are set up and the pipeline has run at least once, navigate to the environments page under **Pipelines > Environments**. -As the pipeline executes, Deploy Boards clearly mark canary pods, enabling +As the pipeline executes, deploy boards clearly mark canary pods, enabling quick and easy insight into the status of each environment and deployment. -Canary deployments are marked with a yellow dot in the Deploy Board so that you +Canary deployments are marked with a yellow dot in the deploy board so that you can easily notice them. - + ### Advanced traffic control with Canary Ingress @@ -104,17 +104,17 @@ Here's an example setup flow from scratch: #### How to check the current traffic weight on a Canary Ingress -1. Visit the [Deploy Board](../../user/project/deploy_boards.md). +1. Visit the [deploy board](../../user/project/deploy_boards.md). 1. View the current weights on the right.  #### How to change the traffic weight on a Canary Ingress -You can change the traffic weight within your environment's Deploy Board by using [GraphiQL](../../api/graphql/getting_started.md#graphiql), +You can change the traffic weight within your environment's deploy board by using [GraphiQL](../../api/graphql/getting_started.md#graphiql), or by sending requests to the [GraphQL API](../../api/graphql/getting_started.md#command-line). -To use your [Deploy Board](../../user/project/deploy_boards.md): +To use your [deploy board](../../user/project/deploy_boards.md): 1. Navigate to **Deployments > Environments** for your project. 1. Set the new weight with the dropdown on the right side. diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index 7d006247177..f7dd24fcfad 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. WARNING: -Use [Infrastrucure as Code](../../infrastructure/index.md) to create new clusters. The method described in this document is deprecated as of GitLab 14.0. +Use [Infrastructure as Code](../../infrastructure/index.md) to create new clusters. The method described in this document is deprecated as of GitLab 14.0. Through GitLab, you can create new clusters and add existing clusters hosted on Amazon Elastic Kubernetes Service (EKS). @@ -48,7 +48,7 @@ To create a new EKS cluster: 1. Go to your: - Project's **Infrastructure > Kubernetes clusters** page, for a project-level cluster. - Group's **Kubernetes** page, for a group-level cluster. - - **Menu >** **{admin}** **Admin > Kubernetes**, for an instance-level cluster. + - **Menu > Admin > Kubernetes**, for an instance-level cluster. 1. Select **Integrate with a cluster certificate**. 1. Under the **Create new cluster** tab, click **Amazon EKS** to display an `Account ID` and `External ID` needed for later steps. @@ -166,7 +166,7 @@ When you create a new cluster, you have the following settings: | Kubernetes cluster name | Your cluster's name. | | Environment scope | The [associated environment](multiple_kubernetes_clusters.md#setting-the-environment-scope). | | Service role | The **EKS IAM role** (**role A**). | -| Kubernetes version | The [Kubernetes version](index.md#supported-cluster-versions) for your cluster. | +| Kubernetes version | The [Kubernetes version](../../infrastructure/clusters/connect/index.md#supported-cluster-versions) for your cluster. | | Key pair name | The [key pair](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) that you can use to connect to your worker nodes. | | VPC | The [VPC](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) to use for your EKS Cluster resources. | | Subnets | The [subnets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html) in your VPC where your worker nodes run. Two are required. | @@ -240,7 +240,7 @@ For example, the following policy document allows assuming a role whose name sta To configure Amazon authentication in GitLab, generate an access key for the IAM user in the Amazon AWS console, and follow these steps: -1. In GitLab, on the top bar, select **Menu >** **{admin}** **Admin > Settings > General** and expand the **Amazon EKS** section. +1. In GitLab, on the top bar, select **Menu > Admin > Settings > General** and expand the **Amazon EKS** section. 1. Check **Enable Amazon EKS integration**. 1. Enter your **Account ID**. 1. Enter your [access key and ID](#eks-access-key-and-id). diff --git a/doc/user/project/clusters/add_existing_cluster.md b/doc/user/project/clusters/add_existing_cluster.md index efd480fa3ce..505c493de4e 100644 --- a/doc/user/project/clusters/add_existing_cluster.md +++ b/doc/user/project/clusters/add_existing_cluster.md @@ -4,11 +4,17 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Add an existing Kubernetes cluster +# Connect existing clusters through cluster certificates If you have an existing Kubernetes cluster, you can add it to a project, group, or instance and benefit from the integration with GitLab. +WARNING: +The process described on this page uses cluster certificates to connect your cluster +to GitLab. Although this method still works, it is **no longer recommended**. +To connect your cluster to GitLab, we **recommend** using the [GitLab Kubernetes Agent](../../clusters/agent/index.md) +instead. **(PREMIUM)** + ## Prerequisites See the prerequisites below to add existing clusters to GitLab. @@ -61,7 +67,7 @@ To add a Kubernetes cluster to your project, group, or instance: 1. Navigate to your: 1. Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level cluster. 1. Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - 1. **Menu >** **{admin}** **Admin >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. + 1. **Menu > Admin > Kubernetes** page, for an instance-level cluster. 1. Click **Add Kubernetes cluster**. 1. Click the **Add existing cluster** tab and fill in the details: 1. **Kubernetes cluster name** (required) - The name you wish to give the cluster. @@ -211,7 +217,8 @@ integration to work properly. WARNING: Disabling RBAC means that any application running in the cluster, or user who can authenticate to the cluster, has full API access. This is a -[security concern](index.md#security-implications), and may not be desirable. +[security concern](../../infrastructure/clusters/connect/index.md#security-implications-for-clusters-connected-with-certificates), +and may not be desirable. To effectively disable RBAC, global permissions can be applied granting full access: diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index a454b4dff99..78d4bce737d 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/6049) in GitLab 14.0. WARNING: -Use [Infrastrucure as Code](../../infrastructure/index.md) to create new clusters. The method described in this document is deprecated as of GitLab 14.0. +Use [Infrastructure as Code](../../infrastructure/index.md) to create new clusters. The method described in this document is deprecated as of GitLab 14.0. Through GitLab, you can create new clusters and add existing clusters hosted on Amazon Elastic Kubernetes Service (EKS). @@ -62,7 +62,7 @@ To create and add a new Kubernetes cluster to your project, group, or instance: - Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level cluster. - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - - **Menu >** **{admin}** **Admin >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. + - **Menu > Admin > Kubernetes** page, for an instance-level cluster. 1. Click **Integrate with a cluster certificate**. 1. Under the **Create new cluster** tab, click **Google GKE**. 1. Connect your Google account if you haven't done already by clicking the diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index fba02183be5..4f2bc5526e0 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -9,11 +9,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. WARNING: -Creating a new cluster through the certificate-based method -is deprecated and no longer recommended. Kubernetes cluster, similar to any other -infrastructure, should be created, updated, maintained using [Infrastructure as Code](../../infrastructure/index.md). -GitLab is developing a built-in capability to create clusters with Terraform. -You can follow along in this [epic](https://gitlab.com/groups/gitlab-org/-/epics/6049). +Creating a new cluster through cluster certificates +is deprecated and no longer recommended. To create a new cluster use +[Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac). NOTE: Every new Google Cloud Platform (GCP) account receives @@ -30,29 +28,38 @@ in a few clicks. ## Create new cluster -> The certificate-based method for creating clusters from GitLab was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. + +As of GitLab 14.0, use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac) +to **safely create new clusters from GitLab**. -As of GitLab 14.0, use [Infrastructure as Code](../../infrastructure/index.md) -to **safely create your new cluster from GitLab**. +Creating clusters from GitLab using cluster certificates is still available on the +GitLab UI but was **deprecated** in GitLab 14.0 and is scheduled for removal in +GitLab 15.0. We don't recommend using this method. -The certificate-based method is **deprecated** and scheduled for removal in -GitLab 15.0. However, you can still use it until then. Through -this method, you can host your cluster in EKS, GKE, on premises, and with other -providers. To host them on premises and with other providers, -use either the EKS or GKE method to guide you through and enter your cluster's -settings manually: +You can create a new cluster hosted in EKS, GKE, on premises, and with other +providers using cluster certificates: - [New cluster hosted on Google Kubernetes Engine (GKE)](add_gke_clusters.md). - [New cluster hosted on Amazon Elastic Kubernetes Service (EKS)](add_eks_clusters.md). +To host them on premises and with other providers, you can use Terraform +or your preferred tool of choice to create and connect a cluster with GitLab. +The [GitLab Terraform provider](https://registry.terraform.io/providers/gitlabhq/gitlab/latest/docs/resources/project_cluster) +supports connecting existing clusters using the certificate-based connection method. + ## Add existing cluster -If you already have a cluster and want to integrate it with GitLab, see how to -[add an existing cluster](add_existing_cluster.md). +As of GitLab 14.0, use the [GitLab Kubernetes Agent](../../clusters/agent/index.md) +to connect your cluster to GitLab. + +Alternatively, you can [add an existing cluster](add_existing_cluster.md) +through the certificate-based method, but we don't recommend using this method for [security implications](../../infrastructure/clusters/connect/index.md#security-implications-for-clusters-connected-with-certificates). ## Configure your cluster -As of GitLab 14.0, use the [GitLab Kubernetes Agent](../../clusters/agent/index.md) to configure your cluster. +As of GitLab 14.0, use the [GitLab Kubernetes Agent](../../clusters/agent/index.md) +to configure your cluster. ## Disable a cluster @@ -62,7 +69,7 @@ one to GitLab, the cluster connection to GitLab becomes enabled. To disable it: 1. Go to your: - Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level cluster. - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - - **Menu >** **{admin}** **Admin >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. + - **Menu > Admin > Kubernetes** page, for an instance-level cluster. 1. Select the name of the cluster you want to disable. 1. Toggle **GitLab Integration** off (in gray). 1. Click **Save changes**. diff --git a/doc/user/project/clusters/deploy_to_cluster.md b/doc/user/project/clusters/deploy_to_cluster.md index fdd65d70242..54141fe1103 100644 --- a/doc/user/project/clusters/deploy_to_cluster.md +++ b/doc/user/project/clusters/deploy_to_cluster.md @@ -4,7 +4,13 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Deploy to a Kubernetes cluster +# Deploy to a Kubernetes cluster with cluster certificates + +WARNING: +The process described on this page uses cluster certificates to deploy to your cluster +from GitLab. Although this method still works, it is **no longer recommended**. +To deploy to your cluster from GitLab, we **recommend** using the [GitLab Kubernetes Agent](../../clusters/agent/index.md) +instead. **(PREMIUM)** A Kubernetes cluster can be the destination for a deployment job. If diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index a0efea267f0..791dc90cad5 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -16,10 +16,6 @@ We offer extensive integrations to help you connect and manage your Kubernetes c Read through this document to get started. -## Clusters infrastructure - -Use [Infrastructure as Code](../../infrastructure) to create and manage your clusters with the GitLab integration with Terraform. - ## Benefit from the GitLab-Kubernetes integration Using the GitLab-Kubernetes integration, you can benefit of GitLab @@ -30,76 +26,18 @@ features such as: - Use [role-based or attribute-based access controls](cluster_access.md). - Run serverless workloads on [Kubernetes with Knative](serverless/index.md). - Connect GitLab to in-cluster applications using [cluster integrations](../../clusters/integrations.md). -- Use [Deploy Boards](../deploy_boards.md) to see the health and status of each CI [environment](../../../ci/environments/index.md) running on your Kubernetes cluster. +- Use [deploy boards](../deploy_boards.md) to see the health and status of each CI [environment](../../../ci/environments/index.md) running on your Kubernetes cluster. - Use [Canary deployments](../canary_deployments.md) to update only a portion of your fleet with the latest version of your application. - View your [Kubernetes podlogs](kubernetes_pod_logs.md) directly in GitLab. - Connect to your cluster through GitLab [web terminals](deploy_to_cluster.md#web-terminals-for-kubernetes-clusters). ## Supported cluster versions -GitLab is committed to support at least two production-ready Kubernetes minor -versions at any given time. We regularly review the versions we support, and -provide a three-month deprecation period before we remove support of a specific -version. The range of supported versions is based on the evaluation of: - -- The versions supported by major managed Kubernetes providers. -- The versions [supported by the Kubernetes community](https://kubernetes.io/releases/version-skew-policy/#supported-versions). - -GitLab supports the following Kubernetes versions, and you can upgrade your -Kubernetes version to any supported version at any time: - -- 1.19 (support ends on February 22, 2022) -- 1.18 (support ends on November 22, 2021) -- 1.17 (support ends on September 22, 2021) -- 1.16 (support ends on July 22, 2021) -- 1.15 (support ends on May 22, 2021) - -Some GitLab features may support versions outside the range provided here. - -## Add and remove clusters - -You can create new or add existing clusters to GitLab: - -- On the project-level, to have a cluster dedicated to a project. -- On the [group level](../../group/clusters/index.md), to use the same cluster across multiple projects within your group. -- On the [instance level](../../instance/clusters/index.md), to use the same cluster across multiple groups and projects. **(FREE SELF)** - -To create new clusters, use one of the following methods: - -- [Infrastructure as Code](../../infrastructure/index.md) (**recommended**). -- [Cluster certificates](add_remove_clusters.md) (**deprecated**). - -You can also [add existing clusters](add_existing_cluster.md) to GitLab. - -## View your clusters - -To view your project-level Kubernetes clusters, to go **Infrastructure > Kubernetes clusters** -from your project. On this page, you can add a new cluster -and view information about your existing clusters, such as: - -- Nodes count. -- Rough estimates of memory and CPU usage. - -## Configuring your Kubernetes cluster - -Use the [GitLab Kubernetes Agent](../../clusters/agent/index.md) to safely -configure your clusters. Otherwise, there are [security implications](#security-implications). - -### Security implications - -WARNING: -The whole cluster security is based on a model where [developers](../../permissions.md) -are trusted, so **only trusted users should be allowed to control your clusters**. - -The default cluster configuration grants access to a wide set of -functionalities needed to successfully build and deploy a containerized -application. Bear in mind that the same credentials are used for all the -applications running on the cluster. +See the [Kubernetes clusters versions supported by GitLab](../../infrastructure/clusters/connect/index.md#supported-cluster-versions). -## Multiple Kubernetes clusters +## Connect your cluster to GitLab -See how to associate [multiple Kubernetes clusters](multiple_kubernetes_clusters.md) -with your GitLab project. +Learn how to [create new and connect existing clusters to GitLab](../../infrastructure/clusters/connect/index.md). ## Cluster integrations diff --git a/doc/user/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md index 7a9c7eb423d..eb0e8d0e91c 100644 --- a/doc/user/project/clusters/kubernetes_pod_logs.md +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -46,15 +46,15 @@ a [metrics dashboard](../../../operations/metrics/index.md) and select **View lo [permissions](../../permissions.md#project-members-permissions) in the project. 1. To navigate to the **Log Explorer** from the sidebar menu, go to **Monitor > Logs** ([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22011) in GitLab 12.5.). -1. To navigate to the **Log Explorer** from a specific pod on a [Deploy Board](../deploy_boards.md): +1. To navigate to the **Log Explorer** from a specific pod on a [deploy board](../deploy_boards.md): 1. Go to **Deployments > Environments** and find the environment which contains the desired pod, like `production`. 1. On the **Environments** page, you should see the status of the environment's - pods with [Deploy Boards](../deploy_boards.md). + pods with [deploy boards](../deploy_boards.md). 1. When mousing over the list of pods, GitLab displays a tooltip with the exact pod name and status. -  +  1. Click on the desired pod to display the **Log Explorer**. ### Logs view diff --git a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md index 62010bb7802..1940cf229b8 100644 --- a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md +++ b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md @@ -137,7 +137,7 @@ Network Policies can be managed through GitLab in one of two ways: - Management through a YAML file in each application's project (for projects using Auto DevOps). For more information, see the [Network Policy documentation](../../../../../topics/autodevops/stages.md#network-policy). - Management through the GitLab Policy management UI (for projects not using Auto DevOps). For more - information, see the [Container Network Policy documentation](../../../../application_security/threat_monitoring/index.md#container-network-policy-management) (Ultimate only). + information, see the [Container Network Policy documentation](../../../../application_security/policies/index.md#container-network-policy) (Ultimate only). Each method has benefits and drawbacks: @@ -167,7 +167,7 @@ hubble: ``` Additional information about the statistics page is available in the -[documentation that describes the Threat Management UI](../../../../application_security/threat_monitoring/index.md#container-network-policy). +[documentation that describes the Threat Management UI](../../../../application_security/policies/index.md#container-network-policy). ## Forwarding logs to a SIEM diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index b2054c4befb..7357fc850e5 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -63,7 +63,7 @@ information. Follow this step-by-step guide to configure an executable runbook in GitLab using the components outlined above and the pre-loaded demo runbook. -1. Create an [OAuth Application for JupyterHub](../../../../integration/oauth_provider.md#gitlab-as-oauth2-authentication-service-provider). +1. Create an [OAuth Application for JupyterHub](../../../../integration/oauth_provider.md#gitlab-as-an-oauth-20-authentication-service-provider). 1. When [installing JupyterHub with Helm](https://zero-to-jupyterhub.readthedocs.io/en/latest/jupyterhub/installation.html), use the following values ```yaml diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index ec22f71157f..fb32579f40e 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -4,9 +4,10 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Serverless **(FREE)** +# Serverless (DEPRECATED) **(FREE)** -> Introduced in GitLab 11.5. +> - Introduced in GitLab 11.5. +> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/6) in GitLab 14.3. WARNING: Serverless is currently in [alpha](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha). @@ -316,7 +317,7 @@ The optional `runtime` parameter can refer to one of the following runtime alias | `openfaas/classic/python3` | OpenFaaS | | `openfaas/classic/ruby` | OpenFaaS | -After the `gitlab-ci.yml` template has been added and the `serverless.yml` file +After the `.gitlab-ci.yml` template has been added and the `serverless.yml` file has been created, pushing a commit to your project results in a CI pipeline being executed which deploys each function as a Knative service. After the deploy stage has finished, additional details for the function display diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 64a5515136b..05f026cca18 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto, reference --- -# Deploy Boards **(FREE)** +# Deploy boards **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1589) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) to GitLab Free in 13.8. @@ -16,7 +16,7 @@ type: howto, reference > This is [fixed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60525) in > GitLab 13.12. -GitLab Deploy Boards offer a consolidated view of the current health and +GitLab deploy boards offer a consolidated view of the current health and status of each CI [environment](../../ci/environments/index.md) running on [Kubernetes](https://kubernetes.io), displaying the status of the pods in the deployment. Developers and other teammates can view the progress and status of a rollout, pod by pod, in the workflow they already use @@ -28,23 +28,23 @@ environments by using [Auto DevOps](../../topics/autodevops/index.md). ## Overview -With Deploy Boards you can gain more insight into deploys with benefits such as: +With deploy boards you can gain more insight into deploys with benefits such as: - Following a deploy from the start, not just when it's done - Watching the rollout of a build across multiple servers - Finer state detail (Succeeded, Running, Failed, Pending, Unknown) - See [Canary Deployments](canary_deployments.md) -Here's an example of a Deploy Board of the production environment. +Here's an example of a deploy board of the production environment. - + The squares represent pods in your Kubernetes cluster that are associated with the given environment. Hovering above each square you can see the state of a deploy rolling out. The percentage is the percent of the pods that are updated to the latest release. -Since Deploy Boards are tightly coupled with Kubernetes, there is some required +Since deploy boards are tightly coupled with Kubernetes, there is some required knowledge. In particular, you should be familiar with: - [Kubernetes pods](https://kubernetes.io/docs/concepts/workloads/pods/) @@ -54,7 +54,7 @@ knowledge. In particular, you should be familiar with: ## Use cases -Since the Deploy Board is a visual representation of the Kubernetes pods for a +Since the deploy board is a visual representation of the Kubernetes pods for a specific environment, there are a lot of use cases. To name a few: - You want to promote what's running in staging, to production. You go to the @@ -73,9 +73,9 @@ specific environment, there are a lot of use cases. To name a few: list, find the [Review App](../../ci/review_apps/index.md) you're interested in, and click the manual action to deploy it to staging. -## Enabling Deploy Boards +## Enabling deploy boards -To display the Deploy Boards for a specific [environment](../../ci/environments/index.md) you should: +To display the deploy boards for a specific [environment](../../ci/environments/index.md) you should: 1. Have [defined an environment](../../ci/environments/index.md) with a deploy stage. @@ -83,7 +83,7 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ NOTE: If you're using OpenShift, ensure that you're using the `Deployment` resource - instead of `DeploymentConfiguration`. Otherwise, the Deploy Boards don't render + instead of `DeploymentConfiguration`. Otherwise, the deploy boards don't render correctly. For more information, read the [OpenShift docs](https://docs.openshift.com/container-platform/3.7/dev_guide/deployments/kubernetes_deployments.html#kubernetes-deployments-vs-deployment-configurations) and [GitLab issue #4584](https://gitlab.com/gitlab-org/gitlab/-/issues/4584). @@ -114,17 +114,17 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ If you use GCP to manage clusters, you can see the deployment details in GCP itself by navigating to **Workloads > deployment name > Details**: -  +  Once all of the above are set up and the pipeline has run at least once, navigate to the environments page under **Deployments > Environments**. -Deploy Boards are visible by default. You can explicitly click +Deploy boards are visible by default. You can explicitly click the triangle next to their respective environment name in order to hide them. ### Example manifest file -The following example is an extract of a Kubernetes manifest deployment file, using the two annotations `app.gitlab.com/env` and `app.gitlab.com/app` to enable the **Deploy Boards**: +The following example is an extract of a Kubernetes manifest deployment file, using the two annotations `app.gitlab.com/env` and `app.gitlab.com/app` to enable the **deploy boards**: ```yaml apiVersion: apps/v1 diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index 1b9a17ee071..e9a38f91677 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -121,7 +121,7 @@ repositories to secure, shared services, such as CI/CD. Instance administrators can add public deploy keys: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Deploy Keys**. 1. Select **New deploy key**. diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 70363b67c88..1798aa0c1c6 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -181,7 +181,7 @@ To pull images from the Dependency Proxy, you must: 1. Create a group deploy token with both `read_registry` and `write_registry` scopes. 1. Take note of your `username` and `token`. -1. Follow the Depenency Proxy [authentication instructions](../../packages/dependency_proxy/index.md). +1. Follow the Dependency Proxy [authentication instructions](../../packages/dependency_proxy/index.md). ### GitLab deploy token diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 72ef88b5fab..5b19a54bd91 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -116,7 +116,7 @@ Only instance administrators can set instance-level templates. To set the instance-level description template repository: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Templates**. 1. Expand **Templates** 1. From the dropdown, select your template project as the template repository at instance level. diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index 802eb3efc51..cda018a0c37 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -16,18 +16,18 @@ Import your projects from Bitbucket Cloud to GitLab with minimal effort. The Bitbucket importer can import: -- Repository description (GitLab 7.7+) -- Git repository data (GitLab 7.7+) -- Issues (GitLab 7.7+) -- Issue comments (GitLab 8.15+) -- Pull requests (GitLab 8.4+) -- Pull request comments (GitLab 8.15+) -- Milestones (GitLab 8.15+) -- Wiki (GitLab 8.15+) +- Repository description +- Git repository data +- Issues +- Issue comments +- Pull requests +- Pull request comments +- Milestones +- Wiki When importing: -- References to pull requests and issues are preserved (GitLab 8.7+). +- References to pull requests and issues are preserved. - Repository public access is retained. If a repository is private in Bitbucket, it's created as private in GitLab as well. diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index 1ab343d75fb..4443ae902fb 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -31,13 +31,18 @@ each imported repository maintains visibility level unless that [visibility level is restricted](../../../public_access/public_access.md#restrict-use-of-public-or-internal-projects), in which case it defaults to the default project visibility. -The namespace is a user or group in GitLab, such as `gitlab.com/janedoe` or `gitlab.com/customer-success`. You can do some bulk actions to move projects to different namespaces in the rails console. +The namespace is a user or group in GitLab, such as `gitlab.com/janedoe` or +`gitlab.com/customer-success`. You can do some bulk actions to move projects to +different namespaces in the rails console. -This process does not migrate or import any types of groups or organizations from GitHub to GitLab. +This process does not migrate or import any types of groups or organizations +from GitHub to GitLab. ## Use cases -The steps you take depend on whether you are importing from GitHub.com or GitHub Enterprise, as well as whether you are importing to GitLab.com or self-managed GitLab instance. +The steps you take depend on whether you are importing from GitHub.com or +GitHub Enterprise. The steps also depend on whether you are importing to GitLab.com or +self-managed GitLab instance. - If you're importing to GitLab.com, you can alternatively import GitHub repositories using a [personal access token](#use-a-github-token). We do not recommend @@ -49,12 +54,14 @@ The steps you take depend on whether you are importing from GitHub.com or GitHub - If you're importing from GitHub Enterprise to your 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 you're importing from GitHub.com to your self-managed GitLab instance, you do not need to set up GitHub integration. You can use the [Import API](../../../api/import.md). +- If you're importing from GitHub.com to your self-managed GitLab instance, + setting up GitHub integration is not required. You can use the [Import API](../../../api/import.md). ## How it works -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 (note that pull requests are called "merge requests" in GitLab). +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 (note +that pull requests are called "merge requests" in GitLab). For this association to succeed, each GitHub author and assignee in the repository must meet one of the following conditions prior to the import: @@ -64,12 +71,13 @@ must meet one of the following conditions prior to the import: that matches their GitLab account's email address. NOTE: - GitLab content imports that use GitHub accounts require that the GitHub public-facing - email address is populated so that all comments and contributions are properly mapped - to the same user in GitLab. GitHub Enterprise (on premise) does not require this field - to be populated to use the product, so you may need to add it on existing GitHub Enterprise - accounts for imported content to be properly mapped to the user in the new system. - Refer to GitHub documentation for instructions on how to add that address. + GitLab content imports that use GitHub accounts require that the GitHub + public-facing email address is populated so that all comments and + contributions are properly mapped to the same user in GitLab. GitHub + Enterprise (on premise) does not require this field to be populated to use the + product, so you may have to add it on existing accounts for the imported + content to be properly mapped to the user in the new system. Refer to GitHub + documentation for instructions on how to add this email address. If a user referenced in the project is not found in the GitLab database, the project creator (typically the user that initiated the import process) is set as the author/assignee, but a note on the issue mentioning the original @@ -132,7 +140,7 @@ If you are not using the GitHub integration, you can still perform an authorizat 1. Copy the token hash. 1. Go back to GitLab and provide the token to the GitHub importer. 1. Hit the **List Your GitHub Repositories** button and wait while GitLab reads your repositories' information. - Once done, you'll be taken to the importer page to select the repositories to import. + Once done, you are taken to the importer page to select the repositories to import. To use a newer personal access token in imports after previously performing these steps, sign out of your GitLab account and sign in again, or revoke the older personal access token in GitHub. @@ -152,7 +160,7 @@ your GitHub repositories are listed.  -## Mirroring and pipeline status sharing +## Mirror a repository and share pipeline status Depending on your GitLab tier, [repository mirroring](../repository/repository_mirroring.md) can be set up to keep your imported repository in sync with its GitHub copy. @@ -169,7 +177,7 @@ Mirroring does not sync any new or updated pull requests from your GitHub projec ## Improve the speed of imports on self-managed instances NOTE: -Administrator access to the GitLab server is required. +An administrator role on the GitLab server is required for this process. For large projects it may take a while to import all data. To reduce the time necessary, you can increase the number of Sidekiq workers that process the following queues: @@ -183,4 +191,52 @@ servers. For 4 servers with 8 cores this means you can import up to 32 objects ( Reducing the time spent in cloning a repository can be done by increasing network throughput, CPU capacity, and disk performance (by using high performance SSDs, for example) of the disks that store the Git repositories (for your GitLab instance). -Increasing the number of Sidekiq workers will *not* reduce the time spent cloning repositories. +Increasing the number of Sidekiq workers does *not* reduce the time spent cloning repositories. + +## Alternative way to import notes and diff notes + +When GitHub Importer runs on extremely large projects not all notes & diff notes can be imported due to GitHub API `issues_comments` & `pull_requests_comments` endpoints limitation. +Not all pages can be fetched due to the following error coming from GitHub API: `In order to keep the API fast for everyone, pagination is limited for this resource. Check the rel=last link relation in the Link response header to see how far back you can traverse.`. + +An alternative approach for importing notes and diff notes is available behind a feature flag. + +Instead of using `issues_comments` and `pull_requests_comments`, use individual resources `issue_comments` and `pull_request_comments` instead to pull notes from one object at a time. +This allows us to carry over any missing comments, however it increases the number of network requests required to perform the import, which means its execution takes a longer time. + +To use the alternative way of importing notes, the `github_importer_single_endpoint_notes_import` feature flag must be enabled on the group project is being imported into. + +Start a [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session). + +```ruby +group = Group.find_by_full_path('my/group/fullpath') + +# Enable +Feature.enable(:github_importer_single_endpoint_notes_import, group) + +# Disable +Feature.disable(:github_importer_single_endpoint_notes_import, group) +``` + +## Reduce GitHub API request objects per page + +Some GitHub API endpoints may return a 500 or 502 error for project imports from large repositories. +To reduce the chance of such errors, you can enable the feature flag +`github_importer_lower_per_page_limit` in the group project importing the data. This reduces the +page size from 100 to 50. + +To enable this feature flag, start a [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session) +and run the following `enable` command: + +```ruby +group = Group.find_by_full_path('my/group/fullpath') + +# Enable +Feature.enable(:github_importer_lower_per_page_limit, group) +``` + +To disable the feature, run this command: + +```ruby +# Disable +Feature.disable(:github_importer_lower_per_page_limit, group) +``` diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index dcc41c6c85e..65e1eafa477 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -76,7 +76,7 @@ a self-managed instance from an old server to a new server. The backups produced don't depend on the operating system running GitLab. You can therefore use the restore method to switch between different operating system distributions or versions, as long -as the same GitLab version [is available for installation](https://docs.gitlab.com/omnibus/package-information/deprecated_os.md). +as the same GitLab version [is available for installation](../../../administration/package_information/deprecated_os.md). To instead merge two self-managed GitLab instances together, use the instructions in [Migrate from self-managed GitLab to GitLab.com](#migrate-from-self-managed-gitlab-to-gitlabcom). diff --git a/doc/user/project/import/jira.md b/doc/user/project/import/jira.md index 3e0faec0a49..c6992422733 100644 --- a/doc/user/project/import/jira.md +++ b/doc/user/project/import/jira.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/engineering/ux/technical-writing/#assignments --- -# Import your Jira project issues to GitLab **(PREMIUM)** +# Import your Jira project issues to GitLab **(FREE)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2766) in GitLab 12.10. diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 668a0dffd32..8c81af418a0 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -22,8 +22,8 @@ Projects include the following [features](https://about.gitlab.com/features/): **Repositories:** - [Issue tracker](issues/index.md): Discuss implementations with your team. - - [Issue Boards](issue_board.md): Organize and prioritize your workflow. - - [Multiple Issue Boards](issue_board.md#multiple-issue-boards): Create team-specific workflows (Issue Boards) for a project. + - [Issue boards](issue_board.md): Organize and prioritize your workflow. + - [Multiple issue boards](issue_board.md#multiple-issue-boards): Create team-specific workflows (issue boards) for a project. - [Repositories](repository/index.md): Host your code in a fully-integrated platform. - [Branches](repository/branches/index.md): Use Git branching strategies to collaborate on code. @@ -41,8 +41,8 @@ Projects include the following [features](https://about.gitlab.com/features/): **Issues and merge requests:** - [Issue tracker](issues/index.md): Discuss implementations with your team. - - [Issue Boards](issue_board.md): Organize and prioritize your workflow. - - [Multiple Issue Boards](issue_board.md#multiple-issue-boards): Create team-specific workflows (Issue Boards) for a project. + - [Issue boards](issue_board.md): Organize and prioritize your workflow. + - [Multiple issue boards](issue_board.md#multiple-issue-boards): Create team-specific workflows (issue boards) for a project. - [Merge Requests](merge_requests/index.md): Apply a branching strategy and get reviewed by your team. - [Merge Request Approvals](merge_requests/approvals/index.md): Ask for approval before @@ -141,7 +141,7 @@ There are numerous [APIs](../../api/index.md) to use with your projects: - [Threads](../../api/discussions.md) - [General](../../api/projects.md) - [Import/export](../../api/project_import_export.md) -- [Issue Board](../../api/boards.md) +- [Issue board](../../api/boards.md) - [Labels](../../api/labels.md) - [Markdown](../../api/markdown.md) - [Merge Requests](../../api/merge_requests.md) diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 6b342392bdf..4908d21e764 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w GitLab provides an integration for updating the pipeline statuses on GitHub. This is especially useful if using GitLab for CI/CD only. -This project integration is separate from the [instance wide GitHub integration](../import/github.md#mirroring-and-pipeline-status-sharing) +This project integration is separate from the [instance wide GitHub integration](../import/github.md#mirror-a-repository-and-share-pipeline-status) and is automatically configured on [GitHub import](../../../integration/github.md).  diff --git a/doc/user/project/integrations/img/slack_setup.png b/doc/user/project/integrations/img/slack_setup.png Binary files differindex 7928fb7d495..8acae659fb4 100644 --- a/doc/user/project/integrations/img/slack_setup.png +++ b/doc/user/project/integrations/img/slack_setup.png diff --git a/doc/user/project/integrations/img/zentao_product_id.png b/doc/user/project/integrations/img/zentao_product_id.png Binary files differnew file mode 100644 index 00000000000..a91b4c3f82d --- /dev/null +++ b/doc/user/project/integrations/img/zentao_product_id.png diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index 6f86098b33d..ac6e18e8e6a 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -17,8 +17,8 @@ For more information, read the [overview of integrations](overview.md) or learn how to manage your integrations: - *For GitLab 13.3 and later,* read [Project integration management](../../admin_area/settings/project_integration_management.md). -- *For GitLab 13.2 and earlier,* read [Service Templates](services_templates.md), - which are deprecated and [scheduled to be removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268032) +- *For GitLab 13.2 and earlier,* read [Integration Management](../../admin_area/settings/project_integration_management.md), + which replaced the deprecated Service Templates [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268032) in GitLab 14.0. ## Project webhooks diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 5b5feb73b69..8027cc1c61e 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -22,7 +22,7 @@ on your configuration: - **Omnibus GitLab installations**: Mattermost is bundled with [Omnibus GitLab](https://docs.gitlab.com/omnibus/). To configure Mattermost for Omnibus GitLab, read the - [Omnibus GitLab Mattermost documentation](https://docs.gitlab.com/omnibus/gitlab-mattermost/). + [Omnibus GitLab Mattermost documentation](../../../integration/mattermost/index.md). - **If Mattermost is installed on the same server as GitLab**, use the [automated configuration](#automated-configuration). - **For all other installations**, use the [manual configuration](#manual-configuration). @@ -68,7 +68,7 @@ information from GitLab. To get this information: 1. In a different browser tab than your current Mattermost session, sign in to GitLab as a user with [Administrator role](../../permissions.md). -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. In the left menu, select **Settings > Integrations**, then select **Mattermost slash commands**. 1. GitLab displays potential values for Mattermost settings. Copy the **Request URL** diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index 13def74450c..a6f739c6408 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -12,8 +12,10 @@ functionality to GitLab. ## Accessing integrations -You can find the available integrations under your project's -**Settings > Integrations** page. +To find the available integrations for your project: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. There are more than 20 integrations to integrate with. Select the one that you want to configure. @@ -60,6 +62,7 @@ Click on the service links to see further configuration instructions and details | [Unify Circuit](unify_circuit.md) | Receive events notifications. | **{dotted-circle}** No | | [Webex Teams](webex_teams.md) | Receive events notifications. | **{dotted-circle}** No | | [YouTrack](youtrack.md) | Use YouTrack as the issue tracker. | **{dotted-circle}** No | +| [ZenTao](zentao.md) | Use ZenTao as the issue tracker. | **{dotted-circle}** No | ## Push hooks limit diff --git a/doc/user/project/integrations/services_templates.md b/doc/user/project/integrations/services_templates.md deleted file mode 100644 index 37df48c75f8..00000000000 --- a/doc/user/project/integrations/services_templates.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: '../../admin_area/settings/project_integration_management.md' -remove_date: '2021-09-09' ---- - -This document was moved to [another location](../../admin_area/settings/project_integration_management.md). - -<!-- This redirect file can be deleted after <2021-09-09>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index 5db4e839b54..a38d2157699 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -10,27 +10,27 @@ The Slack notifications service enables your GitLab project to send events (such as issue creation) to your existing Slack team as notifications. Setting up Slack notifications requires configuration changes for both Slack and GitLab. -You can also use Slack slash commands to control GitLab inside Slack. This is the -separately configured [Slack slash commands](slack_slash_commands.md). +You can also use [Slack slash commands](slack_slash_commands.md) +to control GitLab from Slack. Slash commands are configured separately. -## Slack configuration +## Configure Slack 1. Sign in to your Slack team and [start a new Incoming WebHooks configuration](https://my.slack.com/services/new/incoming-webhook). 1. Identify the Slack channel where notifications should be sent to by default. Select **Add Incoming WebHooks integration** to add the configuration. -1. Copy the **Webhook URL**, which is used later in the GitLab configuration. +1. Copy the **Webhook URL** to use later when you configure GitLab. -## GitLab configuration +## Configure GitLab 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. -1. Select the **Slack notifications** integration to configure it. +1. Select **Slack notifications**. 1. In the **Enable integration** section, select the **Active** checkbox. 1. In the **Trigger** section, select the checkboxes for each type of GitLab event to send to Slack as a notification. For a full list, see - [Triggers available for Slack notifications](#triggers-available-for-slack-notifications). + [Triggers for Slack notifications](#triggers-for-slack-notifications). By default, messages are sent to the channel you configured during - [Slack integration](#slack-configuration). + [Slack configuration](#configure-slack). 1. (Optional) To send messages to a different channel, multiple channels, or as a direct message: - *To send messages to channels,* enter the Slack channel names, separated by @@ -40,38 +40,39 @@ separately configured [Slack slash commands](slack_slash_commands.md). NOTE: Usernames and private channels are not supported. -1. In **Webhook**, enter the webhook URL you copied from the previous - [Slack integration](#slack-configuration) step. +1. In **Webhook**, enter the webhook URL you copied in the + [Slack configuration](#configure-slack) step. 1. (Optional) In **Username**, enter the username of the Slack bot that sends the notifications. 1. Select the **Notify only broken pipelines** checkbox to notify only on failures. 1. In the **Branches to be notified** dropdown, select which types of branches to send notifications for. -1. Leave the **Labels to be notified** field blank to get all notifications or - add labels that the issue or merge request must have in order to trigger a +1. Leave the **Labels to be notified** field blank to get all notifications, or + add labels that the issue or merge request must have to trigger a notification. 1. Select **Test settings** to verify your information, and then select **Save changes**. Your Slack team now starts receiving GitLab event notifications as configured. -### Triggers available for Slack notifications +## Triggers for Slack notifications The following triggers are available for Slack notifications: -| Trigger | Description | -|------------------------|-------------| -| **Push** | Triggered by a push to the repository. | -| **Issue** | Triggered when an issue is created, updated, or closed. | -| **Confidential issue** | Triggered when a confidential issue is created, updated, or closed. | -| **Merge request** | Triggered when a merge request is created, updated, or merged. | -| **Note** | Triggered when someone adds a comment. | -| **Confidential note** | Triggered when someone adds a confidential note. | -| **Tag push** | Triggered when a new tag is pushed to the repository. | -| **Pipeline** | Triggered when a pipeline status changes. | -| **Wiki page** | Triggered when a wiki page is created or updated. | -| **Deployment** | Triggered when a deployment starts or finishes. | -| **Alert** | Triggered when a new, unique alert is recorded. | +| Trigger name | Trigger event | +| ------------------------ | ------------------------------------------------------ | +| **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** | **(ULTIMATE)** A new, unique vulnerability is recorded. | ## Troubleshooting @@ -81,45 +82,48 @@ for errors relating to your Slack service. ### Something went wrong on our end -This is a generic error shown in the GitLab UI and does not mean much by itself. +You might get this generic error message in the GitLab UI. Review [the logs](../../../administration/logs.md#productionlog) to find -an error message and keep troubleshooting from there. +the error message and keep troubleshooting from there. ### `certificate verify failed` -You may see an entry similar to the following in your Sidekiq log: +You might see an entry like the following in your Sidekiq log: ```plaintext 2019-01-10_13:22:08.42572 2019-01-10T13:22:08.425Z 6877 TID-abcdefg ProjectServiceWorker JID-3bade5fb3dd47a85db6d78c5 ERROR: {:class=>"ProjectServiceWorker", :service_class=>"SlackService", :message=>"SSL_connect returned=1 errno=0 state=error: certificate verify failed"} ``` -This is probably a problem either with GitLab communicating with Slack, or GitLab -communicating with itself. The former is less likely, as Slack's security certificates -should _hopefully_ always be trusted. We can establish which we're dealing with by using -the below rails console script. +This issue occurs when there is a problem with GitLab communicating with Slack, +or GitLab communicating with itself. +The former is less likely, as Slack security certificates should always be trusted. -```shell -# start a rails console: -sudo gitlab-rails console -e production +To view which of these problems is the cause of the issue: -# or for source installs: -bundle exec rails console -e production -``` +1. Start a Rails console: -```ruby -# run this in the Rails console -# replace <SLACK URL> with your actual Slack URL -result = Net::HTTP.get(URI('https://<SLACK URL>'));0 + ```shell + sudo gitlab-rails console -e production -# replace <GITLAB URL> with your actual GitLab URL -result = Net::HTTP.get(URI('https://<GITLAB URL>'));0 -``` + # for source installs: + bundle exec rails console -e production + ``` + +1. Run the following commands: + + ```ruby + # replace <SLACK URL> with your actual Slack URL + result = Net::HTTP.get(URI('https://<SLACK URL>'));0 + + # replace <GITLAB URL> with your actual GitLab URL + result = Net::HTTP.get(URI('https://<GITLAB URL>'));0 + ``` -If GitLab is not trusting HTTPS connections to itself, then you may -need to [add your certificate to the GitLab trusted certificates](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). +If GitLab does not trust HTTPS connections to itself, +[add your certificate to the GitLab trusted certificates](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). -If GitLab is not trusting connections to Slack, then the GitLab -OpenSSL trust store is incorrect. Some typical causes: +If GitLab does not trust connections to Slack, +the GitLab OpenSSL trust store is incorrect. Typical causes are: - Overriding the trust store with `gitlab_rails['env'] = {"SSL_CERT_FILE" => "/path/to/file.pem"}`. - Accidentally modifying the default CA bundle `/opt/gitlab/embedded/ssl/certs/cacert.pem`. diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index dfebf9a1123..066a2f83753 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -8,27 +8,36 @@ info: To determine the technical writer assigned to the Stage/Group associated w > Introduced in GitLab 8.15. -Slack slash commands allow you to control GitLab and view content right inside -Slack, without having to leave it. This requires configurations in both Slack and GitLab. +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. -GitLab can also send events (e.g., `issue created`) to Slack as notifications. -This is the separately configured [Slack Notifications Service](slack.md). +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 [Slack app](gitlab_slack_application.md) instead. +For GitLab.com, use the [GitLab Slack app](gitlab_slack_application.md) instead. -## Configuration +## Configure GitLab and Slack -1. Slack slash commands are scoped to a project. Navigate to the [Integrations page](overview.md#accessing-integrations) in your project's settings, i.e. **Project > Settings > Integrations**. -1. Select the **Slack slash commands** integration to configure it. This page contains required information to complete the configuration in Slack. Leave this browser tab open. -1. Open a new browser tab and sign in to your Slack team. [Start a new Slash Commands integration](https://my.slack.com/services/new/slash-commands). -1. Enter a trigger term. We suggest you use the project name. Click **Add Slash Command Integration**. -1. Complete the rest of the fields in the Slack configuration page using information from the GitLab browser tab. In particular, the URL needs to be copied and pasted. Click **Save Integration** to complete the configuration in Slack. -1. While still on the Slack configuration page, copy the **token**. Go back to the GitLab browser tab and paste in the **token**. -1. Ensure that the **Active** toggle is enabled and click **Save changes** to complete the configuration in GitLab. +Slack slash command [integrations](overview.md#accessing-integrations) +are scoped to a project. - +1. In GitLab, on the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Slack slash commands**. Leave this browser tab open. +1. Open a new browser tab, sign in to your Slack team, and [start a new Slash Commands integration](https://my.slack.com/services/new/slash-commands). +1. Enter a trigger command. We suggest you use the project name. + Select **Add Slash Command Integration**. +1. Complete the rest of the fields in the Slack configuration page using information from the GitLab browser tab. + In particular, make sure you copy and paste the **URL**. -## Usage +  -You can now use the [Slack slash commands](../../../integration/slash_commands.md). +1. On the Slack configuration page, select **Save Integration** and copy the **Token**. +1. Go back to the GitLab configuration page and paste in the **Token**. +1. Ensure the **Active** checkbox is selected and select **Save changes**. + +## Slash commands + +You can now use the available [Slack slash commands](../../../integration/slash_commands.md). diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index 3632fdf0e0c..de152aabde5 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -27,7 +27,7 @@ notifications: 1. Navigate to: - **Settings > Integrations** in a project to enable the integration at the project level. - **Settings > Integrations** in a group to enable the integration at the group level. - - On the top bar, select **Menu >** **{admin}** **Admin**. Then, in the left sidebar, + - On the top bar, select **Menu > Admin**. Then, in the left sidebar, select **Settings > Integrations** to enable an instance-level integration. 1. Select the **Webex Teams** integration. 1. Ensure that the **Active** toggle is enabled. diff --git a/doc/user/project/integrations/zentao.md b/doc/user/project/integrations/zentao.md new file mode 100644 index 00000000000..ab8a7829139 --- /dev/null +++ b/doc/user/project/integrations/zentao.md @@ -0,0 +1,40 @@ +--- +stage: Ecosystem +group: Integrations +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# ZenTao product integration **(PREMIUM)** + +[ZenTao](https://www.zentao.net/) is a web-based project management platform. + +## Configure ZenTao + +This integration requires a ZenTao API secret key. + +Complete these steps in ZenTao: + +1. Go to your **Admin** page and select **Develop > Application**. +1. Select **Add Application**. +1. Under **Name** and **Code**, enter a name and a code for the new secret key. +1. Under **Account**, select an existing account name. +1. Select **Save**. +1. Copy the generated key to use in GitLab. + +## Configure GitLab + +Complete these steps in GitLab: + +1. Go to your project and select **Settings > Integrations**. +1. Select **ZenTao**. +1. Turn on the **Active** toggle under **Enable Integration**. +1. Provide the ZenTao configuration information: + - **ZenTao Web URL**: The base URL of the ZenTao instance web interface you're linking to this GitLab project (for example, `example.zentao.net`). + - **ZenTao API URL** (optional): The base URL to the ZenTao instance API. Defaults to the Web URL value if not set. + - **ZenTao API token**: Use the key you generated when you [configured ZenTao](#configure-zentao). + - **ZenTao Product ID**: To display issues from a single ZenTao product in a given GitLab project. The Product ID can be found in the ZenTao product page under **Settings > Overview**. + +  + +1. To verify the ZenTao connection is working, select **Test settings**. +1. Select **Save changes**. diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 0c624d7df01..4d1805e3d31 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -4,9 +4,9 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Issue Boards **(FREE)** +# Issue boards **(FREE)** -The GitLab Issue Board is a software project management tool used to plan, +The issue board is a software project management tool used to plan, organize, and visualize a workflow for a feature or product release. It can be used as a [Kanban](https://en.wikipedia.org/wiki/Kanban_(development)) or a [Scrum](https://en.wikipedia.org/wiki/Scrum_(software_development)) board. @@ -46,7 +46,7 @@ To learn more, visit [GitLab Enterprise features for issue boards](#gitlab-enter <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video presentation](https://youtu.be/vjccjHI7aGI) of -the Issue Board feature. +the issue board feature. ## Multiple issue boards @@ -70,7 +70,7 @@ GitLab automatically loads the last board you visited. To create a new issue board: -1. Click the dropdown with the current board name in the upper left corner of the Issue Boards page. +1. Click the dropdown with the current board name in the upper left corner of the issue boards page. 1. Click **Create new board**. 1. Enter the new board's name and select its scope: milestone, labels, assignee, or weight. @@ -78,7 +78,7 @@ To create a new issue board: To delete the currently active issue board: -1. Click the dropdown with the current board name in the upper left corner of the Issue Boards page. +1. Click the dropdown with the current board name in the upper left corner of the issue boards page. 1. Click **Delete board**. 1. Click **Delete** to confirm. @@ -195,7 +195,7 @@ card includes: ## Permissions Users with the [Reporter and higher roles](../permissions.md) can use all the functionality of the -Issue Board feature to create or delete lists. They can also drag issues from one list to another. +issue board feature to create or delete lists. They can also drag issues from one list to another. ## How GitLab orders issues in a list @@ -229,8 +229,7 @@ and vice versa. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285074) in GitLab 13.9. > - [Deployed behind a feature flag](../feature_flags.md), enabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/248908) in GitLab 14.1 -> - Recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-graphql-based-issue-boards). **(FREE SELF)** +> - [Feature flag `graphql_board_lists`](https://gitlab.com/gitlab-org/gitlab/-/issues/248908) removed in GitLab 14.3 There can be [risks when disabling released features](../../administration/feature_flags.md#risks-when-disabling-released-features). @@ -271,7 +270,7 @@ clicking **View scope**. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video presentation](https://youtu.be/m5UTNCSqaDk) of -the Configurable Issue Board feature. +the configurable issue board feature. ### Focus mode @@ -339,14 +338,14 @@ As in other list types, click the trash icon to remove a list. ### Iteration lists **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250479) in GitLab 13.11. -> - [Deployed behind the `board_new_list` and `iteration_board_lists` feature flags](../feature_flags.md), enabled by default. -> - Enabled on GitLab.com. -> - Recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to disable the feature flags: [`board_new_list`](#enable-or-disable-new-add-list-form) and [`iteration_board_lists`](#enable-or-disable-iteration-lists-in-boards). **(PREMIUM SELF)** +> - Enabled on GitLab.com and is ready for production use. +> - Enabled with `iteration_board_lists` flag for self-managed GitLab and is ready for production use. +> GitLab administrators can opt to [disable the feature flag](#enable-or-disable-iteration-lists-in-boards). -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. +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, ask an +administrator to [disable the `iteration_board_lists` flag](../../administration/feature_flags.md). +On GitLab.com, this feature is available. You're also able to create lists of an iteration. These are lists that filter issues by the assigned @@ -387,7 +386,7 @@ appears on the right. There you can see and edit the issue's: - Title - Assignees -- Epic **PREMIUM** +- Epic **(PREMIUM)** - Milestone - Time tracking value (view only) - Due date @@ -673,52 +672,8 @@ A few things to remember: by default. If you have more than 20 issues, start scrolling down and the next 20 appear. -### Enable or disable GraphQL-based issue boards **(FREE SELF)** - -NOTE: -When enabling GraphQL-based issue boards, you must also enable the -[new add list form](#enable-or-disable-new-add-list-form). - -It is deployed behind a feature flag that is **enabled by default** as of GitLab 14.1. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can disable it. - -To enable it: - -```ruby -Feature.enable(:graphql_board_lists) -``` - -To disable it: - -```ruby -Feature.disable(:graphql_board_lists) -``` - -### Enable or disable new add list form **(FREE SELF)** - -The new form for adding lists is under development but ready for production use. It is -deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can disable it. - -To enable it: - -```ruby -Feature.enable(:board_new_list) -``` - -To disable it: - -```ruby -Feature.disable(:board_new_list) -``` - ### Enable or disable iteration lists in boards **(PREMIUM SELF)** -NOTE: -When disabling iteration lists in boards, you also need to disable the [new add list form](#enable-or-disable-new-add-list-form). - The iteration list is under development but ready for production use. It is deployed behind a feature flag that is **enabled by default**. [GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md index 2b07131df6e..ed6c07f2c6d 100644 --- a/doc/user/project/issues/crosslinking_issues.md +++ b/doc/user/project/issues/crosslinking_issues.md @@ -19,14 +19,20 @@ issue itself and the first commit related to that issue. If the issue and the code you're committing are both in the same project, add `#xxx` to the commit message, where `xxx` is the issue number. -If they are not in the same project, you can add the full URL to the issue -(`https://gitlab.com/<username>/<projectname>/issues/<xxx>`). ```shell git commit -m "this is my commit message. Ref #xxx" ``` -or +If they are in different projects, but in the same group, +add `projectname#xxx` to the commit message. + +```shell +git commit -m "this is my commit message. Ref projectname#xxx" +``` + +If they are not in the same group, you can add the full URL to the issue +(`https://gitlab.com/<username>/<projectname>/issues/<xxx>`). ```shell git commit -m "this is my commit message. Related to https://gitlab.com/<username>/<projectname>/issues/<xxx>" diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 56c219eb8c3..9842b0820e6 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -43,9 +43,9 @@ To learn how the GitLab Strategic Marketing department uses GitLab issues with [ - [Cross-link issues](crosslinking_issues.md) - [Bulk edit issues](../issues/managing_issues.md) - [Sort issue lists](sorting_issue_lists.md) -- [Search for issues](../../search/index.md#filtering-issue-and-merge-request-lists) +- [Search for issues](../../search/index.md#filter-issue-and-merge-request-lists) - [Epics](../../group/epics/index.md) -- [Issue Boards](../issue_board.md) +- [Issue boards](../issue_board.md) - [Issues API](../../../api/issues.md) - [Configure an external issue tracker](../../../integration/external-issue-tracker.md) - [Parts of an issue](issue_data_and_actions.md) diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 78dc6805f2b..6bb60e5e31a 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -129,7 +129,7 @@ element. Due dates can be changed as many times as needed. ### Labels Categorize issues by giving them [labels](../labels.md). They help to organize workflows, -and they enable you to work with the [GitLab Issue Board](../issue_board.md). +and they enable you to work with the [issue board](../issue_board.md). Group Labels, which allow you to use the same labels for all projects in the same group, can also be given to issues. They work exactly the same, but are immediately diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index a2185c83f4d..7033b90b736 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -44,7 +44,7 @@ There are many ways to get to the New Issue form from a project's page:  -- From an **Issue Board**, create a new issue by clicking on the plus sign (**+**) at the top of a list. +- From an **issue board**, create a new issue by clicking on the plus sign (**+**) at the top of a list. It opens a new issue for that project, pre-labeled with its respective list.  @@ -72,7 +72,7 @@ When you're creating a new issue, these are the fields you can fill in: To visit the issue tracker for all projects in your group: 1. Go to the group dashboard. -1. In the left sidebar, select **Issues**. +1. On the left sidebar, select **Issues**. 1. In the top-right, select the **Select project to create issue** button. 1. Select the project you'd like to create an issue for. The button now reflects the selected project. @@ -237,10 +237,10 @@ using the close button:  -You can also close an issue from the [Issue Boards](../issue_board.md) by dragging an issue card +You can also close an issue from the [issue boards](../issue_board.md) by dragging an issue card from its list and dropping it into the **Closed** list. - + ### Closing issues automatically diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md index 2681a39aeb6..aed346fb504 100644 --- a/doc/user/project/issues/sorting_issue_lists.md +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -16,6 +16,7 @@ You can sort a list of issues several ways, including by: - Milestone due date - Popularity - Priority +- Title ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67234) in GitLab 14.3) - Weight The available sorting options can change based on the context of the list. diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 353ce73329e..e1149b85cd5 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -59,7 +59,7 @@ In GitLab 13.11, you can optionally replace the sharing form with a modal window To share a project after enabling this feature: 1. Go to your project's page. -1. In the left sidebar, go to **Project information > Members**, and then select **Invite a group**. +1. On the left sidebar, go to **Project information > Members**, and then select **Invite a group**. 1. Select a group, and select a **Max role**. 1. (Optional) Select an **Access expiration date**. 1. Select **Invite**. diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index 47744edd5ce..aff55419a88 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -61,7 +61,9 @@ GitLab displays one of these buttons after the body of the merge request: Eligible approvers can also use the `/approve` [quick action](../../../project/quick_actions.md) when adding a comment to -a merge request. +a merge request. [In GitLab 13.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/292936), +if a user approves a merge request and is shown in the reviewer list, a green check mark +(**{check-circle-filled}**) displays next to their name. After a merge request receives the [number and type of approvals](rules.md) you configure, it can merge unless it's blocked for another reason. Merge requests can be blocked by other problems, diff --git a/doc/user/project/merge_requests/changes.md b/doc/user/project/merge_requests/changes.md index c59d5973e21..d348c00bdc2 100644 --- a/doc/user/project/merge_requests/changes.md +++ b/doc/user/project/merge_requests/changes.md @@ -97,11 +97,8 @@ a merge request. You can choose to hide or show whitespace changes: ## Mark files as viewed -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51513) in GitLab 13.9. -> - Deployed behind a feature flag, enabled by default. -> - Enabled on GitLab.com. -> - Recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-file-views). **(FREE SELF)** +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51513) in GitLab 13.9 behind a feature flag, enabled by default. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/296674) in GitLab 14.3. When reviewing a merge request with many files multiple times, it may be useful to the reviewer to focus on new changes and ignore the files that they have already reviewed and don't want to @@ -116,25 +113,6 @@ To mark a file as viewed: Once checked, the file remains marked for that reviewer unless there are newly introduced changes to its content or the checkbox is unchecked. -### Enable or disable file views **(FREE SELF)** - -The file view feature is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to enable it for your instance. - -To enable it: - -```ruby -Feature.enable(:local_file_reviews) -``` - -To disable it: - -```ruby -Feature.disable(:local_file_reviews) -``` - ## Show merge request conflicts in diff > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232484) in GitLab 13.5. diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index a0c3efe7143..4a2319774ac 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -11,7 +11,7 @@ GitLab implements Git's powerful feature to [cherry-pick any commit](https://git-scm.com/docs/git-cherry-pick "Git cherry-pick documentation") with a **Cherry-pick** button in merge requests and commit details. -## Cherry-picking a merge request +## Cherry-pick a merge request After the merge request has been merged, a **Cherry-pick** button displays to cherry-pick the changes introduced by that merge request. @@ -25,7 +25,7 @@ where you can choose to either: - Cherry-pick the changes directly into the selected branch. - Create a new merge request with the cherry-picked changes. -### Cherry-pick tracking +### Track a cherry-pick > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2675) in GitLab 12.9. @@ -40,7 +40,7 @@ NOTE: We only track cherry-pick executed from GitLab (both UI and API). Support for tracking cherry-picked commits through the command line is tracked [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/202215). -## Cherry-picking a commit +## Cherry-pick a commit You can cherry-pick a commit from the commit details page: diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 6337fb1e87b..e9f1874eb96 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -56,11 +56,10 @@ See also the Code Climate list of [Supported Languages for Maintainability](http ## Code Quality in diff view **(ULTIMATE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267612) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.11. -> - [Deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267612) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.11, disabled by default behind the `codequality_mr_diff` [feature flag](../../../administration/feature_flags.md). > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/284140) in GitLab 13.12. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284140) in GitLab 14.1. -> - [Inline annotation added](https://gitlab.com/gitlab-org/gitlab/-/issues/2526) in GitLab 14.1. +> - [Disabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/2526) in GitLab 14.0 due to [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/334116). +> - [Inline annotation added](https://gitlab.com/gitlab-org/gitlab/-/issues/2526) and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284140) in GitLab 14.1. Changes to files in merge requests can cause Code Quality to fall if merged. In these cases, the merge request's diff view displays an indicator next to lines with new Code Quality violations. For example: @@ -276,7 +275,7 @@ might look like this example: job1: rules: - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' # Run job1 in merge request pipelines - - if: '$CI_COMMIT_BRANCH == "master"' # Run job1 in pipelines on the master branch (but not in other branch pipelines) + - if: '$CI_COMMIT_BRANCH == "main"' # Run job1 in pipelines on the main branch (but not in other branch pipelines) - if: '$CI_COMMIT_TAG' # Run job1 in pipelines for tags ``` @@ -292,7 +291,7 @@ code_quality: - if: '$CODE_QUALITY_DISABLED' when: never - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' # Run code quality job in merge request pipelines - - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH' # Run code quality job in pipelines on the master branch (but not in other branch pipelines) + - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH' # Run code quality job in pipelines on the default branch (but not in other branch pipelines) - if: '$CI_COMMIT_TAG' # Run code quality job in pipelines for tags ``` diff --git a/doc/user/project/merge_requests/fail_fast_testing.md b/doc/user/project/merge_requests/fail_fast_testing.md index 6d8a128c39f..0d87a04461b 100644 --- a/doc/user/project/merge_requests/fail_fast_testing.md +++ b/doc/user/project/merge_requests/fail_fast_testing.md @@ -45,7 +45,7 @@ This template requires: - Use [Pipelines for merge requests](../../../ci/pipelines/merge_request_pipelines.md#configure-pipelines-for-merge-requests) - [Pipelines for Merged Results](../../../ci/pipelines/pipelines_for_merged_results.md#enable-pipelines-for-merged-results) enabled in the project settings. -- A Docker image with Ruby available. The template uses `image: ruby:2.6` by default, but you [can override](../../../ci/yaml/includes.md#overriding-external-template-values) this. +- A Docker image with Ruby available. The template uses `image: ruby:2.6` by default, but you [can override](../../../ci/yaml/includes.md#override-included-configuration-values) this. ## Configuring Fast RSpec Failure diff --git a/doc/user/project/merge_requests/fast_forward_merge.md b/doc/user/project/merge_requests/fast_forward_merge.md index b1e8d761f5c..7edc379399b 100644 --- a/doc/user/project/merge_requests/fast_forward_merge.md +++ b/doc/user/project/merge_requests/fast_forward_merge.md @@ -24,9 +24,11 @@ When a fast-forward merge is not possible, the user is given the option to rebas ## Enabling fast-forward merges -1. Navigate to your project's **Settings** and search for the 'Merge method' -1. Select the **Fast-forward merge** option -1. Hit **Save changes** for the changes to take effect +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Merge requests**. +1. In the **Merge method** section, select **Fast-forward merge**. +1. Select **Save changes**. Now, when you visit the merge request page, you can accept it **only if a fast-forward merge is possible**. diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 46fc3ec141d..72fcd7f36b0 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -65,7 +65,7 @@ request's page at the top-right side: 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#perform-inline-code-reviews). +- [Perform inline code reviews](reviews/index.md). - Add [merge request dependencies](merge_request_dependencies.md) to restrict it to be merged only when other merge requests have been merged. **(PREMIUM)** - 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). @@ -166,10 +166,13 @@ is set for deletion, the merge request widget displays the ### Branch retargeting on merge **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/320902) in GitLab 13.9. -> - [Deployed behind a feature flag](../../feature_flags.md), disabled by default. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/320895) in GitLab 13.10. -> - Recommended for production use. -> - To use in GitLab self-managed instances, ask a GitLab administrator to [disable it](#enable-or-disable-branch-retargeting-on-merge). **(FREE SELF)** +> - [Disabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/320902) in GitLab 13.9. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/320895) GitLab 13.10. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, +ask an administrator to +[disable the `retarget_merge_requests` flag](../../../administration/feature_flags.md). In specific circumstances, GitLab can retarget the destination branch of open merge request, if the destination branch merges while the merge request is @@ -203,22 +206,3 @@ This improvement is [tracked as a follow-up](https://gitlab.com/gitlab-org/gitla - 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. - -### Enable or disable branch retargeting on merge **(FREE SELF)** - -Automatically retargeting merge requests is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to disable it. - -To enable it: - -```ruby -Feature.enable(:retarget_merge_requests) -``` - -To disable it: - -```ruby -Feature.disable(:retarget_merge_requests) -``` diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 6c2f07d7012..b7e055ca749 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -27,7 +27,7 @@ important parts of the merge request:  - **Overview**: Contains the description, notifications from pipelines, and a - discussion area for [comment threads](../../discussions/index.md#resolve-a-thread)) + discussion area for [comment threads](../../discussions/index.md#resolve-a-thread) and [code suggestions](reviews/suggestions.md). The right sidebar provides fields to add assignees, reviewers, labels, and a milestone to your work, and the [merge request widgets area](widgets.md) reports results from pipelines and tests. @@ -53,7 +53,7 @@ GitLab displays open merge requests, with tabs to filter the list by open and cl  -You can [search and filter](../../search/index.md#filtering-issue-and-merge-request-lists), +You can [search and filter](../../search/index.md#filter-issue-and-merge-request-lists), the results, or select a merge request to begin a review. ## Merge request sidebar @@ -76,6 +76,21 @@ can assign, categorize, and track progress on a merge request: - [**Notifications**](../../profile/notifications.md): A toggle to select whether or not to receive notifications for updates to a merge request. +## Add changes to a merge request + +If you have permission to add changes to a merge request, you can add your changes +to an existing merge request in several ways, depending on the complexity of your change and whether you need access to a development environment: + +- [Edit changes in the Web IDE](../web_ide/index.md) in your browser. Use this + browser-based method to edit multiple files, or if you are not comfortable with Git commands. + You cannot run tests from the Web IDE. +- [Edit changes in Gitpod](../../../integration/gitpod.md#launch-gitpod-in-gitlab), if you + need a fully-featured environment to both edit files, and run tests afterward. Gitpod + supports running the [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit). + To use Gitpod, you must [enable Gitpod in your user account](../../../integration/gitpod.md#enable-gitpod-in-your-user-settings). +- [Push changes from the command line](../../../gitlab-basics/start-using-git.md), if you are + familiar with Git and the command line. + ## Close a merge request If you decide to permanently stop work on a merge request, @@ -130,7 +145,7 @@ For a web developer writing a webpage for your company's website: 1. You request your web designers for their implementation. 1. You request the [approval](approvals/index.md) from your manager. 1. Once approved, your merge request is [squashed and merged](squash_and_merge.md), and [deployed to staging with GitLab Pages](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/). -1. Your production team [cherry picks](cherry_pick_changes.md) the merge commit into production. +1. Your production team [cherry-picks](cherry_pick_changes.md) the merge commit into production. ## Related topics diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index 7ea785c00ea..1d892a3c2e1 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -181,7 +181,7 @@ include: review: stage: deploy environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG url: http://$CI_ENVIRONMENT_SLUG.example.com script: - run_deploy_script diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index a798f2c9b85..e6fb619d365 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -5,12 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Reverting changes **(FREE)** +# Revert changes **(FREE)** You can use Git's powerful feature to [revert any commit](https://git-scm.com/docs/git-revert "Git revert documentation") by clicking the **Revert** button in merge requests and commit details. -## Reverting a merge request +## Revert a merge request NOTE: The **Revert** button is available only for merge requests @@ -34,7 +34,7 @@ create a new merge request with the revert changes. After the merge request has been reverted, the **Revert** button is no longer available. -## Reverting a commit +## Revert a commit You can revert a commit from the commit details page: diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index 61cd0d25aaf..dbf3b0180e6 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -12,9 +12,10 @@ type: index, reference [Merge requests](../index.md) are the primary method of making changes to files in a GitLab project. [Create and submit a merge request](../creating_merge_requests.md) -to propose changes. Your team leaves [comments](../../../discussions/index.md), and -makes [code suggestions](suggestions.md) you can accept from the user interface. -When your work is reviewed, your team members can choose to accept or reject it. +to propose changes. Your team leaves [comments](../../../discussions/index.md) on +your merge request, and makes [code suggestions](suggestions.md) you can accept +from the user interface. When your work is reviewed, your team members can choose +to accept or reject it. ## Review a merge request @@ -28,7 +29,9 @@ 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). -1. Select a line of code. In GitLab version 13.2 and later, you can [highlight a set of lines](#comment-on-multiple-lines). +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). 1. Write your first comment, and select **Start a review** below your comment:  1. Continue adding comments to lines of code, and select the appropriate button after @@ -40,7 +43,13 @@ To start your review: The comment shows the actions to perform after publication, but does not perform them until you submit your review. 1. When your review is complete, you can [submit the review](#submit-a-review). Your comments - are now visible, and any quick actions included your comments are performed. + are now visible, and any [quick actions](../../quick_actions.md) included in + your comments are performed. + +[In GitLab 13.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/292936), +if you [approve a merge request](../approvals/index.md#approve-a-merge-request) and +are shown in the reviewer list, a green check mark **{check-circle-filled}** +displays next to your name. ### Submit a review @@ -57,7 +66,7 @@ When you submit your review, GitLab: review comments attached. Replying to this email creates a new comment on the merge request. - Perform any quick actions you added to your review comments. -### Resolving/Unresolving threads +### Resolve or unresolve thread with a comment Review comments can also resolve or unresolve [resolvable threads](../../../discussions/index.md#resolve-a-thread)). When replying to a comment, a checkbox is displayed to resolve or unresolve @@ -72,7 +81,7 @@ comment itself.  -### Adding a new comment +### Add a new comment > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8225) in GitLab 13.10. @@ -97,7 +106,7 @@ This example shows reviewers and approval rules in a merge request sidebar:  -### Requesting a new review +### Request a new review > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/293933) in GitLab 13.9. @@ -112,13 +121,6 @@ the author of the merge request can request a new review from the reviewer: GitLab creates a new [to-do item](../../../todos.md) for the reviewer, and sends them a notification email. -#### Approval status - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292936) in GitLab 13.10. - -If a user in the reviewer list has approved the merge request, a green tick symbol is -shown to the right of their name. - ## Semi-linear history merge requests A merge commit is created for every merge, but the branch is only merged if @@ -130,18 +132,7 @@ succeeded, the target branch build also succeeds after the merge. 1. In the **Merge method** section, select **Merge commit with semi-linear history**. 1. Select **Save changes**. -## Perform inline code reviews - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/13950) in GitLab 11.5. - -In a merge request, you can leave comments in any part of the file being changed. -In the merge request Diff UI, you can: - -- **Comment on a single line**: Select the **{comment}** **comment** icon in the - gutter to expand the diff lines and display a comment box. -- [**Comment on multiple lines**](#comment-on-multiple-lines). - -### Comment on multiple lines +## 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. diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index 8ee068531c8..4027ec08234 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -46,7 +46,7 @@ branch. The [Developer role](../../../permissions.md) is required to do so. ## Multi-line suggestions -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53310) in GitLab 11.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53310) in GitLab 11.10. Reviewers can also suggest changes to multiple lines with a single suggestion within merge request diff threads by adjusting the range offsets. The diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 2842c084bc5..c3fc2fa871f 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -12,8 +12,6 @@ type: reference, concepts With squash and merge you can combine all your merge request's commits into one and retain a clean history. -## Overview - Squashing lets you tidy up the commit history of a branch when accepting a merge request. It applies all of the changes in the merge request as a single commit, and then merges that commit using the merge method set for the project. @@ -58,7 +56,7 @@ meaningful commit messages and: - It's simpler to [revert](revert_changes.md) if necessary. - The merged branch retains the full commit history. -## Enabling squash for a merge request +## Enable squash for a merge request Anyone who can create or edit a merge request can choose for it to be squashed on the merge request form. Users can select or clear the checkbox when they @@ -98,7 +96,7 @@ it. This is because squashing is only available when accepting a merge request, so a merge request may need to be rebased before squashing, even though squashing can itself be considered equivalent to rebasing. -## Squash Commits Options +## Squash commits options > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17613) in GitLab 13.2. > - Deployed behind a feature flag, disabled by default. diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index 1576b639a76..399d7958bbf 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -125,7 +125,7 @@ the status checks as `pending`:  -After GitLab [receives a response](../../../api/status_checks.md#set-approval-status-of-an-external-status-check) +After GitLab [receives a response](../../../api/status_checks.md#set-status-of-an-external-status-check) from the external status check, the widget updates accordingly. NOTE: diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index ce8bfa2d054..813e3c1c9ce 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -24,7 +24,8 @@ Collecting the coverage information is done via GitLab CI/CD's [artifacts reports feature](../../../ci/yaml/index.md#artifactsreports). You can specify one or more coverage reports to collect, including wildcard paths. GitLab then takes the coverage information in all the files and combines it -together. +together. Coverage files are parsed in a background job so there can be a delay +between pipeline completion and the visualization loading on the page. For the coverage analysis to work, you have to provide a properly formatted [Cobertura XML](https://cobertura.github.io/cobertura/) report to @@ -129,7 +130,7 @@ The `source` is ignored if the path does not follow this pattern. The parser ass ### JavaScript example -The following [`gitlab-ci.yml`](../../../ci/yaml/index.md) example uses [Mocha](https://mochajs.org/) +The following [`.gitlab-ci.yml`](../../../ci/yaml/index.md) example uses [Mocha](https://mochajs.org/) JavaScript testing and [nyc](https://github.com/istanbuljs/nyc) coverage-tooling to generate the coverage artifact: @@ -147,7 +148,7 @@ test: #### Maven example -The following [`gitlab-ci.yml`](../../../ci/yaml/index.md) example for Java or Kotlin uses [Maven](https://maven.apache.org/) +The following [`.gitlab-ci.yml`](../../../ci/yaml/index.md) example for Java or Kotlin uses [Maven](https://maven.apache.org/) to build the project and [JaCoCo](https://www.eclemma.org/jacoco/) coverage-tooling to generate the coverage artifact. You can check the [Docker image configuration and scripts](https://gitlab.com/haynes/jacoco2cobertura) if you want to build your own image. @@ -185,7 +186,7 @@ coverage-jdk11: #### Gradle example -The following [`gitlab-ci.yml`](../../../ci/yaml/index.md) example for Java or Kotlin uses [Gradle](https://gradle.org/) +The following [`.gitlab-ci.yml`](../../../ci/yaml/index.md) example for Java or Kotlin uses [Gradle](https://gradle.org/) to build the project and [JaCoCo](https://www.eclemma.org/jacoco/) coverage-tooling to generate the coverage artifact. You can check the [Docker image configuration and scripts](https://gitlab.com/haynes/jacoco2cobertura) if you want to build your own image. @@ -223,7 +224,7 @@ coverage-jdk11: ### Python example -The following [`gitlab-ci.yml`](../../../ci/yaml/index.md) example for Python uses [pytest-cov](https://pytest-cov.readthedocs.io/) to collect test coverage data and [coverage.py](https://coverage.readthedocs.io/) to convert the report to use full relative paths. +The following [`.gitlab-ci.yml`](../../../ci/yaml/index.md) example for Python uses [pytest-cov](https://pytest-cov.readthedocs.io/) to collect test coverage data and [coverage.py](https://coverage.readthedocs.io/) to convert the report to use full relative paths. The information isn't displayed without the conversion. This example assumes that the code for your package is in `src/` and your tests are in `tests.py`: @@ -243,7 +244,7 @@ run tests: ### C/C++ example -The following [`gitlab-ci.yml`](../../../ci/yaml/index.md) example for C/C++ with +The following [`.gitlab-ci.yml`](../../../ci/yaml/index.md) example for C/C++ with `gcc` or `g++` as the compiler uses [`gcovr`](https://gcovr.com/en/stable/) to generate the coverage output file in Cobertura XML format. diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 1d196de36e2..3922ee4d770 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -1,6 +1,6 @@ --- -stage: none -group: unassigned +stage: Create +group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 5a688fbb485..385a4fafa7d 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -46,7 +46,7 @@ To create a GitLab Pages website: | Document | Description | | -------- | ----------- | -| [Create a `gitlab-ci.yml` file from scratch](getting_started/pages_from_scratch.md) | Add a Pages site to an existing project. Learn how to create and configure your own CI file. | +| [Create a `.gitlab-ci.yml` file from scratch](getting_started/pages_from_scratch.md) | Add a Pages site to an existing project. Learn how to create and configure your own CI file. | | [Use a `.gitlab-ci.yml` template](getting_started/pages_ci_cd_template.md) | Add a Pages site to an existing project. Use a pre-populated CI template file. | | [Fork a sample project](getting_started/pages_forked_sample_project.md) | Create a new project with Pages already configured by forking a sample project. | | [Use a project template](getting_started/pages_new_project_template.md) | Create a new project with Pages already configured by using a template. | diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index 532a36b2327..4b4d479e3e9 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -52,6 +52,6 @@ To sign out of your GitLab Pages website, revoke the application access token for GitLab Pages: 1. In the top menu, select your profile, and then select **Settings**. -1. In the left sidebar, select **Applications**. +1. On the left sidebar, select **Applications**. 1. Scroll to the **Authorized applications** section, find the **GitLab Pages** entry, and select its **Revoke** button. diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md index 8ed6f214605..3deea92f56e 100644 --- a/doc/user/project/pages/redirects.md +++ b/doc/user/project/pages/redirects.md @@ -9,62 +9,58 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/24) in GitLab Pages 1.25.0 and GitLab 13.4 behind a feature flag, disabled by default. > - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/367) in GitLab 13.5. -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - In GitLab Pages, you can configure rules to forward one URL to another using [Netlify style](https://docs.netlify.com/routing/redirects/#syntax-for-the-redirects-file) HTTP redirects. -## Supported features - -GitLab Pages only supports the -[`_redirects` plain text file syntax](https://docs.netlify.com/routing/redirects/#syntax-for-the-redirects-file), -and `.toml` files are not supported. - -Redirects are only supported at a basic level. GitLab Pages doesn't support all -[special options offered by Netlify](https://docs.netlify.com/routing/redirects/redirect-options/). - -Note that supported paths must start with a forward slash `/`. +Not all +[special options offered by Netlify](https://docs.netlify.com/routing/redirects/redirect-options/) +are supported. | Feature | Supported | Example | | ------- | --------- | ------- | -| Redirects (`301`, `302`) | **{check-circle}** Yes | `/wardrobe.html /narnia.html 302` -| Rewrites (other status codes) | **{dotted-circle}** No | `/en/* /en/404.html 404` | -| [Splats](https://docs.netlify.com/routing/redirects/redirect-options/#splats) | **{dotted-circle}** No | `/news/* /blog/:splat` | -| Placeholders | **{dotted-circle}** No | `/news/:year/:month/:date/:slug /blog/:year/:month/:date/:slug` | +| [Redirects (`301`, `302`)](#redirects) | **{check-circle}** Yes | `/wardrobe.html /narnia.html 302` +| [Rewrites (`200`)](#rewrites) | **{check-circle}** Yes | `/* / 200` | +| [Splats](#splats) | **{check-circle}** Yes | `/news/* /blog/:splat` | +| [Placeholders](#placeholders) | **{check-circle}** Yes | `/news/:year/:month/:date /blog-:year-:month-:date.html` | +| Rewrites (other than `200`) | **{dotted-circle}** No | `/en/* /en/404.html 404` | | Query parameters | **{dotted-circle}** No | `/store id=:id /blog/:id 301` | | Force ([shadowing](https://docs.netlify.com/routing/redirects/rewrites-proxies/#shadowing)) | **{dotted-circle}** No | `/app/ /app/index.html 200!` | | Domain-level redirects | **{dotted-circle}** No | `http://blog.example.com/* https://www.example.com/blog/:splat 301` | | Redirect by country or language | **{dotted-circle}** No | `/ /anz 302 Country=au,nz` | | Redirect by role | **{dotted-circle}** No | `/admin/* 200! Role=admin` | +NOTE: +The [matching behavior test cases](https://gitlab.com/gitlab-org/gitlab-pages/-/blob/master/internal/redirects/matching_test.go) +are a good resource for understanding how GitLab implements rule matching in +detail. Community contributions are welcome for any edge cases that aren't included in +this test suite! + ## Create redirects -To create redirects, -create a configuration file named `_redirects` in the `public/` directory of your -GitLab Pages site. +To create redirects, create a configuration file named `_redirects` in the +`public/` directory of your GitLab Pages site. -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: +Note that: -```plaintext -/projectname/redirect-portal.html /projectname/magic-land.html 301 -/projectname/cake-portal.html /projectname/still-alive.html 302 -/projectname/wardrobe.html /projectname/narnia.html 302 -/projectname/pit.html /projectname/spikes.html 302 -``` +- 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 of 64KB and a maximum of 1,000 rules per project. + Only the first 1,000 rules are processed. +- 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: -If your GitLab Pages site uses [custom domains](custom_domains_ssl_tls_certification/index.md), -no project name prefix is needed. For example, if your custom domain is `example.com`, -your `_redirect` file would look like: + ```plaintext + /projectname/wardrobe.html /projectname/narnia.html 302 + ``` -```plaintext -/redirect-portal.html /magic-land.html 301 -/cake-portal.html /still-alive.html 302 -/wardrobe.html /narnia.html 302 -/pit.html /spikes.html 302 -``` +- If your GitLab Pages site uses [custom domains](custom_domains_ssl_tls_certification/index.md), + no project name prefix is needed. For example, if your custom domain is `example.com`, + your `_redirects` file would look like: + + ```plaintext + /wardrobe.html /narnia.html 302 + ``` ## Files override redirects @@ -81,6 +77,132 @@ GitLab doesn't support Netlify's [force option](https://docs.netlify.com/routing/redirects/rewrites-proxies/#shadowing) to change this behavior. +## HTTP status codes + +A default status code of `301` is applied if no status code is provided, but +you can explicitly set your own. The following HTTP codes are supported: + +- **301**: Permanent redirect. +- **302**: Temporary redirect. +- **200**: Standard response for successful HTTP requests. Pages + serves the content in the `to` rule if it exists, without changing the URL in + the address bar. + +## Redirects + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/458) in GitLab 14.3. +> - Enabled on GitLab.com. +> - Enabled by default in self-managed GitLab behind the [`FF_ENABLE_REDIRECTS` feature flag](#feature-flag-for-redirects). + +To create a redirect, add a rule that includes a `from` path, a `to` path, +and an [HTTP status code](#http-status-codes): + +```plaintext +# 301 permanent redirect +/old/file.html /new/file.html 301 + +# 302 temporary redirect +/old/another_file.html /new/another_file.html 302 +``` + +## Rewrites + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/458) in GitLab 14.3. +> - Enabled on GitLab.com. +> - Disabled by default in self-managed GitLab behind the [`FF_ENABLE_PLACEHOLDERS` feature flag](#feature-flag-for-rewrites). + +Provide a status code of `200` to serve the content of the `to` path when the +request matches the `from`: + +```plaintext +/old/file.html /new/file.html 200 +``` + +This status code can be used in combination with [splat rules](#splats) to dynamically +rewrite the URL. + +## Splats + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/458) in GitLab 14.3. + +A rule with an asterisk (`*`) in its `from` path, known as a splat, matches +anything at the start, middle, or end of the requested path. This example +matches anything after `/old/` and rewrites it to `/new/file.html`: + +```plaintext +/old/* /new/file.html 200 +``` + +### Splat placeholders + +The content matched by a `*` in a rule's `from` path can be injected into the +`to` path using the `:splat` placeholder: + +```plaintext +/old/* /new/:splat 200 +``` + +In this example, a request to `/old/file.html` serves the contents of `/new/file.html` +with a `200` status code. + +If a rule's `from` path includes multiple splats, the value of the first splat +match replaces any `:splat`s in the `to` path. + +### Splat matching behavior + +Splats are "greedy" and match as many characters as possible: + +```plaintext +/old/*/file /new/:splat/file 301 +``` + +In this example, the rule redirects `/old/a/b/c/file` to `/new/a/b/c/file`. + +Splats also match empty strings, so the previous rule redirects +`/old/file` to `/new/file`. + +### Rewrite all requests to a root `index.html` + +Single page applications (SPAs) often perform their own routing using +client-side routes. For these applications, it's important that _all_ requests +are rewritten to the root `index.html` so that the routing logic can be handled +by the JavaScript application. You can do this with a `_redirects` +rule like: + +```plaintext +/* /index.html 200 +``` + +## Placeholders + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/458) in GitLab 14.3. + +Use placeholders in rules to match portions of the requested URL and use these +matches when rewriting or redirecting to a new URL. + +A placehold is formatted as a `:` character followed by a string of letters +(`[a-zA-Z]+`) in both the `from` and `to` paths: + +```plaintext +/news/:year/:month/:date/:slug /blog/:year-:month-:date-:slug 200 +``` + +This rule instructs Pages to respond to a request for `/news/2021/08/12/file.html` by +serving the content of `/blog/2021-08-12-file.html` with a `200`. + +### Placeholder matching behavior + +Compared to [splats](#splats), placeholders are more limited in how much content +they match. Placeholders match text between forward slashes +(`/`), so use placeholders to match single path segments. + +In addition, placeholders do not match empty strings. A rule like the following +would **not** match a request URL like `/old/file`: + +```plaintext +/old/:path /new/:path +``` + ## Debug redirect rules If a redirect isn't working as expected, or you want to check your redirect syntax, visit @@ -103,8 +225,49 @@ rule 10: valid rule 11: valid ``` -## Disable redirects +## Differences from Netlify's implementation + +Most supported `_redirects` rules behave the same in both GitLab and Netlify. +However, there are some minor differences: + +- **All rule URLs must begin with a slash:** + + Netlify does not require URLs to begin with a forward slash: + + ```plaintext + # Valid in Netlify, invalid in GitLab + */path /new/path 200 + ``` + + GitLab validates that all URLs begin with a forward slash. A valid + equivalent of the previous example: + + ```plaintext + # Valid in both Netlify and GitLab + /old/path /new/path 200 + ``` +- **All placeholder values are populated:** + + Netlify only populates placeholder values that appear in the `to` path: + + ```plaintext + /old /new/:placeholder + ``` + + Given a request to `/old`: + + - Netlify redirects to `/new/:placeholder` (with a + literal `:placeholder`). + - GitLab redirects to `/new/`. + +## Features behind feature flags + +Some Pages features are behind feature flags. + +### Feature flag for redirects + +FLAG: Redirects in GitLab Pages is under development, and is deployed behind a feature flag that is **enabled by default**. @@ -126,3 +289,28 @@ For [source installations](../../../administration/pages/source.md), define the export FF_ENABLE_REDIRECTS="false" /path/to/pages/bin/gitlab-pages -config gitlab-pages.conf ``` + +### Feature flag for rewrites + +FLAG: +Rewrites in GitLab Pages is under development, and is deployed behind a feature flag +that is **disabled by default**. + +To enable rewrites, for [Omnibus installations](../../../administration/pages/index.md), define the +`FF_ENABLE_PLACEHOLDERS` environment variable in the +[global settings](../../../administration/pages/index.md#global-settings). +Add the following line to `/etc/gitlab/gitlab.rb` and +[reconfigure the instance](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure): + +```ruby +gitlab_pages['env']['FF_ENABLE_PLACEHOLDERS'] = 'true' +``` + +For [source installations](../../../administration/pages/source.md), define the +`FF_ENABLE_PLACEHOLDERS` environment variable, then +[restart GitLab](../../../administration/restart_gitlab.md#installations-from-source): + +```shell +export FF_ENABLE_PLACEHOLDERS="true" +/path/to/pages/bin/gitlab-pages -config gitlab-pages.conf +``` diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 683496b4a9b..52b59d70302 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -103,6 +103,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/target_branch <local branch name>` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set target branch. | | `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. | | `/todo` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add a to-do item. | +| `/unapprove` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Unapprove the merge request. ([introduced in GitLab 14.3](https://gitlab.com/gitlab-org/gitlab/-/issues/8003)| | `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific assignees. | | `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all assignees. | | `/unassign_reviewer @user1 @user2` or `/remove_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific reviewers. | diff --git a/doc/user/project/releases/img/deploy_freeze_v13_10.png b/doc/user/project/releases/img/deploy_freeze_v13_10.png Binary files differdeleted file mode 100644 index 5c4b2d983dd..00000000000 --- a/doc/user/project/releases/img/deploy_freeze_v13_10.png +++ /dev/null diff --git a/doc/user/project/releases/img/deploy_freeze_v14_3.png b/doc/user/project/releases/img/deploy_freeze_v14_3.png Binary files differnew file mode 100644 index 00000000000..13580ac1576 --- /dev/null +++ b/doc/user/project/releases/img/deploy_freeze_v14_3.png diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 76b300bdd57..49b5ec2ca60 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -186,7 +186,8 @@ To subscribe to notifications for releases: ## Prevent unintentional releases by setting a deploy freeze -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29382) in GitLab 13.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29382) in GitLab 13.0. +> - The ability to delete freeze periods through the UI was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212451) in GitLab 14.3. Prevent unintended production releases during a period of time you specify by setting a [*deploy freeze* period](../../../ci/environments/deployment_safety.md). @@ -199,7 +200,7 @@ If the job that's executing is within a freeze period, GitLab CI/CD creates an e variable named `$CI_DEPLOY_FREEZE`. To prevent the deployment job from executing, create a `rules` entry in your -`gitlab-ci.yml`, for example: +`.gitlab-ci.yml`, for example: ```yaml deploy_to_production: @@ -219,11 +220,8 @@ To set a deploy freeze window in the UI, complete these steps: 1. Click **Add deploy freeze** to open the deploy freeze modal. 1. Enter the start time, end time, and timezone of the desired deploy freeze period. 1. Click **Add deploy freeze** in the modal. -1. After the deploy freeze is saved, you can edit it by selecting the edit button (**{pencil}**). -  - -WARNING: -To delete a deploy freeze, use the [Freeze Periods API](../../../api/freeze_periods.md). +1. After the deploy freeze is saved, you can edit it by selecting the edit button (**{pencil}**) and remove it by selecting the delete button (**{remove}**). +  If a project contains multiple freeze periods, all periods apply. If they overlap, the freeze covers the complete overlapping period. @@ -394,9 +392,9 @@ upload: - if: $CI_COMMIT_TAG script: - | - curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" --upload-file bin/${DARWIN_AMD64_BINARY} ${PACKAGE_REGISTRY_URL}/${DARWIN_AMD64_BINARY} + curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" --upload-file bin/${DARWIN_AMD64_BINARY} "${PACKAGE_REGISTRY_URL}/${DARWIN_AMD64_BINARY}" - | - curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" --upload-file bin/${LINUX_AMD64_BINARY} ${PACKAGE_REGISTRY_URL}/${LINUX_AMD64_BINARY} + curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" --upload-file bin/${LINUX_AMD64_BINARY} "${PACKAGE_REGISTRY_URL}/${LINUX_AMD64_BINARY}" release: # Caution, as of 2021-02-02 these assets links require a login, see: diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index 12fd7389f21..a1ea929bb49 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -37,7 +37,7 @@ the [Git commands you need](#update-the-default-branch-name-in-your-repository) To update the default branch name for an individual [project](../../index.md): -1. Sign in to GitLab as a user with the [Administrator](../../../permissions.md) role. +1. Sign in to GitLab with at least the [Maintainer](../../../permissions.md) role. 1. In the left navigation menu, go to **Settings > Repository**. 1. Expand **Default branch**, and select a new default branch. 1. (Optional) Select the **Auto-close referenced issues on default branch** checkbox to close @@ -63,8 +63,8 @@ GitLab [administrators](../../../permissions.md) of self-managed instances can customize the initial branch for projects hosted on that instance. Individual groups and subgroups can override this instance-wide setting for their projects. -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Repository**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Repository**. 1. Expand **Default initial branch name**. 1. Change the default initial branch to a custom name of your choice. 1. Select **Save changes**. @@ -77,7 +77,7 @@ overrides it. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221014) in GitLab 13.6. -Administrators of groups and subgroups can configure the default branch name for a group: +Users with at least the Owner role of groups and subgroups can configure the default branch name for a group: 1. Go to the group **Settings > Repository**. 1. Expand **Default initial branch name**. @@ -128,8 +128,8 @@ renames a Git repository's (`example`) default branch. git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main ``` -1. Sign in to GitLab as an [administrator](../../../permissions.md) and follow - the instructions to +1. Sign in to GitLab with at least the [Maintainer](../../../permissions.md) + role and follow the instructions to [change the default branch for this project](#change-the-default-branch-name-for-a-project). Select `main` as your new default branch. 1. Protect your new `main` branch as described in the [protected branches documentation](../../protected_branches.md). diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index c41b3ed8615..23d7aecc960 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -19,6 +19,11 @@ NOTE: The term GPG is used for all OpenPGP/PGP/GPG related material and implementations. +To view a user's public GPG key, you can: + +- Go to `https://gitlab.example.com/<username>.gpg`. +- Select **View public GPG keys** (**{key}**) in the top right of the user's profile. + GPG verified tags are not supported yet. See the [further reading](#further-reading) section for more details on GPG. @@ -150,7 +155,7 @@ You can add a GPG key in your user settings: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **GPG Keys**. +1. On the left sidebar, select **GPG Keys**. 1. Paste your _public_ key in the **Key** text box.  @@ -248,7 +253,7 @@ To revoke a GPG key: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **GPG Keys**. +1. On the left sidebar, select **GPG Keys**. 1. Select **Revoke** next to the GPG key you want to delete. ## Removing a GPG key @@ -262,7 +267,7 @@ To remove a GPG key from your account: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **GPG Keys**. +1. On the left sidebar, select **GPG Keys**. 1. Select the trash icon (**{remove}**) next to the GPG key you want to delete. ## Rejecting commits that are not signed **(PREMIUM)** diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index afdcf2a94fa..de7459e6278 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -34,7 +34,7 @@ You can [commit your changes](https://git-scm.com/book/en/v2/Git-Basics-Recordin to a branch in the repository. When you use the command line, you can commit multiple times before you push. - **Commit message:** - A commit message identities what is being changed and why. + A commit message identifies what is being changed and why. In GitLab, you can add keywords to the commit message to perform one of the following actions: - **Trigger a GitLab CI/CD pipeline:** @@ -50,10 +50,10 @@ to a branch in the repository. When you use the command line, you can commit mul on their respective thread. - **Cherry-pick a commit:** In GitLab, you can - [cherry-pick a commit](../merge_requests/cherry_pick_changes.md#cherry-picking-a-commit) + [cherry-pick a commit](../merge_requests/cherry_pick_changes.md#cherry-pick-a-commit) from the UI. - **Revert a commit:** - [Revert a commit](../merge_requests/revert_changes.md#reverting-a-commit) + [Revert a commit](../merge_requests/revert_changes.md#revert-a-commit) from the UI to a selected branch. - **Sign a commit:** Use GPG to [sign your commits](gpg_signed_commits/index.md). diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index 76eae58b431..5a02a35fce1 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -223,13 +223,15 @@ If a repository you're interested in is located on a different server, and you w to browse its content and its activity using the GitLab interface, you can configure mirror pulling: -1. If you [configured two-factor authentication (2FA)](https://docs.github.com/en/github/authenticating-to-github/securing-your-account-with-two-factor-authentication-2fa) - for GitHub, create a [personal access token for GitHub](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) - with the `read_repository` scope. If 2FA is enabled, this personal access +1. If your remote repository is on GitHub and you have + [two-factor authentication (2FA) configured](https://docs.github.com/en/github/authenticating-to-github/securing-your-account-with-two-factor-authentication-2fa), + create a [personal access token for GitHub](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token). + with the `repo` scope. If 2FA is enabled, this personal access token serves as your GitHub password. 1. In your project, go to **Settings > Repository**, and then expand the **Mirroring repositories** section. -1. In the **Git repository URL** field, enter a repository URL. +1. In the **Git repository URL** field, enter a repository URL. Include the username + in the URL if required: `https://MYUSERNAME@github.com/group/PROJECTNAME.git` 1. In the **Mirror direction** dropdown, select **Pull**. 1. In the **Authentication method** dropdown, select your authentication method. 1. Select from the following checkboxes, if needed: @@ -611,7 +613,7 @@ If you receive this error after creating a new project using Check if the repository owner is specified in the URL of your mirrored repository: 1. Go to your project. -1. In the left sidebar, select **Settings > Repository**. +1. On the left sidebar, select **Settings > Repository**. 1. Select **Mirroring repositories**. 1. If no repository owner is specified, delete and add the URL again in this format: diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index 7c115734345..17031dd29af 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -5,72 +5,82 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: concepts, howto --- -# Signing commits and tags with X.509 **(FREE)** +# Sign commits and tags with X.509 certificates **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17773) in GitLab 12.8. [X.509](https://en.wikipedia.org/wiki/X.509) is a standard format for public key certificates issued by a public or private Public Key Infrastructure (PKI). Personal X.509 certificates are used for authentication or signing purposes -such as SMIME, but Git also supports signing of commits and tags -with X.509 certificates in a similar way as with [GPG](../gpg_signed_commits/index.md). -The main difference is the trust anchor which is the PKI for X.509 certificates -instead of a web of trust with GPG. - -## How GitLab handles X.509 - -GitLab uses its own certificate store and therefore defines the trust chain. - +such as S/MIME (Secure/Multipurpose Internet Mail Extensions). +However, Git also supports signing of commits and tags with X.509 certificates in a +similar way as with [GPG (GnuPG, or GNU Privacy Guard)](../gpg_signed_commits/index.md). +The main difference is the way GitLab determines whether or not the developer's signature is trusted: + +- For X.509, a root certificate authority is added to the GitLab trust store. + (A trust store is a repository of trusted security certificates.) Combined with + any required intermediate certificates in the signature, the developer's certificate + can be chained back to a trusted root certificate. +- For GPG, developers [add their GPG key](../gpg_signed_commits/index.md#adding-a-gpg-key-to-your-account) + to their account. + +GitLab uses its own certificate store and therefore defines the +[trust chain](https://www.ssl.com/faqs/what-is-a-chain-of-trust/). For a commit or tag to be *verified* by GitLab: -- The signing certificate email must match a verified email address used by the committer in GitLab. -- The Certificate Authority has to be trusted by the GitLab instance, see also - [Omnibus install custom public certificates](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). -- The signing time has to be within the time range of the [certificate validity](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.1.2.5) +- The signing certificate email must match a verified email address in GitLab. +- The GitLab instance must be able to establish a full [trust chain](https://www.ssl.com/faqs/what-is-a-chain-of-trust/) + from the certificate in the signature to a trusted certificate in the GitLab certificate store. + This chain may include intermediate certificates supplied in the signature. You may + need to add certificates, such as Certificate Authority root certificates, + [to the GitLab certificate store](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). +- The signing time must be in the time range of the + [certificate validity](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.1.2.5), which is usually up to three years. -- The signing time is equal or later than commit time. - -NOTE: -Certificate revocation lists are checked on a daily basis via background worker. +- The signing time is equal to, or later than, the commit time. -NOTE: -Self signed certificates without `authorityKeyIdentifier`, -`subjectKeyIdentifier`, and `crlDistributionPoints` are not supported. We -recommend using certificates from a PKI that are in line with -[RFC 5280](https://tools.ietf.org/html/rfc5280). +If a commit's status has already been determined and stored in the database, +use the Rake task [to re-check the status](../../../../raketasks/x509_signatures.md). +Refer to the [Troubleshooting section](#troubleshooting). +GitLab checks certificate revocation lists on a daily basis with a background worker. ## Limitations +- Self-signed certificates without `authorityKeyIdentifier`, + `subjectKeyIdentifier`, and `crlDistributionPoints` are not supported. We + recommend using certificates from a PKI that are in line with + [RFC 5280](https://tools.ietf.org/html/rfc5280). - If you have more than one email in the Subject Alternative Name list in your signing certificate, [only the first one is used to verify commits](https://gitlab.com/gitlab-org/gitlab/-/issues/336677). - The `X509v3 Subject Key Identifier` (SKI) in the issuer certificate and the signing certificate [must be 40 characters long](https://gitlab.com/gitlab-org/gitlab/-/issues/332503). - If your SKI is shorter, commits will not show as verified in GitLab, and + If your SKI is shorter, commits don't show as verified in GitLab, and short subject key identifiers may also [cause errors when accessing the project](https://gitlab.com/gitlab-org/gitlab/-/issues/332464), such as 'An error occurred while loading commit signatures' and `HTTP 422 Unprocessable Entity` errors. -## Obtaining an X.509 key pair +## Configure for signed commits -If your organization has Public Key Infrastructure (PKI), that PKI provides -an S/MIME key. +To sign your commits, tags, or both, you must: -If you do not have an S/MIME key pair from a PKI, you can either create your -own self-signed one, or purchase one. MozillaZine keeps a nice collection -of [S/MIME-capable signing authorities](http://kb.mozillazine.org/Getting_an_SMIME_certificate) -and some of them generate keys for free. +1. [Obtain an X.509 key pair](#obtain-an-x509-key-pair). +1. [Associate your X.509 certificate with Git](#associate-your-x509-certificate-with-git). +1. [Sign and verify commits](#sign-and-verify-commits). +1. [Sign and verify tags](#sign-and-verify-tags). -## Associating your X.509 certificate with Git +### Obtain an X.509 key pair -To take advantage of X.509 signing, you need Git 2.19.0 or later. You can -check your Git version with: +If your organization has Public Key Infrastructure (PKI), that PKI provides +an S/MIME key. If you do not have an S/MIME key pair from a PKI, you can either +create your own self-signed pair, or purchase a pair. -```shell -git --version -``` +### Associate your X.509 certificate with Git + +To take advantage of X.509 signing, you need Git 2.19.0 or later. You can +check your Git version with the command `git --version`. If you have the correct version, you can proceed to configure Git. @@ -84,71 +94,267 @@ git config --global user.signingkey $signingkey git config --global gpg.format x509 ``` -### Windows and MacOS +#### Windows and macOS -Install [S/MIME Sign](https://github.com/github/smimesign) by downloading the -installer or via `brew install smimesign` on MacOS. +To configure Windows or macOS: -Get the ID of your certificate with `smimesign --list-keys` and set your -signing key `git config --global user.signingkey ID`, then configure X.509: +1. Install [S/MIME Sign](https://github.com/github/smimesign) by either: + - Downloading the installer. + - Running `brew install smimesign` on macOS. +1. Get the ID of your certificate by running `smimesign --list-keys`. +1. Set your signing key by running `git config --global user.signingkey ID`. +1. Configure X.509 with this command: -```shell -git config --global gpg.x509.program smimesign -git config --global gpg.format x509 -``` + ```shell + git config --global gpg.x509.program smimesign + git config --global gpg.format x509 + ``` -## Signing commits +### Sign and verify commits -After you have [associated your X.509 certificate with Git](#associating-your-x509-certificate-with-git) you -can start signing your commits: +After you have [associated your X.509 certificate with Git](#associate-your-x509-certificate-with-git) you +can sign your commits: -1. Commit like you used to, the only difference is the addition of the `-S` flag: +1. When you create a Git commit, add the `-S` flag: ```shell git commit -S -m "feat: x509 signed commits" ``` -1. Push to GitLab and check that your commits [are verified](#verifying-commits). +1. Push to GitLab, and check that your commits are verified with the `--show-signature` flag: -If you don't want to type the `-S` flag every time you commit, you can tell Git -to sign your commits automatically: - -```shell -git config --global commit.gpgsign true -``` - -## Verifying commits + ```shell + git log --show-signature + ``` -To verify that a commit is signed, you can use the `--show-signature` flag: +1. *If you don't want to type the `-S` flag every time you commit,* run this command + for Git to sign your commits every time: -```shell -git log --show-signature -``` + ```shell + git config --global commit.gpgsign true + ``` -## Signing tags +### Sign and verify tags -After you have [associated your X.509 certificate with Git](#associating-your-x509-certificate-with-git) you +After you have [associated your X.509 certificate with Git](#associate-your-x509-certificate-with-git) you can start signing your tags: -1. Tag like you used to, the only difference is the addition of the `-s` flag: +1. When you create a Git tag, add the `-s` flag: ```shell git tag -s v1.1.1 -m "My signed tag" ``` -1. Push to GitLab and check that your tags [are verified](#verifying-tags). +1. Push to GitLab and verify your tags are signed with this command: + + ```shell + git tag --verify v1.1.1 + ``` + +1. *If you don't want to type the `-s` flag every time you tag,* run this command + for Git to sign your tags each time: -If you don't want to type the `-s` flag every time you tag, you can tell Git -to sign your tags automatically: + ```shell + git config --global tag.gpgsign true + ``` -```shell -git config --global tag.gpgsign true -``` +## Resources -## Verifying tags +- [Rake task for X.509 signatures](../../../../raketasks/x509_signatures.md) -To verify that a tag is signed, you can use the `--verify` flag: +## Troubleshooting + +### Re-verify commits + +GitLab stores the status of any checked commits in the database. You can use a +Rake task to [check the status of any previously checked commits](../../../../raketasks/x509_signatures.md). + +After you make any changes, run this command: ```shell -git tag --verify v1.1.1 +sudo gitlab-rake gitlab:x509:update_signatures ``` + +### Main verification checks + +The code performs +[these key checks](https://gitlab.com/gitlab-org/gitlab/-/blob/v14.1.0-ee/lib/gitlab/x509/signature.rb#L33), +which all must return `verified`: + +- `x509_certificate.nil?` should be false. +- `x509_certificate.revoked?` should be false. +- `verified_signature` should be true. +- `user.nil?` should be false. +- `user.verified_emails.include?(@email)` should be true. +- `certificate_email == @email` should be true. + +To investigate why a commit shows as `Unverified`: + +1. [Start a Rails console](../../../../administration/operations/rails_console.md#starting-a-rails-console-session): + + ```shell + sudo gitlab-rails console + ``` + +1. Identify the project (either by path or ID) and full commit SHA that you're investigating. + Use this information to create `signature` to run other checks against: + + ```ruby + project = Project.find_by_full_path('group/subgroup/project') + project = Project.find_by_id('121') + commit = project.repository.commit_by(oid: '87fdbd0f9382781442053b0b76da729344e37653') + signedcommit=Gitlab::X509::Commit.new(commit) + signature=Gitlab::X509::Signature.new(signedcommit.signature_text, signedcommit.signed_text, commit.committer_email, commit.created_at) + ``` + + If you make changes to address issues identified running through the checks, restart the + Rails console and run though the checks again from the start. + +1. Check the certificate on the commit: + + ```ruby + signature.x509_certificate.nil? + signature.x509_certificate.revoked? + ``` + + Both checks should return `false`: + + ```ruby + > signature.x509_certificate.nil? + => false + > signature.x509_certificate.revoked? + => false + ``` + + A [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/332503) causes + these checks to fail with `Validation failed: Subject key identifier is invalid`. + +1. Run a cryptographic check on the signature. The code must return `true`: + + ```ruby + signature.verified_signature + ``` + + If it returns `false` then [investigate this check further](#cryptographic-verification-checks). + +1. Confirm the email addresses match on the commit and the signature: + + - The Rails console displays the email addresses being compared. + - The final command must return `true`: + + ```ruby + sigemail=signature.__send__:certificate_email + commitemail=commit.committer_email + sigemail == commitemail + ``` + + A [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/336677) exists: + only the first email in the `Subject Alternative Name` list is compared. To + display the `Subject Alternative Name` list, run: + + ```ruby + signature.__send__ :get_certificate_extension,'subjectAltName' + ``` + + If the developer's email address is not the first one in the list, this check + fails, and the commit is marked `unverified`. + +1. The email address on the commit must be associated with an account in GitLab. + This check should return `false`: + + ```ruby + signature.user.nil? + ``` + +1. Check the email address is associated with a user in GitLab. This check should + return a user, such as `#<User id:1234 @user_handle>`: + + ```ruby + User.find_by_any_email(commit.committer_email) + ``` + + If it returns `nil`, the email address is not associated with a user, and the check fails. + +1. Confirm the developer's email address is verified. This check must return true: + + ```ruby + signature.user.verified_emails.include?(commit.committer_email) + ``` + + If the previous check returned `nil`, this command displays an error: + + ```plaintext + NoMethodError (undefined method `verified_emails' for nil:NilClass) + ``` + +1. The verification status is stored in the database. To display the database record: + + ```ruby + pp X509CommitSignature.by_commit_sha(commit.sha);nil + ``` + + If all the previous checks returned the correct values: + + - `verification_status: "unverified"` indicates the database record needs + updating. [Use the Rake task](#re-verify-commits). + + - `[]` indicates the database doesn't have a record yet. Locate the commit + in GitLab to check the signature and store the result. + +#### Cryptographic verification checks + +If GitLab determines that `verified_signature` is `false`, investigate the reason +in the Rails console. These checks require `signature` to exist. Refer to the `signature` +step of the previous [main verification checks](#main-verification-checks). + +1. Check the signature, without checking the issuer, returns `true`: + + ```ruby + signature.__send__ :valid_signature? + ``` + +1. Check the signing time and date. This check must return `true`: + + ```ruby + signature.__send__ :valid_signing_time? + ``` + + - The code allows for code signing certificates to expire. + - A commit must be signed during the validity period of the certificate, + and at or after the commit's datestamp. Display the commit time and + certificate details including `not_before`, `not_after` with: + + ```ruby + commit.created_at + pp signature.__send__ :cert; nil + ``` + +1. Check the signature, including that TLS trust can be established. This check must return `true`: + + ```ruby + signature.__send__(:p7).verify([], signature.__send__(:cert_store), signature.__send__(:signed_text)) + ``` + + 1. If this fails, add the missing certificate(s) required to establish trust + [to the GitLab certificate store](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). + + 1. After adding more certificates, (if these troubleshooting steps then pass) + run the Rake task to [re-verify commits](#re-verify-commits). + + 1. Display the certificates, including in the signature: + + ```ruby + pp signature.__send__(:p7).certificates ; nil + ``` + +Ensure any additional intermediate certificate(s) and the root certificate are added +to the certificate store. For consistency with how certificate chains are built on +web servers: + +- Git clients that are signing commits should include the certificate + and all intermediate certificates in the signature. +- The GitLab certificate store should only contain the root. + +If you remove a root certificate from the GitLab +trust store, such as when it expires, commit signatures which chain back to that +root display as `unverified`. diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index d46e55ca005..fa5ef35418a 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -244,8 +244,8 @@ Graph API instead of IMAP. Follow the [documentation in the incoming email secti gitlab_rails['service_desk_email_email'] = "project_contact@example.onmicrosoft.com" gitlab_rails['service_desk_email_mailbox_name'] = "inbox" gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" - gitlab_rails['service_desk_inbox_method'] = 'microsoft_graph' - gitlab_rails['service_desk_inbox_options'] = { + gitlab_rails['service_desk_email_inbox_method'] = 'microsoft_graph' + gitlab_rails['service_desk_email_inbox_options'] = { 'tenant_id': '<YOUR-TENANT-ID>', 'client_id': '<YOUR-CLIENT-ID>', 'client_secret': '<YOUR-CLIENT-SECRET>', diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 52e064ef66e..662d7e70910 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -45,6 +45,8 @@ Note the following: a maintainer or administrator role in the group where the exported project lives. - Project members with the [Owner role](../../permissions.md) are imported as Maintainers. - Imported users can be mapped by their public email on self-managed instances, if an administrative user (not an owner) does the import. + Additionally, the user must be an existing member of the namespace, or the user can be added as a +member of the project for contributions to be mapped. Otherwise, a supplementary comment is left to mention that the original author and the MRs, notes, or issues are owned by the importer. - For project migration imports performed over GitLab.com Groups, preserving author information is @@ -217,7 +219,7 @@ GitLab.com may have [different settings](../../gitlab_com/index.md#importexport) ## Troubleshooting -### Import workaround for large repositories +### Import workaround for large repositories [Maximum import size limitations](#import-the-project) can prevent an import from being successful. @@ -225,7 +227,7 @@ If changing the import limits is not possible, the following local workflow can be used to temporarily reduce the repository size for another import attempt. -1. Create a temporary working directory from the export: +1. Create a temporary working directory from the export: ```shell EXPORT=<filename-without-extension> @@ -238,9 +240,11 @@ reduce the repository size for another import attempt. # Prevent interference with recreating an importable file later mv project.bundle ../"$EXPORT"-original.bundle mv ../"$EXPORT".tar.gz ../"$EXPORT"-original.tar.gz + + git switch --create smaller-tmp-main ``` -1. To reduce the repository size, +1. To reduce the repository size, work on this `smaller-tmp-main` branch: [identify and remove large files](../repository/reducing_the_repo_size_using_git.md) or [interactively rebase and fixup](../../../topics/git/git_rebase.md#interactive-rebase) to reduce the number of commits. @@ -252,7 +256,7 @@ reduce the repository size for another import attempt. git gc --prune=now --aggressive # Prepare recreating an importable file - git bundle create ../project.bundle <default-branch-name> + git bundle create ../project.bundle smaller-tmp-main cd .. mv project/ ../"$EXPORT"-project cd .. @@ -268,5 +272,5 @@ reduce the repository size for another import attempt. 1. Update the imported repository's [branch protection rules](../protected_branches.md) and its [default branch](../repository/branches/default.md), and - delete the temporary, `smaller-…` branch, and + delete the temporary, `smaller-tmp-main` branch, and the local, temporary data. diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 66fdace81ba..8b159a75451 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -87,59 +87,64 @@ Example `.compliance-gitlab-ci.yml` # Allows compliance team to control the ordering and interweaving of stages/jobs. # Stages without jobs defined will remain hidden. stages: -- pre-compliance -- build -- test -- pre-deploy-compliance -- deploy -- post-compliance - -variables: # can be overriden by a developer's local .gitlab-ci.yml + - pre-compliance + - build + - test + - pre-deploy-compliance + - deploy + - post-compliance + +variables: # Can be overridden by setting a job-specific variable in project's local .gitlab-ci.yml FOO: sast -sast: # none of these attributes can be overriden by a developer's local .gitlab-ci.yml +sast: # None of these attributes can be overridden by a project's local .gitlab-ci.yml variables: FOO: sast image: ruby:2.6 stage: pre-compliance rules: - - when: always + - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push" + when: never + - when: always # or when: on_success allow_failure: false before_script: - - "# No before scripts." + - "# No before scripts." script: - - echo "running $FOO" + - echo "running $FOO" after_script: - - "# No after scripts." + - "# No after scripts." sanity check: image: ruby:2.6 stage: pre-deploy-compliance rules: - - when: always + - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push" + when: never + - when: always # or when: on_success allow_failure: false before_script: - - "# No before scripts." + - "# No before scripts." script: - - echo "running $FOO" + - echo "running $FOO" after_script: - - "# No after scripts." - + - "# No after scripts." audit trail: image: ruby:2.6 stage: post-compliance rules: - - when: always + - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push" + when: never + - when: always # or when: on_success allow_failure: false before_script: - - "# No before scripts." + - "# No before scripts." script: - - echo "running $FOO" + - echo "running $FOO" after_script: - - "# No after scripts." + - "# No after scripts." -include: # Execute individual project's configuration +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. @@ -174,7 +179,7 @@ cannot change them: - Explicitly set the container image file to run the job in. This ensures that your script steps execute in the correct environment. - Explicitly set any relevant GitLab pre-defined [job keywords](../../../ci/yaml/index.md#job-keywords). - This ensures that your job uses the settings you intend and that they are not overriden by + This ensures that your job uses the settings you intend and that they are not overridden by project-level pipelines. ### Sharing and permissions @@ -187,33 +192,34 @@ section. You can now change the [Project visibility](../../../public_access/public_access.md). If you set **Project Visibility** to public, you can limit access to some features to **Only Project Members**. In addition, you can select the option to -[Allow users to request access](../members/index.md#prevent-users-from-requesting-access-to-a-project). +[Allow users to request access](../members/index.md#request-access-to-a-project). Use the switches to enable or disable the following features: -| Option | More access limit options | Description | -|:----------------------------------|:--------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **Issues** | ✓ | Activates the GitLab issues tracker | -| **Repository** | ✓ | Enables [repository](../repository/) functionality | -| **Merge Requests** | ✓ | Enables [merge request](../merge_requests/) functionality; also see [Merge request settings](#merge-request-settings) | -| **Forks** | ✓ | Enables [forking](../repository/forking_workflow.md) functionality | -| **Pipelines** | ✓ | Enables [CI/CD](../../../ci/index.md) functionality | -| **Container Registry** | | Activates a [registry](../../packages/container_registry/) for your Docker images | -| **Git Large File Storage** | | Enables the use of [large files](../../../topics/git/lfs/index.md#git-large-file-storage-lfs) | -| **Packages** | | Supports configuration of a [package registry](../../../administration/packages/index.md#gitlab-package-registry-administration) functionality | -| **Analytics** | ✓ | Enables [analytics](../../analytics/) | -| **Wiki** | ✓ | Enables a separate system for [documentation](../wiki/) | -| **Snippets** | ✓ | Enables [sharing of code and text](../../snippets.md) | -| **Pages** | ✓ | Allows you to [publish static websites](../pages/) | -| **Metrics Dashboard** | ✓ | Control access to [metrics dashboard](../integrations/prometheus.md) -| **Requirements** | ✓ | Control access to [Requirements Management](../requirements/index.md) | -| **Operations Dashboard** | ✓ | Control access to [operations dashboard](../../../operations/index.md) +| Option | More access limit options | Description | +|:---------------------------------|:--------------------------|:--------------| +| **Issues** | ✓ | Activates the GitLab issues tracker. | +| **Repository** | ✓ | Enables [repository](../repository/) functionality | +| **Merge Requests** | ✓ | Enables [merge request](../merge_requests/) functionality; also see [Merge request settings](#merge-request-settings). | +| **Forks** | ✓ | Enables [forking](../repository/forking_workflow.md) functionality. | +| **Git Large File Storage (LFS)** | | Enables the use of [large files](../../../topics/git/lfs/index.md#git-large-file-storage-lfs). | +| **Packages** | | Supports configuration of a [package registry](../../../administration/packages/index.md#gitlab-package-registry-administration) functionality. | +| **CI/CD** | ✓ | Enables [CI/CD](../../../ci/index.md) functionality. | +| **Container Registry** | | Activates a [registry](../../packages/container_registry/) for your Docker images. | +| **Analytics** | ✓ | Enables [analytics](../../analytics/). | +| **Requirements** | ✓ | Control access to [Requirements Management](../requirements/index.md). | +| **Security & Compliance** | ✓ | Control access to [security features](../../application_security/index.md). | +| **Wiki** | ✓ | Enables a separate system for [documentation](../wiki/). | +| **Snippets** | ✓ | Enables [sharing of code and text](../../snippets.md). | +| **Pages** | ✓ | Allows you to [publish static websites](../pages/). | +| **Operations** | ✓ | Control access to [operations dashboard](../../../operations/index.md). | +| **Metrics Dashboard** | ✓ | Control access to [metrics dashboard](../integrations/prometheus.md). | Some features depend on others: - If you disable the **Issues** option, GitLab also removes the following features: - - **Issue Boards** + - **issue boards** - [**Service Desk**](#service-desk) NOTE: @@ -227,7 +233,7 @@ Some features depend on others: - If you disable **Repository** functionality, GitLab also disables the following features for your project: - **Merge Requests** - - **Pipelines** + - **CI/CD** - **Container Registry** - **Git Large File Storage** - **Packages** @@ -247,7 +253,7 @@ setting **Enable CVE ID requests in the issue sidebar**. #### Disabling email notifications -Project owners can disable all [email notifications](../../profile/notifications.md#gitlab-notification-emails) +Project owners can disable all [email notifications](../../profile/notifications.md) related to the project by selecting the **Disable email notifications** checkbox. ### Merge request settings @@ -350,7 +356,7 @@ to transfer a project. You can transfer an existing project into a [group](../../group/index.md) if: -- You have at least the Maintainer** role in that group. +- You have at least **Maintainer** [role](../../permissions.md#project-members-permissions) in that group. - You're at least an **Owner** of the project to be transferred. - The group to which the project is being transferred to must allow creation of new projects. @@ -457,7 +463,7 @@ To do so: 1. Confirm the action by typing the project's path as instructed. NOTE: -Only project Owners have the [permissions](../../permissions.md#project-members-permissions) +Only project owners have the [permissions](../../permissions.md#project-members-permissions) to remove a fork relationship. ## Monitor settings diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 643042cb96a..cae9276eafd 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -7,25 +7,30 @@ type: reference, howto # Project access tokens -NOTE: -Project access tokens are supported for self-managed instances on Free and above. They are also supported on GitLab SaaS Premium and above (excluding [trial licenses](https://about.gitlab.com/free-trial/)). Self-managed Free instances should review their security and compliance policies with regards to [user self-enrollment](../../admin_area/settings/sign_up_restrictions.md#disable-new-sign-ups) and consider [disabling project access tokens](#enable-or-disable-project-access-token-creation) to lower potential abuse. - > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210181) in GitLab 13.0. > - [Became available on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in GitLab 13.5 for paid groups only. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in GitLab 13.5. -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +Project access tokens are similar to [personal access tokens](../../profile/personal_access_tokens.md) +except they are attached to a project rather than a user. They can be used to: + +- Authenticate with the [GitLab API](../../../api/index.md#personalproject-access-tokens). +- Authenticate with Git using HTTP Basic Authentication. If you are asked for a username when + authenticating, you can use any non-empty value because only the token is needed. -Project access tokens are scoped to a project and can be used to authenticate with the -[GitLab API](../../../api/index.md#personalproject-access-tokens). You can also use -project access tokens with Git to authenticate over HTTPS. If you are asked for a -username when authenticating over HTTPS, you can use any non-empty value because only -the token is needed. +Project access tokens: -Project access tokens expire on the date you define, at midnight UTC. +- Expire on the date you define, at midnight UTC. +- Are supported for self-managed instances on Free tier and above. Free self-managed instances + should: + - Review their security and compliance policies with regards to + [user self-enrollment](../../admin_area/settings/sign_up_restrictions.md#disable-new-sign-ups). + - Consider [disabling project access tokens](#enable-or-disable-project-access-token-creation) to + lower potential abuse. +- Are also supported on GitLab SaaS Premium and above (excluding [trial licenses](https://about.gitlab.com/free-trial/).) -For examples of how you can use a project access token to authenticate with the API, see the following section from our [API Docs](../../../api/index.md#personalproject-access-tokens). +For examples of how you can use a project access token to authenticate with the API, see the +[relevant section from our API Docs](../../../api/index.md#personalproject-access-tokens). ## Creating a project access token @@ -60,10 +65,7 @@ API calls made with a project access token are associated with the corresponding These bot users are included in a project's **Project information > Members** list but cannot be modified. Also, a bot user cannot be added to any other project. -- The username is set to `project_{project_id}_bot` for the first access token, such as `project_123_bot`. -- The username is set to `project_{project_id}_bot{bot_count}` for further access tokens, such as `project_123_bot1`. - -When the project access token is [revoked](#revoking-a-project-access-token) the bot user is deleted +When the project access token is [revoked](#revoking-a-project-access-token), the bot user is deleted and all records are moved to a system-wide user with the username "Ghost User". For more information, see [Associated Records](../../profile/account/delete_account.md#associated-records). diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index 2b901ddc17b..8902bdc21c4 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -115,7 +115,7 @@ In GitLab self-managed instances, you can limit the display of time units to hours. To do so: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences**. 1. Expand **Localization**. 1. Under **Time tracking**, select the **Limit display of time tracking units to hours** checkbox. diff --git a/doc/user/project/web_ide/img/open_web_ide.png b/doc/user/project/web_ide/img/open_web_ide.png Binary files differdeleted file mode 100644 index 02a5a564472..00000000000 --- a/doc/user/project/web_ide/img/open_web_ide.png +++ /dev/null diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 160c2314ded..010a63b7957 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -16,9 +16,22 @@ projects by providing an advanced editor with commit staging. ## Open the Web IDE You can open the Web IDE when viewing a file, from the repository file list, -and from merge requests. - - +and from merge requests: + +- *When viewing a file, or the repository file list* - + 1. In the upper right corner of the page, select **Edit in Web IDE** if it is visible. + 1. If **Edit in Web IDE** is not visible: + 1. Select the **(angle-down)** next to **Edit** or **Gitpod**, depending on your configuration. + 1. Select **Edit in Web IDE** from the list to display it as the editing option. + 1. Select **Edit in Web IDE** to open the editor. +- *When viewing a merge request* - + 1. Go to your merge request, and select the **Overview** tab. + 1. Scroll to the widgets area, after the merge request description. + 1. Select **Edit in Web IDE** if it is visible. + 1. If **Edit in Web IDE** is not visible: + 1. Select the **(angle-down)** next to **Open in Gitpod**. + 1. Select **Open in Web IDE** from the list to display it as the editing option. + 1. Select **Open in Web IDE** to open the editor. ## File finder @@ -249,7 +262,7 @@ The image is uploaded to the same directory and is named `image.png` by default. If another file already exists with the same name, a numeric suffix is automatically added to the filename. -There are two ways to preview Markdown content in the Web IDE: +There are two ways to preview Markdown content in the Web IDE: 1. At the top of the file's tab, select **Preview Markdown** to preview the formatting in your file. You can't edit the file in this view. @@ -280,8 +293,8 @@ a `main` entry point inside the Web IDE. Live Preview is enabled for all projects on GitLab.com. If you are an administrator of a self-managed GitLab instance, and you want to enable Live Preview: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Scroll to **Web IDE** and select **Expand**:  1. Select **Enable Live Preview** and select **Save changes**. diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 0507b6b78ca..d0a1f485fa8 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -46,13 +46,17 @@ for previously created wikis. ## Create the wiki home page -When a wiki is created, it is empty. On your first visit, create the landing page -users see when viewing the wiki: +When a wiki is created, it is empty. On your first visit, you can create the +home page users see when viewing the wiki. This page requires a specific title +to be used as your wiki's home page. To create it: 1. Go to your project or group and select **Wiki**. 1. Select **Create your first page**. +1. GitLab requires this first page be titled `home`. The page with this + title serves as the front page for your wiki. 1. Select a **Format** for styling your text. -1. Add a welcome message in the **Content** section. You can always edit it later. +1. Add a welcome message for your home page in the **Content** section. You can + always edit it later. 1. Add a **Commit message**. Git requires a commit message, so GitLab creates one if you don't enter one yourself. 1. Select **Create page**. @@ -105,7 +109,7 @@ Wiki pages are stored as files in a Git repository, so certain characters have a ### Length restrictions for file and directory names -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/24364) in GitLab 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/24364) in GitLab 12.8. Many common file systems have a [limit of 255 bytes](https://en.wikipedia.org/wiki/Comparison_of_file_systems#Limits) for file and directory names. Git and GitLab both support paths exceeding @@ -123,7 +127,7 @@ may not be able to check out the wiki locally afterward. ## Edit a wiki page -You need the [Developer role](../../permissions.md) or higher to edit a wiki page: +You need at least the [Developer role](../../permissions.md) to edit a wiki page: 1. Go to your project or group and select **Wiki**. 1. Go to the page you want to edit. @@ -138,7 +142,7 @@ For an example, read [Table of contents](../../markdown.md#table-of-contents). ## Delete a wiki page -You need the [Maintainer role](../../permissions.md) or higher to delete a wiki page: +You need at least the [Maintainer role](../../permissions.md) to delete a wiki page: 1. Go to your project or group and select **Wiki**. 1. Go to the page you want to delete. @@ -148,7 +152,7 @@ You need the [Maintainer role](../../permissions.md) or higher to delete a wiki ## Move a wiki page -You need the [Developer role](../../permissions.md) or higher to move a wiki page: +You need at least the [Developer role](../../permissions.md) to move a wiki page: 1. Go to your project or group and select **Wiki**. 1. Go to the page you want to move. @@ -175,7 +179,7 @@ From the history page you can see: ### View changes between page versions -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15242) in GitLab 13.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15242) in GitLab 13.2. You can see the changes made in a version of a wiki page, similar to versioned diff file views: @@ -201,9 +205,9 @@ Commits to wikis are not counted in [repository analytics](../../analytics/repos ## Customize sidebar -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23109) in GitLab 13.8, the sidebar can be customized by selecting the **Edit sidebar** button. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23109) in GitLab 13.8, the sidebar can be customized by selecting the **Edit sidebar** button. -You need Developer [permissions](../../permissions.md) or higher to customize the wiki +You need at least the [Developer role](../../permissions.md) to customize the wiki navigation sidebar. This process creates a wiki page named `_sidebar` which fully replaces the default sidebar navigation: @@ -238,7 +242,7 @@ Administrators for self-managed GitLab installs can ## Group wikis **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13195) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13195) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5. Group wikis work the same way as project wikis. Their usage is similar to project wikis, with a few limitations: @@ -306,7 +310,7 @@ to disable the wiki but toggle it on (in blue). ## Content Editor **(FREE)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5643) in GitLab 14.0. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5643) in GitLab 14.0. GitLab version 14.0 introduces a WYSIWYG editing experience for GitLab Flavored Markdown in Wikis through the [Content Editor](../../../development/fe_guide/content_editor.md). diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 77dd44e5c7f..32bb202767a 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -334,6 +334,52 @@ git config --global url."https://${user}:${personal_access_token}@gitlab.example git config --global url."git@gitlab.example.com".insteadOf "https://gitlab.example.com" ``` +### Fetch Go modules from Geo secondary sites + +As Go modules are stored in Git repositories, you can use the [Geo](../../administration/geo/index.md) +feature that allows Git repositories to be accessed on the secondary Geo servers. + +In the following examples, the primary's site domain name is `gitlab.example.com`, +and the secondary's is `gitlab-secondary.example.com`. + +`go get` will initially generate some HTTP traffic to the primary, but when the module +download commences, the `insteadOf` configuration sends the traffic to the secondary. + +#### Use SSH to access the Geo secondary + +To fetch Go modules from the secondary using SSH: + +1. Reconfigure Git on the client to send traffic for the primary to the secondary: + + ```plaintext + git config --global url."git@gitlab-secondary.example.com".insteadOf "https://gitlab.example.com" + git config --global url."git@gitlab-secondary.example.com".insteadOf "http://gitlab.example.com" + ``` + +1. Ensure the client is set up for SSH access to GitLab repositories. This can be tested on the primary, + and GitLab will replicate the public key to the secondary. + +#### Use HTTP to access the Geo secondary + +Using HTTP to fetch Go modules does not work with CI/CD job tokens, only with +persistent access tokens that are replicated to the secondary. + +To fetch Go modules from the secondary using HTTP: + +1. Put in place a Git `insteadOf` redirect on the client: + + ```plaintext + git config --global url."https://gitlab-secondary.example.com".insteadOf "https://gitlab.example.com" + ``` + +1. Generate a [personal access token](../profile/personal_access_tokens.md) and + provide those credentials in the client's `~/.netrc` file: + + ```plaintext + machine gitlab.example.com login USERNAME password TOKEN + machine gitlab-secondary.example.com login USERNAME password TOKEN + ``` + ## Access project page with project ID > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53671) in GitLab 11.8. diff --git a/doc/user/search/advanced_search.md b/doc/user/search/advanced_search.md index f29ac531d2e..f994539b9fc 100644 --- a/doc/user/search/advanced_search.md +++ b/doc/user/search/advanced_search.md @@ -119,3 +119,24 @@ You can search a specific issue or merge request by its ID with a special prefix - To search by issue ID, use prefix `#` followed by issue ID. For example, [#23456](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=%2323456&group_id=9970&project_id=278964) - To search by merge request ID, use prefix `!` followed by merge request ID. For example [!23456](https://gitlab.com/search?snippets=&scope=merge_requests&repository_ref=&search=%2123456&group_id=9970&project_id=278964) + +## Global search scopes **(FREE SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68640) in GitLab 14.3. + +To improve the performance of your instance's global search, you can limit +the scope of the search. To do so, you can exclude global search scopes by disabling +[`ops` feature flags](../../development/feature_flags/index.md#ops-type). + +Global search has all its scopes **enabled** by default in GitLab SaaS and +self-managed instances. A GitLab administrator can disable the following `ops` +feature flags to limit the scope of your instance's global search and optimize +its performance: + +| Scope | Feature flag | Description | +|--|--|--| +| Code | `global_search_code_tab` | When enabled, the global search includes code as part of the search. | +| Commits | `global_search_commits_tab` | When enabled, the global search includes commits as part of the search. | +| Issues | `global_search_issues_tab` | When enabled, the global search includes issues as part of the search. | +| Merge Requests | `global_search_merge_requests_tab` | When enabled, the global search includes merge requests as part of the search. | +| Wiki | `global_search_wiki_tab` | When enabled, the global search includes wiki as part of the search. | diff --git a/doc/user/search/index.md b/doc/user/search/index.md index 92d01e6a43e..7cf62f09303 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -27,8 +27,8 @@ When you click **Issues**, GitLab shows the opened issues assigned to you: You can search through **Open**, **Closed**, or **All** issues. -You can also filter the results using the search and filter field, as described below in -[Filtering issue and merge request lists](#filtering-issue-and-merge-request-lists). +You can also filter the results using the search and filter field, as described in +[Filter issue and merge request lists](#filter-issue-and-merge-request-lists). ### Issues and MRs assigned to you or created by you @@ -37,11 +37,11 @@ in the search field in the upper right corner:  -### Filtering issue and merge request lists +### Filter issue and merge request lists -> - Filtering by Epics was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195704) in GitLab Ultimate 12.9. -> - Filtering by child Epics was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9029) in GitLab Ultimate 13.0. -> - Filtering by Iterations was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6. Moved to GitLab Premium in 13.9. +> - Filter by Epics was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195704) in GitLab Ultimate 12.9. +> - Filter by child Epics was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9029) in GitLab Ultimate 13.0. +> - Filter by Iterations was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6. Moved to GitLab Premium in 13.9. Follow these steps to filter the **Issues** and **Merge Requests** list pages in projects and groups: @@ -64,12 +64,13 @@ groups: - `!=`: Is not ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18059) in GitLab 12.7) 1. Enter the text to [filter the attribute by](#filters-autocomplete). 1. Repeat this process to filter by multiple attributes. Multiple attributes are joined by a logical - `AND`. + `AND`. For example, filtering by an Author and Milestone `!=` 12.6 filters for the issues where the + author matches your selection, and the milestone is not 12.6: -For example, filtering by Author `=` Jane and Milestone `!=` 12.6 filters for the issues where Jane -is the author and the milestone is not 12.6. +  - +GitLab displays the results on-screen, but you can also +[retrieve them as an RSS feed](#retrieve-search-results-as-feed). ### Filtering by **None** / **Any** @@ -96,6 +97,21 @@ You can filter issues and merge requests by specific terms included in titles or  +### Retrieve search results as feed + +> Feeds for merge requests were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66336) in GitLab 14.3. + +GitLab provides RSS feeds of search results for your project. To subscribe to the +RSS feed of search results: + +1. Go to your project's page. +1. On the left sidebar, select **Issues** or **Merge requests**. +1. Build your search query as described in [Filter issue and merge request lists](#filter-issue-and-merge-request-lists). +1. 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 your search query. +You can add this URL to your feed reader. + ### Filtering by ID > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39908) in GitLab 12.1. @@ -217,12 +233,12 @@ filters them for you as you type. You can also **Explore** all public and internal groups available in GitLab.com, and sort them by **Last created**, **Oldest created**, **Last updated**, or **Oldest updated**. -## Issue Boards +## Issue boards -From an [Issue Board](../../user/project/issue_board.md), you can filter issues by **Author**, **Assignee**, **Milestone**, and **Labels**. +From an [issue board](../../user/project/issue_board.md), you can filter issues by **Author**, **Assignee**, **Milestone**, and **Labels**. You can also filter them by name (issue title), from the field **Filter by name**, which is loaded as you type. -To search for issues to add to lists present in your Issue Board, click +To search for issues to add to lists present in your issue board, click the button **Add issues** on the top-right of your screen, opening a modal window from which you can, besides filtering them by **Name**, **Author**, **Assignee**, **Milestone**, and **Labels**, select multiple issues to add to a list of your choice: diff --git a/doc/user/workspace/img/hardware_settings.png b/doc/user/workspace/img/hardware_settings.png Binary files differindex ff460918f25..919ff46f8c8 100644 --- a/doc/user/workspace/img/hardware_settings.png +++ b/doc/user/workspace/img/hardware_settings.png diff --git a/doc/user/workspace/index.md b/doc/user/workspace/index.md index d9c9d19721b..2ce30c645d5 100644 --- a/doc/user/workspace/index.md +++ b/doc/user/workspace/index.md @@ -1,25 +1,25 @@ --- stage: Manage -group: Access +group: Workspace info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Workspace -Workspace will be the top [namespace](../group/index.md#namespaces) for you to manage -everything GitLab, including: +Workspace will be above the [top-level namespaces](../group/index.md#namespaces) for you to manage everything you can do as a GitLab administrator, including: - Defining and applying settings to all of your groups, subgroups, and projects. - Aggregating data from all your groups, subgroups, and projects. -Workspace will take many of the features from the -[Admin Area](../admin_area/index.md) and will: +The functionality in the [Admin Area](../admin_area/index.md) of self-managed installations will be split up and go to: -- Enable a top namespace for GitLab.com. -- Eventually replace the instance level for self-managed installations. +1. Groups (available in the Workspace, Top-level group namespaces, and Sub-groups) +1. Hardware Controls (for functionality that does not apply to groups) -Our goal is to reach feature parity between SaaS and self-managed installations, with one -exception: **Hardware Controls** will appear **only** on self-managed installations. +Our goal is to reach feature parity between SaaS and Self-Managed installations, with all [Admin Area settings](/ee/user/admin_area/settings/) moving to either: + +- Workspace (contains features relevant to both GitLab-managed and self-managed installations) with a dedicated Settings menu available within the left navigation bar. +- Hardware controls (only contains features relative to Self-Managed installations, with one per installation). NOTE: Workspace is currently in development. |
